ra8_viewer_reader_internal.h File Reference

Cross-translation-unit state for the bounded JOF/comic viewer. More...

#include <stddef.h>
#include <stdint.h>
#include "comic.h"
#include "jof.h"
#include "longstrip.h"
#include "ra8_attributes.h"
#include "ra8_decomp_limits.h"
#include "ra8_err.h"
#include "ra8_tile_cache.h"
#include "ra8_viewer_reader.h"

Include dependency graph for ra8_viewer_reader_internal.h:

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

Go to the source code of this file.

Data Structures
struct	viewer_file_ctx_t
	Raw host descriptor behind the reusable positional-read callback. More...
struct	viewer_jof_t
	Caller-bound JOF engine and one-band cache backing. More...
struct	viewer_comic_t
	Bare comic engine and every caller-bound backing slice. More...
struct	ra8_viewer_reader
	Bound reader state; every buffer is borrowed from one workspace. More...

Enumerations
enum	ra8_viewer_budget_t : uint32_t {   k_viewer_jof_cells = 1U ,   k_viewer_jof_buckets = 64U ,   k_viewer_layout_version = 0x56570002U ,   k_viewer_background = 0x00FFFFFFU ,   k_viewer_white_byte = 0xFFU }
	Stable constants used by requirements and bind. More...
enum	ra8_viewer_comic_budget_t : uint32_t {   k_viewer_comic_page_cap = 8192U ,   k_viewer_comic_name_bytes = 512U * 1024U ,   k_viewer_comic_page_bytes = 4U * 1024U * 1024U ,   k_viewer_comic_arena_bytes = 8U * 1024U * 1024U }
	Fixed bounded slices for the bare comic engine. More...

Functions
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.
ra8_err_t	priv_viewer_open_jof (ra8_viewer_reader_t *reader)
	Open and wire the JOF engine over a bound reader.
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_render_jof (ra8_viewer_reader_t *reader, uint32_t page)
	Render one JOF viewport into the fixed framebuffer.
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_jof (ra8_viewer_reader_t *reader, uint32_t index, uint16_t *pixels, size_t pixel_bytes, uint32_t *width, uint32_t *height)
	Render one JOF viewport into caller-owned RGB565 output.
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.
ra8_err_t	priv_viewer_size_comic_tiles (ra8_viewer_reader_t *reader)
	Probe every comic page into the bound dimension arrays.
void	priv_viewer_size_jof_tiles (ra8_viewer_reader_t *reader, uint32_t count)
	Populate native tile dimensions after the strip opens.

Detailed Description

Cross-translation-unit state for the bounded JOF/comic viewer.

Shares only caller-bound reader state and explicitly attributed RA8_PRIV engine seams between dispatch, JOF, and comic translation units.

Copyright

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

Since

0.1.0

Definition in file ra8_viewer_reader_internal.h.

Enumeration Type Documentation

ra8_viewer_budget_t

enum ra8_viewer_budget_t : uint32_t

Stable constants used by requirements and bind.

Enumerator
k_viewer_jof_cells	One decoded band resident.
k_viewer_jof_buckets	Power-of-two cache bucket count.
k_viewer_layout_version	Workspace layout ABI guard.
k_viewer_background	White graphics clear colour.
k_viewer_white_byte	Byte fill for white RGB565.

Definition at line 29 of file ra8_viewer_reader_internal.h.

ra8_viewer_comic_budget_t

enum ra8_viewer_comic_budget_t : uint32_t

Fixed bounded slices for the bare comic engine.

Enumerator
k_viewer_comic_page_cap	Maximum indexed pages.
k_viewer_comic_name_bytes	Member-name arena bytes.
k_viewer_comic_page_bytes	Encoded-page resident cap.
k_viewer_comic_arena_bytes	stb decode arena capacity.

Definition at line 38 of file ra8_viewer_reader_internal.h.

Function Documentation

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

ra8_err_t priv_viewer_open_jof ( ra8_viewer_reader_t * reader )

nodiscard

Open and wire the JOF engine over a bound reader.

Definition at line 189 of file ra8_viewer_jof.c.

References jof_info_t::bpp, viewer_jof_t::cell_cap, jof_info_t::codec, viewer_jof_t::dctx, ra8_viewer_reader::file, longstrip_decode_ctx_t::info, internal_wire(), ra8_viewer_reader::jof, jof_parse(), jof_stored_bound(), k_jof_codec_raw, k_ra8_err_invalid_size, k_ra8_ok, longstrip_decode_ctx_t::pread, longstrip_decode_ctx_t::pread_ctx, priv_viewer_pread(), ra8_decomp_check_declared(), ra8_decomp_limits_default(), viewer_jof_t::scratch_cap, viewer_file_ctx_t::size, jof_info_t::tile_h, and jof_info_t::tile_w.

Referenced by internal_open_selected().

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

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

ra8_err_t priv_viewer_render_jof ( ra8_viewer_reader_t * reader, uint32_t page )

nodiscard

Render one JOF viewport into the fixed framebuffer.

Definition at line 217 of file ra8_viewer_jof.c.

References viewer_jof_t::dctx, ra8_viewer_reader::fb, longstrip_decode_ctx_t::info, internal_seek(), ra8_viewer_reader::jof, k_ra8_ok, k_ra8_viewer_fb_height, k_ra8_viewer_fb_width, k_viewer_white_byte, longstrip_render(), memset(), ra8_viewer_reader::rt565, ra8_viewer_reader::rt_h, ra8_viewer_reader::rt_w, viewer_jof_t::strip, jof_info_t::width, and viewer_jof_t::x_off.

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

void priv_viewer_size_jof_tiles	(	ra8_viewer_reader_t *	reader,
		uint32_t	count )

Populate native tile dimensions after the strip opens.

Clips the last viewport to the remaining canvas rows.

Parameters

[in,out]	reader	Open JOF reader.
[in]	count	Number of dimension entries to populate.

Precondition

reader has parsed JOF geometry.

count does not exceed the bound tile capacity.

Postcondition

Every width equals the strip width.

Every height is non-zero and at most the viewport height.

Note

Not thread-safe; mutates reader dimension arrays.

Since

0.1.0

Definition at line 271 of file ra8_viewer_jof.c.

References viewer_jof_t::dctx, jof_info_t::height, longstrip_decode_ctx_t::info, ra8_viewer_reader::jof, ra8_viewer_reader::tile_hpx, ra8_viewer_reader::tile_wpx, viewer_jof_t::viewport_h, and jof_info_t::width.

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

priv_viewer_tile_jof()

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

nodiscard

Render one JOF viewport into caller-owned RGB565 output.

Definition at line 237 of file ra8_viewer_jof.c.

References ra8_viewer_reader::fb, internal_seek(), ra8_viewer_reader::jof, k_ra8_err_invalid_size, k_ra8_ok, k_ra8_viewer_fb_height, k_ra8_viewer_fb_width, k_viewer_white_byte, longstrip_render(), memset(), ra8_viewer_reader::rt565, ra8_viewer_reader::rt_h, ra8_viewer_reader::rt_w, viewer_jof_t::strip, ra8_viewer_reader::tile_hpx, ra8_viewer_reader::tile_wpx, and viewer_jof_t::x_off.

Referenced by ra8_viewer_render_tile565().