Video Processing Unit (VPU)

VPU Overview

The Video Processing Unit (VPU) handles all video output on the Sandpiper platform. It supports multiple video modes (320x240, 640x480, 320x480, 640x240) with both 8-bit indexed color and 16-bit RGB color modes. The VPU uses DMA to stream video data from shared memory to the display hardware.

The VPU supports double buffering for smooth animation, hardware palette manipulation, and includes a built-in text console system for displaying text with customizable colors.

Data Structures

EVideoMode

enum EVideoMode
{
    EVM_320_240,    // 320x240 pixels
    EVM_640_480,    // 640x480 pixels
    EVM_320_480,    // 320x480 pixels
    EVM_640_240,    // 640x240 pixels
    EVM_Count
};

Defines the supported video resolutions.

EColorMode

enum EColorMode
{
    ECM_8bit_Indexed,   // 8-bit indexed color (256 colors from palette)
    ECM_16bit_RGB,      // 16-bit direct RGB (R5G6B5)
    ECM_Count
};

Defines the supported color modes.

Color Macros

MAKECOLORRGB24(_r, _g, _b)

Creates a 24-bit RGB color value for setting palette entries. Parameters are 8-bit values (0-255).

MAKECOLORRGB16(_r, _g, _b)

Creates a 16-bit RGB color value (R5G6B5) for direct color mode. Red and blue are 5-bit (0-31), green is 6-bit (0-63).

API Documentation

Initialization / Shutdown

void VPUInitVideo(struct EVideoContext* _context, struct SPPlatform* _platform);

Initializes the video context. Allocates memory for the character and color buffers used by the text console, and sets the default VGA color palette. This must be called before using any other VPU functions.

void VPUShutdownVideo(struct EVideoContext* _context);

Shuts down the video context by freeing allocated resources (character and color buffers).

Video Mode Configuration

void VPUSetVideoMode(struct EVideoContext *_context, const enum EVideoMode _mode, const enum EColorMode _cmode, const enum EVideoScanoutEnable _scanEnable);

Configures the video mode, color mode, and scanout enable settings. Updates the context's state with the new settings including stride, dimensions, and console size.

void VPUGetDimensions(const enum EVideoMode _mode, uint32_t *_width, uint32_t *_height);

Retrieves the width and height dimensions in pixels for a given video mode.

uint32_t VPUGetStride(const enum EVideoMode _mode, const enum EColorMode _cmode);

Calculates the stride (number of bytes per row) for a given video mode and color mode.

Framebuffer Control

void VPUSetScanoutAddress(struct EVideoContext *_context, const uint32_t _scanOutAddress64ByteAligned);

Sets the primary scanout address for the VPU. The address must be 64-byte aligned and should be a physical address obtained from SPAllocateBuffer().

void VPUClear(struct EVideoContext *_context, const uint32_t _colorWord);

Clears the current CPU write page with the specified color. The _colorWord is a 32-bit value containing a 4-pixel wide color pattern.

void VPUSwapPages(struct EVideoContext* _context, struct EVideoSwapContext *_sc);

Swaps the read and write pages for double buffering on the CPU side. Updates the swap context with new read/write pointers and increments the cycle counter.

Synchronization

void VPUSyncSwap(struct EVideoContext *_context, uint8_t _donotwaitforvsync);

Initiates a swap between the two video pages. If _donotwaitforvsync is non-zero, the swap will not wait for vertical sync.

void VPUWaitVSync(struct EVideoContext *_context);

Blocks until the VPU's VBlank counter flips, indicating a new frame has started.

Palette Control

void VPUSetDefaultPalette(struct EVideoContext *_context);

Sets the default VGA color palette by writing all 256 color entries to the hardware.

void VPUSetPal(struct EVideoContext *_context, const uint8_t _paletteIndex, const uint32_t _red, const uint32_t _green, const uint32_t _blue);

Sets a single palette entry. _paletteIndex specifies the palette slot (0-255). RGB values are 0-255.

Console Functions

The VPU includes a built-in text console system with character and color buffers. The console uses an 8x8 pixel built-in font.

void VPUConsoleClear(struct EVideoContext *_context);

Clears the console screen by filling it with spaces and the current background color. Resets the cursor position to the top-left corner.

void VPUConsolePrint(struct EVideoContext *_context, const char *_message, int _length);

Prints a string of text onto the console at the current cursor position. Respects newline, tab, and carriage return characters. Automatically scrolls when reaching the bottom of the screen.

void VPUConsoleSetColors(struct EVideoContext *_context, const uint8_t _foregroundIndex, const uint8_t _backgroundIndex);

Sets both the foreground and background colors for subsequent console text output. Values are palette indices (0-15 for standard console colors).

Example Usage

// Initialize platform and video
struct SPPlatform* platform = SPInitPlatform();
struct EVideoContext videoCtx;
VPUInitVideo(&videoCtx, platform);

// Allocate framebuffers (must be 64-byte aligned)
uint32_t stride = VPUGetStride(EVM_640_480, ECM_8bit_Indexed);
struct SPSizeAlloc framebufferA, framebufferB;
framebufferA.size = stride * 480;
framebufferB.size = stride * 480;
SPAllocateBuffer(platform, &framebufferA);
SPAllocateBuffer(platform, &framebufferB);

// Configure video mode
VPUSetVideoMode(&videoCtx, EVM_640_480, ECM_8bit_Indexed, EVS_Enable);

// Clear screen with black
VPUClear(&videoCtx, 0x00000000);

// Use the console
VPUConsoleSetColors(&videoCtx, CONSOLEWHITE, CONSOLEDIMBLUE);
VPUConsoleClear(&videoCtx);
VPUConsolePrint(&videoCtx, "Hello, Sandpiper!\n", 18);

// Cleanup
VPUShutdownVideo(&videoCtx);
SPShutdownPlatform(platform);