Bounded host composition root for the JOF/comic viewer. More...

#include <signal.h>
#include <stdalign.h>
#include <stddef.h>
#include <stdint.h>
#include <stdlib.h>
#include <string.h>
#include <time.h>
#include <unistd.h>
#include "ra8_attributes.h"
#include "ra8_err.h"
#include "ra8_io_stream.h"
#include "ra8_io_stream_posix.h"
#include "ra8_log.h"
#include "ra8_viewer_output_internal.h"
#include "ra8_viewer_reader.h"
#include "ra8_viewer_view.h"

Include dependency graph for main.c:

Data Structures
struct	viewer_options_t
	Parsed command-line options. More...

Enumerations
enum	viewer_main_config_t : int32_t { k_viewer_frame_ns = 16000000 , k_viewer_min_args = 2 , k_viewer_radix_dec = 10 , k_viewer_composition_bytes = 32 * 1024 * 1024 }
	Composition limits and CLI constants. More...

Functions
static void	internal_usage (ra8_io_stream_t output, const char executable)
	Print usage through the standard-error descriptor.
static bool	internal_parse_arguments (int argc, char *argv, viewer_options_t options)
	Parse the bounded viewer command line.
static uint32_t	internal_clamp_page (uint32_t page, uint32_t count)
	Clamp a requested page into the document.
static bool	internal_align_offset (size_t offset, size_t alignment, size_t *out)
	Align a composition offset upward.
static void	internal_report_capacity (ra8_io_stream_t output, const char subject, const ra8_viewer_workspace_report_t *report)
	Report exact capacity evidence.
static bool	internal_render_page (ra8_viewer_reader_t reader, const viewer_options_t options, uint32_t page, ra8_io_stream_t *diagnostic)
	Render and optionally write one fixed-framebuffer page.
static bool	internal_dump_tile (ra8_viewer_reader_t reader, uint32_t tile, const char path, void workspace, size_t workspace_bytes, ra8_io_stream_t diagnostic)
	Render and publish one caller-buffered scroll tile.
static int	internal_run_window (ra8_viewer_reader_t reader, void workspace, size_t workspace_bytes, ra8_io_stream_t *diagnostic)
	Open and cooperatively pump the caller-workspace Cocoa view.
static void	internal_log_sink (void *context, uint8_t byte)
	Route firmware log bytes through the standard-error descriptor.
static ra8_err_t	internal_bind_diagnostic (ra8_io_stream_t output, ra8_io_stream_posix_state_t state)
	Bind standard error through the raw POSIX stream adapter.
static int	internal_execute (ra8_viewer_reader_t reader, const ra8_viewer_reader_requirements_t requirements, const viewer_options_t options, uint32_t page, ra8_io_stream_t diagnostic)
	Execute the selected viewer mode over the composition remainder.
int	main (int argc, char **argv)
	Program entry point.

Variables
static uint8_t	s_viewer_composition [k_viewer_composition_bytes]
	Explicit host composition storage; another target may replace it.

Detailed Description

Bounded host composition root for the JOF/comic viewer.

One named 32-MiB backing holds the reader plus the mutually exclusive headless-tile or Cocoa-view scratch. Exact requirements are checked before every bind; larger atlases fail visibly instead of reaching an allocator or acquiring an implicit mapping.

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

Since: 0.1.0

Definition in file main.c.

Enumeration Type Documentation

◆ viewer_main_config_t

enum viewer_main_config_t : int32_t

Composition limits and CLI constants.

Enumerator
k_viewer_frame_ns	Cooperative pump period.
k_viewer_min_args	argv count with an input path.
k_viewer_radix_dec	Decimal option radix.
k_viewer_composition_bytes	Entire first-party byte budget.

Definition at line 32 of file main.c.

Function Documentation

◆ internal_align_offset()

bool internal_align_offset	(	size_t	offset,
		size_t	alignment,
		size_t *	out )

static

Align a composition offset upward.

Rejects non-power-of-two alignment and addition overflow.

Parameters

[in]	offset	Unaligned byte offset.
[in]	alignment	Required power-of-two alignment.
[out]	out	Aligned offset.

Returns: Whether alignment succeeded.

Return values

true	`out` is populated.
false	Inputs were invalid or overflowed.

Precondition: out is writable.; offset is a composition-relative extent.

Postcondition: Success publishes an offset no smaller than offset.; Failure leaves caller storage untouched.

Note: Pure apart from out.

Since: 0.1.0

Definition at line 146 of file main.c.

References RA8_INTERNAL.

Referenced by internal_execute().

◆ internal_bind_diagnostic()

ra8_err_t internal_bind_diagnostic	(	ra8_io_stream_t *	output,
		ra8_io_stream_posix_state_t *	state )

static

Bind standard error through the raw POSIX stream adapter.

Ignores SIGPIPE so a closed diagnostic consumer becomes EPIPE and can be mapped to a normal stream error rather than terminating the viewer.

Parameters

[out]	output	Stream handle to bind.
[out]	state	Caller-owned POSIX adapter state.

Returns: Canonical binding or signal-configuration status.

Return values

k_ra8_ok	Standard error is bound and ready.
k_ra8_err_comm_error	SIGPIPE disposition setup failed.

Precondition: output and state are writable.; Standard error remains process-owned for the binding lifetime.

Postcondition: Success leaves SIGPIPE ignored for the process lifetime.; Failure leaves output unbound.

Note: This process-wide policy belongs at the composition boundary.

Since: 0.1.0

Definition at line 358 of file main.c.

References k_ra8_err_comm_error, RA8_INTERNAL, and ra8_io_stream_posix_init().

Referenced by main().

◆ internal_clamp_page()

uint32_t internal_clamp_page	(	uint32_t	page,
		uint32_t	count )

static

Clamp a requested page into the document.

Empty documents map to zero; over-range requests map to the last page.

Parameters

[in]	page	Requested index.
[in]	count	Document page count.

Returns: A bounded page index.

Return values

0	The document is empty or page zero was requested.

Precondition: count is the reader-reported count.; page is an unsigned command-line value.

Postcondition: A non-empty result is below count.; No state is mutated.

Note: Pure and thread-safe.

Since: 0.1.0

Definition at line 122 of file main.c.

References RA8_INTERNAL.

Referenced by main().

◆ internal_dump_tile()

bool internal_dump_tile	(	ra8_viewer_reader_t *	reader,
		uint32_t	tile,
		const char *	path,
		void *	workspace,
		size_t	workspace_bytes,
		ra8_io_stream_t *	diagnostic )

static

Render and publish one caller-buffered scroll tile.

Renders into the supplied remainder and writes the exact RGB565 tile.

Parameters

[in,out]	reader	Open reader.
[in]	tile	Tile index.
[in]	path	NUL-terminated output path.
[in,out]	workspace	Caller tile backing.
[in]	workspace_bytes	Accessible tile backing extent.
[in,out]	diagnostic	Bound diagnostic byte stream.

Returns: Whether render and publication succeeded.

Return values

true	The PPM was written.
false	Capacity, render, or publication failed.

Precondition: reader is open and path is non-NULL.; workspace spans workspace_bytes bytes.

Postcondition: Success writes one complete PPM.; Failure reports the exact capacity when applicable.

Note: Not thread-safe; it drives shared reader state.

Since: 0.1.0

Definition at line 235 of file main.c.

References internal_report_capacity(), k_ra8_err_invalid_size, k_ra8_ok, priv_viewer_output_error(), priv_viewer_output_index_error(), priv_viewer_output_tile(), RA8_INTERNAL, ra8_viewer_render_tile565(), and ra8_viewer_write_ppm565().

Referenced by internal_execute().

◆ internal_execute()

int internal_execute	(	ra8_viewer_reader_t *	reader,
		const ra8_viewer_reader_requirements_t *	requirements,
		const viewer_options_t *	options,
		uint32_t	page,
		ra8_io_stream_t *	diagnostic )

static

Execute the selected viewer mode over the composition remainder.

Aligns the scratch slice after the bound reader, then dispatches to tile, fixed-page, or interactive-window rendering without acquiring storage.

Parameters

[in,out]	reader	Open reader bound in composition storage.
[in]	requirements	Exact reader workspace requirements.
[in]	options	Parsed viewer options.
[in]	page	Bounded page index.
[in,out]	diagnostic	Bound diagnostic stream.

Returns: Process-style command status.

Return values

0	The selected mode completed successfully.
1	Scratch geometry or the selected mode failed.

Precondition: reader is open and requirements describes its binding.; options and diagnostic remain valid throughout the call.

Postcondition: The reader remains open and caller-owned.; Composition bytes outside the selected scratch slice remain unchanged.

Note: Not thread-safe; it drives the caller's reader and shared composition.

Since: 0.1.0

Definition at line 387 of file main.c.

References viewer_options_t::dump_ppm, viewer_options_t::dump_tile, viewer_options_t::headless, internal_align_offset(), internal_dump_tile(), internal_render_page(), internal_run_window(), RA8_INTERNAL, ra8_viewer_reader_requirements_t::required_bytes, and s_viewer_composition.

Referenced by main().

◆ internal_log_sink()

void internal_log_sink	(	void *	context,
		uint8_t	byte )

static

Route firmware log bytes through the standard-error descriptor.

Delegates the byte to the bound portable stream and intentionally ignores its best-effort diagnostic status.

Parameters

[in,out]	context	Bound ra8_io_stream_t logger cookie.
[in]	byte	Log byte.

Precondition: The logger installed this callback.; Standard error may accept a best-effort byte.

Postcondition: One byte write was attempted.; Reader and composition state remain unchanged.

Note: The single-threaded tool serialises calls.

Since: 0.1.0

Definition at line 337 of file main.c.

References RA8_INTERNAL, and ra8_io_stream_putc().

◆ internal_parse_arguments()

bool internal_parse_arguments	(	int	argc,
		char **	argv,
		viewer_options_t *	options )

static

Parse the bounded viewer command line.

Accepts only the documented value-taking flags and headless switch.

Parameters

[in]	argc	Argument count.
[in]	argv	Argument vector.
[out]	options	Parsed options.

Returns: Whether every argument was valid.

Return values

true	Options were populated.
false	Arguments were incomplete or unknown.

Precondition: argv spans argc entries.; options is writable.

Postcondition: Success publishes a document path and defaults tile to -1.; Failure causes no external I/O.

Note: Pure apart from options.

Since: 0.1.0

Definition at line 85 of file main.c.

References viewer_options_t::dump_ppm, viewer_options_t::dump_tile, viewer_options_t::headless, k_viewer_min_args, k_viewer_radix_dec, viewer_options_t::page, RA8_INTERNAL, and strcmp().

Referenced by main().

◆ internal_render_page()

bool internal_render_page	(	ra8_viewer_reader_t *	reader,
		const viewer_options_t *	options,
		uint32_t	page,
		ra8_io_stream_t *	diagnostic )

static

Render and optionally write one fixed-framebuffer page.

Drives the fixed target and publishes it only when a path was given.

Parameters

[in,out]	reader	Open reader.
[in]	options	Parsed options.
[in]	page	Bounded page index.
[in,out]	diagnostic	Bound diagnostic byte stream.

Returns: Whether render and optional publication succeeded.

Return values

true	All requested work completed.
false	A render or descriptor publication failed.

Precondition: reader is open.; options is populated.

Postcondition: Success leaves the framebuffer rendered.; Failure is reported on standard error.

Note: Not thread-safe; it drives shared reader state.

Since: 0.1.0

Definition at line 194 of file main.c.

References viewer_options_t::dump_ppm, k_ra8_ok, priv_viewer_output_index_error(), priv_viewer_output_text(), priv_viewer_output_wrote(), RA8_INTERNAL, ra8_viewer_dump_ppm(), and ra8_viewer_render_page().

Referenced by internal_execute().

◆ internal_report_capacity()

void internal_report_capacity	(	ra8_io_stream_t *	output,
		const char *	subject,
		const ra8_viewer_workspace_report_t *	report )

static

Report exact capacity evidence.

Emits the subject plus exact required and supplied byte counts.

Parameters

[in,out]	output	Bound diagnostic byte stream.
[in]	subject	NUL-terminated workspace name.
[in]	report	Completed capacity report.

Precondition: subject is non-NULL.; report is non-NULL.

Postcondition: A diagnostic write was attempted.; Workspace bytes remain unchanged.

Note: Descriptor diagnostics are best-effort.

Since: 0.1.0

Definition at line 169 of file main.c.

References priv_viewer_output_capacity(), and RA8_INTERNAL.

Referenced by internal_dump_tile(), internal_run_window(), and main().

◆ internal_run_window()

int internal_run_window	(	ra8_viewer_reader_t *	reader,
		void *	workspace,
		size_t	workspace_bytes,
		ra8_io_stream_t *	diagnostic )

static

Open and cooperatively pump the caller-workspace Cocoa view.

Sizes, binds, pumps, and closes the platform view in the caller slice.

Parameters

[in,out]	reader	Open reader borrowed by the view.
[in,out]	workspace	Caller view backing.
[in]	workspace_bytes	Accessible backing extent.
[in,out]	diagnostic	Bound diagnostic byte stream.

Returns: Process-style status.

Return values

0	The window was opened and closed normally.
1	The platform or workspace could not provide a view.

Precondition: reader remains open throughout the pump.; workspace spans workspace_bytes bytes.

Postcondition: Any successfully opened view is closed.; The reader remains open and caller-owned.

Note: Must execute on the Cocoa main thread.

Since: 0.1.0

Definition at line 288 of file main.c.

References internal_report_capacity(), k_ra8_err_invalid_size, k_ra8_ok, k_viewer_frame_ns, priv_viewer_output_text(), RA8_INTERNAL, ra8_viewer_view_close(), ra8_viewer_view_open(), ra8_viewer_view_pump(), and ra8_viewer_view_requirements().

Referenced by internal_execute().

◆ internal_usage()

void internal_usage	(	ra8_io_stream_t *	output,
		const char *	executable )

static

Print usage through the standard-error descriptor.

Uses one descriptor-formatted write so no hosted stream is owned.

Parameters

[in,out]	output	Bound diagnostic byte stream.
[in]	executable	NUL-terminated argv[0] spelling.

Precondition: executable is non-NULL.; Standard error may accept a best-effort diagnostic.

Postcondition: One complete usage message was attempted.; Composition storage and options remain unchanged.

Note: The diagnostic failure is intentionally non-fatal.

Since: 0.1.0

Definition at line 64 of file main.c.

References priv_viewer_output_usage(), and RA8_INTERNAL.

◆ main()

int main	(	int	argc,
		char **	argv )

Variable Documentation

◆ s_viewer_composition

uint8_t s_viewer_composition[k_viewer_composition_bytes]

static

Explicit host composition storage; another target may replace it.

Definition at line 50 of file main.c.

Referenced by internal_execute(), and main().

Data Structures

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ viewer_main_config_t

Function Documentation

◆ internal_align_offset()

◆ internal_bind_diagnostic()

◆ internal_clamp_page()

◆ internal_dump_tile()

◆ internal_execute()

◆ internal_log_sink()

◆ internal_parse_arguments()

◆ internal_render_page()

◆ internal_report_capacity()

◆ internal_run_window()

◆ internal_usage()

◆ main()

Variable Documentation

◆ s_viewer_composition