ra8_webp.h File Reference

Zero-heap WebP (VP8 / VP8L) decode facade over the vendored libwebp. More...

#include <stddef.h>
#include <stdint.h>
#include "ra8_err.h"
#include "ra8_webp_arena.h"

Include dependency graph for ra8_webp.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Enumerations
enum	ra8_webp_limits_t : uint32_t {   k_ra8_webp_max_dim = 8192U ,   k_ra8_webp_bytes_per_px = 4U }
	WebP decode facade fixed limits (no magic numbers). More...

Functions
ra8_err_t	ra8_webp_get_info (const uint8_t *data, size_t size, uint32_t *out_w, uint32_t *out_h)
	Read a WebP header's pixel dimensions without decoding the body.
ra8_err_t	ra8_webp_decode_rgba (const uint8_t *data, size_t size, ra8_webp_arena_t *arena, uint8_t *out_rgba, size_t out_stride, size_t out_capacity, uint32_t *out_w, uint32_t *out_h)
	Decode a WebP into a caller-owned RGBA8888 buffer, heap-free.

Detailed Description

Zero-heap WebP (VP8 / VP8L) decode facade over the vendored libwebp.

Longstrip corpora are increasingly WebP-heavy, and stb_image cannot decode WebP, so the e-reader vendors libwebp (decode-only) under apps/shared_libs/third_party/libwebp/ and wraps it here behind a small ra8_err_t facade. The facade decodes an in-memory WebP directly into a caller-provided RGBA8888 buffer, drawing all of libwebp's transient scratch from a caller-owned ra8_webp_arena_t (see ra8_webp_arena.h) so the decode reaches no malloc (NASA P10 Rule 3). The bytes are treated as fully attacker-controlled initial-access content – a WebP inside a downloaded book – and are fuzzed by tests/fuzz/src/fuzz_ra8_webp.c.

Integration (#290 normalize-on-import):

The JOF tile producer consumes this facade (ra8_jof_produce() -> priv_webp_transcode): a WebP manifest image is decoded whole-frame here and banded into the one normalized band-tile format, so render time touches a single codec regardless of source. The small-image (non-tiled) ra8_reflow / ra8_img inline raster dispatch does not yet have a WebP arm – that lands with the #289 longstrip render path; see the TODO(#289) seam in ra8_webp.c.

[Ring 4 / WebP] {World: NS}

Copyright

Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Since

0.1.0

Definition in file ra8_webp.h.

Enumeration Type Documentation

ra8_webp_limits_t

enum ra8_webp_limits_t : uint32_t

WebP decode facade fixed limits (no magic numbers).

These bound attacker-controlled inputs before any allocation: k_ra8_webp_max_dim rejects an absurd declared width/height the way stb_image_impl.c caps STBI_MAX_DIMENSIONS, keeping w * h * bpp far below the 32-bit overflow threshold; k_ra8_webp_bytes_per_px fixes the RGBA8888 output pixel stride.

Invariant

k_ra8_webp_max_dim * k_ra8_webp_max_dim * k_ra8_webp_bytes_per_px fits in a 32-bit unsigned integer without overflow.

See also

ra8_webp_decode_rgba()

Since

0.1.0

Enumerator
k_ra8_webp_max_dim	Max accepted width/height, pixels/axis.
k_ra8_webp_bytes_per_px	Output bytes per pixel (RGBA8888).

Definition at line 57 of file ra8_webp.h.

Function Documentation

ra8_webp_decode_rgba()

ra8_err_t ra8_webp_decode_rgba ( const uint8_t * data, size_t size, ra8_webp_arena_t * arena, uint8_t * out_rgba, size_t out_stride, size_t out_capacity, uint32_t * out_w, uint32_t * out_h )

nodiscard

Decode a WebP into a caller-owned RGBA8888 buffer, heap-free.

Validates the header via ra8_webp_get_info(), checks the output buffer is large enough for height * stride, binds arena as libwebp's scratch allocator, and calls WebPDecodeRGBAInto to decode straight into out_rgba. The arena supplies every internal allocation, so the decode reaches no malloc; it fully drains before this call returns. Both VP8 (lossy) and VP8L (lossless) WebP bitstreams are handled by the one codec.

Parameters

[in]	data	In-memory WebP bytes. Must be non-NULL.
[in]	size	Length of data in bytes. Must be non-zero.
[in,out]	arena	Scratch arena; reset, used, and drained here. Must be non-NULL and back at least the decode's peak scratch footprint (a few KiB for a thumbnail up to a few MiB for a full page).
[out]	out_rgba	Destination RGBA8888 pixels. Must be non-NULL and span at least out_capacity bytes.
[in]	out_stride	Destination row stride in bytes; must be at least width * k_ra8_webp_bytes_per_px and <= INT_MAX.
[in]	out_capacity	Size of out_rgba in bytes; must be at least height * out_stride.
[out]	out_w	Receives the decoded width. May be NULL.
[out]	out_h	Receives the decoded height. May be NULL.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Decoded; out_rgba filled top-to-bottom.
k_ra8_err_null_ptr	data, arena or out_rgba is NULL.
k_ra8_err_invalid_arg	size is zero.
k_ra8_err_validation_failed	Not a valid WebP, or the decode failed (corrupt body or arena exhausted).
k_ra8_err_not_supported	A dimension exceeds k_ra8_webp_max_dim.
k_ra8_err_range_check_failed	out_stride / out_capacity too small, or out_stride exceeds INT_MAX.

Precondition

arena has base pointing at cap writable bytes and cap >= the decode's peak scratch footprint.

out_rgba spans at least out_capacity writable bytes.

Postcondition

On k_ra8_ok, out_rgba holds height rows of RGBA8888 at out_stride.

On return the arena is drained (live == 0, offset == 0) and unbound.

Note

Not thread-safe: WebP decoding is single-threaded on this target.

Warning

arena is reset on entry; any prior contents are discarded.

Example:

alignas(16) static uint8_t scratch[2U * 1024U * 1024U];
ra8_webp_arena_t arena = {.base = scratch, .cap = sizeof scratch};
uint32_t w = 0, h = 0;
ra8_err_t e = ra8_webp_decode_rgba(buf, len, &arena, fb, w * 4U,
                                   sizeof fb, &w, &h);

See also

ra8_webp_get_info()

ra8_webp_arena_bind()

Since

0.1.0

Definition at line 187 of file ra8_webp.c.

References internal_webp_decode_impl(), RA8_CHECK_NULL_PTR, and s_ra8_webp_tag.

Referenced by internal_decode_webp(), priv_jof_webp_transcode(), and webp_demo_decode_ok().

ra8_webp_get_info()

ra8_err_t ra8_webp_get_info ( const uint8_t * data, size_t size, uint32_t * out_w, uint32_t * out_h )

nodiscard

Read a WebP header's pixel dimensions without decoding the body.

Wraps libwebp's WebPGetInfo. Validates the RIFF/VP8(L) container and returns the declared canvas size, rejecting a non-WebP buffer or an absurd dimension (> k_ra8_webp_max_dim per axis) so a caller can size an output buffer / arena before committing to a full decode.

Parameters

[in]	data	Pointer to the in-memory WebP bytes. Must be non-NULL.
[in]	size	Length of data in bytes. Must be non-zero.
[out]	out_w	Receives the decoded width in pixels. Must be non-NULL.
[out]	out_h	Receives the decoded height in pixels. Must be non-NULL.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Header parsed; out_w / out_h set.
k_ra8_err_null_ptr	data, out_w or out_h is NULL.
k_ra8_err_invalid_arg	size is zero.
k_ra8_err_validation_failed	Not a valid WebP / non-positive dims.
k_ra8_err_not_supported	A dimension exceeds k_ra8_webp_max_dim.

Precondition

data points to at least size readable bytes.

out_w and out_h point to writable uint32_t storage.

Postcondition

On k_ra8_ok, *out_w and *out_h are in [1, k_ra8_webp_max_dim].

On any error, *out_w and *out_h are left unmodified.

Note

Not thread-safe: WebP decoding is single-threaded on this target.

Pure query: does not allocate and does not bind an arena.

Example:

uint32_t w = 0, h = 0;
if (ra8_webp_get_info(buf, len, &w, &h) == k_ra8_ok) { ... }

See also

ra8_webp_decode_rgba()

Since

0.1.0

Definition at line 33 of file ra8_webp.c.

References k_ra8_err_invalid_arg, k_ra8_err_not_supported, k_ra8_err_validation_failed, k_ra8_ok, k_ra8_webp_max_dim, RA8_CHECK_NULL_PTR, ra8_log_error, and s_ra8_webp_tag.

Referenced by internal_decode_webp(), internal_probe(), internal_probe_sniff(), internal_webp_check_output(), and priv_jof_webp_transcode().