Bounded raw-descriptor presentation surface and scratch workspace. More...

#include <stddef.h>
#include <stdint.h>
#include "board_overlay.h"
#include "ra8_attributes.h"

Include dependency graph for emu_presentation.h:

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

Data Structures
struct	emu_presentation_spec_t
	Inputs controlling exact presentation requirements. More...
struct	emu_presentation_result_t
	Exact result of a requirements or workspace operation. More...
struct	emu_presentation_workspace_t
	One independent owned surface plus non-owning bounded scratch. More...

Enumerations
enum	emu_presentation_limit_t : size_t { k_emu_presentation_max_panel_px = 4096U , k_emu_presentation_tile_px = 64U , k_emu_presentation_max_scratch_bytes }
	Geometry and bounded tile limits for streamed presentation. More...
enum	emu_presentation_status_t : uint8_t { k_emu_presentation_ok = 0U , k_emu_presentation_invalid , k_emu_presentation_overflow , k_emu_presentation_capacity , k_emu_presentation_io }
	Presentation planning, creation, and transfer status. More...

Functions
emu_presentation_result_t	emu_presentation_requirements (const emu_presentation_spec_t *spec)
	Compute exact raw-fd and scratch requirements without mutation.
emu_presentation_result_t	emu_presentation_open (const emu_presentation_spec_t spec, void scratch, size_t supplied_scratch_bytes, emu_presentation_workspace_t *workspace)
	Create and bind one unlinked raw-fd presentation workspace.
bool	emu_presentation_close (emu_presentation_workspace_t *workspace)
	Close one owned presentation descriptor and invalidate the workspace.
bool	emu_presentation_fill (void *context, uint16_t x, uint16_t y, uint16_t width, uint16_t height, uint16_t color)
	Fill a checked RGB565 rectangle in a raw-fd surface.
bool	emu_presentation_read (const emu_presentation_workspace_t workspace, size_t offset, void bytes, size_t count)
	Read exact RGB565 bytes at a checked surface offset.
bool	emu_presentation_write (emu_presentation_workspace_t workspace, size_t offset, const void bytes, size_t count)
	Write exact RGB565 bytes at a checked surface offset.
bool	emu_presentation_snapshot (emu_presentation_workspace_t workspace, int snapshot_fd)
	Create an immutable unlinked descriptor snapshot of one surface.

Detailed Description

Bounded raw-descriptor presentation surface and scratch workspace.

Plans exact disk and caller-scratch requirements, creates one unlinked raw backing descriptor, and exposes checked rectangle/read access.

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

Since: 0.1.0

Definition in file emu_presentation.h.

Enumeration Type Documentation

◆ emu_presentation_limit_t

enum emu_presentation_limit_t : size_t

Geometry and bounded tile limits for streamed presentation.

Enumerator
k_emu_presentation_max_panel_px	Largest panel dimension.
k_emu_presentation_tile_px	Square rotation tile side.
k_emu_presentation_max_scratch_bytes	Exact maximum caller scratch: source plus rotated 64x64 RGB565 tiles.

Definition at line 25 of file emu_presentation.h.

◆ emu_presentation_status_t

enum emu_presentation_status_t : uint8_t

Presentation planning, creation, and transfer status.

Enumerator
k_emu_presentation_ok	Operation completed exactly.
k_emu_presentation_invalid	Geometry, rotation, pointer, or fd invalid.
k_emu_presentation_overflow	A checked size/offset operation overflowed.
k_emu_presentation_capacity	Caller scratch is smaller than required.
k_emu_presentation_io	Raw descriptor create/size/I/O failed.

Definition at line 34 of file emu_presentation.h.

Function Documentation

◆ emu_presentation_close()

bool emu_presentation_close ( emu_presentation_workspace_t * workspace )

Close one owned presentation descriptor and invalidate the workspace.

Parameters

[in,out] workspace Workspace returned by emu_presentation_open.

Returns: Whether close completed or the workspace was already inactive.

Postcondition: workspace is reset with fd -1 even when close reports failure.

Note: Does not modify borrowed scratch bytes.

Since: 0.1.0

Close one owned presentation descriptor and invalidate the workspace; this step is contained within the emu presentation model and uses bounded caller or module-owned storage.

Return values

true	The emu presentation close condition holds or completed successfully; false otherwise.

Precondition: Arguments satisfy the ranges documented for emu presentation close.; The call executes on the emulator's single owning thread.

Postcondition: Ownership of caller-supplied storage is unchanged.

Definition at line 303 of file emu_presentation.c.

References emu_presentation_workspace_t::fd.

Referenced by internal_main_load_images(), main(), and priv_run_cleanup().

◆ emu_presentation_fill()

bool emu_presentation_fill	(	void *	context,
		uint16_t	x,
		uint16_t	y,
		uint16_t	width,
		uint16_t	height,
		uint16_t	color )

Fill a checked RGB565 rectangle in a raw-fd surface.

Matches board_overlay_fill_fn and uses only bound row scratch.

Parameters

[in,out]	context	An emu_presentation_workspace_t.
[in]	x	Rectangle column.
[in]	y	Rectangle row.
[in]	width	Rectangle width.
[in]	height	Rectangle height.
[in]	color	RGB565 fill color.

Returns: True when every row was written exactly.

Precondition: The rectangle is inside the composite geometry.

Postcondition: Failure is bounded to the owned raw surface; no external output changes.

Since: 0.1.0

Return values

true	The emu presentation fill condition holds or completed successfully; false otherwise.

Precondition: The call executes on the emulator's single owning thread.

Postcondition: Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Definition at line 339 of file emu_presentation.c.

References emu_presentation_workspace_t::composite_height, emu_presentation_workspace_t::composite_width, emu_presentation_write(), emu_presentation_workspace_t::scratch, and emu_presentation_workspace_t::scratch_bytes.

Referenced by priv_emu_view_surface_build().

◆ emu_presentation_open()

emu_presentation_result_t emu_presentation_open	(	const emu_presentation_spec_t *	spec,
		void *	scratch,
		size_t	supplied_scratch_bytes,
		emu_presentation_workspace_t *	workspace )

nodiscard

Create and bind one unlinked raw-fd presentation workspace.

Validates exact capacity before creating an anonymous temporary; failure preserves workspace and every scratch byte.

Parameters

[in]	spec	Presentation geometry and mode.
[in,out]	scratch	Caller-owned bounded scratch, or nullptr if inactive.
[in]	supplied_scratch_bytes	Writable scratch capacity.
[out]	workspace	Receives one independent owned descriptor on success.

Returns: Exact requirements, supplied capacity, and captured I/O error.

Precondition: spec and workspace are non-null.; Non-null scratch spans supplied_scratch_bytes writable bytes.; Active scratch is aligned to alignof(uint16_t).

Postcondition: Success leaves no named temporary path and owns exactly one descriptor.; Failure leaves workspace and scratch unchanged with no descriptor leak.

Note: Distinct workspaces are independently usable and closeable.

Since: 0.1.0

Definition at line 246 of file emu_presentation.c.

Referenced by internal_main_open_presentation().

◆ emu_presentation_read()

bool emu_presentation_read	(	const emu_presentation_workspace_t *	workspace,
		size_t	offset,
		void *	bytes,
		size_t	count )

Read exact RGB565 bytes at a checked surface offset.

Read exact rgb565 bytes at a checked surface offset; this step is contained within the emu presentation model and uses bounded caller or module-owned storage.

Parameters

[in]	workspace	Caller-owned workspace used by the operation.
[in]	offset	Byte or register offset at which processing begins.
[in,out]	bytes	Byte storage transferred by the operation.
[in]	count	Number of elements or bytes to process.

Returns: The emu presentation read result produced by the emu presentation model.

Return values

true	The emu presentation read condition holds or completed successfully; false otherwise.

Precondition: Arguments satisfy the ranges documented for emu presentation read.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the emu presentation model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 313 of file emu_presentation.c.

References emu_presentation_workspace_t::fd, k_emu_io_ok, priv_emu_io_pread_exact(), emu_io_result_t::status, and emu_presentation_workspace_t::surface_bytes.

Referenced by emu_presentation_snapshot(), and internal_write_ppm_pixels().

◆ emu_presentation_requirements()

emu_presentation_result_t emu_presentation_requirements ( const emu_presentation_spec_t * spec )

nodiscard

Compute exact raw-fd and scratch requirements without mutation.

Parameters

[in] spec Presentation geometry and mode.

Returns: Exact requirements or validation/overflow status.

Precondition: spec is non-null.

Postcondition: No caller memory, descriptor, filesystem name, or global changes.

Note: Pure and thread-safe.

Since: 0.1.0

Definition at line 235 of file emu_presentation.c.

References internal_plan(), internal_result(), k_emu_presentation_ok, emu_presentation_plan_t::scratch_bytes, and emu_presentation_plan_t::surface_bytes.

◆ emu_presentation_snapshot()

bool emu_presentation_snapshot	(	emu_presentation_workspace_t *	workspace,
		int *	snapshot_fd )

Create an immutable unlinked descriptor snapshot of one surface.

Parameters

[in,out]	workspace	Complete surface and bounded transfer scratch.
[out]	snapshot_fd	Receives an owned descriptor positioned arbitrarily.

Returns: True only when every source byte was copied exactly.

Postcondition: Success transfers close ownership of snapshot_fd to the caller.; Failure preserves snapshot_fd and leaks no descriptor or path.

Note: The immutable copy prevents asynchronous display-provider data races.

Since: 0.1.0

Create an immutable unlinked descriptor snapshot of one surface; this step is contained within the emu presentation model and uses bounded caller or module-owned storage.

Return values

true	The emu presentation snapshot condition holds or completed successfully; false otherwise.

Precondition: Arguments satisfy the ranges documented for emu presentation snapshot.; The call executes on the emulator's single owning thread.

Definition at line 377 of file emu_presentation.c.

References emu_presentation_read(), emu_presentation_workspace_t::fd, internal_anonymous_fd(), k_emu_io_ok, priv_emu_io_pwrite_exact(), emu_presentation_workspace_t::scratch, emu_presentation_workspace_t::scratch_bytes, emu_io_result_t::status, and emu_presentation_workspace_t::surface_bytes.

◆ emu_presentation_write()

bool emu_presentation_write	(	emu_presentation_workspace_t *	workspace,
		size_t	offset,
		const void *	bytes,
		size_t	count )

Write exact RGB565 bytes at a checked surface offset.

Write exact rgb565 bytes at a checked surface offset; this step is contained within the emu presentation model and uses bounded caller or module-owned storage.

Parameters

[in,out]	workspace	Caller-owned workspace used by the operation.
[in]	offset	Byte or register offset at which processing begins.
[in]	bytes	Byte storage transferred by the operation.
[in]	count	Number of elements or bytes to process.

Returns: The emu presentation write result produced by the emu presentation model.

Return values

true	The emu presentation write condition holds or completed successfully; false otherwise.

Precondition: Arguments satisfy the ranges documented for emu presentation write.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the emu presentation model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 326 of file emu_presentation.c.

References emu_presentation_workspace_t::fd, k_emu_io_ok, priv_emu_io_pwrite_exact(), emu_io_result_t::status, and emu_presentation_workspace_t::surface_bytes.

Referenced by emu_presentation_fill(), and internal_write_rows().

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ emu_presentation_limit_t

◆ emu_presentation_status_t

Function Documentation

◆ emu_presentation_close()

◆ emu_presentation_fill()

◆ emu_presentation_open()

◆ emu_presentation_read()

◆ emu_presentation_requirements()

◆ emu_presentation_snapshot()

◆ emu_presentation_write()