Minimal self-contained macOS window for the board emulator. More...

#include <stddef.h>
#include <stdint.h>
#include <sys/types.h>
#include "emu_presentation.h"
#include "ra8_attributes.h"

Include dependency graph for board_view.h:

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

Go to the source code of this file.

Data Structures
struct	board_view_storage_t
	Caller-owned pointer-aligned storage for one platform view handle. More...

Typedefs
typedef struct board_view	board_view_t
	Opaque desktop-window handle (defined in board_view.m).

Functions
board_view_t *	board_view_open (board_view_storage_t storage, uint16_t width_px, uint16_t height_px, const char title)
	Open a desktop window of the given pixel size.
void	board_view_present (board_view_t view, emu_presentation_workspace_t presentation)
	Snapshot an RGB565 fd surface and request a redraw.
size_t	board_view_read_rgb888_fd (int fd, off_t position, void *buffer, size_t count)
	Expand an arbitrary byte range from a sealed RGB565 descriptor.
bool	board_view_pump (board_view_t *view)
	Drain pending UI events; report whether the window was closed.
bool	board_view_poll_click (board_view_t view, uint16_t x, uint16_t *y)
	Report the most recent unprocessed left mouse-down, once.
bool	board_view_poll_drag (board_view_t view, uint16_t x, uint16_t *y)
	Report the current position of a held-button drag, once.
bool	board_view_poll_release (board_view_t *view)
	Report whether the primary mouse button was released since the last poll.
int32_t	board_view_poll_scroll (board_view_t *view)
	Drain the accumulated console scroll-wheel notches since the last poll.
void	board_view_close (board_view_t *view)
	Close the window and release its resources.

Detailed Description

Minimal self-contained macOS window for the board emulator.

A tiny C-ABI over Cocoa so ra8_emulator can SHOW what the emulated GLCDC is driving – present an immutable fd-backed RGB565 surface in a desktop window and report when the user closes it. Deliberately standalone (no firmware display-PAL dependency) to keep ra8_emulator a self-contained tool. The real Objective-C lives in board_view.m; this header is plain C so main.c needs no AppKit.

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

Since: 0.1.0

Definition in file board_view.h.

Typedef Documentation

◆ board_view_t

typedef struct board_view board_view_t

Opaque desktop-window handle (defined in board_view.m).

Definition at line 31 of file board_view.h.

Function Documentation

◆ board_view_close()

void board_view_close ( board_view_t * view )

Close the window and release its resources.

Parameters

[in] view Handle from board_view_open (nullptr is a no-op).

Close the window and release its resources; this step is contained within the board view model and uses bounded caller or module-owned storage.

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

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

Close the window and release its resources.

Parameters

[in] view Always nullptr from board_view_open (unused).

Definition at line 140 of file board_view_stub.c.

Referenced by priv_run_hold_view().

◆ board_view_open()

board_view_t * board_view_open	(	board_view_storage_t *	storage,
		uint16_t	width_px,
		uint16_t	height_px,
		const char *	title )

Open a desktop window of the given pixel size.

Parameters

[in,out]	storage	Caller-owned zeroed handle storage.
[in]	width_px	Content width in pixels (>= 1).
[in]	height_px	Content height in pixels (>= 1).
[in]	title	NUL-terminated window title (ASCII).

Returns: Window handle, or nullptr on failure.

Open a desktop window of the given pixel size.

Parameters

[in,out]	storage	Caller-owned handle storage (unused, headless).
[in]	width_px	Content width in pixels (unused, headless).
[in]	height_px	Content height in pixels (unused, headless).
[in]	title	Window title (unused, headless).

Returns: Always nullptr – there is no window server off the APPLE path.

Definition at line 35 of file board_view_stub.c.

Referenced by internal_run_open_view().

◆ board_view_poll_click()

bool board_view_poll_click	(	board_view_t *	view,
		uint16_t *	x,
		uint16_t *	y )

Report the most recent unprocessed left mouse-down, once.

Latches the framebuffer-pixel coordinate of the last left-button press on the content view (recorded by the view's mouseDown handler) and returns it to the caller exactly once – the latch is cleared on read, so a held button or repeated polls do not re-report the same press. Coordinates use the framebuffer's top-left origin (row 0 at the top), matching how board_view_present uploads pixels; the view's flipped-Y window space is converted here so the caller never sees AppKit's bottom-left origin. Pump the window (board_view_pump) first so AppKit has delivered the click.

Parameters

[in]	view	Handle from board_view_open (nullptr reports no click).
[out]	x	Click column in framebuffer pixels (top-left origin).
[out]	y	Click row in framebuffer pixels (top-left origin).

Returns: true if a fresh click was reported (and consumed); false otherwise.

Return values

true	The board view poll click condition holds or completed successfully; false otherwise.

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

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

Report the most recent unprocessed left mouse-down, once.

Parameters

[in]	view	Always nullptr from board_view_open (unused).
[out]	x	Click column (unused, never written).
[out]	y	Click row (unused, never written).

Returns: Always false – a headless build reports no clicks.

Definition at line 83 of file board_view_stub.c.

Referenced by internal_run_loop_view().

◆ board_view_poll_drag()

bool board_view_poll_drag	(	board_view_t *	view,
		uint16_t *	x,
		uint16_t *	y )

Report the current position of a held-button drag, once.

Latches the framebuffer-pixel coordinate published by the view's mouseDragged handler while the primary button is held and moved, returning it to the caller once (the latch clears on read). This is independent of board_view_poll_click: the initial press is still reported once via that latch (so a click is routed once), while continued motion updates only the drag latch – letting the run loop follow the cursor for a grabbed control (the battery slider) without re-firing the one-shot press. Coordinates use the framebuffer's top-left origin, matching board_view_poll_click. Pump the window first.

Parameters

[in]	view	Handle from board_view_open (nullptr reports no drag).
[out]	x	Drag column in framebuffer pixels (top-left origin).
[out]	y	Drag row in framebuffer pixels (top-left origin).

Returns: true if a fresh drag position was reported (and consumed); false otherwise.

Since: 0.1.0

Return values

true	The board view poll drag condition holds or completed successfully; false otherwise.

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

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

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

Report the current position of a held-button drag, once.

Parameters

[in]	view	Always nullptr from board_view_open (unused).
[out]	x	Drag column (unused, never written).
[out]	y	Drag row (unused, never written).

Returns: Always false – a headless build reports no drags.

Definition at line 103 of file board_view_stub.c.

Referenced by internal_run_loop_view().

◆ board_view_poll_release()

bool board_view_poll_release ( board_view_t * view )

Report whether the primary mouse button was released since the last poll.

Latches the view's mouseUp event (left button released anywhere over the content view) and returns it to the caller exactly once – the latch clears on read. The run loop uses this to release a momentary on-screen push-button (SW1/SW2) that a prior board_view_poll_click pressed, so the buttons behave as real push-buttons (held only while the mouse is down) rather than latching switches, and to drop a battery-slider grab when the drag ends. Unlike board_view_poll_click/_drag this carries no coordinate – a release is a pure edge. Pump the window (board_view_pump) first so AppKit has delivered the up event.

Parameters

[in] view Handle from board_view_open (nullptr reports no release).

Returns: true if a fresh mouse-up was reported (and consumed); false otherwise.

Since: 0.1.0

Return values

true	The board view poll release condition holds or completed successfully; false otherwise.

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

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

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

Report whether the primary mouse button was released since the last poll.

Parameters

[in] view Always nullptr from board_view_open (unused).

Returns: Always false – a headless build reports no releases.

Definition at line 117 of file board_view_stub.c.

Referenced by internal_run_loop_view().

◆ board_view_poll_scroll()

int32_t board_view_poll_scroll ( board_view_t * view )

Drain the accumulated console scroll-wheel notches since the last poll.

The content view's scrollWheel handler accumulates one notch per wheel / two-finger scroll step (positive scrolling up into older console history, negative scrolling back down toward the newest line). This returns the net accumulated notches and clears the accumulator, so the run loop can advance a console scrollback offset. Independent of board_view_poll_click and of the keyDown path (which feeds the firmware UART RX), so scrolling the console never collides with clicking buttons or typing into the running app.

Parameters

[in] view Handle from board_view_open (nullptr returns 0).

Returns: Net scroll notches since the last poll (+up / -down), 0 if none.

Since: 0.1.0

Return values

value The operation-specific board view poll scroll value.

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

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

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

Drain the accumulated console scroll-wheel notches since the last poll.

Parameters

[in] view Always nullptr from board_view_open (unused).

Returns: Always 0.

Definition at line 129 of file board_view_stub.c.

Referenced by internal_run_loop_view().

◆ board_view_present()

void board_view_present	(	board_view_t *	view,
		emu_presentation_workspace_t *	presentation )

Snapshot an RGB565 fd surface and request a redraw.

The provider owns a separate immutable descriptor snapshot until CoreGraphics releases it, so callbacks cannot race the next emulated frame.

Parameters

[in]	view	Handle from board_view_open (nullptr is a no-op).
[in,out]	presentation	Complete fd surface and snapshot scratch.

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

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

Snapshot an RGB565 fd surface and request a redraw.

Parameters

[in]	view	Always nullptr from board_view_open (unused).
[in,out]	presentation	Fd-backed surface (unused, headless).

Definition at line 53 of file board_view_stub.c.

Referenced by internal_run_view_maybe_present(), and priv_run_hold_view().

◆ board_view_pump()

bool board_view_pump ( board_view_t * view )

Drain pending UI events; report whether the window was closed.

Parameters

[in] view Handle from board_view_open (nullptr returns true).

Returns: true once the user has closed the window (stop the run loop).

Drain pending ui events; report whether the window was closed; this step is contained within the board view model and uses bounded caller or module-owned storage.

Return values

true	The board view pump condition holds or completed successfully; false otherwise.

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

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

Drain pending UI events; report whether the window was closed.

Parameters

[in] view Always nullptr from board_view_open (unused).

Returns: Always true – there is no live window to keep a loop running.

Definition at line 65 of file board_view_stub.c.

Referenced by internal_run_loop_view(), and priv_run_hold_view().

◆ board_view_read_rgb888_fd()

size_t board_view_read_rgb888_fd	(	int	fd,
		off_t	position,
		void *	buffer,
		size_t	count )

Expand an arbitrary byte range from a sealed RGB565 descriptor.

Parameters

[in]	fd	Immutable RGB565 surface descriptor.
[in]	position	Byte position in the virtual 0x00RRGGBB stream.
[out]	buffer	CoreGraphics-supplied destination bytes.
[in]	count	Requested destination byte count.

Returns: Bytes expanded exactly; zero on validation or raw-read failure.

Precondition: fd remains open and immutable for the call.

Postcondition: Success matches the legacy 0x00RRGGBB little-endian upload bytes.

Note: Uses fixed stack chunks and performs no acquisition.

Since: 0.1.0

Expand an arbitrary byte range from a sealed rgb565 descriptor; this step is contained within the board view model and uses bounded caller or module-owned storage.

Return values

value The operation-specific board view read rgb888 descriptor value.

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

Postcondition: Ownership of caller-supplied storage is unchanged.

Definition at line 87 of file board_view_pixels.c.

References internal_available_bytes(), internal_expand_chunk(), k_emu_io_ok, k_view_pixel_chunk, memcpy(), and priv_emu_io_pread_exact().

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ board_view_t

Function Documentation

◆ board_view_close()

◆ board_view_open()

◆ board_view_poll_click()

◆ board_view_poll_drag()

◆ board_view_poll_release()

◆ board_view_poll_scroll()

◆ board_view_present()

◆ board_view_pump()

◆ board_view_read_rgb888_fd()