media_download_format.c File Reference

Private source-image to RBKC formatter for the media app. More...

#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include "media_download_format_internal.h"
#include "ra8_attributes.h"

Include dependency graph for media_download_format.c:

Go to the source code of this file.

Functions
ra8_err_t	priv_media_download_memory_write_at (media_download_memory_t *memory, uint64_t offset, const uint8_t *source, uint32_t requested, uint32_t *written)
	Write one exact span at an absolute private-spool offset.
ra8_err_t	priv_media_download_memory_read (void *context, uint32_t offset, uint8_t *destination, uint32_t requested, uint32_t *out_read)
	Read one exact initialized range from a private spool.
static ra8_err_t	internal_image_write (void *context, uint32_t offset, const uint8_t *source, uint32_t requested, uint32_t *out_written)
	Adapt the comic image-spool random writer to bounded memory.
static ra8_err_t	internal_flat_append (void *context, const uint8_t *source, uint32_t requested, uint32_t *out_written)
	Append one flat RABOOK1 fragment to bounded memory.
static ra8_err_t	internal_packed_write (void *context, uint64_t offset, const uint8_t *source, uint32_t requested, uint32_t *out_written)
	Adapt the RBKC random writer to bounded packed memory.
static ra8_err_t	internal_validate_format_request (const uint8_t *source, size_t source_size, const media_download_format_config_t *config, const media_download_format_workspace_t *workspace, uint64_t *packed_size)
	Validate one source-image formatting request.
ra8_err_t	priv_media_download_format_rabook (const uint8_t *source, size_t source_size, const media_download_format_config_t *config, media_download_format_workspace_t *workspace, uint64_t *packed_size)
	Format one encoded source image as a reader-native .rabook.

Detailed Description

Private source-image to RBKC formatter for the media app.

Adapts bounded caller memory to the production comic and container streaming callbacks without owning a filesystem, heap, or static conversion workspace.

Copyright

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

Since

0.1.0

Definition in file media_download_format.c.

Function Documentation

internal_flat_append()

ra8_err_t internal_flat_append ( void * context, const uint8_t * source, uint32_t requested, uint32_t * out_written )

static

Append one flat RABOOK1 fragment to bounded memory.

Selects the current logical end as the destination offset before delegating the exact append to the common memory writer.

Parameters

[in,out]	context	Bound flat spool.
[in]	source	Ordered flat-book bytes.
[in]	requested	Exact requested byte count.
[out]	out_written	Accepted byte count.

Returns

priv_media_download_memory_write_at status.

Return values

k_ra8_ok

The complete flat fragment was appended.

Precondition

Callback arguments satisfy ra8_rabook_write_fn.

The flat spool is private and writable.

Postcondition

Success extends the flat spool by exactly requested.

Failure reports zero progress.

Note

The current logical length selects the append offset.

Since

0.1.0

Definition at line 127 of file media_download_format.c.

References k_ra8_err_null_ptr, media_download_memory_t::length, priv_media_download_memory_write_at(), and RA8_INTERNAL.

Referenced by priv_media_download_format_rabook().

internal_image_write()

ra8_err_t internal_image_write ( void * context, uint32_t offset, const uint8_t * source, uint32_t requested, uint32_t * out_written )

static

Adapt the comic image-spool random writer to bounded memory.

Preserves the callback's uint32 offset while delegating all range and exact-progress checks to the common memory writer.

Parameters

[in,out]	context	Bound image spool.
[in]	offset	Logical image-pool offset.
[in]	source	Normalized image bytes.
[in]	requested	Exact requested byte count.
[out]	out_written	Accepted byte count.

Returns

priv_media_download_memory_write_at status.

Return values

k_ra8_ok

The complete image fragment was stored.

Precondition

Callback arguments satisfy ra8_rabook_comic_write_at_fn.

The image spool is private and writable.

Postcondition

Success initializes the complete requested image span.

Failure reports zero progress.

Note

Thin typed callback adapter.

Since

0.1.0

Definition at line 101 of file media_download_format.c.

References priv_media_download_memory_write_at(), and RA8_INTERNAL.

Referenced by priv_media_download_format_rabook().

internal_packed_write()

ra8_err_t internal_packed_write ( void * context, uint64_t offset, const uint8_t * source, uint32_t requested, uint32_t * out_written )

static

Adapt the RBKC random writer to bounded packed memory.

Preserves the writer's uint64 backfill offset while delegating the capacity and exact-progress checks to the common memory writer.

Parameters

[in,out]	context	Bound packed destination.
[in]	offset	Absolute RBKC byte offset.
[in]	source	Container bytes.
[in]	requested	Exact requested byte count.
[out]	out_written	Accepted byte count.

Returns

priv_media_download_memory_write_at status.

Return values

k_ra8_ok

The complete container fragment was stored.

Precondition

Callback arguments satisfy ra8_rabook_write_at_fn.

The packed destination is private and writable.

Postcondition

Success initializes the complete requested range.

Failure reports zero progress.

Note

Supports the writer's final offset-table backfill.

Since

0.1.0

Definition at line 161 of file media_download_format.c.

References priv_media_download_memory_write_at(), and RA8_INTERNAL.

Referenced by priv_media_download_format_rabook().

internal_validate_format_request()

ra8_err_t internal_validate_format_request ( const uint8_t * source, size_t source_size, const media_download_format_config_t * config, const media_download_format_workspace_t * workspace, uint64_t * packed_size )

static

Validate one source-image formatting request.

Clears the caller's result before checking every required input, workspace span, and workspace capacity in the public contract order.

Parameters

[in]	source	Complete encoded source image.
[in]	source_size	Exact encoded image extent in bytes.
[in]	config	Immutable conversion policy.
[in]	workspace	Caller-owned fixed conversion workspace.
[out]	packed_size	Produced RBKC byte count, cleared before validation.

Returns

Request-validation status.

Return values

k_ra8_ok	Every required pointer and extent is valid.
k_ra8_err_null_ptr	A required pointer or workspace span is absent.
k_ra8_err_invalid_size	A required input or workspace extent is zero.

Precondition

Pointer arguments may be null only for deliberate contract validation.

Non-null workspace fields describe caller-owned writable storage.

Postcondition

Success guarantees the formatting pipeline can bind all fixed spans.

Failure leaves packed_size at zero when that pointer is non-null.

Note

Validation performs no conversion and writes no workspace bytes.

Since

0.1.0

Definition at line 191 of file media_download_format.c.

References media_download_format_workspace_t::flat, media_download_format_workspace_t::flat_cap, media_download_format_workspace_t::image, media_download_format_workspace_t::image_cap, k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_ok, media_download_format_workspace_t::packed, and media_download_format_workspace_t::packed_cap.

Referenced by priv_media_download_format_rabook().

priv_media_download_format_rabook()

ra8_err_t priv_media_download_format_rabook ( const uint8_t * source, size_t source_size, const media_download_format_config_t * config, media_download_format_workspace_t * workspace, uint64_t * packed_size )

nodiscard

Format one encoded source image as a reader-native .rabook.

Parameters

[in]	source	Complete encoded JPEG, PNG, GIF, BMP, or WebP bytes.
[in]	source_size	Exact encoded byte count.
[in]	config	Page, book, raster, and chunk policy.
[in,out]	workspace	Exclusive caller-owned conversion storage.
[out]	packed_size	Exact RBKC artifact byte count.

Returns

Conversion status.

Return values

k_ra8_ok	A complete RBKC artifact occupies workspace->packed.
k_ra8_err_null_ptr	A required pointer or workspace span is NULL.
k_ra8_err_invalid_size	A capacity, source, or callback extent failed.

Returns

Raster, builder, compressor, and validation statuses propagate.

Precondition

Workspace spans are live, writable, and mutually non-overlapping.

source is disjoint from every mutable workspace span.

Postcondition

Success initializes exactly packed_size bytes of packed storage.

Failure sets packed_size to zero and publishes no external object.

Note

The caller must strictly validate before transactionally publishing.

Since

0.1.0

Definition at line 234 of file media_download_format.c.

References media_download_format_config_t::chunk_bytes, media_download_format_workspace_t::comic, media_download_format_workspace_t::container, media_download_format_workspace_t::flat, media_download_format_workspace_t::flat_cap, media_download_format_workspace_t::image, media_download_format_workspace_t::image_cap, internal_flat_append(), internal_image_write(), internal_packed_write(), internal_validate_format_request(), k_ra8_err_validation_failed, k_ra8_ok, media_download_memory_t::length, media_download_format_config_t::max_image_edge, media_download_format_config_t::metadata, media_download_format_workspace_t::packed, media_download_format_workspace_t::packed_cap, media_download_format_config_t::page_id, media_download_format_config_t::pixel_format, priv_media_download_memory_read(), RA8_PRIV, ra8_rabook_comic_add_page(), ra8_rabook_comic_finish(), ra8_rabook_comic_init(), and ra8_rabook_container_write().

Referenced by internal_format().

priv_media_download_memory_read()

ra8_err_t priv_media_download_memory_read ( void * context, uint32_t offset, uint8_t * destination, uint32_t requested, uint32_t * out_read )

nodiscard

Read one exact initialized range from a private spool.

Parameters

[in]	context	Bound media_download_memory_t source.
[in]	offset	Absolute source offset.
[out]	destination	Writable destination span.
[in]	requested	Exact byte count.
[out]	out_read	Copied byte count.

Returns

Memory-read status.

Return values

k_ra8_ok	The complete range was copied.
k_ra8_err_null_ptr	A required pointer was NULL.
k_ra8_err_invalid_size	The requested range exceeded initialized bytes.

Precondition

Context and destination remain live for the call.

Destination does not overlap the selected source range.

Postcondition

Success reports requested and initializes the destination range.

Failure reports zero when out_read is available and preserves source state.

Note

Private formatter seam exposed only to same-module tests.

Since

0.1.0

Definition at line 53 of file media_download_format.c.

References media_download_memory_t::bytes, k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_ok, media_download_memory_t::length, memcpy(), and RA8_PRIV.

Referenced by priv_media_download_format_rabook().

priv_media_download_memory_write_at()

ra8_err_t priv_media_download_memory_write_at ( media_download_memory_t * memory, uint64_t offset, const uint8_t * source, uint32_t requested, uint32_t * written )

nodiscard

Write one exact span at an absolute private-spool offset.

Parameters

[in,out]	memory	Destination spool.
[in]	offset	Absolute destination offset.
[in]	source	Complete source span.
[in]	requested	Exact byte count.
[out]	written	Accepted byte count.

Returns

Memory-write status.

Return values

k_ra8_ok	The complete span was copied.
k_ra8_err_null_ptr	A required pointer was NULL.
k_ra8_err_invalid_size	The requested range exceeded capacity.

Precondition

Non-NULL pointers span their declared extents.

Source and destination ranges do not overlap.

Postcondition

Success reports requested and extends length monotonically.

Failure reports zero when written is available and preserves length.

Note

Private formatter seam exposed only to same-module tests.

Since

0.1.0

Definition at line 20 of file media_download_format.c.

References media_download_memory_t::bytes, media_download_memory_t::capacity, k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_ok, media_download_memory_t::length, memcpy(), and RA8_PRIV.

Referenced by internal_flat_append(), internal_image_write(), and internal_packed_write().