Bounded-tile GLCDC rotation, raw-fd composition, and PPM export. More...

#include <stddef.h>
#include <stdint.h>
#include "emu_host_io_internal.h"
#include "emu_memmap.h"
#include "emu_mmio.h"
#include "emu_view.h"
#include "emu_view_surface_internal.h"
#include "emu_view_tile_internal.h"

Include dependency graph for emu_view_surface.c:

Data Structures
struct	surface_layer_t
	Live GLCDC source layer clipped to native panel geometry. More...
struct	surface_tile_t
	One bounded source tile inside the live GLCDC layer. More...

Enumerations
enum	surface_glcdc_reg_t : uint64_t { k_surface_gr1_saddr = 0x4034310CUL , k_surface_gr1_flm3 = 0x40343110UL , k_surface_gr1_flm5 = 0x40343118UL , k_surface_gr1_fmt = 0x4034311CUL }
	GLCDC layer registers decoded by the streamed renderer. More...
enum	surface_color_t : uint32_t { k_surface_fmt_rgb565 = 2U , k_surface_fmt_shift = 28U , k_surface_fmt_mask = 0x7U , k_surface_high_shift = 16U , k_surface_stride_mask = 0xFFFFU , k_surface_lnnum_mask = 0x7FFU , k_surface_rgb_r_shift = 16U , k_surface_rgb_g_shift = 8U , k_surface_rgb_mask = 0x00FFFFFFU , k_surface_byte_mask = 0xFFU , k_surface_r_keep = 0xF8U , k_surface_g_keep = 0xFCU , k_surface_r_pos = 8U , k_surface_g_pos = 3U , k_surface_b_drop = 3U , k_surface_r565_shift = 11U , k_surface_g565_shift = 5U , k_surface_5bit = 0x1FU , k_surface_6bit = 0x3FU }
	GLCDC field and RGB conversion constants. More...

Functions
static uint16_t	internal_rgb888_to_565 (uint32_t rgb)
	Pack a live 0x00RRGGBB background into RGB565.
static bool	internal_address_is_ram (uint32_t address)
	True when a source base lies in one emulated RAM region.
static surface_layer_t	internal_layer (uint16_t panel_width, uint16_t panel_height)
	Decode and clip the current GLCDC layer without guest-facing reads.
static bool	internal_read_tile (uc_engine uc, const surface_layer_t layer, const surface_tile_t tile, uint16_t source)
	Read one bounded tile of the live layer into the scratch pixels.
static bool	internal_write_layer (uc_engine uc, emu_presentation_workspace_t presentation, const surface_layer_t *layer)
	Read, rotate, and write every active GLCDC tile.
bool	priv_emu_view_surface_build (uc_engine uc, emu_presentation_workspace_t presentation, const board_status_t *status)
	Build one exact fd-backed composite from live engine and status state.
static bool	internal_write_ppm_pixels (int fd, const emu_presentation_workspace_t *presentation)
	Convert and emit one bounded RGB565 chunk as PPM RGB bytes.
int	write_ppm (const char path, const emu_presentation_workspace_t presentation)
	Write an RGB565 frame to a binary PPM (P6) for headless inspection.

Detailed Description

Bounded-tile GLCDC rotation, raw-fd composition, and PPM export.

Reads live framebuffer rows through the authoritative memory seam, rotates them in fixed-capacity tiles into a descriptor-backed composite, applies board status overlays, and exports exact PPM scanlines.

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

Since: 0.1.0

Definition in file emu_view_surface.c.

Enumeration Type Documentation

◆ surface_color_t

enum surface_color_t : uint32_t

GLCDC field and RGB conversion constants.

Enumerator
k_surface_fmt_rgb565	GLCDC RGB565 format code.
k_surface_fmt_shift	FORMAT[30:28] shift.
k_surface_fmt_mask	FORMAT mask.
k_surface_high_shift	Stride/count high-half shift.
k_surface_stride_mask	FLM3 stride mask.
k_surface_lnnum_mask	FLM5 line count mask.
k_surface_rgb_r_shift	RGB888 red shift.
k_surface_rgb_g_shift	RGB888 green shift.
k_surface_rgb_mask	Live background color mask.
k_surface_byte_mask	One RGB888 component.
k_surface_r_keep	RGB565 red high bits.
k_surface_g_keep	RGB565 green high bits.
k_surface_r_pos	Packed red position.
k_surface_g_pos	Packed green position.
k_surface_b_drop	Packed blue truncation.
k_surface_r565_shift	RGB565 red field shift.
k_surface_g565_shift	RGB565 green field shift.
k_surface_5bit	Five-bit channel mask.
k_surface_6bit	Six-bit channel mask.

Definition at line 32 of file emu_view_surface.c.

◆ surface_glcdc_reg_t

enum surface_glcdc_reg_t : uint64_t

GLCDC layer registers decoded by the streamed renderer.

Enumerator
k_surface_gr1_saddr	GR[0].FLM2 framebuffer base.
k_surface_gr1_flm3	GR[0].FLM3 line stride.
k_surface_gr1_flm5	GR[0].FLM5 line count.
k_surface_gr1_fmt	GR[0].FLM6 pixel format.

Definition at line 24 of file emu_view_surface.c.

Function Documentation

◆ internal_address_is_ram()

bool internal_address_is_ram ( uint32_t address )

static

True when a source base lies in one emulated RAM region.

True when a source base lies in one emulated ram region; this step is contained within the emu view surface model and uses bounded caller or module-owned storage.

Parameters

[in] address Guest address involved in the operation.

Returns: The address is ram result produced by the emu view surface model.

Return values

true	The address is ram condition holds or completed successfully; false otherwise.

Precondition: Arguments satisfy the ranges documented for address is ram.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the emu view surface 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 94 of file emu_view_surface.c.

References k_dtcm_base, k_dtcm_end, k_sdram_base, k_sdram_end, k_sram_base, k_sram_end, and RA8_INTERNAL.

Referenced by internal_layer().

◆ internal_layer()

surface_layer_t internal_layer	(	uint16_t	panel_width,
		uint16_t	panel_height )

static

Decode and clip the current GLCDC layer without guest-facing reads.

Decode and clip the current glcdc layer without guest-facing reads; this step is contained within the emu view surface model and uses bounded caller or module-owned storage.

Parameters

[in]	panel_width	Panel width input used by the operation.
[in]	panel_height	Panel height input used by the operation.

Returns: The layer result produced by the emu view surface model.

Return values

value The operation-specific layer value.

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

Postcondition: State changes remain confined to the emu view surface 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 113 of file emu_view_surface.c.

References internal_address_is_ram(), k_surface_fmt_mask, k_surface_fmt_rgb565, k_surface_fmt_shift, k_surface_gr1_flm3, k_surface_gr1_flm5, k_surface_gr1_fmt, k_surface_gr1_saddr, k_surface_high_shift, k_surface_lnnum_mask, k_surface_stride_mask, mmio_peek(), and RA8_INTERNAL.

Referenced by priv_emu_view_surface_build().

◆ internal_read_tile()

bool internal_read_tile	(	uc_engine *	uc,
		const surface_layer_t *	layer,
		const surface_tile_t *	tile,
		uint16_t *	source )

static

Read one bounded tile of the live layer into the scratch pixels.

Copies tile row by row out of emulated memory through the authoritative memory seam, packing the rows tightly so the rotation stage sees a contiguous tile.

Parameters

[in,out]	uc	Unicorn engine whose emulated state is read or updated.
[in]	layer	Decoded and clipped live GLCDC source layer.
[in]	tile	Bounded tile origin and extent inside `layer`.
[out]	source	Scratch tile receiving the packed tile pixels.

Returns: The read tile result produced by the emu view surface model.

Return values

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

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

Postcondition: State changes remain confined to the emu view surface 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 156 of file emu_view_surface.c.

References surface_layer_t::address, emu_mem_read(), surface_tile_t::height, RA8_INTERNAL, surface_layer_t::stride, surface_tile_t::width, surface_tile_t::x, and surface_tile_t::y.

Referenced by internal_write_layer().

◆ internal_rgb888_to_565()

uint16_t internal_rgb888_to_565 ( uint32_t rgb )

static

Pack a live 0x00RRGGBB background into RGB565.

Pack a live 0x00rrggbb background into rgb565; this step is contained within the emu view surface model and uses bounded caller or module-owned storage.

Parameters

[in] rgb Rgb input used by the operation.

Returns: The rgb888 to 565 result produced by the emu view surface model.

Return values

value The operation-specific rgb888 to 565 value.

Precondition: Arguments satisfy the ranges documented for rgb888 to 565.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the emu view surface 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 74 of file emu_view_surface.c.

References k_surface_b_drop, k_surface_byte_mask, k_surface_g_keep, k_surface_g_pos, k_surface_r_keep, k_surface_r_pos, k_surface_rgb_g_shift, k_surface_rgb_r_shift, and RA8_INTERNAL.

Referenced by priv_emu_view_surface_build().

◆ internal_write_layer()

bool internal_write_layer	(	uc_engine *	uc,
		emu_presentation_workspace_t *	presentation,
		const surface_layer_t *	layer )

static

Read, rotate, and write every active GLCDC tile.

Read, rotate, and write every active glcdc tile; this step is contained within the emu view surface model and uses bounded caller or module-owned storage.

Parameters

[in,out]	uc	Unicorn engine whose emulated state is read or updated.
[in,out]	presentation	Descriptor-backed presentation workspace accessed by the operation.
[in]	layer	Layer input used by the operation.

Returns: The write layer result produced by the emu view surface model.

Return values

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

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

Postcondition: State changes remain confined to the emu view surface 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 186 of file emu_view_surface.c.

References surface_layer_t::active, surface_layer_t::height, internal_read_tile(), k_emu_presentation_tile_px, priv_emu_view_tile_write(), RA8_INTERNAL, emu_presentation_workspace_t::scratch, and surface_layer_t::width.

Referenced by priv_emu_view_surface_build().

◆ internal_write_ppm_pixels()

bool internal_write_ppm_pixels	(	int	fd,
		const emu_presentation_workspace_t *	presentation )

static

Convert and emit one bounded RGB565 chunk as PPM RGB bytes.

Convert and emit one bounded rgb565 chunk as ppm rgb bytes; this step is contained within the emu view surface model and uses bounded caller or module-owned storage.

Parameters

[in]	fd	Open raw descriptor used for the transfer.
[in]	presentation	Descriptor-backed presentation workspace accessed by the operation.

Returns: The write ppm pixels result produced by the emu view surface model.

Return values

true	The write ppm pixels condition holds or completed successfully; false otherwise.

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

Postcondition: State changes remain confined to the emu view surface 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

< Fixed conversion chunk pixel count.

Definition at line 266 of file emu_view_surface.c.

References emu_presentation_read(), k_emu_io_ok, k_surface_5bit, k_surface_6bit, k_surface_g565_shift, k_surface_r565_shift, priv_emu_io_write_exact(), RA8_INTERNAL, and emu_presentation_workspace_t::surface_bytes.

Referenced by write_ppm().

◆ priv_emu_view_surface_build()

bool priv_emu_view_surface_build	(	uc_engine *	uc,
		emu_presentation_workspace_t *	presentation,
		const board_status_t *	status )

Build one exact fd-backed composite from live engine and status state.

Build one exact fd-backed composite from live engine and status state; this step is contained within the emu view surface model and uses bounded caller or module-owned storage.

Parameters

[in,out]	uc	Unicorn engine whose emulated state is read or updated.
[in,out]	presentation	Descriptor-backed presentation workspace accessed by the operation.
[in]	status	Status value consumed or published by the operation.

Returns: The emu view surface build result produced by the emu view surface model.

Return values

true	The emu view surface build condition holds or completed successfully; false otherwise.

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

Postcondition: State changes remain confined to the emu view surface 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 218 of file emu_view_surface.c.

References board_overlay_draw_sidebar(), emu_presentation_workspace_t::composite_height, emu_presentation_workspace_t::composite_width, emu_presentation_workspace_t::display_height, emu_presentation_workspace_t::display_width, emu_presentation_fill(), emu_presentation_workspace_t::fd, internal_layer(), internal_rgb888_to_565(), internal_write_layer(), k_glcdc_bg_bgc, k_surface_rgb_mask, mmio_peek(), emu_presentation_workspace_t::panel_height, and emu_presentation_workspace_t::panel_width.

Referenced by build_composite().

◆ write_ppm()

int write_ppm	(	const char *	path,
		const emu_presentation_workspace_t *	presentation )

Write an RGB565 frame to a binary PPM (P6) for headless inspection.

Uses bounded RGB conversion plus a synced sibling transaction so a failed export cannot replace an existing target with a partial image.

Parameters

[in]	path	Output file path.
[in]	presentation	Open fd-backed RGB565 composite to stream.

Returns: 0 on success, -1 when the file cannot be created.

Return values

0	The frame was written.
-1	Transaction creation, raw write, sync, or publication failed.

Precondition: presentation is open and holds the full composite.; path names a writable location.

Postcondition: On success the P6 file exists with 8-bit RGB expansion.; On failure the pre-existing final target remains unchanged.

Note: Not thread-safe; the emulator is single-threaded host-side.

Since: 0.1.0

Definition at line 300 of file emu_view_surface.c.

References emu_presentation_workspace_t::composite_height, emu_presentation_workspace_t::composite_width, emu_io_txn_t::fd, emu_presentation_workspace_t::fd, internal_write_ppm_pixels(), k_emu_io_ok, priv_emu_io_filef(), priv_emu_io_txn_abort(), priv_emu_io_txn_begin(), priv_emu_io_txn_commit(), and emu_io_result_t::status.

Referenced by internal_run_loop_record(), and priv_run_write_outputs().

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ surface_color_t

◆ surface_glcdc_reg_t

Function Documentation

◆ internal_address_is_ram()

◆ internal_layer()

◆ internal_read_tile()

◆ internal_rgb888_to_565()

◆ internal_write_layer()

◆ internal_write_ppm_pixels()

◆ priv_emu_view_surface_build()

◆ write_ppm()