Platforms and Drivers¶

PixelRoot32 supports multiple platforms through driver abstraction. This guide covers supported platforms, display drivers, audio backends, and build configuration.

Supported Platforms¶

ESP32¶

Primary platform for PixelRoot32 games.

Characteristics: - TFT_eSPI display driver - Internal DAC or I2S audio - GPIO button input - Limited RAM/Flash - Real hardware constraints

Use for: - Final game deployment - Hardware testing - Production builds

Native/Desktop (SDL2)¶

Development platform for rapid iteration.

Characteristics: - SDL2 display driver - SDL2 audio backend - Keyboard input - Unlimited resources (for testing) - Fast development cycle

Use for: - Development and debugging - Testing without hardware - Rapid prototyping - CI/CD testing

Display Drivers¶

TFT_eSPI (ESP32)¶

TFT_eSPI is the display driver for ESP32, supporting many TFT displays.

Configuration¶

Configure TFT_eSPI via build flags in platformio.ini:

[env:esp32dev]
build_flags = 
    -D ST7789_DRIVER          # Display type
    -D TFT_WIDTH=240          # Display width
    -D TFT_HEIGHT=240         # Display height
    -D TFT_MOSI=23            # SPI MOSI pin
    -D TFT_SCLK=18            # SPI clock pin
    -D TFT_DC=2               # Data/Command pin
    -D TFT_RST=4              # Reset pin
    -D TFT_CS=-1              # Chip select (-1 if not used)
    -D SPI_FREQUENCY=40000000 # SPI frequency

Supported Displays¶

ST7735: 128x128, 128x160
ST7789: 240x240, 240x320
ILI9341: 240x320
And more: See TFT_eSPI documentation

Usage¶

#include <drivers/esp32/TFT_eSPI_Drawer.h>

// Display configuration
pixelroot32::graphics::DisplayConfig displayConfig(
    pixelroot32::graphics::DisplayType::ST7789,
    0,      // rotation
    240,    // width
    240     // height
);

// TFT_eSPI_Drawer is created automatically by Engine
// No manual driver creation needed

SDL2_Drawer (Native)¶

SDL2_Drawer provides display output for PC/desktop development.

Configuration¶

#include <drivers/native/SDL2_Drawer.h>

// Display configuration (NONE defaults to SDL2)
pixelroot32::graphics::DisplayConfig displayConfig(
    pixelroot32::graphics::DisplayType::NONE,
    0,      // rotation
    240,    // width
    240     // height
);

// SDL2_Drawer is created automatically

SDL2 Installation¶

Windows (MSYS2):

pacman -S mingw-w64-x86_64-SDL2

Linux:

sudo apt-get install libsdl2-dev

macOS:

brew install sdl2

Audio Backends¶

ESP32_DAC_AudioBackend¶

Uses ESP32's internal DAC for audio output.

Configuration¶

#include <drivers/esp32/ESP32_DAC_AudioBackend.h>

const int DAC_PIN = 25; // GPIO 25 or 26
pixelroot32::drivers::esp32::ESP32_DAC_AudioBackend audioBackend(
    DAC_PIN,    // DAC pin (25 or 26)
    11025       // Sample rate (Hz)
);

pixelroot32::audio::AudioConfig audioConfig(
    &audioBackend, 
    audioBackend.getSampleRate()
);

Characteristics: - Simple setup (just one pin) - Lower quality than I2S - Good for basic audio - Sample rate: 11025 Hz recommended

ESP32_I2S_AudioBackend¶

Uses ESP32's I2S peripheral for higher quality audio.

Configuration¶

#include <drivers/esp32/ESP32_I2S_AudioBackend.h>

const int I2S_BCLK = 26;  // Bit clock pin
const int I2S_LRCK = 25;  // Left/Right clock pin
const int I2S_DOUT = 22;  // Data out pin

pixelroot32::drivers::esp32::ESP32_I2S_AudioBackend audioBackend(
    I2S_BCLK,
    I2S_LRCK,
    I2S_DOUT,
    22050  // Sample rate (Hz)
);

pixelroot32::audio::AudioConfig audioConfig(&audioBackend, 22050);

Characteristics: - Higher quality than DAC - Requires external I2S DAC (e.g., MAX98357A) - Better for music - Sample rate: 22050 Hz recommended

SDL2_AudioBackend (Native)¶

SDL2 audio for PC development.

Configuration¶

#include <drivers/native/SDL2_AudioBackend.h>

pixelroot32::drivers::native::SDL2_AudioBackend audioBackend(
    22050,  // Sample rate
    1024    // Buffer size
);

pixelroot32::audio::AudioConfig audioConfig(&audioBackend, 22050);

Build Flags¶

Experimental Features¶

Enable experimental features with build flags:

[env:esp32dev]
build_flags = 
    -D PIXELROOT32_ENABLE_2BPP_SPRITES    # Enable 2bpp sprite format
    -D PIXELROOT32_ENABLE_4BPP_SPRITES   # Enable 4bpp sprite format
    -D PIXELROOT32_ENABLE_SCENE_ARENA    # Enable Scene Arena (experimental)

Platform Detection¶

#ifdef PLATFORM_ESP32
    // ESP32-specific code
    Serial.println("Running on ESP32");
#endif

#ifdef PLATFORM_NATIVE
    // Native/PC-specific code
    printf("Running on PC\n");
#endif

Optimization Flags¶

[env:esp32dev]
build_flags = 
    -O2              # Optimization level
    -ffunction-sections
    -fdata-sections
    -Wl,--gc-sections

Complete Platform Setup Examples¶

ESP32 Complete Setup¶

#include <Arduino.h>
#include <core/Engine.h>
#include <drivers/esp32/TFT_eSPI_Drawer.h>
#include <drivers/esp32/ESP32_DAC_AudioBackend.h>

namespace pr32 = pixelroot32;

// Audio
const int DAC_PIN = 25;
pr32::drivers::esp32::ESP32_DAC_AudioBackend audioBackend(DAC_PIN, 11025);

// Display
pr32::graphics::DisplayConfig displayConfig(
    pr32::graphics::DisplayType::ST7789,
    0, 240, 240
);

// Input
pr32::input::InputConfig inputConfig(
    6, 32, 27, 33, 14, 13, 12  // 6 buttons, pins
);

// Audio config
pr32::audio::AudioConfig audioConfig(&audioBackend, 11025);

// Engine
pr32::core::Engine engine(displayConfig, inputConfig, audioConfig);

void setup() {
    Serial.begin(115200);
    engine.init();
    // ... scene setup
}

void loop() {
    engine.run();
}

Native Complete Setup¶

#define SDL_MAIN_HANDLED
#include <SDL2/SDL.h>
#include <core/Engine.h>
#include <drivers/native/SDL2_Drawer.h>
#include <drivers/native/SDL2_AudioBackend.h>

namespace pr32 = pixelroot32;

// Audio
pr32::drivers::native::SDL2_AudioBackend audioBackend(22050, 1024);

// Display
pr32::graphics::DisplayConfig displayConfig(
    pr32::graphics::DisplayType::NONE,
    0, 240, 240
);

// Input (SDL scancodes)
pr32::input::InputConfig inputConfig(
    6,
    SDL_SCANCODE_UP,
    SDL_SCANCODE_DOWN,
    SDL_SCANCODE_LEFT,
    SDL_SCANCODE_RIGHT,
    SDL_SCANCODE_SPACE,
    SDL_SCANCODE_RETURN
);

// Audio config
pr32::audio::AudioConfig audioConfig(&audioBackend, 22050);

// Engine
pr32::core::Engine engine(displayConfig, inputConfig, audioConfig);

int main(int argc, char* argv[]) {
    engine.init();
    // ... scene setup
    engine.run();
    return 0;
}

Platform-Specific Considerations¶

ESP32¶

Memory: - Limited RAM (~320KB) - Use object pooling - Store data in flash - Avoid dynamic allocation

Performance: - Target 30-60 FPS - Optimize rendering - Reduce entity count - Profile on hardware

Hardware: - GPIO pin configuration - SPI display setup - Audio hardware connections - Power considerations

Native¶

Development: - Fast iteration - Easy debugging - Unlimited resources - Visual debugging tools

Testing: - Test logic without hardware - Rapid prototyping - CI/CD integration - Cross-platform testing

Troubleshooting¶

ESP32 Display Issues¶

Check wiring connections
Verify pin numbers
Lower SPI frequency
Check display type matches
Verify power supply

ESP32 Audio Issues¶

Check DAC/I2S pin configuration
Verify sample rate
Check hardware connections
Lower volume if distorted
Test with different sample rates

Native Build Issues¶

Verify SDL2 installation
Check include/library paths
Ensure SDL2 version compatibility
Check linker flags

Next Steps¶

Now that you understand platforms and drivers, learn about: - Extensibility - Create custom drivers - Memory Management - ESP32 memory constraints - Performance Optimization - Platform-specific optimization