Test-access surface for ra8_drw internal helpers (MC/DC). More...

#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_drw.h"

Include dependency graph for ra8_drw_internal.h:

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

Enumerations
enum	ra8_drw_internal_const_t : uint16_t { k_ra8_drw_internal_byte_mask = 0x00FFU , k_ra8_drw_internal_one_subpx = 16U , k_ra8_drw_internal_clut_max = 256U , k_ra8_drw_internal_dlist_align = 4U , k_ra8_drw_internal_perfev_max = 0x001FU }
	Driver-internal numeric constants – avoid bare literals. More...
enum	ra8_drw_internal_mask32_t : uint32_t { k_ra8_drw_internal_color_alpha_mask = 0x00FFFFFFUL , k_ra8_drw_internal_align_mask = 0x00000003UL }
	32-bit driver-internal masks. More...

Functions
static uint32_t	internal_to_subpixel (int32_t px)
	Convert a signed pixel coordinate to the DRW Q12.4 sub-pixel grid.
static int32_t	internal_iabs (int32_t v)
	Compute integer absolute value with no library calls.
void	priv_program_rect_bbox (const ra8_drw_rect_t *rect)
	Programme the bounding box that describes an axis-aligned rect.
uint32_t	priv_ra8_drw_internal_rect_origin (const ra8_drw_rect_t *rect)
	Framebuffer byte address of a rectangle's top-left pixel.
bool	priv_ra8_drw_internal_rect_off_surface (const ra8_drw_rect_t *rect)
	Reject a rectangle that would rasterize outside the framebuffer.
bool	priv_ra8_drw_internal_rect_below_min (uint16_t min_dim, uint16_t width, uint16_t height)
	Pure predicate for the "rect is below min dim" rejection.
bool	priv_ra8_drw_internal_rect_above_max (uint16_t max_w, uint16_t max_h, uint16_t width, uint16_t height)
	Pure predicate for the "rect exceeds max dim" rejection.
uint32_t	priv_ra8_drw_internal_origin (void)
	Read the cached ORIGIN (framebuffer base) render-trigger value.
void	priv_ra8_drw_internal_color1_write (uint32_t argb8888)
	Write COLOR1 through the software shadow (write-only register).

Detailed Description

Test-access surface for ra8_drw internal helpers (MC/DC).

Declares module-private geometry helpers shared by the DRW command and drawing translation units.

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

Definition in file ra8_drw_internal.h.

Enumeration Type Documentation

◆ ra8_drw_internal_const_t

enum ra8_drw_internal_const_t : uint16_t

Driver-internal numeric constants – avoid bare literals.

Shared between ra8_drw.c and ra8_drw_draw.c so the surface-setup TU and the geometry-primitive TU draw on the same named constants.

Invariant: Every member fits in uint16_t.

See also: ra8_drw_internal_mask32_t

Enumerator
k_ra8_drw_internal_byte_mask	8-bit channel mask.
k_ra8_drw_internal_one_subpx	1 px == 16 sub-pixels.
k_ra8_drw_internal_clut_max	CLUT entries (HUM 62.5.4).
k_ra8_drw_internal_dlist_align	4-byte alignment of DLIST.
k_ra8_drw_internal_perfev_max	0x1F is "every clock".

Definition at line 35 of file ra8_drw_internal.h.

◆ ra8_drw_internal_mask32_t

enum ra8_drw_internal_mask32_t : uint32_t

32-bit driver-internal masks.

Shared between ra8_drw.c and ra8_drw_draw.c.

Invariant: Every member fits in uint32_t.

See also: ra8_drw_internal_const_t

Enumerator
k_ra8_drw_internal_color_alpha_mask	0x00RRGGBB low bits.
k_ra8_drw_internal_align_mask	4-byte alignment.

Definition at line 54 of file ra8_drw_internal.h.

Function Documentation

◆ internal_iabs()

int32_t internal_iabs ( int32_t v )

inlinestatic

Compute integer absolute value with no library calls.

Branch-on-sign absolute value, used by the line and triangle primitives. Shared between DRW TUs.

Parameters

[in] v Signed value (range [-32768, 32767]).

Returns: Non-negative absolute value cast to int32_t.

Return values

-v	When `v` is negative (v < 0): the arithmetic negation.
v	When `v` is non-negative (v >= 0): `v` unchanged.

Precondition: v may be any int32_t except INT32_MIN.; Result fits in int32_t.

Postcondition: Returned value is >= 0.; No side effects.

Note: Pure; thread-safe.

Since: 0.1.0

Definition at line 110 of file ra8_drw_internal.h.

References RA8_INTERNAL.

Referenced by internal_program_line_limiters().

◆ internal_to_subpixel()

uint32_t internal_to_subpixel ( int32_t px )

inlinestatic

Convert a signed pixel coordinate to the DRW Q12.4 sub-pixel grid.

Shifts px left by the sub-pixel shift so 1 px maps to 16 sub-pixels. Shared by both DRW TUs (surface setup and geometry primitives).

Parameters

[in] px Pixel coordinate (signed, in [-32768, 32767] range – the framebuffer never grows beyond 1024x1024).

Returns: Sub-pixel value (px << 4), wrapped to uint32_t.

Return values

(uint32_t)px<<4 The coordinate scaled by 16 sub-pixels per pixel; two's-complement wrap makes a negative px yield the bit-identical unsigned Q12.4 value.

Precondition: Caller has range-checked px upstream.; The shift cannot overflow 32 bits for the supported FB size.

Postcondition: Returned value preserves bit width and is suitable for LnSTART / LnXADD / LnYADD writes.; No side effects.

Note: Pure; thread-safe.

Since: 0.1.0

Definition at line 82 of file ra8_drw_internal.h.

References k_ra8_drw_subpixel_shift, and RA8_INTERNAL.

Referenced by internal_program_line_limiters(), and ra8_drw_draw_triangle().

◆ priv_program_rect_bbox()

void priv_program_rect_bbox ( const ra8_drw_rect_t * rect )

Programme the bounding box that describes an axis-aligned rect.

Writes SIZE (HUM Ch 62.2.29 p 3704) and clears the six spatial limiters (HUM Ch 62.2.10-62.2.12 pp 3698-3699). An axis-aligned solid rectangle needs NO limiter: HUM Ch 62.6.2 p 3716 has the engine scan "the whole bounding box" anchored at ORIGIN, so the box scan already produces exactly the requested extent. Position comes from ORIGIN, which the caller writes last because that write is the render trigger (HUM Ch 62.2.31 p 3705).

Shared between ra8_drw.c and ra8_drw_draw.c so the solid-fill and the textured-blit primitive describe their extent identically.

Parameters

[in] rect Rectangle in pixel space (validated by caller).

Precondition: rect dimensions in [1..1024].; Driver initialized.

Postcondition: SIZE = (height << 16) | width.; L1..L4 START / XADD / YADD are all zero.

Note: Not thread-safe; writes MMIO.

Since: 0.1.0

Definition at line 416 of file ra8_drw.c.

References ra8_drw_rect_t::height_px, k_ra8_drw_off_l1start, k_ra8_drw_off_l1xadd, k_ra8_drw_off_l1yadd, k_ra8_drw_off_l2start, k_ra8_drw_off_l2xadd, k_ra8_drw_off_l2yadd, k_ra8_drw_off_l3start, k_ra8_drw_off_l3xadd, k_ra8_drw_off_l3yadd, k_ra8_drw_off_l4start, k_ra8_drw_off_l4xadd, k_ra8_drw_off_l4yadd, k_ra8_drw_off_size, k_ra8_drw_size_height_pos, ra8_drw_reg32(), and ra8_drw_rect_t::width_px.

Referenced by ra8_drw_blit_textured_rect(), and ra8_drw_fill_rect().

◆ priv_ra8_drw_internal_color1_write()

void priv_ra8_drw_internal_color1_write ( uint32_t argb8888 )

Write COLOR1 through the software shadow (write-only register).

COLOR1 – like the whole DRW register file – is write-only on silicon (HUM Ch 62.2.7, R/W column "W"), so the alpha-preserving update in ra8_drw_set_blend cannot read the current value back from hardware. Every COLOR1 write in both DRW TUs goes through this helper, which writes the register and keeps the driver-side shadow coherent.

Parameters

[in] argb8888 Full 0xAARRGGBB value to program.

Precondition: ra8_drw_init succeeded (DRW clock enabled).; argb8888 is the complete register value (no partial masks).

Postcondition: COLOR1 holds argb8888.; The driver shadow matches the register.

Note: Not thread-safe; writes MMIO.

Since: 0.1.0

Write COLOR1 through the software shadow (write-only register).

Definition at line 238 of file ra8_drw.c.

References k_ra8_drw_off_color1, ra8_drw_reg32(), and s_drw_color1.

Referenced by ra8_drw_draw_line(), ra8_drw_draw_triangle(), ra8_drw_fill_rect(), ra8_drw_set_blend(), and ra8_drw_set_gradient().

◆ priv_ra8_drw_internal_origin()

uint32_t priv_ra8_drw_internal_origin ( void )

Read the cached ORIGIN (framebuffer base) render-trigger value.

HUM Ch 62.2.31: writing ORIGIN triggers the start of rendering, so every geometry primitive in ra8_drw_draw.c re-writes it as its final step. The value is cached by ra8_drw_init (the DRW register file is write-only, so it cannot be read back from hardware).

Returns: The framebuffer base address programmed at init.

Return values

0	Driver not initialized (or de-initialized).
addr	The 32-bit framebuffer base from ra8_drw_init.

Precondition: ra8_drw_init succeeded (else returns 0).; None.

Postcondition: No state mutated.; Return depends solely on the cached init value.

Note: Shared between the two DRW TUs; not thread-safe with a concurrent re-init.

Since: 0.1.0

Read the cached ORIGIN (framebuffer base) render-trigger value.

Definition at line 212 of file ra8_drw.c.

References s_drw_origin.

Referenced by ra8_drw_draw_line(), and ra8_drw_draw_triangle().

◆ priv_ra8_drw_internal_rect_above_max()

bool priv_ra8_drw_internal_rect_above_max	(	uint16_t	max_w,
		uint16_t	max_h,
		uint16_t	width,
		uint16_t	height )

Pure predicate for the "rect exceeds max dim" rejection.

Returns true iff width exceeds max_w or height exceeds max_h. Promoted from the inline compound OR at libs/ra8_hal/src/ra8_drw.c inside ra8_drw_blit_textured_rect.

Parameters

[in]	max_w	Maximum permitted width (1024 px).
[in]	max_h	Maximum permitted height (1024 px).
[in]	width	Width in pixels.
[in]	height	Height in pixels.

Returns: Boolean reject predicate.

Return values

true	Caller must return `k_ra8_err_invalid_arg`.
false	Dimensions are within both upper bounds.

Precondition: None.; None.

Postcondition: No state mutated.; Return depends solely on the four inputs.

Note: Test-access only. Pure function.

MC/DC:

2-condition OR; N+1 = 3 vectors:

w<=max_w, h<=max_h -> false
w>max_w, h<=max_h -> true (varies left)
w<=max_w, h>max_h -> true (varies right)

Since: 0.1.0

Pure predicate for the "rect exceeds max dim" rejection.

Promoted helper so the line-780 OR can be driven under MC/DC.

Parameters

[in]	max_w	Maximum permitted width.
[in]	max_h	Maximum permitted height.
[in]	width	Width in pixels.
[in]	height	Height in pixels.

Returns: Boolean reject predicate.

Return values

true	Dimension above max.
false	Both within bounds.

Precondition: None.; None.

Postcondition: No state mutated.; Return depends solely on inputs.

Note: Pure; thread-safe.

Since: 0.1.0

Definition at line 97 of file ra8_drw.c.

Referenced by ra8_drw_blit_textured_rect(), and ra8_drw_dlist_add_fill().

◆ priv_ra8_drw_internal_rect_below_min()

bool priv_ra8_drw_internal_rect_below_min	(	uint16_t	min_dim,
		uint16_t	width,
		uint16_t	height )

Pure predicate for the "rect is below min dim" rejection.

Returns true iff width or height is below min_dim. Promoted from the inline compound OR at libs/ra8_hal/src/ra8_drw.c inside ra8_drw_blit_textured_rect.

Parameters

[in]	min_dim	Minimum permitted dimension (1 px).
[in]	width	Width in pixels.
[in]	height	Height in pixels.

Returns: Boolean reject predicate.

Return values

true	Caller must return `k_ra8_err_invalid_arg`.
false	Dimensions meet the lower bound.

Precondition: None.; None.

Postcondition: No state mutated.; Return depends solely on the three inputs.

Note: Test-access only. Pure function.

MC/DC:

2-condition OR; N+1 = 3 vectors:

w>=min, h>=min -> false
w<min, h>=min -> true (varies left)
w>=min, h<min -> true (varies right)

Since: 0.1.0

Pure predicate for the "rect is below min dim" rejection.

Promoted helper so the line-776 OR can be driven under MC/DC.

Parameters

[in]	min_dim	Minimum permitted dimension (1 px).
[in]	width	Width in pixels.
[in]	height	Height in pixels.

Returns: Boolean reject predicate.

Return values

true	Dimension below min.
false	Both dimensions in range.

Precondition: None.; None.

Postcondition: No state mutated.; Return depends solely on inputs.

Note: Pure; thread-safe.

Since: 0.1.0

Definition at line 75 of file ra8_drw.c.

Referenced by ra8_drw_blit_textured_rect(), and ra8_drw_dlist_add_fill().

◆ priv_ra8_drw_internal_rect_off_surface()

bool priv_ra8_drw_internal_rect_off_surface ( const ra8_drw_rect_t * rect )

Reject a rectangle that would rasterize outside the framebuffer.

With the bounding box positioned by ORIGIN there is no limiter clipping left to contain an out-of-range rectangle, so a negative origin or a right edge past the pitch would have the engine scribble over unrelated memory. Callers must reject before triggering a render.

Parameters

[in] rect Rectangle in pixel space.

Returns: Boolean reject predicate.

Return values

true	Caller must return `k_ra8_err_invalid_arg`.
false	The rect starts on the surface and fits the pitch.

Precondition: Driver initialized (pitch cached).; rect is non-null.

Postcondition: No state mutated.; Return depends only on rect and the cached pitch.

MC/DC:

Decision rect->x < 0 || rect->y < 0 (2 conditions), then the independent right > pitch test. N+1 = 3 vectors for the OR:

x>=0, y>=0 -> false (control)
x<0, y>=0 -> true (varies x)
x>=0, y<0 -> true (varies y)

Note: Not thread-safe; reads driver-private state.

Since: 0.1.0

Definition at line 225 of file ra8_drw.c.

References s_drw_pitch_px, ra8_drw_rect_t::width_px, ra8_drw_rect_t::x, and ra8_drw_rect_t::y.

Referenced by ra8_drw_blit_textured_rect(), ra8_drw_dlist_add_fill(), and ra8_drw_fill_rect().

◆ priv_ra8_drw_internal_rect_origin()

uint32_t priv_ra8_drw_internal_rect_origin ( const ra8_drw_rect_t * rect )

Framebuffer byte address of a rectangle's top-left pixel.

The engine scans its bounding box anchored at ORIGIN (HUM Ch 62.6.2 p 3716), so a primitive is positioned by pointing ORIGIN at its own top-left pixel rather than at the framebuffer base. Computes base + ((y * pitch) + x) * bytes_per_px from the geometry cached at ra8_drw_init.

Parameters

[in] rect Rectangle in pixel space (validated by caller).

Returns: Absolute byte address to write to ORIGIN.

Return values

base	The rect is at (0, 0).

Precondition: Driver initialized (pitch and pixel stride cached).; rect lies on the surface – see priv_ra8_drw_internal_rect_off_surface.

Postcondition: No state mutated.; Result is within the framebuffer for an on-surface rect.

Note: Pure with respect to hardware; reads driver-private state.

Since: 0.1.0

Definition at line 217 of file ra8_drw.c.

References s_drw_bytes_px, s_drw_origin, s_drw_pitch_px, ra8_drw_rect_t::x, and ra8_drw_rect_t::y.

Referenced by ra8_drw_blit_textured_rect(), ra8_drw_dlist_add_fill(), and ra8_drw_fill_rect().

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ ra8_drw_internal_const_t

◆ ra8_drw_internal_mask32_t

Function Documentation

◆ internal_iabs()

◆ internal_to_subpixel()

◆ priv_program_rect_bbox()

◆ priv_ra8_drw_internal_color1_write()

◆ priv_ra8_drw_internal_origin()

◆ priv_ra8_drw_internal_rect_above_max()

◆ priv_ra8_drw_internal_rect_below_min()

◆ priv_ra8_drw_internal_rect_off_surface()

◆ priv_ra8_drw_internal_rect_origin()