Streamed JOF long-strip rendering over a one-band caller cache. More...

#include <stdint.h>
#include <string.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 "ra8_viewer_reader_internal.h"

Include dependency graph for ra8_viewer_jof.c:

Enumerations
enum	viewer_pixel_t : uint8_t { k_viewer_bpp_gray = 1U , k_viewer_bpp_rgb565 = 2U , k_viewer_px_r = 0U , k_viewer_px_g = 1U , k_viewer_px_b = 2U }
	Supported source pixel widths and channel indices. More...

Functions
static uint16_t	internal_band_pixel (const uint8_t *source, uint8_t bpp)
	Convert one source pixel to native RGB565.
static ra8_err_t	internal_jof_blit (void ctx, const uint8_t pixels, uint16_t source_width, uint16_t source_height, uint8_t bpp, int32_t destination_x, int32_t destination_y)
	Composite one decoded band window into the active RGB565 target.
static ra8_err_t	internal_wire (ra8_viewer_reader_t *reader, size_t band_bytes)
	Wire the one-cell cache and long-strip engine.
static ra8_err_t	internal_seek (viewer_jof_t *jof, uint32_t page)
	Seek to a viewport, including the short final page.
ra8_err_t	priv_viewer_open_jof (ra8_viewer_reader_t *reader)
	Open and wire the JOF 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_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.
void	priv_viewer_size_jof_tiles (ra8_viewer_reader_t *reader, uint32_t count)
	Populate native tile dimensions after the strip opens.

Detailed Description

Streamed JOF long-strip rendering over a one-band caller cache.

Binds the portable JOF and long-strip engines to raw positional reads, one caller-owned decoded band, and caller-selected RGB565 targets.

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

Since: 0.1.0

Definition in file ra8_viewer_jof.c.

Enumeration Type Documentation

◆ viewer_pixel_t

enum viewer_pixel_t : uint8_t

Supported source pixel widths and channel indices.

Enumerator
k_viewer_bpp_gray	8-bit grayscale.
k_viewer_bpp_rgb565	Little-endian RGB565.
k_viewer_px_r	Red, gray, or RGB565 low byte.
k_viewer_px_g	Green or RGB565 high byte.
k_viewer_px_b	Blue byte.

Definition at line 24 of file ra8_viewer_jof.c.

Function Documentation

◆ internal_band_pixel()

uint16_t internal_band_pixel	(	const uint8_t *	source,
		uint8_t	bpp )

static

Convert one source pixel to native RGB565.

Handles grayscale, little-endian RGB565, RGB, and RGBA-with-alpha-dropped.

Parameters

[in]	source	Source pixel bytes.
[in]	bpp	Bytes per source pixel.

Returns: Packed RGB565 value.

Return values

0	A black source pixel.

Precondition: source spans bpp readable bytes.; bpp is one of the JOF-supported pixel widths.

Postcondition: No state is mutated.; Alpha, when present, is ignored.

Note: Pure and thread-safe.

Since: 0.1.0

Definition at line 46 of file ra8_viewer_jof.c.

References k_viewer_bpp_gray, k_viewer_bpp_rgb565, k_viewer_px_b, k_viewer_px_g, k_viewer_px_r, RA8_INTERNAL, ra8_viewer_pack565(), and ra8_viewer_pack565_le_pair().

Referenced by internal_jof_blit().

◆ internal_jof_blit()

ra8_err_t internal_jof_blit	(	void *	ctx,
		const uint8_t *	pixels,
		uint16_t	source_width,
		uint16_t	source_height,
		uint8_t	bpp,
		int32_t	destination_x,
		int32_t	destination_y )

static

Composite one decoded band window into the active RGB565 target.

Converts pixels row-wise while clipping to the caller-selected target.

Parameters

[in,out]	ctx	Bound reader.
[in]	pixels	Decoded source pixels.
[in]	source_width	Source window width.
[in]	source_height	Source window height.
[in]	bpp	Source bytes per pixel.
[in]	destination_x	Target-relative x coordinate.
[in]	destination_y	Target-relative y coordinate.

Returns: Composite status.

Return values

k_ra8_ok Pixels were converted; clipping is not an error.

Precondition: ctx is a bound reader with an active target.; pixels spans the declared source window.

Postcondition: Every in-bounds target pixel is written once.; Out-of-bounds source pixels are ignored.

Note: Not thread-safe; writes reader target state.

Since: 0.1.0

Definition at line 76 of file ra8_viewer_jof.c.

References internal_band_pixel(), ra8_viewer_reader::jof, k_ra8_ok, RA8_INTERNAL, ra8_viewer_reader::rt565, ra8_viewer_reader::rt_h, ra8_viewer_reader::rt_w, and viewer_jof_t::x_off.

Referenced by internal_wire().

◆ internal_seek()

ra8_err_t internal_seek	(	viewer_jof_t *	jof,
		uint32_t	page )

static

Seek to a viewport, including the short final page.

Resizes the final viewport before applying its absolute scroll delta.

Parameters

[in,out]	jof	Open JOF state.
[in]	page	Viewport index.

Returns: Scroll status.

Return values

k_ra8_ok	The viewport begins at `page`.
k_ra8_err_out_of_range	No canvas rows remain.

Precondition: jof is open.; page is a candidate unsigned index.

Postcondition: Success sets the exact final-page height.; Failure performs no composite.

Note: Not thread-safe; mutates strip scroll state.

Since: 0.1.0

Definition at line 172 of file ra8_viewer_jof.c.

References viewer_jof_t::dctx, jof_info_t::height, longstrip_decode_ctx_t::info, k_ra8_err_out_of_range, k_ra8_ok, longstrip_scroll_by(), longstrip_set_viewport(), RA8_INTERNAL, longstrip_t::scroll_y, viewer_jof_t::strip, viewer_jof_t::viewport_h, and jof_info_t::width.

Referenced by priv_viewer_render_jof(), and priv_viewer_tile_jof().

◆ internal_wire()

ra8_err_t internal_wire	(	ra8_viewer_reader_t *	reader,
		size_t	band_bytes )

static

Wire the one-cell cache and long-strip engine.

Binds caller slices to the cache and raw-descriptor pread seam.

Parameters

[in,out]	reader	Bound reader with parsed JOF information.
[in]	band_bytes	Exact decoded band capacity.

Returns: Cache or long-strip open status.

Return values

k_ra8_ok Both engines are ready.

Precondition: reader owns an open descriptor.; band_bytes fits the bound cache cell.

Postcondition: Success publishes an open strip over one cache cell.; Failure allocates and maps nothing.

Note: Not thread-safe; initialises shared engine state.

Since: 0.1.0

Definition at line 120 of file ra8_viewer_jof.c.

References viewer_jof_t::buckets, viewer_jof_t::cache, viewer_jof_t::cells, viewer_jof_t::dctx, viewer_jof_t::dims, ra8_viewer_reader::file, longstrip_decode_ctx_t::info, internal_jof_blit(), ra8_viewer_reader::jof, k_ra8_ok, k_ra8_viewer_fb_height, k_viewer_jof_buckets, k_viewer_jof_cells, viewer_jof_t::keys, longstrip_open(), longstrip_tile_decode(), viewer_jof_t::meta, priv_viewer_pread(), RA8_INTERNAL, ra8_tile_cache_init(), longstrip_decode_ctx_t::scratch, viewer_jof_t::scratch, longstrip_decode_ctx_t::scratch_cap, viewer_jof_t::scratch_cap, viewer_file_ctx_t::size, viewer_jof_t::strip, viewer_jof_t::viewport_h, jof_info_t::width, and viewer_jof_t::x_off.

Referenced by priv_viewer_open_jof().

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

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ viewer_pixel_t

Function Documentation

◆ internal_band_pixel()

◆ internal_jof_blit()

◆ internal_seek()

◆ internal_wire()

◆ priv_viewer_open_jof()

◆ priv_viewer_render_jof()

◆ priv_viewer_size_jof_tiles()

◆ priv_viewer_tile_jof()