Caller-workspace CBZ, CBR, and CBT reader engine. More...

#include <stddef.h>
#include <stdint.h>
#include "comic.h"
#include "ra8_attributes.h"
#include "ra8_decomp_limits.h"
#include "ra8_err.h"
#include "ra8_gfx.h"
#include "ra8_img_arena.h"
#include "ra8_viewer_reader_internal.h"
#include "reflow_image.h"

Include dependency graph for ra8_viewer_comic.c:

Data Structures
struct	viewer_fit_box_t
	Destination rectangle for aspect-preserving page placement. More...

Functions
static void	internal_fit_centered (int32_t source_width, int32_t source_height, int32_t target_width, int32_t target_height, viewer_fit_box_t *box)
	Fit an image into a target while preserving aspect ratio.
static void	internal_cap_render (uint32_t native_width, uint32_t native_height, uint32_t render_width, uint32_t render_height)
	Cap a page to the graphics engine edge limit.
static ra8_err_t	internal_read_page (ra8_viewer_reader_t reader, uint32_t page, size_t out_bytes)
	Extract one bounded encoded page into its resident slice.
static ra8_err_t	internal_probe_page (ra8_viewer_reader_t *reader, uint32_t page)
	Probe one page and publish its bounded render dimensions.
static ra8_err_t	internal_decode (ra8_viewer_reader_t reader, uint32_t page, const viewer_fit_box_t fit)
	Decode one page into the currently selected graphics target.
size_t	priv_viewer_comic_read (void ctx, uint64_t offset, void buffer, size_t length)
	Adapt exact descriptor reads to the comic size-returning seam.
ra8_err_t	priv_viewer_open_comic (ra8_viewer_reader_t *reader)
	Open a bare CBZ/CBR/CBT engine over a bound reader.
ra8_err_t	priv_viewer_size_comic_tiles (ra8_viewer_reader_t *reader)
	Probe every comic page into the bound dimension arrays.
ra8_err_t	priv_viewer_render_comic (ra8_viewer_reader_t *reader, uint32_t page)
	Render one comic page into the fixed framebuffer.
ra8_err_t	priv_viewer_tile_comic (ra8_viewer_reader_t reader, uint32_t index, uint16_t pixels, size_t pixel_bytes, uint32_t width, uint32_t height)
	Render one comic page into caller-owned RGB565 storage.

Detailed Description

Caller-workspace CBZ, CBR, and CBT reader engine.

Extracts one bounded encoded page through comic, probes and decodes it through the caller-bound stb arena, and renders into either the fixed framebuffer or a caller-owned scroll tile. The archive, page index, names, encoded bytes, decode arena, and output pixels never use the heap.

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

Since: 0.1.0

Definition in file ra8_viewer_comic.c.

Function Documentation

◆ internal_cap_render()

void internal_cap_render	(	uint32_t	native_width,
		uint32_t	native_height,
		uint32_t *	render_width,
		uint32_t *	render_height )

static

Cap a page to the graphics engine edge limit.

Applies width and height caps in sequence while preserving aspect.

Parameters

[in]	native_width	Positive source width.
[in]	native_height	Positive source height.
[out]	render_width	Capped positive width.
[out]	render_height	Capped positive height.

Precondition: Output pointers are writable.; Native dimensions are positive.

Postcondition: Both outputs are within k_ra8_gfx_max_dim.; The output aspect follows the source to integer precision.

Note: Pure apart from the outputs.

Since: 0.1.0

Definition at line 89 of file ra8_viewer_comic.c.

References k_ra8_gfx_max_dim, and RA8_INTERNAL.

Referenced by internal_probe_page().

◆ internal_decode()

ra8_err_t internal_decode	(	ra8_viewer_reader_t *	reader,
		uint32_t	page,
		const viewer_fit_box_t *	fit )

static

Decode one page into the currently selected graphics target.

Re-extracts the encoded page, clears the target white, then invokes the zero-heap image decoder over the bound arena and requested fit rectangle.

Parameters

[in,out]	reader	Open comic reader.
[in]	page	Page index.
[in]	fit	Aspect-preserving destination box.

Returns: Decode or graphics status.

Return values

k_ra8_ok	The requested page is present in the graphics target.
k_ra8_err_invalid_size	The encoded page exceeds its bounded slice.

Precondition: The graphics target was initialized for the supplied dimensions.; fit lies inside the target.

Postcondition: Success leaves decoded RGB565 pixels in the current target.; The image arena is unbound on every path.

Note: Not thread-safe; drives global gfx and arena state.

Since: 0.1.0

Definition at line 211 of file ra8_viewer_comic.c.

References viewer_comic_t::arena, viewer_comic_t::arena_cap, ra8_viewer_reader::comic, viewer_fit_box_t::height, internal_read_page(), k_ra8_ok, k_viewer_background, viewer_comic_t::page, ra8_gfx_clear(), ra8_img_decode_blit(), viewer_fit_box_t::width, viewer_fit_box_t::x, and viewer_fit_box_t::y.

Referenced by priv_viewer_render_comic(), and priv_viewer_tile_comic().

◆ internal_fit_centered()

void internal_fit_centered	(	int32_t	source_width,
		int32_t	source_height,
		int32_t	target_width,
		int32_t	target_height,
		viewer_fit_box_t *	box )

static

Fit an image into a target while preserving aspect ratio.

Tries the full target width, falls back to a height fit, and centres the result on both axes with every output edge clamped to at least one pixel.

Parameters

[in]	source_width	Positive source width.
[in]	source_height	Positive source height.
[in]	target_width	Positive target width.
[in]	target_height	Positive target height.
[out]	box	Resulting centred rectangle.

Precondition: box is writable.; Every dimension is positive and fits int32_t.

Postcondition: box lies inside the target.; box preserves the source aspect to integer precision.

Note: Pure apart from box.

Since: 0.1.0

Definition at line 49 of file ra8_viewer_comic.c.

References RA8_INTERNAL.

Referenced by priv_viewer_render_comic().

◆ internal_probe_page()

ra8_err_t internal_probe_page	(	ra8_viewer_reader_t *	reader,
		uint32_t	page )

static

Probe one page and publish its bounded render dimensions.

Extracts only the encoded page, binds the caller arena around the image header probe, validates positive geometry, and applies the gfx cap.

Parameters

[in,out]	reader	Open comic reader.
[in]	page	Page index.

Returns: Probe status.

Return values

k_ra8_ok	Dimension arrays are populated for `page`.
k_ra8_err_invalid_size	The decoded geometry is not positive.

Precondition: reader has bound dimension arrays and comic storage.; page is below the comic page count.

Postcondition: Success publishes positive bounded dimensions.; The decode arena is unbound on every path.

Note: Not thread-safe; drives the shared image arena binding.

Since: 0.1.0

Definition at line 169 of file ra8_viewer_comic.c.

References viewer_comic_t::arena, viewer_comic_t::arena_cap, ra8_viewer_reader::comic, internal_cap_render(), internal_read_page(), k_ra8_err_invalid_size, k_ra8_ok, viewer_comic_t::page, ra8_img_arena_bind(), ra8_img_arena_unbind(), ra8_img_probe_size(), RA8_INTERNAL, ra8_viewer_reader::tile_hpx, and ra8_viewer_reader::tile_wpx.

Referenced by priv_viewer_size_comic_tiles().

◆ internal_read_page()

ra8_err_t internal_read_page	(	ra8_viewer_reader_t *	reader,
		uint32_t	page,
		size_t *	out_bytes )

static

Extract one bounded encoded page into its resident slice.

Checks the shared output/ratio policy and the viewer's explicit page capacity before asking the container backend to copy or decompress bytes.

Parameters

[in,out]	reader	Open comic reader.
[in]	page	Page index.
[out]	out_bytes	Exact extracted byte count.

Returns: Extraction status.

Return values

k_ra8_ok	The resident page slice is populated.
k_ra8_err_invalid_size	The page exceeds the explicit resident cap.

Precondition: reader owns an open comic and page is in range.; out_bytes is writable.

Postcondition: Success publishes no more than reader->comic.page_cap bytes.; Failure performs no unbounded allocation.

Note: Not thread-safe; reuses the resident page slice.

Since: 0.1.0

Definition at line 127 of file ra8_viewer_comic.c.

References viewer_comic_t::archive, ra8_viewer_reader::comic, comic_page_info(), comic_page_read(), ra8_viewer_reader::file, k_ra8_err_invalid_size, k_ra8_ok, ra8_viewer_reader::limits, viewer_comic_t::page, viewer_comic_t::page_cap, ra8_decomp_check_declared(), and viewer_file_ctx_t::size.

Referenced by internal_decode(), and internal_probe_page().

◆ priv_viewer_comic_read()

size_t priv_viewer_comic_read	(	void *	ctx,
		uint64_t	offset,
		void *	buffer,
		size_t	length )

Adapt exact descriptor reads to the comic size-returning seam.

Delegates to the reader's positional I/O contract and converts a successful exact read to its byte count, while every failure becomes zero.

Parameters

[in]	ctx	Bound viewer_file_ctx_t.
[in]	offset	Absolute source offset.
[out]	buffer	Destination for exactly `length` bytes.
[in]	length	Requested byte count.

Returns: Exact bytes read or zero on any descriptor/read failure.

Return values

0	The positional read failed or could not complete exactly.

Precondition: ctx is non-NULL and names an open viewer descriptor.; buffer spans length writable bytes when length is non-zero.

Postcondition: Success initializes exactly length destination bytes.; Failure publishes no partial byte count to the comic facade.

Note: Not thread-safe; shares descriptor state with the reader.

Since: 0.1.0

Definition at line 233 of file ra8_viewer_comic.c.

References k_ra8_ok, and priv_viewer_pread().

Referenced by priv_viewer_open_comic().

◆ priv_viewer_open_comic()

ra8_err_t priv_viewer_open_comic ( ra8_viewer_reader_t * reader )

nodiscard

Open a bare CBZ/CBR/CBT engine over a bound reader.

Definition at line 239 of file ra8_viewer_comic.c.

References viewer_comic_t::archive, ra8_viewer_reader::comic, comic_open(), ra8_viewer_reader::file, k_viewer_comic_name_bytes, k_viewer_comic_page_cap, viewer_comic_t::names, viewer_comic_t::pages, priv_viewer_comic_read(), and viewer_file_ctx_t::size.

Referenced by internal_open_selected().

◆ priv_viewer_render_comic()

ra8_err_t priv_viewer_render_comic	(	ra8_viewer_reader_t *	reader,
		uint32_t	page )

nodiscard

Render one comic page into the fixed framebuffer.

Definition at line 262 of file ra8_viewer_comic.c.

References ra8_viewer_reader::fb, internal_decode(), internal_fit_centered(), k_ra8_gfx_format_rgb565, k_ra8_ok, k_ra8_viewer_fb_height, k_ra8_viewer_fb_width, ra8_gfx_init(), ra8_viewer_reader::tile_hpx, and ra8_viewer_reader::tile_wpx.

Referenced by ra8_viewer_render_page().

◆ priv_viewer_size_comic_tiles()

ra8_err_t priv_viewer_size_comic_tiles ( ra8_viewer_reader_t * reader )

nodiscard

Probe every comic page into the bound dimension arrays.

Definition at line 251 of file ra8_viewer_comic.c.

References internal_probe_page(), k_ra8_ok, and ra8_viewer_reader::tile_n.

Referenced by internal_open_selected().

◆ priv_viewer_tile_comic()

ra8_err_t priv_viewer_tile_comic	(	ra8_viewer_reader_t *	reader,
		uint32_t	index,
		uint16_t *	pixels,
		size_t	pixel_bytes,
		uint32_t *	width,
		uint32_t *	height )

nodiscard

Render one comic page into caller-owned RGB565 storage.

Definition at line 279 of file ra8_viewer_comic.c.

References ra8_viewer_reader::fb, internal_decode(), k_ra8_err_invalid_size, k_ra8_gfx_format_rgb565, k_ra8_ok, k_ra8_viewer_fb_height, k_ra8_viewer_fb_width, ra8_gfx_init(), ra8_viewer_reader::tile_hpx, and ra8_viewer_reader::tile_wpx.

Referenced by ra8_viewer_render_tile565().

Data Structures

Functions

Detailed Description

Function Documentation

◆ internal_cap_render()

◆ internal_decode()

◆ internal_fit_centered()

◆ internal_probe_page()

◆ internal_read_page()

◆ priv_viewer_comic_read()

◆ priv_viewer_open_comic()

◆ priv_viewer_render_comic()

◆ priv_viewer_size_comic_tiles()

◆ priv_viewer_tile_comic()