FBGL: Framebuffer Graphics Library

A high-performance, production-ready framebuffer graphics library for Linux systems. FBGL delivers direct hardware-level rendering capabilities through a clean, well-documented API, optimized for embedded systems, industrial applications, and performance-critical graphics workloads.

Overview
Technical Specifications
Installation
API Documentation
Implementation Examples
Performance Characteristics
Development & Testing
Architecture
Contributing
License

Overview

FBGL (Framebuffer Graphics Library) is a single-header C library providing comprehensive 2D graphics primitives with direct Linux framebuffer device access. Designed for scenarios requiring minimal system overhead and deterministic rendering performance, FBGL eliminates dependencies on complex graphics stacks while maintaining a robust feature set.

Primary Use Cases

Embedded Systems: Resource-constrained environments requiring efficient graphics rendering
Industrial Control Panels: Real-time display systems with strict performance requirements
Digital Signage: Kiosk and information display systems
Boot Graphics: Pre-desktop environment visual feedback
Prototyping: Rapid development of graphics concepts without framework overhead
Educational: Low-level graphics programming instruction

Design Principles

Minimal Footprint: Header-only architecture with zero external dependencies
Predictable Performance: Direct memory access with deterministic execution paths
API Clarity: Intuitive function signatures following industry conventions
Production Ready: Comprehensive error handling and boundary validation
Standards Compliance: POSIX-compliant implementation using standard Linux interfaces

Technical Specifications

Core Features

Rendering Capabilities

Pixel-level manipulation with bounds checking
Anti-aliased line rendering using Bresenham's algorithm
Geometric primitives: rectangles, circles (filled and outlined variants)
Texture mapping with alpha channel compositing
Bitmap font rendering with PSF1 format support

System Integration

Direct memory-mapped framebuffer I/O
Non-blocking keyboard input with escape sequence handling
Frame timing utilities for animation synchronization
Configurable validation levels for development vs. production builds

Supported Formats

Textures: TGA (24-bit RGB, 32-bit RGBA with transparency)
Fonts: PSF1 (PC Screen Font version 1)
Color Space: 32-bit ARGB with byte-aligned channels

Platform Requirements

Operating System: Linux kernel 2.6+ with framebuffer support
Compiler: C99-compliant compiler (GCC 4.8+, Clang 3.4+)
Runtime: Standard C library, POSIX threads support
Permissions: Read/write access to framebuffer device (/dev/fb0 or equivalent)
Architecture: Platform-independent (tested on x86_64, ARM, ARM64)

Installation

FBGL implements a header-only architecture requiring no pre-compilation or linking. Integration into existing projects follows standard C header inclusion patterns.

Integration Steps

Acquire Source: Clone repository or download fbgl.h
```
git clone https://github.com/lvntky/fbgl.git
```
Include Header: Add to project with implementation macro in exactly one translation unit
```
// In main.c or dedicated fbgl.c
#define FBGL_IMPLEMENTATION
#include "fbgl.h"
```

Compile: Link against math library

gcc -std=c99 -O2 -o application main.c -lm

Build Configuration

Optional Preprocessor Directives:

FBGL_VALIDATE_PUT_PIXEL: Enable runtime bounds checking for pixel operations (development builds)
DEBUG: Enable verbose error reporting and diagnostic output

Example Makefile:

CC = gcc
CFLAGS = -std=c99 -O2 -Wall -Wextra
LDFLAGS = -lm

TARGET = application
SOURCES = main.c

$(TARGET): $(SOURCES)
	$(CC) $(CFLAGS) -o $@ $^ $(LDFLAGS)

clean:
	rm -f $(TARGET)

API Documentation

Initialization & Lifecycle Management

int fbgl_init(const char *device, fbgl_t *fb);

Description: Initialize framebuffer context with specified device.
Parameters:

device: Path to framebuffer device (use NULL for default /dev/fb0)
fb: Pointer to framebuffer context structure
Returns: 0 on success, -1 on failure with errno set appropriately
Thread Safety: Not thread-safe; call from single thread during initialization

void fbgl_destroy(fbgl_t *fb);

Description: Release framebuffer resources and unmap memory.
Parameters:

fb: Pointer to initialized framebuffer context
Thread Safety: Not thread-safe; ensure all rendering operations complete before calling

Rendering Primitives

void fbgl_put_pixel(int x, int y, uint32_t color, fbgl_t *fb);

Description: Write single pixel at specified coordinates.
Parameters:

x, y: Pixel coordinates in screen space
color: 32-bit ARGB color value
fb: Framebuffer context
Performance: O(1) operation, suitable for high-frequency calls
Notes: Bounds checking only active when FBGL_VALIDATE_PUT_PIXEL defined

void fbgl_draw_line(fbgl_point_t start, fbgl_point_t end, 
                    uint32_t color, fbgl_t *fb);

Description: Render line segment using Bresenham's algorithm.
Parameters:

start: Starting point coordinates
end: Ending point coordinates
color: Line color
fb: Framebuffer context
Complexity: O(max(dx, dy)) where dx, dy are coordinate deltas

void fbgl_draw_rectangle_filled(fbgl_point_t top_left, 
                                fbgl_point_t bottom_right,
                                uint32_t color, fbgl_t *fb);

Description: Render filled axis-aligned rectangle.
Parameters:

top_left: Upper-left corner coordinates
bottom_right: Lower-right corner coordinates
color: Fill color
fb: Framebuffer context
Complexity: O(width × height)

void fbgl_draw_circle_filled(int x, int y, int radius, 
                             uint32_t color, fbgl_t *fb);

Description: Render filled circle using optimized scanline algorithm.
Parameters:

x, y: Center point coordinates
radius: Circle radius in pixels
color: Fill color
fb: Framebuffer context
Complexity: O(radius²)

Texture Operations

fbgl_tga_texture_t *fbgl_load_tga_texture(const char *path);

Description: Load TGA texture from filesystem with automatic format detection.
Parameters:

path: Filesystem path to TGA file
Returns: Texture handle on success, NULL on failure
Supported Formats: 24-bit RGB, 32-bit RGBA (uncompressed)
Memory Management: Caller responsible for deallocation via fbgl_destroy_texture()

void fbgl_draw_texture(fbgl_t *fb, const fbgl_tga_texture_t *texture,
                       int32_t x, int32_t y);

Description: Blit texture to framebuffer with alpha blending support.
Parameters:

fb: Framebuffer context
texture: Source texture handle
x, y: Destination coordinates (top-left corner)
Complexity: O(texture_width × texture_height)
Notes: Automatically clips to viewport boundaries

void fbgl_destroy_texture(fbgl_tga_texture_t *texture);

Description: Release texture resources.
Parameters:

texture: Texture handle to deallocate
Thread Safety: Not thread-safe with concurrent texture operations

Typography

fbgl_psf1_font_t *fbgl_load_psf1_font(const char *path);

Description: Load PSF1 bitmap font from file.
Parameters:

path: Filesystem path to PSF1 font file
Returns: Font handle on success, NULL on failure
Font Properties: 8-pixel fixed width, variable height, 256 or 512 glyphs

void fbgl_render_psf1_text(fbgl_t *fb, fbgl_psf1_font_t *font,
                           const char *text, int x, int y, 
                           uint32_t color);

Description: Render text string using bitmap font.
Parameters:

fb: Framebuffer context
font: Font handle
text: NULL-terminated string
x, y: Text baseline coordinates
color: Text color
Complexity: O(string_length × glyph_height × glyph_width)

Input Handling

int fbgl_keyboard_init(void);

Description: Initialize non-blocking keyboard input system.
Returns: 0 on success, -1 on failure
Side Effects: Modifies terminal attributes; automatically restored on exit

fbgl_key_t fbgl_get_key(void);

Description: Poll for keyboard input without blocking.
Returns: Key code constant or FBGL_KEY_NONE if no input available
Supported Keys: Arrow keys, WASD, Enter, Space, Escape

bool fbgl_is_key_pressed(fbgl_key_t key);

Description: Check if specific key is currently pressed.
Parameters:

key: Key code to check
Returns: true if key pressed, false otherwise

void fbgl_destroy_keyboard(void);

Description: Restore terminal attributes and cleanup input system.

Utility Functions

float fbgl_get_fps(void);

Description: Calculate instantaneous frame rate based on frame timing.
Returns: Frames per second as floating-point value
Usage: Call once per frame after rendering operations

uint32_

Fbgl

Install / Use

README