Convert one C6-fetched encoded image into a strict .rabook. More...

#include <stddef.h>
#include <stdint.h>
#include "book.h"
#include "mdl_format.h"
#include "media_download_format_internal.h"
#include "media_download_image_internal.h"
#include "ra8_compress.h"
#include "ra8_img_arena.h"
#include "ra8_mdl_storage_ram.h"
#include "ra8_webp_arena.h"

Include dependency graph for media_download_image.c:

Data Structures
struct	image_compressor_t
	Aligned caller-owned miniz compressor storage. More...

Enumerations
enum	image_limit_t : uint32_t { k_image_source_bytes = 4194304U , k_image_stb_arena_bytes = 12582912U , k_image_webp_arena_bytes = 4194304U , k_image_rgba_bytes = 16777216U , k_image_edge = 1600U , k_image_gray_bytes = 2560000U , k_image_normalized_bytes = 1280000U , k_image_flat_bytes = 1500000U , k_image_packed_bytes = 1600000U , k_image_string_bytes = 1024U , k_image_chunk_bytes = 65536U , k_image_compressed_bytes = 66560U , k_image_offset_entries = 25U }
	Fixed one-page source and conversion capacities. More...

Functions
static RA8_INTERNAL ra8_rabook_buffers_t	internal_builder (void)
	Construct the fixed one-page builder arena descriptor.
static RA8_INTERNAL media_download_format_workspace_t	internal_workspace (ra8_img_arena_t stb, ra8_webp_arena_t webp)
	Bind all fixed source-image formatter workspaces.
static RA8_INTERNAL ra8_err_t	internal_format (uint64_t *packed_size)
	Convert the committed encoded source into private RBKC bytes.
static RA8_INTERNAL ra8_err_t	internal_publish_fragment (const ra8_mdl_transfer_config_t *transfer, uint64_t offset, uint16_t length)
	Append and hash one generated artifact fragment.
static RA8_INTERNAL ra8_err_t	internal_publish (const ra8_mdl_transfer_config_t transfer, uint64_t packed_size, const char destination)
	Strictly publish one complete locally generated RBKC artifact.
static RA8_INTERNAL ra8_err_t	internal_check_transfer (const ra8_mdl_transfer_config_t *transfer)
	Prove every injected callback required by image mode is present.
RA8_PRIV ra8_err_t	priv_media_download_image_run (ra8_c6link_t link, const char url, const char destination, const ra8_mdl_transfer_config_t transfer)
	Download one encoded image and publish it as a strict .rabook.

Variables
static const mdl_format_t	s_output_format = k_mdl_format_rabook
	Real application output selection, independent of the C6 transport.
static ra8_mdl_storage_ram_t	s_source_storage
	Private transaction for the encoded source bytes.
static book_chapter_t	s_chapters [1]
	One-page resident builder tables.
static book_node_t	s_nodes [2]
	Minimal body/img DOM.
static book_attr_t	s_attrs [1]
	One image-source attribute.
static book_stylesheet_t	s_styles [1]
	Required non-null stylesheet arena.
static book_image_t	s_images [1]
	One normalized image descriptor.
static char	s_strings [k_image_string_bytes]
	Metadata and DOM string pool.
static uint8_t	s_dummy_image [1]
	External-image mode sentinel arena.
static uint8_t	s_dummy_output [1]
	Streaming-output mode sentinel arena.
static uint8_t	s_source [k_image_source_bytes]
	Complete fetched encoded image.
static uint8_t	s_stb_arena [k_image_stb_arena_bytes]
	Caller arena for stb JPEG/PNG/GIF/BMP decoding.
static uint8_t	s_webp_arena [k_image_webp_arena_bytes]
	Caller arena for WebP decoder transient storage.
static uint8_t	s_rgba [k_image_rgba_bytes]
	Full-resolution WebP RGBA frame storage.
static uint8_t	s_gray [k_image_gray_bytes]
	Downscaled grayscale frame storage.
static uint8_t	s_normalized [k_image_normalized_bytes]
	One normalized gray4 payload.
static uint8_t	s_image [k_image_normalized_bytes]
	External normalized-image spool.
static uint8_t	s_flat [k_image_flat_bytes]
	Complete private flat RABOOK1 spool.
static uint8_t	s_packed [k_image_packed_bytes]
	Complete private chunked RBKC output.
static uint8_t	s_container_input [k_image_chunk_bytes]
	One uncompressed container chunk.
static uint8_t	s_container_compressed [k_image_compressed_bytes]
	One compressed container stream.
static uint64_t	s_container_offsets [k_image_offset_entries]
	Complete RBKC offset table for the bounded flat spool.
static image_compressor_t	s_compressor
	RBKC compressor state.

Detailed Description

Convert one C6-fetched encoded image into a strict .rabook.

Owns only fixed application workspaces. Source bytes are first committed to private RAM, transformed into canonical RABOOK1 and RBKC, then hashed, strictly validated, and published through the injected VFS transaction.

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

Since: 0.1.0

Definition in file media_download_image.c.

Enumeration Type Documentation

◆ image_limit_t

enum image_limit_t : uint32_t

Fixed one-page source and conversion capacities.

Enumerator
k_image_source_bytes	Maximum fetched encoded image.
k_image_stb_arena_bytes	stb decoder allocation arena.
k_image_webp_arena_bytes	WebP decoder scratch arena.
k_image_rgba_bytes	Maximum decoded RGBA frame.
k_image_edge	Longest normalized page edge.
k_image_gray_bytes	1600x1600 grayscale frame.
k_image_normalized_bytes	Gray4 normalized page bytes.
k_image_flat_bytes	Flat RABOOK1 capacity.
k_image_packed_bytes	Final RBKC capacity.
k_image_string_bytes	Builder string-pool bytes.
k_image_chunk_bytes	RBKC inflated chunk geometry.
k_image_compressed_bytes	One zlib stream capacity.
k_image_offset_entries	Flat chunks plus terminator.

Definition at line 27 of file media_download_image.c.

Function Documentation

◆ internal_builder()

RA8_INTERNAL ra8_rabook_buffers_t internal_builder ( void )

static

Construct the fixed one-page builder arena descriptor.

Maps each bounded application array to the builder field that owns it without initializing or copying any payload bytes.

Returns: Complete builder buffers by value.

Return values

ra8_rabook_buffers_t Every member names its exact backing extent.

Precondition: Static builder arrays are exclusively owned by one conversion.; No retained builder context refers to the arrays.

Postcondition: No backing byte is initialized by this descriptor-only operation.; Every typed capacity matches its one-page table.

Note: File-local and not thread-safe through shared static storage.

Since: 0.1.0

Definition at line 117 of file media_download_image.c.

References RA8_INTERNAL, s_attrs, s_chapters, s_dummy_image, s_dummy_output, s_images, s_nodes, s_strings, and s_styles.

Referenced by internal_workspace().

◆ internal_check_transfer()

RA8_INTERNAL ra8_err_t internal_check_transfer ( const ra8_mdl_transfer_config_t * transfer )

static

Prove every injected callback required by image mode is present.

Checks the complete storage and digest callback surface before any source fetch, conversion, or publication transaction begins.

Parameters

[in] transfer Candidate transfer configuration.

Returns: Callback validation status.

Return values

k_ra8_ok	Every required storage and SHA callback is non-null.
k_ra8_err_null_ptr	A required configuration or callback is null.

Precondition: transfer may be null.; No callback is invoked by this check.

Postcondition: No caller or application state is modified.; Success permits both source transfer and strict local publication.

Note: Image mode requires validation because it claims RABOOK output.

Since: 0.1.0

Definition at line 338 of file media_download_image.c.

References ra8_mdl_storage_iface::abort, ra8_mdl_storage_iface::begin, ra8_mdl_storage_iface::commit, ra8_mdl_sha256_iface::ctx, ra8_mdl_storage_iface::ctx, ra8_mdl_sha256_iface::final, ra8_mdl_sha256_iface::init, k_ra8_err_null_ptr, k_ra8_ok, RA8_INTERNAL, ra8_mdl_transfer_config::sha256, ra8_mdl_transfer_config::storage, ra8_mdl_sha256_iface::update, ra8_mdl_storage_iface::validate, and ra8_mdl_storage_iface::write.

Referenced by priv_media_download_image_run().

◆ internal_format()

RA8_INTERNAL ra8_err_t internal_format ( uint64_t * packed_size )

static

Convert the committed encoded source into private RBKC bytes.

Opens the committed RAM source, binds the bounded image pipeline, and emits one canonical RABOOK1 page wrapped in an RBKC container.

Parameters

[out] packed_size Exact generated artifact size.

Returns: Source-view or formatter status.

Return values

k_ra8_ok	A complete private RBKC artifact occupies s_packed.
k_ra8_err_not_supported	Output policy is not RABOOK.

Precondition: The source RAM transaction committed a nonempty immutable view.; All conversion workspaces are exclusively owned.

Postcondition: Success initializes exactly packed_size packed bytes.; Failure publishes no VFS object.

Note: Metadata is fixed because this mode imports one direct image URL.

Since: 0.1.0

Definition at line 205 of file media_download_image.c.

References internal_workspace(), k_book_pixfmt_gray4, k_image_chunk_bytes, k_image_edge, k_mdl_format_rabook, k_ra8_err_not_supported, k_ra8_ok, priv_media_download_format_rabook(), RA8_INTERNAL, ra8_mdl_storage_ram_view(), s_output_format, and s_source_storage.

Referenced by priv_media_download_image_run().

◆ internal_publish()

RA8_INTERNAL ra8_err_t internal_publish	(	const ra8_mdl_transfer_config_t *	transfer,
		uint64_t	packed_size,
		const char *	destination )

static

Strictly publish one complete locally generated RBKC artifact.

Streams the generated bytes through hashing and staged storage, validates the exact digest and length, then commits atomically.

Parameters

[in]	transfer	Bound publication transaction, validator, and SHA.
[in]	packed_size	Exact generated artifact byte count.
[in]	destination	Canonical final VFS destination.

Returns: Hash, validation, transaction, or publication status.

Return values

k_ra8_ok	The strict validated destination is visible.
k_ra8_err_invalid_size	Artifact or chunk policy is not representable.

Precondition: The packed bytes are private and immutable for the call.; Every required callback is non-null and storage is idle or committed.

Postcondition: Success leaves one committed destination and no stage.; Failure after begin invokes abort and preserves the primary error.

Note: Local generation has no remote digest; the RA8 hashes its own output.

Since: 0.1.0

Definition at line 282 of file media_download_image.c.

References ra8_mdl_storage_iface::abort, ra8_mdl_storage_iface::begin, ra8_mdl_transfer_config::chunk_bytes, ra8_mdl_storage_iface::commit, ra8_mdl_sha256_iface::ctx, ra8_mdl_storage_iface::ctx, ra8_mdl_sha256_iface::final, ra8_mdl_sha256_iface::init, internal_publish_fragment(), k_ra8_err_invalid_size, k_ra8_mdl_sha256_bytes, k_ra8_ok, RA8_INTERNAL, s_packed, ra8_mdl_transfer_config::sha256, ra8_mdl_transfer_config::storage, and ra8_mdl_storage_iface::validate.

Referenced by priv_media_download_image_run().

◆ internal_publish_fragment()

RA8_INTERNAL ra8_err_t internal_publish_fragment	(	const ra8_mdl_transfer_config_t *	transfer,
		uint64_t	offset,
		uint16_t	length )

static

Append and hash one generated artifact fragment.

Writes the same ordered byte span to the active storage stage and SHA-256 stream, rejecting a successful short storage write.

Parameters

[in]	transfer	Bound publication transaction and SHA callbacks.
[in]	offset	First packed byte to append.
[in]	length	Exact fragment byte count.

Returns: Storage, progress, or SHA status.

Return values

k_ra8_ok	The fragment was stored and hashed exactly once.
k_ra8_err_invalid_size	Storage reported successful short progress.

Precondition: transfer owns an active private storage transaction and SHA stream.; offset + length is inside the generated packed artifact.

Postcondition: Success appends and hashes exactly length ordered bytes.; Failure leaves the outer caller responsible for transaction abort.

Note: Length is bounded to the injected uint16 chunk policy.

Since: 0.1.0

Definition at line 249 of file media_download_image.c.

References ra8_mdl_sha256_iface::ctx, ra8_mdl_storage_iface::ctx, k_ra8_err_invalid_size, k_ra8_ok, RA8_INTERNAL, s_packed, ra8_mdl_transfer_config::sha256, ra8_mdl_transfer_config::storage, ra8_mdl_sha256_iface::update, and ra8_mdl_storage_iface::write.

Referenced by internal_publish().

◆ internal_workspace()

RA8_INTERNAL media_download_format_workspace_t internal_workspace	(	ra8_img_arena_t *	stb,
		ra8_webp_arena_t *	webp )

static

Bind all fixed source-image formatter workspaces.

Resets both decoder arenas and assembles the comic and container workspaces over the application's statically reserved SDRAM.

Parameters

[out]	stb	Caller descriptor for the stb arena.
[out]	webp	Caller descriptor for the WebP arena.

Returns: Complete formatter workspace by value.

Return values

media_download_format_workspace_t Every fixed span is bound.

Precondition: Static conversion storage is exclusively owned.; Descriptor outputs are non-null and writable.

Postcondition: Codec arenas are reset and all capacities match their backing arrays.; No source or output byte is published.

Note: File-local and not thread-safe through codec arena bindings.

Since: 0.1.0

Definition at line 152 of file media_download_image.c.

References internal_builder(), k_image_offset_entries, RA8_INTERNAL, s_compressor, s_container_compressed, s_container_input, s_container_offsets, s_flat, s_gray, s_image, s_normalized, s_packed, s_rgba, s_stb_arena, and s_webp_arena.

Referenced by internal_format().

◆ priv_media_download_image_run()

RA8_PRIV ra8_err_t priv_media_download_image_run	(	ra8_c6link_t *	link,
		const char *	url,
		const char *	destination,
		const ra8_mdl_transfer_config_t *	transfer )

nodiscard

Download one encoded image and publish it as a strict .rabook.

Parameters

[in,out]	link	Open, exclusively owned C6 link.
[in]	url	NUL-terminated HTTPS source-image URL.
[in]	destination	Canonical final VFS destination.
[in]	transfer	Bound strict VFS storage, SHA, and chunk policy.

Returns: Download, format, validation, or publication status.

Return values

k_ra8_ok	A generated RBKC/RABOOK1 artifact was published.
k_ra8_err_null_ptr	A required pointer or callback was null.
k_ra8_err_not_supported	The configured output is not RABOOK.
other	C6, raster, builder, compression, hash, VFS, and validation errors propagate unchanged.

Precondition: link is open and no other caller uses it or the supplied contexts.; transfer owns a strict format validator and unused transaction.

Postcondition: Success leaves one validated final artifact and no private stage.; Failure leaves no newly published artifact and aborts an opened stage.