Caller-owned host JOF/comic reader and RGB565 render surface. More...

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

Include dependency graph for ra8_viewer_reader.h:

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

Data Structures
struct	ra8_viewer_reader_requirements_t
	Exact immutable layout returned for one document. More...
struct	ra8_viewer_workspace_report_t
	Required-versus-supplied evidence from a bind attempt. More...

Typedefs
typedef struct ra8_viewer_reader	ra8_viewer_reader_t
	Opaque state bound inside caller-owned workspace.

Enumerations
enum	ra8_viewer_geom_t : uint16_t { k_ra8_viewer_fb_width = 720U , k_ra8_viewer_fb_height = 1080U }
	Fixed framebuffer geometry used by headless page rendering. More...
enum	ra8_viewer_reader_engine_t : uint32_t { k_ra8_viewer_engine_jof = 1U , k_ra8_viewer_engine_comic = 2U }
	Reader engine selected by the requirements query. More...

Functions
ra8_err_t	ra8_viewer_reader_requirements (const char path, ra8_viewer_reader_requirements_t out)
	Inspect `path` and calculate its exact reader workspace.
ra8_err_t	ra8_viewer_reader_bind (ra8_viewer_reader_t *out, void workspace, size_t workspace_bytes, const ra8_viewer_reader_requirements_t requirements, ra8_viewer_workspace_report_t report)
	Bind one reader state to caller-owned bytes.
ra8_err_t	ra8_viewer_open (ra8_viewer_reader_t reader, const char path)
	Open the document class used to size and bind `reader`.
uint32_t	ra8_viewer_page_count (const ra8_viewer_reader_t *reader)
	Number of viewport pages in `reader`, or zero for NULL/closed.
ra8_err_t	ra8_viewer_render_page (ra8_viewer_reader_t *reader, uint32_t page)
	Render one page into the reader's fixed RGB565 framebuffer.
uint32_t	ra8_viewer_tile_count (const ra8_viewer_reader_t *reader)
	Number of scroll tiles in `reader`, or zero for NULL/closed.
ra8_err_t	ra8_viewer_tile_size (const ra8_viewer_reader_t reader, uint32_t index, uint32_t width, uint32_t *height)
	Read native dimensions for tile `index`.
ra8_err_t	ra8_viewer_tile_requirements (const ra8_viewer_reader_t reader, uint32_t index, size_t out_bytes, size_t *out_alignment)
	Report exact caller storage needed to render tile `index`.
ra8_err_t	ra8_viewer_render_tile565 (ra8_viewer_reader_t reader, uint32_t index, void workspace, size_t workspace_bytes, uint32_t width, uint32_t height, uint16_t *out_pixels, ra8_viewer_workspace_report_t report)
	Render tile `index` into caller-owned RGB565 storage.
ra8_err_t	ra8_viewer_dump_ppm (const ra8_viewer_reader_t reader, const char path)
	Write the current fixed framebuffer as binary PPM.
ra8_err_t	ra8_viewer_write_ppm565 (const uint16_t px, uint32_t w, uint32_t h, const char path)
	Write arbitrary caller-owned RGB565 pixels as binary PPM.
uint16_t	ra8_viewer_pack565 (uint8_t rr, uint8_t gg, uint8_t bb)
	Pack 8-bit RGB channels into one RGB565 word.
uint16_t	ra8_viewer_pack565_le_pair (uint8_t low, uint8_t high)
	Reassemble one little-endian RGB565 word.
void	ra8_viewer_close (ra8_viewer_reader_t *reader)
	Close the descriptor and reset reader state without freeing workspace.

Detailed Description

Caller-owned host JOF/comic reader and RGB565 render surface.

The reader is deliberately storage- and allocator-agnostic below its POSIX composition edge. A format-aware requirements query reports the exact bytes and alignment needed by one JOF or bare CBZ/CBR/CBT document; bind partitions caller-owned storage; open attaches a raw descriptor behind a positional-read callback. No reusable reader function owns dynamic memory or exposes a hosted stream type. Comic decoding uses explicit bounded slices for its page index, name arena, resident encoded page, and stb decode arena. Gzip/XZ-wrapped comics remain unsupported because the shared wrapper API still requires the complete unwrapped archive to be resident at once.

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

Since: 0.1.0

Definition in file ra8_viewer_reader.h.

Typedef Documentation

◆ ra8_viewer_reader_t

typedef struct ra8_viewer_reader ra8_viewer_reader_t

Opaque state bound inside caller-owned workspace.

Definition at line 37 of file ra8_viewer_reader.h.

Enumeration Type Documentation

◆ ra8_viewer_geom_t

enum ra8_viewer_geom_t : uint16_t

Fixed framebuffer geometry used by headless page rendering.

Enumerator
k_ra8_viewer_fb_width	Framebuffer width in pixels.
k_ra8_viewer_fb_height	Framebuffer height in pixels.

Definition at line 31 of file ra8_viewer_reader.h.

◆ ra8_viewer_reader_engine_t

enum ra8_viewer_reader_engine_t : uint32_t

Reader engine selected by the requirements query.

Enumerator
k_ra8_viewer_engine_jof	Streamed JOF long-strip engine.
k_ra8_viewer_engine_comic	Bare CBZ/CBR/CBT comic engine.

Definition at line 40 of file ra8_viewer_reader.h.

Function Documentation

◆ ra8_viewer_close()

void ra8_viewer_close ( ra8_viewer_reader_t * reader )

Close the descriptor and reset reader state without freeing workspace.

Releases only the owned raw descriptor and restores the fixed target.

Parameters

[in,out] reader Bound reader, or NULL.

Precondition: reader is NULL or came from a successful bind.; No render operation is in progress.

Postcondition: Borrowed workspace remains caller-owned and reusable.; A non-NULL reader is closed and reports zero pages.

Note: Safe on NULL; not thread-safe for a shared reader.

Since: 0.1.0

Definition at line 832 of file ra8_viewer_reader.c.

References viewer_comic_t::archive, ra8_viewer_reader::comic, comic_close(), ra8_viewer_reader::engine, ra8_viewer_reader::fb, viewer_file_ctx_t::fd, ra8_viewer_reader::file, ra8_viewer_reader::is_open, viewer_file_ctx_t::is_open, k_ra8_viewer_engine_comic, k_ra8_viewer_fb_height, k_ra8_viewer_fb_width, ra8_viewer_reader::rt565, ra8_viewer_reader::rt_h, ra8_viewer_reader::rt_w, and ra8_viewer_reader::tile_n.

Referenced by main().

◆ ra8_viewer_dump_ppm()

ra8_err_t ra8_viewer_dump_ppm	(	const ra8_viewer_reader_t *	reader,
		const char *	path )

nodiscard

Write the current fixed framebuffer as binary PPM.

Definition at line 263 of file ra8_viewer_ppm.c.

References ra8_viewer_reader::fb, k_ra8_err_null_ptr, k_ra8_viewer_fb_height, k_ra8_viewer_fb_width, and ra8_viewer_write_ppm565().

Referenced by internal_render_page().

◆ ra8_viewer_open()

ra8_err_t ra8_viewer_open	(	ra8_viewer_reader_t *	reader,
		const char *	path )

nodiscard

Open the document class used to size and bind reader.

Parameters

[in,out]	reader	Bound, closed reader.
[in]	path	NUL-terminated JOF or bare comic path.

Returns: k_ra8_ok on success or a propagated parse/open error.

Return values

k_ra8_ok	The descriptor and selected reader engine are open.
k_ra8_err_null_ptr	A required pointer was NULL.
k_ra8_err_invalid_state	The reader is unbound or already open.
k_ra8_err_not_supported	`path` does not match the bound engine.

Postcondition: Failure leaves reader closed.

Note: The reader owns only its raw descriptor; all memory remains borrowed.

Definition at line 701 of file ra8_viewer_reader.c.

References viewer_comic_t::archive, ra8_viewer_reader::comic, comic_close(), ra8_viewer_reader::engine, viewer_file_ctx_t::fd, ra8_viewer_reader::file, internal_classify(), internal_engine_matches(), internal_file_open(), internal_open_selected(), ra8_viewer_reader::is_bound, ra8_viewer_reader::is_open, viewer_file_ctx_t::is_open, k_ra8_err_invalid_state, k_ra8_err_null_ptr, k_ra8_ok, k_ra8_viewer_engine_comic, and ra8_viewer_reader::tile_n.

Referenced by main().

◆ ra8_viewer_pack565()

uint16_t ra8_viewer_pack565	(	uint8_t	rr,
		uint8_t	gg,
		uint8_t	bb )

nodiscard

Pack 8-bit RGB channels into one RGB565 word.

Definition at line 87 of file ra8_viewer_ppm.c.

References k_rgb565_g6_drop, k_rgb565_g_shift, k_rgb565_r5_drop, and k_rgb565_r_shift.

Referenced by internal_band_pixel().

◆ ra8_viewer_pack565_le_pair()

uint16_t ra8_viewer_pack565_le_pair	(	uint8_t	low,
		uint8_t	high )

nodiscard

Reassemble one little-endian RGB565 word.

Definition at line 95 of file ra8_viewer_ppm.c.

References k_rgb565_hi_shift.

Referenced by internal_band_pixel().

◆ ra8_viewer_page_count()

uint32_t ra8_viewer_page_count ( const ra8_viewer_reader_t * reader )

nodiscard

Number of viewport pages in reader, or zero for NULL/closed.

Definition at line 732 of file ra8_viewer_reader.c.

References ra8_viewer_reader::is_open, and ra8_viewer_reader::tile_n.

Referenced by main(), and ra8_viewer_tile_count().

◆ ra8_viewer_reader_bind()

ra8_err_t ra8_viewer_reader_bind	(	ra8_viewer_reader_t **	out,
		void *	workspace,
		size_t	workspace_bytes,
		const ra8_viewer_reader_requirements_t *	requirements,
		ra8_viewer_workspace_report_t *	report )

nodiscard

Bind one reader state to caller-owned bytes.

Parameters

[out]	out	Receives the bound reader.
[in,out]	workspace	Aligned caller-owned backing.
[in]	workspace_bytes	Accessible backing extent.
[in]	requirements	Unmodified successful requirements result.
[out]	report	Exact required/supplied sizes, including on failure.

Returns: k_ra8_ok on success.

Return values

k_ra8_ok	The workspace was partitioned and `out` published.
k_ra8_err_null_ptr	A required pointer was NULL.
k_ra8_err_invalid_size	The layout, alignment, or capacity is invalid.

Postcondition: Failure leaves out NULL and does not mutate workspace bytes.; Success publishes a closed reader borrowing workspace.

Definition at line 576 of file ra8_viewer_reader.c.

References ra8_viewer_reader_requirements_t::dimensions_bytes, ra8_viewer_reader_requirements_t::engine, ra8_viewer_reader_requirements_t::framebuffer_bytes, internal_requirements_valid(), internal_take(), internal_take_comic(), internal_take_jof(), k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_ok, k_ra8_viewer_engine_jof, k_ra8_viewer_fb_height, k_ra8_viewer_fb_width, ra8_decomp_limits_default(), ra8_viewer_reader_requirements_t::required_alignment, ra8_viewer_reader_requirements_t::required_bytes, ra8_viewer_reader_requirements_t::tile_count, viewer_layout_t::used, and viewer_layout_t::valid.

Referenced by main().

◆ ra8_viewer_reader_requirements()

ra8_err_t ra8_viewer_reader_requirements	(	const char *	path,
		ra8_viewer_reader_requirements_t *	out )

nodiscard

Inspect path and calculate its exact reader workspace.

Parameters

[in]	path	NUL-terminated host path.
[out]	out	Exact requirements on success.

Returns: k_ra8_ok on success; an error for I/O, unsupported format, or an invalid document geometry.

Return values

k_ra8_ok	Requirements are complete.
k_ra8_err_null_ptr	A required pointer was NULL.
k_ra8_err_not_found	The input is absent, empty, or not regular.
k_ra8_err_not_supported	The format is wrapped, reflow, or unknown.

Postcondition: On failure out is zeroed.

Note: The sizing descriptor opened internally is closed before return.

Definition at line 537 of file ra8_viewer_reader.c.

References ra8_viewer_reader_requirements_t::framebuffer_bytes, internal_classify(), internal_file_open(), internal_layout(), internal_reject(), internal_require_comic(), internal_require_jof(), k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_ok, k_ra8_viewer_fb_height, k_ra8_viewer_fb_width, k_viewer_fmt_comic, k_viewer_fmt_jof, k_viewer_layout_version, ra8_viewer_reader_requirements_t::layout_version, ra8_viewer_reader_requirements_t::required_alignment, ra8_viewer_reader_requirements_t::required_bytes, viewer_layout_t::used, and viewer_layout_t::valid.

Referenced by main().

◆ ra8_viewer_render_page()

ra8_err_t ra8_viewer_render_page	(	ra8_viewer_reader_t *	reader,
		uint32_t	page )

nodiscard

Render one page into the reader's fixed RGB565 framebuffer.

Parameters

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

Returns: Render status.

Definition at line 737 of file ra8_viewer_reader.c.

References ra8_viewer_reader::engine, ra8_viewer_reader::is_open, k_ra8_err_invalid_state, k_ra8_err_null_ptr, k_ra8_err_out_of_range, k_ra8_viewer_engine_comic, priv_viewer_render_comic(), priv_viewer_render_jof(), and ra8_viewer_reader::tile_n.

Referenced by internal_render_page().

◆ ra8_viewer_render_tile565()

ra8_err_t ra8_viewer_render_tile565	(	ra8_viewer_reader_t *	reader,
		uint32_t	index,
		void *	workspace,
		size_t	workspace_bytes,
		uint32_t *	width,
		uint32_t *	height,
		uint16_t **	out_pixels,
		ra8_viewer_workspace_report_t *	report )

nodiscard

Render tile index into caller-owned RGB565 storage.

Parameters

[in,out]	reader	Open reader.
[in]	index	Tile index.
[in,out]	workspace	Caller output backing.
[in]	workspace_bytes	Accessible backing extent.
[out]	width	Rendered width.
[out]	height	Rendered height.
[out]	out_pixels	Aliases `workspace` on success.
[out]	report	Exact required/supplied sizes.

Returns: Render status.

Postcondition: Failure leaves out_pixels NULL and restores the fixed target.

Definition at line 796 of file ra8_viewer_reader.c.

References ra8_viewer_reader::engine, k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_ok, k_ra8_viewer_engine_comic, priv_viewer_tile_comic(), priv_viewer_tile_jof(), and ra8_viewer_tile_requirements().

Referenced by internal_dump_tile().

◆ ra8_viewer_tile_count()

uint32_t ra8_viewer_tile_count ( const ra8_viewer_reader_t * reader )

nodiscard

Number of scroll tiles in reader, or zero for NULL/closed.

Definition at line 753 of file ra8_viewer_reader.c.

References ra8_viewer_page_count().

◆ ra8_viewer_tile_requirements()

ra8_err_t ra8_viewer_tile_requirements	(	const ra8_viewer_reader_t *	reader,
		uint32_t	index,
		size_t *	out_bytes,
		size_t *	out_alignment )

nodiscard

Report exact caller storage needed to render tile index.

Parameters

[in]	reader	Open reader.
[in]	index	Tile index.
[out]	out_bytes	Required RGB565 bytes.
[out]	out_alignment	Required base alignment.

Returns: k_ra8_ok on success.

Definition at line 777 of file ra8_viewer_reader.c.

References k_ra8_err_null_ptr, k_ra8_ok, and ra8_viewer_tile_size().

Referenced by ra8_viewer_render_tile565().

◆ ra8_viewer_tile_size()

ra8_err_t ra8_viewer_tile_size	(	const ra8_viewer_reader_t *	reader,
		uint32_t	index,
		uint32_t *	width,
		uint32_t *	height )

nodiscard

Read native dimensions for tile index.

Definition at line 758 of file ra8_viewer_reader.c.

References ra8_viewer_reader::is_open, k_ra8_err_invalid_state, k_ra8_err_null_ptr, k_ra8_err_out_of_range, k_ra8_ok, ra8_viewer_reader::tile_hpx, ra8_viewer_reader::tile_n, and ra8_viewer_reader::tile_wpx.

Referenced by ra8_viewer_tile_requirements().

◆ ra8_viewer_write_ppm565()

ra8_err_t ra8_viewer_write_ppm565	(	const uint16_t *	px,
		uint32_t	w,
		uint32_t	h,
		const char *	path )

nodiscard

Write arbitrary caller-owned RGB565 pixels as binary PPM.

Definition at line 227 of file ra8_viewer_ppm.c.

References internal_ppm_header(), internal_unpack565(), internal_write_all(), k_ppm_channels, k_ppm_chunk_bytes, k_ppm_chunk_pixels, k_ppm_file_mode, k_ppm_header_bytes, k_ra8_err_invalid_size, k_ra8_err_not_found, k_ra8_err_null_ptr, k_ra8_ok, and O_CLOEXEC.

Referenced by internal_dump_tile(), and ra8_viewer_dump_ppm().

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ ra8_viewer_reader_t

Enumeration Type Documentation

◆ ra8_viewer_geom_t

◆ ra8_viewer_reader_engine_t

Function Documentation

◆ ra8_viewer_close()

◆ ra8_viewer_dump_ppm()

◆ ra8_viewer_open()

◆ ra8_viewer_pack565()

◆ ra8_viewer_pack565_le_pair()

◆ ra8_viewer_page_count()

◆ ra8_viewer_reader_bind()

◆ ra8_viewer_reader_requirements()

◆ ra8_viewer_render_page()

◆ ra8_viewer_render_tile565()

◆ ra8_viewer_tile_count()

◆ ra8_viewer_tile_requirements()

◆ ra8_viewer_tile_size()

◆ ra8_viewer_write_ppm565()