Graphics LCD Controller driver – layer composition and CLUT. More...

#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_glcdc.h"
#include "ra8_glcdc_regs.h"
#include "ra8_log.h"

Include dependency graph for ra8_glcdc_layer.c:

Enumerations
enum	ra8_glcdc_priv_const_t : uint8_t { k_ra8_glcdc_layer_count = 2U , k_ra8_glcdc_layer1 = 0U , k_ra8_glcdc_dispsel_below = 1U , k_ra8_glcdc_dispsel_above = 2U , k_ra8_glcdc_arcdef_shift = 16U , k_ra8_glcdc_clutsel_shift = 16U , k_ra8_glcdc_word_shift = 16U }
enum	ra8_glcdc_clut_const_t : uint16_t { k_ra8_glcdc_clut_entries = 256U }
enum	ra8_glcdc_priv_mask_t : uint32_t { k_ra8_glcdc_clutsel_mask = 0x10000UL , k_ra8_glcdc_arcon_mask = 0x1000UL }
enum	ra8_glcdc_layout_priv_t : uint32_t { k_glcdc_shift_high = 16U , k_glcdc_shift_flm6_fmt = 28U , k_glcdc_shift_arcdef = 16U , k_glcdc_axi_burst_bytes = 64U , k_glcdc_bpp_rgb565 = 2U }
enum	ra8_glcdc_alpha_priv_t : uint32_t { k_glcdc_alpha_opaque = 0xFFUL }
enum	ra8_glcdc_out_set_fmt_t : uint32_t { k_glcdc_out_set_rgb565 = 2U }

Functions
ra8_err_t	ra8_glcdc_set_layer2 (const ra8_glcdc_layer2_cfg_t *cfg)
	Configure the Graphics 2 (background-image) layer.
ra8_err_t	ra8_glcdc_set_blend (ra8_glcdc_blend_mode_t mode, uint8_t global_alpha)
	Set the layer-1-over-layer-2 blend mode and global alpha.
ra8_err_t	ra8_glcdc_set_background_color (uint32_t argb)
	Set the panel-wide background colour shown where neither layer covers a pixel.
ra8_err_t	ra8_glcdc_layer1_show (uintptr_t fb_addr)
	Implementation of ra8_glcdc_layer1_show.
ra8_err_t	ra8_glcdc_layer2_chroma_key_enable (uint32_t key_rgb888)
	Enable chroma-key transparency on GLCDC graphics layer 2.
ra8_err_t	ra8_glcdc_layer2_show (uintptr_t fb_addr, uint16_t panel_x, uint16_t panel_y, uint16_t fb_w, uint16_t fb_h)
	Make graphics layer 2 visible at the given panel position.
static volatile uint32_t *	internal_clut_plane (uint8_t layer, uint8_t plane)
static volatile uint32_t *	internal_clutint_reg (uint8_t layer)
ra8_err_t	ra8_glcdc_set_clut_double_buffered (uint8_t layer, const uint32_t *clut, uint32_t entries, bool swap_now)
	Update a CLUT plane double-buffered, optionally swapping on the next vsync.

Variables
static const char *	s_tag = "GLCDC"

Detailed Description

Graphics LCD Controller driver – layer composition and CLUT.

Tag: [Ring 3 / HAL] {World: NS}

Runtime layer-composition slice of the RA8D2 GLCDC driver, split out of ra8_glcdc.c to keep each translation unit under the file-size cap. Holds the graphics-layer config helpers (layer 2 background image, layer 1 / layer 2 show, chroma-key), the layer 1 / layer 2 alpha blender, the direct-write background colour, and the double-buffered CLUT update. Mirrors the register order of FSP's r_glcdc_graphics_layer_set and the shadow-CLUT swap pattern in FSP's R_GLCDC_ClutEdit / R_GLCDC_ColorPaletteUpdate. Every register access carries a HUM Ch 63 citation.

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

Since: 0.1.0

Definition in file ra8_glcdc_layer.c.

Enumeration Type Documentation

◆ ra8_glcdc_alpha_priv_t

enum ra8_glcdc_alpha_priv_t : uint32_t

Enumerator
k_glcdc_alpha_opaque	Fully opaque (constant alpha).

Definition at line 72 of file ra8_glcdc_layer.c.

◆ ra8_glcdc_clut_const_t

enum ra8_glcdc_clut_const_t : uint16_t

Enumerator
k_ra8_glcdc_clut_entries	Entries per CLUT plane.

Definition at line 54 of file ra8_glcdc_layer.c.

◆ ra8_glcdc_layout_priv_t

enum ra8_glcdc_layout_priv_t : uint32_t

Enumerator
k_glcdc_shift_high	GLCDC shift high.
k_glcdc_shift_flm6_fmt	GLCDC shift flm6 fmt.
k_glcdc_shift_arcdef	GLCDC shift arcdef.
k_glcdc_axi_burst_bytes	GLCDC axi burst bytes.
k_glcdc_bpp_rgb565	GLCDC bpp rgb565.

Definition at line 63 of file ra8_glcdc_layer.c.

◆ ra8_glcdc_out_set_fmt_t

enum ra8_glcdc_out_set_fmt_t : uint32_t

Enumerator
k_glcdc_out_set_rgb565	GLCDC out set rgb565.

Definition at line 77 of file ra8_glcdc_layer.c.

◆ ra8_glcdc_priv_const_t

enum ra8_glcdc_priv_const_t : uint8_t

Enumerator
k_ra8_glcdc_layer_count	Number of graphics layers.
k_ra8_glcdc_layer1	Layer index for GR[0].
k_ra8_glcdc_dispsel_below	AB1.DISPSEL = lower layer.
k_ra8_glcdc_dispsel_above	AB1.DISPSEL = upper layer.
k_ra8_glcdc_arcdef_shift	AB7.ARCDEF bit shift.
k_ra8_glcdc_clutsel_shift	CLUTINT.SEL bit position.
k_ra8_glcdc_word_shift	16-bit field shift.

Definition at line 44 of file ra8_glcdc_layer.c.

◆ ra8_glcdc_priv_mask_t

enum ra8_glcdc_priv_mask_t : uint32_t

Enumerator
k_ra8_glcdc_clutsel_mask	CLUTINT.SEL bit mask.
k_ra8_glcdc_arcon_mask	AB1.ARCON bit mask.

Definition at line 58 of file ra8_glcdc_layer.c.

Function Documentation

◆ internal_clut_plane()

volatile uint32_t * internal_clut_plane	(	uint8_t	layer,
		uint8_t	plane )

static

Definition at line 390 of file ra8_glcdc_layer.c.

References k_ra8_glcdc_base_addr, k_ra8_glcdc_layer1, k_ra8_glcdc_off_gr1_clut0, k_ra8_glcdc_off_gr1_clut1, k_ra8_glcdc_off_gr2_clut0, and k_ra8_glcdc_off_gr2_clut1.

Referenced by ra8_glcdc_set_clut_double_buffered().

◆ internal_clutint_reg()

volatile uint32_t * internal_clutint_reg ( uint8_t layer )

static

Definition at line 403 of file ra8_glcdc_layer.c.

References k_ra8_glcdc_layer1, k_ra8_glcdc_off_gr1_clutint, k_ra8_glcdc_off_gr2_clutint, and ra8_glcdc_reg32().

Referenced by ra8_glcdc_set_clut_double_buffered().

◆ ra8_glcdc_layer1_show()

ra8_err_t ra8_glcdc_layer1_show ( uintptr_t fb_addr )

nodiscard

Implementation of ra8_glcdc_layer1_show.

Make graphics layer 1 visible by pointing it at a framebuffer.

See header for caller-facing contract. Writes SADDR, alpha=0xFF, DISPSEL=non_transparent, FLMRD=1, then asserts GR1.VEN so the chip commits the layer-1 visibility flip at the next VS.

Parameters

[in] fb_addr Framebuffer base address (see header for dims).

Returns: Always k_ra8_ok (writes can't fail at this point).

Return values

k_ra8_ok Layer 1 visible from next VS.

Precondition: ra8_glcdc_init and ra8_glcdc_start have run.; fb_addr is valid for the framebuffer size from init.

Postcondition: GR1 fetches and composites pixels from fb_addr.; GR1.VEN is asserted (auto-clears at next VS).

Note: Single-threaded; not safe to call from IRQ.

Since: 0.1.0

< Gr1 ven.

< AB1.DISPSEL = ON_LOWER (FSP's BLEND_ON_LOWER_LAYER).

Definition at line 234 of file ra8_glcdc_layer.c.

References k_glcdc_alpha_opaque, k_glcdc_shift_arcdef, k_ra8_glcdc_off_gr1_ab1, k_ra8_glcdc_off_gr1_ab7, k_ra8_glcdc_off_gr1_en, k_ra8_glcdc_off_gr1_flmrd, k_ra8_glcdc_off_gr1_saddr, k_ra8_ok, and ra8_glcdc_reg32().

Referenced by internal_lcd_bringup_panel().

◆ ra8_glcdc_layer2_chroma_key_enable()

ra8_err_t ra8_glcdc_layer2_chroma_key_enable ( uint32_t key_rgb888 )

nodiscard

Enable chroma-key transparency on GLCDC graphics layer 2.

Enable chroma-key transparency on graphics layer 2.

Programmes GR2.AB8 / AB9 with the match/replace colour pair so that every framebuffer pixel matching key_rgb888 composites with alpha=0 (i.e. the lower layer / BG plane shows through). Also asserts the AB1.ARCON bit because some RA parts gate the per-pixel alpha replacement behind ARCON; without it the compositor clamps alpha back to AB7.ARCDEF (0xFF) and the pixel stays opaque. See HUM Ch 63 for the AB7 / AB8 / AB9 layouts.

Parameters

[in] key_rgb888 Chroma-key match colour, 0x00RRGGBB. The function adds an explicit alpha=0xFF for the comparator and masks the supplied value to 24 bits, so callers may pass either 0x00RRGGBB or 0xFFRRGGBB.

Returns: ra8_err_t

Return values

k_ra8_ok Chroma-key enabled; effect lands at next vsync.

Precondition: ra8_glcdc_layer2_show has run (GR2 has a framebuffer and panel position).; Caller serialises GLCDC register access (single-threaded init context, or interrupts masked).

Postcondition: GR2.AB7.CKON=1, GR2.AB8 holds the match colour, GR2.AB9 holds (0, transparent).; GR2.VEN is asserted (auto-clears at next vsync).

Note: Not thread-safe; not ISR-safe.

Since: 0.1.0

< Gr2 ven.

Ab7 ckon.

Ab1 arcon.

Arcdef op.

< AB8 alpha-byte = opaque.

< 24-bit colour mask.

< AB9 = alpha-0 replace.

Definition at line 284 of file ra8_glcdc_layer.c.

References k_glcdc_alpha_opaque, k_glcdc_shift_arcdef, k_ra8_glcdc_off_gr2_ab1, k_ra8_glcdc_off_gr2_ab7, k_ra8_glcdc_off_gr2_ab8, k_ra8_glcdc_off_gr2_ab9, k_ra8_glcdc_off_gr2_en, k_ra8_ok, and ra8_glcdc_reg32().

◆ ra8_glcdc_layer2_show()

ra8_err_t ra8_glcdc_layer2_show	(	uintptr_t	fb_addr,
		uint16_t	panel_x,
		uint16_t	panel_y,
		uint16_t	fb_w,
		uint16_t	fb_h )

nodiscard

Make graphics layer 2 visible at the given panel position.

Make graphics layer 2 visible at an arbitrary panel position.

Programmes GR2's framebuffer pointer, line stride, line count, panel position, alpha, DISPSEL, FLMRD, and asserts GR2.VEN to latch on the next vertical sync. The framebuffer format is hard-coded to RGB565; for other formats use the chroma-key helper after this call.

Parameters

[in]	fb_addr	Layer-2 framebuffer base (RGB565).
[in]	panel_x	Horizontal panel position (GLCDC coords).
[in]	panel_y	Vertical panel position (GLCDC coords).
[in]	fb_w	Framebuffer width in pixels.
[in]	fb_h	Framebuffer height in pixels.

Returns: ra8_err_t

Return values

k_ra8_ok Layer 2 visible from next vsync.

Precondition: ra8_glcdc_init and ra8_glcdc_start have been called.; fb_addr points to an fb_w * fb_h * 2-byte RGB565 framebuffer.

Postcondition: GR2 composites pixels from fb_addr at (panel_x, panel_y).; GR2.VEN is asserted (auto-clears at next vsync).

Note: Single-threaded; not safe to call from IRQ.

Since: 0.1.0

< Gr2 ven.

< AB1.DISPSEL = ON_LOWER (FSP's BLEND_ON_LOWER_LAYER).

Definition at line 340 of file ra8_glcdc_layer.c.

References k_glcdc_alpha_opaque, k_glcdc_axi_burst_bytes, k_glcdc_bpp_rgb565, k_glcdc_out_set_rgb565, k_glcdc_shift_arcdef, k_glcdc_shift_flm6_fmt, k_glcdc_shift_high, k_ra8_glcdc_off_gr2_ab1, k_ra8_glcdc_off_gr2_ab2, k_ra8_glcdc_off_gr2_ab4, k_ra8_glcdc_off_gr2_ab5, k_ra8_glcdc_off_gr2_ab7, k_ra8_glcdc_off_gr2_en, k_ra8_glcdc_off_gr2_flm3, k_ra8_glcdc_off_gr2_flmrd, k_ra8_glcdc_off_gr2_fmt, k_ra8_glcdc_off_gr2_line, k_ra8_glcdc_off_gr2_saddr, k_ra8_glcdc_off_gr2_size, k_ra8_ok, and ra8_glcdc_reg32().

◆ ra8_glcdc_set_background_color()

ra8_err_t ra8_glcdc_set_background_color ( uint32_t argb )

nodiscard

Set the panel-wide background colour shown where neither layer covers a pixel.

Writes argb to BG.BGC. The alpha byte is ignored by hardware but preserved in the register for symmetry with the layer-base colour registers.

Parameters

[in] argb 0xAARRGGBB packed colour.

Returns: ra8_err_t

Return values

k_ra8_ok Always.

Since: 0.1.0

< Bg en ven.

< > 1 frame at 1 GHz CPU.

Definition at line 186 of file ra8_glcdc_layer.c.

References k_ra8_glcdc_off_bg_bgc, k_ra8_glcdc_off_bg_en, k_ra8_ok, and ra8_glcdc_reg32().

Referenced by internal_lcd_bringup_panel(), internal_lcd_bringup_panel(), and main().

◆ ra8_glcdc_set_blend()

ra8_err_t ra8_glcdc_set_blend	(	ra8_glcdc_blend_mode_t	mode,
		uint8_t	global_alpha )

nodiscard

Set the layer-1-over-layer-2 blend mode and global alpha.

Writes layer-1 AB1.DISPSEL / AB1.ARCON and AB7.ARCDEF to select "overwrite", "normal" (top opaque over bottom), or "alpha" (top blended over bottom using per-pixel alpha multiplied by the global alpha argument).

Parameters

[in]	mode	Compositing mode.
[in]	global_alpha	0..255 constant alpha applied in k_ra8_blend_alpha mode (AB7.ARCDEF).

Returns: ra8_err_t

Return values

k_ra8_ok	Blend programmed successfully.
k_ra8_err_invalid_arg	mode was out of range.

Since: 0.1.0

Definition at line 146 of file ra8_glcdc_layer.c.

References k_ra8_blend_alpha, k_ra8_blend_normal, k_ra8_blend_overwrite, k_ra8_err_invalid_arg, k_ra8_glcdc_arcdef_shift, k_ra8_glcdc_arcon_mask, k_ra8_glcdc_dispsel_above, k_ra8_glcdc_dispsel_below, k_ra8_glcdc_off_gr1_ab1, k_ra8_glcdc_off_gr1_ab7, k_ra8_ok, and ra8_glcdc_reg32().

◆ ra8_glcdc_set_clut_double_buffered()

ra8_err_t ra8_glcdc_set_clut_double_buffered	(	uint8_t	layer,
		const uint32_t *	clut,
		uint32_t	entries,
		bool	swap_now )

nodiscard

Update a CLUT plane double-buffered, optionally swapping on the next vsync.

GLCDC keeps two CLUT planes per layer (CLUT0/CLUT1) selected by GR[layer].CLUTINT.SEL. This function writes entries 32-bit ARGB entries into the inactive plane, then either:

leaves SEL alone (swap_now == false): the new table sits ready for a future swap, mirroring FSP's R_GLCDC_ClutEdit "shadow" pattern, or
flips SEL (swap_now == true): the hardware will switch to the freshly-written table at the next vertical sync, mirroring FSP's R_GLCDC_ColorPaletteUpdate.

Parameters

[in]	layer	0 = Graphics 1, 1 = Graphics 2.
[in]	clut	Source array of ARGB8888 entries.
[in]	entries	Number of entries to copy (1..256).
[in]	swap_now	true to flip CLUTINT.SEL after the write.

Returns: ra8_err_t

Return values

k_ra8_ok	Programmed successfully.
k_ra8_err_null_ptr	clut was NULL.
k_ra8_err_invalid_arg	layer >= 2 or entries out of range.

Since: 0.1.0

Definition at line 411 of file ra8_glcdc_layer.c.

References internal_clut_plane(), internal_clutint_reg(), k_ra8_err_invalid_arg, k_ra8_glcdc_clut_entries, k_ra8_glcdc_clutsel_mask, k_ra8_glcdc_clutsel_shift, k_ra8_glcdc_layer_count, k_ra8_ok, RA8_CHECK_NULL_PTR, and s_tag.

◆ ra8_glcdc_set_layer2()

ra8_err_t ra8_glcdc_set_layer2 ( const ra8_glcdc_layer2_cfg_t * cfg )

nodiscard

Configure the Graphics 2 (background-image) layer.

Programmes the per-layer GR2 register block (FLM2/FLM3/FLM5/FLM6/ AB1..AB7) so the layer is read from cfg->framebuffer_addr, placed at (cfg->pos_x, cfg->pos_y) inside the panel viewport with size (cfg->width_px, cfg->height_px), and treated as the lower layer in the blender. The constant alpha is loaded into AB7.ARCDEF and gated by AB1.ARCON when the active blend mode is k_ra8_blend_alpha.

Parameters

[in] cfg Layer configuration. Must be non-NULL.

Returns: ra8_err_t

Return values

k_ra8_ok	Layer 2 programmed successfully.
k_ra8_err_null_ptr	cfg was NULL.

Precondition: GLCDC has been opened via ra8_glcdc_init.; cfg->framebuffer_addr is valid for the chosen pixel format.

Postcondition: GR2_FLM2 == cfg->framebuffer_addr.; GR2 layer is enabled for read (FLMRD.RENB = 1).

Note: Not thread-safe; caller serialises register access.

Since: 0.1.0

Definition at line 91 of file ra8_glcdc_layer.c.

References ra8_glcdc_layer2_cfg_t::alpha, ra8_glcdc_layer2_cfg_t::format, ra8_glcdc_layer2_cfg_t::framebuffer_addr, ra8_glcdc_layer2_cfg_t::height_px, k_ra8_glcdc_arcdef_shift, k_ra8_glcdc_dispsel_below, k_ra8_glcdc_off_gr2_ab1, k_ra8_glcdc_off_gr2_ab2, k_ra8_glcdc_off_gr2_ab4, k_ra8_glcdc_off_gr2_ab5, k_ra8_glcdc_off_gr2_ab7, k_ra8_glcdc_off_gr2_en, k_ra8_glcdc_off_gr2_flm3, k_ra8_glcdc_off_gr2_flmrd, k_ra8_glcdc_off_gr2_fmt, k_ra8_glcdc_off_gr2_line, k_ra8_glcdc_off_gr2_saddr, k_ra8_glcdc_off_gr2_size, k_ra8_glcdc_word_shift, k_ra8_ok, ra8_glcdc_layer2_cfg_t::line_stride_bytes, ra8_glcdc_layer2_cfg_t::pos_x, ra8_glcdc_layer2_cfg_t::pos_y, RA8_CHECK_NULL_PTR, ra8_glcdc_reg32(), ra8_log_info_val, s_tag, and ra8_glcdc_layer2_cfg_t::width_px.

Variable Documentation

◆ s_tag

const char* s_tag = "GLCDC"

static

Definition at line 33 of file ra8_glcdc_layer.c.

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ ra8_glcdc_alpha_priv_t

◆ ra8_glcdc_clut_const_t

◆ ra8_glcdc_layout_priv_t

◆ ra8_glcdc_out_set_fmt_t

◆ ra8_glcdc_priv_const_t

◆ ra8_glcdc_priv_mask_t

Function Documentation

◆ internal_clut_plane()

◆ internal_clutint_reg()

◆ ra8_glcdc_layer1_show()

◆ ra8_glcdc_layer2_chroma_key_enable()

◆ ra8_glcdc_layer2_show()

◆ ra8_glcdc_set_background_color()

◆ ra8_glcdc_set_blend()

◆ ra8_glcdc_set_clut_double_buffered()

◆ ra8_glcdc_set_layer2()

Variable Documentation

◆ s_tag