fb_generic

Generic framebuffer abstraction layer for bare-metal Ada applications.

Overview

fb_generic provides a hardware-independent framebuffer interface with automatic double-buffering for embedded systems. It builds on dc_generic and bitmap, managing off-screen buffers in SDRAM and coordinating display updates.

Features

• Automatic double-buffering per layer
• SDRAM allocation for framebuffers
• Bitmap buffer abstraction
• Polling or interrupt-based updates
• Background color control
• Coordinate transformation (swapped displays)
• Zero-copy buffer management

Architecture

The package is organized into three layers:

• FB_Types - Layer state, wait modes, pixel format conversion
• FB_Control - Framebuffer initialization and configuration
• FB_Data - Buffer access and update operations
• FB_Interface - Combined control and data interface

API

FB_Types

package FB_Types is
   type Wait_Mode is (Polling, Interrupt);
   
   type Layer_State is record
      Is_Initialized : Boolean;
      Format         : Pixel_Format;
      X, Y           : Natural;
      W, H           : Positive;
      Buffer_0       : System.Address;
      Buffer_1       : System.Address;
      Hidden         : Natural;  -- 0 or 1
   end record;
   
   function To_Color_Mode (F : Pixel_Format) return Bitmap_Color_Mode;
end FB_Types;

FB_Interface

generic
   LCD_Width  : Positive;
   LCD_Height : Positive;
   Swapped    : Boolean := False;
   
   --  DC control plane
   with procedure DC_Initialize;
   with function  DC_Is_Initialized return Boolean;
   with procedure DC_Set_Background (R, G, B : UInt8);
   with procedure DC_Reload (Mode : Reload_Mode);
   with procedure DC_Reload_Async;
   with procedure DC_Wait_For_Reload;
   with procedure DC_Set_Frame_Buffer (Layer : LCD_Layer; Addr : System.Address);
   
   --  DC data plane
   with procedure DC_Layer_Init (...);
   with function DC_Get_Frame_Buffer (Layer : LCD_Layer) return System.Address;
   
   --  SDRAM allocator
   with function Driver_Reserve (Amount, Align : UInt32) return System.Address;
   with procedure Driver_Fill (Addr : System.Address; Size : UInt32; Value : UInt8 := 0);

package FB_Interface is
   procedure Initialize (Mode : Wait_Mode := Interrupt);
   
   procedure Initialize_Layer
     (Layer  : LCD_Layer;
      Format : Pixel_Format;
      X, Y   : Natural  := 0;
      Width, Height : Positive := LCD_Width);
   
   function Initialized (Layer : LCD_Layer) return Boolean;
   function Get_Hidden_Buffer (Layer : LCD_Layer) return Bitmap_Buffer;
   function Get_Color_Mode (Layer : LCD_Layer) return Bitmap_Color_Mode;
   function Get_Pixel_Size (Layer : LCD_Layer) return Positive;
   
   procedure Set_Background (R, G, B : UInt8);
   function Get_Width  return Positive;
   function Get_Height return Positive;
   function Is_Swapped return Boolean;
   
   procedure Update_Layer (Layer : LCD_Layer; Copy_Back : Boolean := False);
   procedure Update_Layers;
end FB_Interface;

Usage

Application code draws to the hidden buffer returned by Get_Hidden_Buffer, then calls Update_Layer to swap buffers and trigger display refresh.

Design Rationale

Double-Buffering

Each layer maintains two buffers. One is visible (on-screen), the other is hidden (writable). Update_Layer swaps them atomically.

SDRAM Integration

Framebuffers are allocated from SDRAM via Driver_Reserve, enabling large displays without exhausting internal RAM.

Copy-Back Option

Update_Layer (Layer, Copy_Back => True) copies the visible buffer to the new hidden buffer, enabling incremental rendering.

Integration

Add to your alire.toml:

[[depends-on]]
fb_generic = "^0.1.0"

Dependencies

• bitmap - Bitmap types and color modes
• dc_generic - Display controller interface

Used By

• stm32f746g_disco - STM32F746G-DISCO board support

License

MIT OR Apache-2.0 WITH LLVM-exception