Requirements, workspace binding, descriptor lifecycle, and dispatch. More...

#include "ra8_viewer_reader.h"
#include <errno.h>
#include <fcntl.h>
#include <limits.h>
#include <stdalign.h>
#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include <sys/stat.h>
#include <unistd.h>
#include "jof.h"
#include "ra8_attributes.h"
#include "ra8_decomp_limits.h"
#include "ra8_err.h"
#include "ra8_viewer_reader_internal.h"

Include dependency graph for ra8_viewer_reader.c:

Data Structures
struct	viewer_layout_t
	Mutable cursor used to calculate or bind one aligned layout. More...

Macros
#define	O_CLOEXEC (0)
	No-op close-on-exec fallback for hosts lacking the flag.

Enumerations
enum	viewer_fmt_t : uint8_t { k_viewer_fmt_unknown = 0U , k_viewer_fmt_jof = 1U , k_viewer_fmt_comic = 2U , k_viewer_fmt_comic_wrap = 3U , k_viewer_fmt_reflow = 4U }
	Recognised filename classes at the host composition edge. More...

Functions
static bool	internal_align_up (size_t value, size_t alignment, size_t *out)
	Align `value` upward with overflow rejection.
static void *	internal_take (viewer_layout_t *layout, size_t bytes, size_t alignment)
	Take one aligned layout slice, or only charge it while sizing.
static viewer_jof_t	internal_take_jof (viewer_layout_t layout, const ra8_viewer_reader_requirements_t requirements)
	Take the complete JOF-specific workspace tail.
static viewer_comic_t	internal_take_comic (viewer_layout_t layout, const ra8_viewer_reader_requirements_t requirements)
	Take the complete comic-specific workspace tail.
static bool	internal_ends_with (const char path, const char suffix)
	Test one case-insensitive ASCII filename suffix.
static viewer_fmt_t	internal_classify (const char *path)
	Classify a path without opening it.
static void	internal_stderr_write (const char *text)
	Best-effort exact diagnostic fragment over standard error.
static ra8_err_t	internal_reject (viewer_fmt_t format, const char *path)
	Emit the truthful unsupported-format reason.
static ra8_err_t	internal_file_open (viewer_file_ctx_t file, const char path)
	Open and size one non-empty regular host file.
ra8_err_t	priv_viewer_pread (void ctx, uint64_t offset, uint8_t buffer, size_t length, size_t *out_read)
	JOF positional-reader seam over viewer_file_ctx_t.
static viewer_layout_t	internal_layout (const ra8_viewer_reader_requirements_t need, uint8_t base, size_t capacity)
	Charge the complete deterministic reader layout.
static bool	internal_engine_requirements_valid (const ra8_viewer_reader_requirements_t *need)
	Validate engine-specific requirement fields.
static bool	internal_requirements_valid (const ra8_viewer_reader_requirements_t *need)
	Validate a requirements object before workspace mutation.
static ra8_err_t	internal_require_jof (viewer_file_ctx_t file, ra8_viewer_reader_requirements_t out)
	Populate JOF-specific requirements from one open descriptor.
static void	internal_require_comic (ra8_viewer_reader_requirements_t *out)
	Populate the fixed bounded bare-comic requirements shape.
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.
static ra8_err_t	internal_open_selected (ra8_viewer_reader_t *reader)
	Open and size the reader's selected engine.
static bool	internal_engine_matches (const ra8_viewer_reader_t *reader, viewer_fmt_t format)
	Whether a path class matches the engine frozen at bind time.
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.
void	ra8_viewer_close (ra8_viewer_reader_t *reader)
	Close the descriptor and reset reader state without freeing workspace.

Detailed Description

Requirements, workspace binding, descriptor lifecycle, and dispatch.

Implements the JOF/bare-comic requirements-to-bind lifecycle and keeps host descriptor ownership at this composition edge.

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

Since: 0.1.0

Definition in file ra8_viewer_reader.c.

Macro Definition Documentation

◆ O_CLOEXEC

#define O_CLOEXEC (0)

No-op close-on-exec fallback for hosts lacking the flag.

Definition at line 31 of file ra8_viewer_reader.c.

Enumeration Type Documentation

◆ viewer_fmt_t

enum viewer_fmt_t : uint8_t

Recognised filename classes at the host composition edge.

Enumerator
k_viewer_fmt_unknown	Unrecognised extension.
k_viewer_fmt_jof	Supported streamed JOF.
k_viewer_fmt_comic	Supported bare CBZ/CBR/CBT.
k_viewer_fmt_comic_wrap	Gzip/XZ whole-output seam remains.
k_viewer_fmt_reflow	EPUB/RABOOK engine not wired.

Definition at line 35 of file ra8_viewer_reader.c.

Function Documentation

◆ internal_align_up()

bool internal_align_up	(	size_t	value,
		size_t	alignment,
		size_t *	out )

static

Align value upward with overflow rejection.

Accepts power-of-two alignments and checks the rounding addition.

Parameters

[in]	value	Unaligned extent.
[in]	alignment	Required alignment.
[out]	out	Aligned result.

Returns: Whether rounding succeeded.

Return values

true	`out` is populated.
false	Alignment was invalid or overflowed.

Precondition: out is writable.; value is a workspace-relative extent.

Postcondition: Success publishes a result no smaller than value.; Failure mutates no workspace bytes.

Note: Pure apart from out.

Since: 0.1.0

Definition at line 67 of file ra8_viewer_reader.c.

References RA8_INTERNAL.

Referenced by internal_take().

◆ internal_classify()

viewer_fmt_t internal_classify ( const char * path )

static

Classify a path without opening it.

Recognises JOF, comic/wrapper, and reflow extension families.

Parameters

[in] path NUL-terminated path.

Returns: Recognised filename class.

Return values

k_viewer_fmt_unknown No recognised extension matched.

Precondition: path is non-NULL.; path is NUL-terminated.

Postcondition: No descriptor is opened.; No state is mutated.

Note: Pure and thread-safe.

Since: 0.1.0

Definition at line 224 of file ra8_viewer_reader.c.

References internal_ends_with(), k_viewer_fmt_comic, k_viewer_fmt_comic_wrap, k_viewer_fmt_jof, k_viewer_fmt_reflow, k_viewer_fmt_unknown, and RA8_INTERNAL.

Referenced by ra8_viewer_open(), and ra8_viewer_reader_requirements().

◆ internal_ends_with()

bool internal_ends_with	(	const char *	path,
		const char *	suffix )

static

Test one case-insensitive ASCII filename suffix.

Folds only ASCII uppercase characters in the path tail.

Parameters

[in]	path	NUL-terminated path.
[in]	suffix	Lowercase NUL-terminated suffix.

Returns: Whether the suffix matches.

Return values

true	The path ends with `suffix` ignoring ASCII case.
false	It is shorter or differs.

Precondition: path is non-NULL and terminated.; suffix is non-NULL, lowercase, and terminated.

Postcondition: No state is mutated.; The result depends only on inputs.

Note: Pure and thread-safe.

Since: 0.1.0

Definition at line 191 of file ra8_viewer_reader.c.

References RA8_INTERNAL, and strlen().

Referenced by internal_classify().

◆ internal_engine_matches()

bool internal_engine_matches	(	const ra8_viewer_reader_t *	reader,
		viewer_fmt_t	format )

static

Whether a path class matches the engine frozen at bind time.

Prevents a requirements object calculated for one engine from being reused to open a differently laid-out document.

Parameters

[in]	reader	Bound reader.
[in]	format	Classified requested path.

Returns: Whether the pair is compatible.

Return values

true	The path and workspace select the same engine.
false	They differ or the engine is unknown.

Precondition: reader is non-NULL and bound.; format came from internal_classify.

Postcondition: No state is mutated.; A wrapped or reflow format never matches.

Note: Pure and thread-safe.

Since: 0.1.0

Definition at line 693 of file ra8_viewer_reader.c.

References ra8_viewer_reader::engine, k_ra8_viewer_engine_comic, k_ra8_viewer_engine_jof, k_viewer_fmt_comic, k_viewer_fmt_jof, and RA8_INTERNAL.

Referenced by ra8_viewer_open().

◆ internal_engine_requirements_valid()

bool internal_engine_requirements_valid ( const ra8_viewer_reader_requirements_t * need )

static

Validate engine-specific requirement fields.

Requires exact fixed comic capacities or mutually exclusive JOF slices.

Parameters

[in] need Candidate requirements object.

Returns: Whether its selected engine fields are canonical.

Return values

true	The engine and all exclusive fields match policy.
false	The object is stale, forged, or internally inconsistent.

Precondition: need is non-NULL.; Common fields are checked separately.

Postcondition: No state is mutated.; Exactly one engine shape can pass.

Note: Pure and thread-safe.

Since: 0.1.0

Definition at line 425 of file ra8_viewer_reader.c.

Referenced by internal_requirements_valid().

◆ internal_file_open()

ra8_err_t internal_file_open	(	viewer_file_ctx_t *	file,
		const char *	path )

static

Open and size one non-empty regular host file.

Acquires a close-on-exec descriptor and records its stat size.

Parameters

[out]	file	Descriptor context.
[in]	path	NUL-terminated host path.

Returns: Open status.

Return values

k_ra8_ok	A non-empty regular file is owned by `file`.
k_ra8_err_not_found	Open or validation failed.

Precondition: file is writable.; path is non-NULL and terminated.

Postcondition: Success publishes one owned descriptor.; Failure leaves no acquired descriptor.

Note: The caller must close success.

Since: 0.1.0

Definition at line 316 of file ra8_viewer_reader.c.

References k_ra8_err_not_found, k_ra8_ok, O_CLOEXEC, and RA8_INTERNAL.

Referenced by ra8_viewer_open(), and ra8_viewer_reader_requirements().

◆ internal_layout()

viewer_layout_t internal_layout	(	const ra8_viewer_reader_requirements_t *	need,
		uint8_t *	base,
		size_t	capacity )

static

Charge the complete deterministic reader layout.

Walks common state then the selected JOF or comic engine tail.

Parameters

[in]	need	Valid requirements fields.
[in,out]	base	Backing base, or NULL for sizing only.
[in]	capacity	Accessible extent when `base` is non-NULL.

Returns: Completed layout cursor.

Return values

viewer_layout_t Cursor with valid false on any failure.

Precondition: need is non-NULL.; base is aligned when non-NULL.

Postcondition: Sizing mode mutates no bytes.; Binding mode only calculates addresses; callers publish later.

Note: Pure in sizing mode.

Since: 0.1.0

Definition at line 392 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_take(), internal_take_comic(), internal_take_jof(), k_ra8_viewer_engine_comic, k_ra8_viewer_engine_jof, and viewer_layout_t::valid.

Referenced by internal_requirements_valid(), and ra8_viewer_reader_requirements().

◆ internal_open_selected()

ra8_err_t internal_open_selected ( ra8_viewer_reader_t * reader )

static

Open and size the reader's selected engine.

Dispatches only from the immutable engine recorded at bind time and populates the common tile count/dimension arrays before publication.

Parameters

[in,out] reader Bound reader with an open descriptor.

Returns: Engine open, geometry, or capacity status.

Return values

k_ra8_ok	The selected engine and all tile dimensions are ready.
k_ra8_err_invalid_state	The bound engine is unknown.

Precondition: reader->file is open and matches the bound engine's path class.; Every engine-specific workspace slice is bound.

Postcondition: Success publishes a non-zero tile count no greater than tile capacity.; Failure leaves reader->is_open false.

Note: Not thread-safe; drives the selected parser.

Since: 0.1.0

Definition at line 646 of file ra8_viewer_reader.c.

References viewer_comic_t::archive, ra8_viewer_reader::comic, comic_page_count(), viewer_jof_t::dctx, ra8_viewer_reader::engine, jof_info_t::height, longstrip_decode_ctx_t::info, ra8_viewer_reader::jof, k_ra8_err_invalid_size, k_ra8_err_invalid_state, k_ra8_ok, k_ra8_viewer_engine_comic, k_ra8_viewer_engine_jof, k_ra8_viewer_fb_height, priv_viewer_open_comic(), priv_viewer_open_jof(), priv_viewer_size_comic_tiles(), priv_viewer_size_jof_tiles(), RA8_INTERNAL, ra8_viewer_reader::tile_cap, and ra8_viewer_reader::tile_n.

Referenced by ra8_viewer_open().

◆ internal_reject()

ra8_err_t internal_reject	(	viewer_fmt_t	format,
		const char *	path )

static

Emit the truthful unsupported-format reason.

Distinguishes codec-contract, reflow-wiring, and unknown formats.

Parameters

[in]	format	Classified path family.
[in]	path	NUL-terminated path for the diagnostic.

Returns: Always unsupported.

Return values

k_ra8_err_not_supported The format cannot open in this checkpoint.

Precondition: path is non-NULL and terminated.; format came from internal_classify.

Postcondition: A reason naming path was attempted.; No reader state is mutated.

Note: Descriptor output is best-effort.

Since: 0.1.0

Definition at line 284 of file ra8_viewer_reader.c.

References internal_stderr_write(), k_ra8_err_not_supported, k_viewer_fmt_comic_wrap, k_viewer_fmt_reflow, and RA8_INTERNAL.

Referenced by ra8_viewer_reader_requirements().

◆ internal_require_comic()

void internal_require_comic ( ra8_viewer_reader_requirements_t * out )

static

Populate the fixed bounded bare-comic requirements shape.

Reserves maximum page metadata plus explicit encoded/decode slices; archive parsing happens only after those caller-owned regions are bound.

Parameters

[out] out Requirements object with common fields initialized.

Precondition: out is writable and zero-initialized.; Fixed comic capacities fit size_t.

Postcondition: A canonical comic engine shape is published.; No file bytes or workspace bytes are touched.

Note: Pure apart from out.

Since: 0.1.0

Definition at line 526 of file ra8_viewer_reader.c.

References ra8_viewer_reader_requirements_t::comic_arena_bytes, ra8_viewer_reader_requirements_t::comic_names_bytes, ra8_viewer_reader_requirements_t::comic_page_bytes, ra8_viewer_reader_requirements_t::comic_pages_bytes, ra8_viewer_reader_requirements_t::dimensions_bytes, ra8_viewer_reader_requirements_t::engine, k_ra8_viewer_engine_comic, k_viewer_comic_arena_bytes, k_viewer_comic_name_bytes, k_viewer_comic_page_bytes, k_viewer_comic_page_cap, RA8_INTERNAL, and ra8_viewer_reader_requirements_t::tile_count.

Referenced by ra8_viewer_reader_requirements().

◆ internal_require_jof()

ra8_err_t internal_require_jof	(	viewer_file_ctx_t *	file,
		ra8_viewer_reader_requirements_t *	out )

static

Populate JOF-specific requirements from one open descriptor.

Parses geometry, validates the declared decoded band, and sizes one cache cell plus the exact compressed-band staging bound.

Parameters

[in,out]	file	Open regular JOF descriptor.
[out]	out	Requirements object with common fields initialized.

Returns: Parse or geometry status.

Return values

k_ra8_ok	Canonical JOF requirements were published.
k_ra8_err_invalid_size	Decoded band geometry is invalid.

Precondition: file is open and non-empty.; out is writable and zero-initialized.

Postcondition: Success publishes a canonical JOF engine shape.; Failure acquires no memory or descriptor.

Note: The caller retains descriptor ownership.

Since: 0.1.0

Definition at line 487 of file ra8_viewer_reader.c.

References jof_info_t::bpp, ra8_viewer_reader_requirements_t::cell_bytes, jof_info_t::codec, ra8_viewer_reader_requirements_t::dimensions_bytes, ra8_viewer_reader_requirements_t::engine, jof_info_t::height, jof_parse(), jof_stored_bound(), k_jof_codec_raw, k_ra8_err_invalid_size, k_ra8_ok, k_ra8_viewer_engine_jof, k_ra8_viewer_fb_height, priv_viewer_pread(), ra8_decomp_check_declared(), ra8_decomp_limits_default(), RA8_INTERNAL, ra8_viewer_reader_requirements_t::scratch_bytes, ra8_viewer_reader_requirements_t::tile_count, jof_info_t::tile_h, and jof_info_t::tile_w.

Referenced by ra8_viewer_reader_requirements().

◆ internal_requirements_valid()

bool internal_requirements_valid ( const ra8_viewer_reader_requirements_t * need )

static

Validate a requirements object before workspace mutation.

Checks ABI, fixed extents, non-zero variable slices, and recomputed total.

Parameters

[in] need Candidate requirements.

Returns: Whether bind may consume the layout.

Return values

true	Every invariant and exact total matched.
false	The object was stale, corrupt, or inconsistent.

Precondition: need is non-NULL.; need was supplied to a bind request.

Postcondition: No workspace byte is modified.; The result is deterministic for need.

Note: Pure and thread-safe.

Since: 0.1.0

Definition at line 457 of file ra8_viewer_reader.c.

References ra8_viewer_reader_requirements_t::dimensions_bytes, ra8_viewer_reader_requirements_t::framebuffer_bytes, internal_engine_requirements_valid(), internal_layout(), k_ra8_viewer_fb_height, k_ra8_viewer_fb_width, k_viewer_layout_version, ra8_viewer_reader_requirements_t::layout_version, RA8_INTERNAL, 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 ra8_viewer_reader_bind().

◆ internal_stderr_write()

void internal_stderr_write ( const char * text )

static

Best-effort exact diagnostic fragment over standard error.

Advances across short writes and retries interrupted writes.

Parameters

[in] text NUL-terminated diagnostic fragment.

Precondition: text is non-NULL.; Standard error may accept descriptor writes.

Postcondition: The complete fragment was attempted.; Reader state remains unchanged.

Note: Concurrent fragments may interleave.

Since: 0.1.0

Definition at line 254 of file ra8_viewer_reader.c.

References RA8_INTERNAL, and strlen().

Referenced by internal_reject().

◆ internal_take()

void * internal_take	(	viewer_layout_t *	layout,
		size_t	bytes,
		size_t	alignment )

static

Take one aligned layout slice, or only charge it while sizing.

Advances the cursor after checked alignment and extent arithmetic.

Parameters

[in,out]	layout	Mutable layout cursor.
[in]	bytes	Requested slice extent.
[in]	alignment	Required power-of-two alignment.

Returns: Slice base in binding mode, otherwise NULL.

Return values

non-NULL	The requested bound slice is available.
NULL	Sizing mode is active or the request failed.

Precondition: layout is non-NULL.; layout was initialized by the caller.

Postcondition: Failure marks the cursor invalid.; Success advances used to the end of the slice.

Note: Sizing mode charges space without touching workspace bytes.

Since: 0.1.0

Definition at line 93 of file ra8_viewer_reader.c.

References viewer_layout_t::base, viewer_layout_t::capacity, internal_align_up(), RA8_INTERNAL, viewer_layout_t::used, and viewer_layout_t::valid.

Referenced by internal_layout(), internal_take_comic(), internal_take_jof(), and ra8_viewer_reader_bind().

◆ internal_take_comic()

viewer_comic_t internal_take_comic	(	viewer_layout_t *	layout,
		const ra8_viewer_reader_requirements_t *	requirements )

static

Take the complete comic-specific workspace tail.

Charges or binds page index, names, encoded-page, and decode-arena slices.

Parameters

[in,out]	layout	Active sizing or binding cursor.
[in]	requirements	Valid comic requirements.

Returns: Comic pointer bundle; pointers are NULL in sizing mode.

Return values

viewer_comic_t The complete bound or sizing-mode bundle.

Precondition: layout and requirements are valid.; requirements->engine == k_ra8_viewer_engine_comic.

Postcondition: The cursor advances through every comic-specific slice.; Failure marks the cursor invalid.

Note: Performs no workspace writes.

Since: 0.1.0

Definition at line 161 of file ra8_viewer_reader.c.

References viewer_comic_t::arena, viewer_comic_t::arena_cap, ra8_viewer_reader_requirements_t::comic_arena_bytes, ra8_viewer_reader_requirements_t::comic_names_bytes, ra8_viewer_reader_requirements_t::comic_page_bytes, ra8_viewer_reader_requirements_t::comic_pages_bytes, internal_take(), viewer_comic_t::names, viewer_comic_t::page, viewer_comic_t::page_cap, and viewer_comic_t::pages.

Referenced by internal_layout(), and ra8_viewer_reader_bind().

◆ internal_take_jof()

viewer_jof_t internal_take_jof	(	viewer_layout_t *	layout,
		const ra8_viewer_reader_requirements_t *	requirements )

static

Take the complete JOF-specific workspace tail.

Charges or binds the one-cell cache metadata and compressed scratch.

Parameters

[in,out]	layout	Active sizing or binding cursor.
[in]	requirements	Valid JOF requirements.

Returns: JOF pointer bundle; pointers are NULL in sizing mode.

Return values

viewer_jof_t The complete bound or sizing-mode bundle.

Precondition: layout and requirements are valid.; requirements->engine == k_ra8_viewer_engine_jof.

Postcondition: The cursor advances through every JOF-specific slice.; Failure marks the cursor invalid.

Note: Performs no workspace writes.

Since: 0.1.0

Definition at line 126 of file ra8_viewer_reader.c.

References viewer_jof_t::buckets, ra8_viewer_reader_requirements_t::cell_bytes, viewer_jof_t::cell_cap, viewer_jof_t::cells, viewer_jof_t::dims, internal_take(), k_viewer_jof_buckets, viewer_jof_t::keys, viewer_jof_t::meta, viewer_jof_t::scratch, ra8_viewer_reader_requirements_t::scratch_bytes, and viewer_jof_t::scratch_cap.

Referenced by internal_layout(), and ra8_viewer_reader_bind().

◆ priv_viewer_pread()

ra8_err_t priv_viewer_pread	(	void *	ctx,
		uint64_t	offset,
		uint8_t *	buffer,
		size_t	length,
		size_t *	out_read )

nodiscard

JOF positional-reader seam over viewer_file_ctx_t.

Definition at line 334 of file ra8_viewer_reader.c.

References k_ra8_err_invalid_state, k_ra8_err_not_found, k_ra8_err_null_ptr, and k_ra8_ok.

Referenced by internal_require_jof(), internal_wire(), priv_viewer_comic_read(), and priv_viewer_open_jof().

◆ 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_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_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().

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ O_CLOEXEC

Enumeration Type Documentation

◆ viewer_fmt_t

Function Documentation

◆ internal_align_up()

◆ internal_classify()

◆ internal_ends_with()

◆ internal_engine_matches()

◆ internal_engine_requirements_valid()

◆ internal_file_open()

◆ internal_layout()

◆ internal_open_selected()

◆ internal_reject()

◆ internal_require_comic()

◆ internal_require_jof()

◆ internal_requirements_valid()

◆ internal_stderr_write()

◆ internal_take()

◆ internal_take_comic()

◆ internal_take_jof()

◆ priv_viewer_pread()

◆ ra8_viewer_close()

◆ ra8_viewer_open()

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