Zero-heap WebP decode facade over the vendored libwebp (impl). More...

#include "ra8_webp.h"
#include <limits.h>
#include <stddef.h>
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_webp_arena.h"
#include "src/webp/decode.h"

Include dependency graph for ra8_webp.c:

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.
static ra8_err_t	internal_webp_check_output (const uint8_t data, size_t size, size_t out_stride, size_t out_capacity, uint32_t w, uint32_t *h)
	Read the WebP header and validate the caller's output geometry.
static ra8_err_t	internal_webp_decode_impl (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)
	Validate geometry, decode the WebP into `out_rgba`, and report size.
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.

Variables
static const char	s_ra8_webp_tag [] = "WEBP"
	Component tag used in validation log lines.

Detailed Description

Zero-heap WebP decode facade over the vendored libwebp (impl).

See ra8_webp.h for the contract. This TU is the only first-party code that includes libwebp's public src/webp/decode.h; every consumer reaches WebP through the ra8_err_t facade here, never through libwebp directly.

[Ring 4 / WebP] {World: NS}

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

Since: 0.1.0

Definition in file ra8_webp.c.

Function Documentation

◆ internal_webp_check_output()

ra8_err_t internal_webp_check_output	(	const uint8_t *	data,
		size_t	size,
		size_t	out_stride,
		size_t	out_capacity,
		uint32_t *	w,
		uint32_t *	h )

static

Read the WebP header and validate the caller's output geometry.

Fetches the image dimensions via ra8_webp_get_info(), then checks that the output buffer holds height rows of at least width * 4 bytes and that the stride fits libwebp's int parameter. Extracted from ra8_webp_decode_rgba() so the public entry stays within the NASA Rule 4 function-size budget.

Parameters

[in]	data	WebP byte buffer base.
[in]	size	Buffer length in bytes.
[in]	out_stride	Destination row stride in bytes.
[in]	out_capacity	Destination buffer capacity in bytes.
[out]	w	Decoded image width on success.
[out]	h	Decoded image height on success.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Header valid and the output geometry fits.
k_ra8_err_validation_failed	Malformed WebP container.
k_ra8_err_not_supported	Dimension exceeds the decode cap.
k_ra8_err_range_check_failed	Output buffer too small, or stride > INT_MAX.

Precondition: data, w and h are non-NULL (caller-guaranteed).; size describes the readable extent of data.

Postcondition: On success w and h hold the image dimensions.; On failure w and h are not relied upon.

Note: Re-entrant; reads only.

Since: 0.1.0

Definition at line 92 of file ra8_webp.c.

References k_ra8_err_range_check_failed, k_ra8_ok, k_ra8_webp_bytes_per_px, ra8_log_error, RA8_RETURN_ON_ERROR, ra8_webp_get_info(), and s_ra8_webp_tag.

Referenced by internal_webp_decode_impl().

◆ internal_webp_decode_impl()

ra8_err_t internal_webp_decode_impl	(	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 )

static

Validate geometry, decode the WebP into out_rgba, and report size.

Runs the decode pipeline after the public entry has null-checked its pointers: output-geometry validation, arena-bound WebPDecodeRGBAInto(), then the optional width/height reporting. Extracted from ra8_webp_decode_rgba() so the public entry stays within the NASA Rule 4 function-size budget.

Parameters

[in]	data	WebP byte buffer base (non-NULL, caller-checked).
[in]	size	Buffer length in bytes.
[in]	arena	Bump allocator libwebp draws its scratch from (non-NULL).
[out]	out_rgba	Destination RGBA8888 buffer (non-NULL).
[in]	out_stride	Destination row stride in bytes.
[in]	out_capacity	Destination buffer capacity in bytes.
[out]	out_w	Decoded width, or NULL if unwanted.
[out]	out_h	Decoded height, or NULL if unwanted.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Decode succeeded; `out_rgba` filled, sizes reported.
k_ra8_err_validation_failed	Malformed WebP or decode failure.
k_ra8_err_not_supported	Dimension exceeds the decode cap.
k_ra8_err_range_check_failed	Output buffer too small, or stride > INT_MAX.

Precondition: data, arena and out_rgba are non-NULL (caller-guaranteed).; out_capacity describes the writable extent of out_rgba.

Postcondition: On success out_rgba holds the decoded image.; On failure out_w and out_h are not written.

Note: Not re-entrant: binds the shared decode arena for the call's duration.

Since: 0.1.0

Definition at line 145 of file ra8_webp.c.

References internal_webp_check_output(), k_ra8_err_validation_failed, k_ra8_ok, RA8_RETURN_ON_ERROR, ra8_webp_arena_bind(), ra8_webp_arena_unbind(), and s_ra8_webp_tag.

Referenced by ra8_webp_decode_rgba().

◆ 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);

ra8_err_t
ra8_err_codes_t ra8_err_t
Canonical error-return type used by every ra8-firmware API.
Definition ra8_err.h:546

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)
Decode a WebP into a caller-owned RGBA8888 buffer, heap-free.
Definition ra8_webp.c:187

ra8_webp_arena_t
Caller-owned bump arena backing a single WebP decode.
Definition ra8_webp_arena.h:71

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) { ... }

k_ra8_ok
@ k_ra8_ok
Success – operation completed with all postconditions satisfied.
Definition ra8_err.h:119

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)
Read a WebP header's pixel dimensions without decoding the body.
Definition ra8_webp.c:33