Skip to content

DisplayConfig

Configuration settings for initializing the display.

Description

DisplayConfig holds display parameters used by the renderer and camera to draw correctly on the target device. It defines the display type, dimensions, rotation, and creates the appropriate DrawSurface implementation for the platform.

Namespace

namespace pixelroot32::graphics {
    struct DisplayConfig {
        // ...
    };
}

DisplayType Enum

Supported display types:

  • DisplayType::ST7789: 240x240 TFT display
  • DisplayType::ST7735: 128x128 TFT display
  • DisplayType::SSD1306: 128x64 Monochrome OLED (U8G2)
  • DisplayType::SH1106: 128x64 Monochrome OLED (U8G2)
  • DisplayType::NONE: For SDL2 native (no driver needed)
  • DisplayType::CUSTOM: For user-provided DrawSurface implementations. See Extensibility Guide for details.

Structure

DisplayType type

The type of display.

Type: DisplayType enum

Access: Read-write

Notes:

  • Determines which driver to use (ESP32)
  • NONE for Native/SDL2 platform

int rotation

Display rotation. Supports both index-based (0-3) and degree-based (0, 90, 180, 270) values.

Type: int

Access: Read-write

Default: 0

Notes:

  • 0: Normal orientation (0°)
  • 1 or 90: Rotated 90 degrees clockwise
  • 2 or 180: Rotated 180 degrees
  • 3 or 270: Rotated 90 degrees counter-clockwise (270°)
  • Rotation is applied during initialization.
  • On ESP32, this affects both the hardware display orientation and the internal framebuffer.
  • On Native (SDL2), this rotates the rendered texture before presenting it.

int clockPin, dataPin, csPin, dcPin, resetPin, backlightPin

Hardware pin configuration (ESP32 only).

Type: int

Access: Read-write

Default: -1 (Use platform defaults if available)

Notes: - clockPin: SPI Clock (SCK) - dataPin: SPI Data (MOSI) - csPin: Chip Select (CS) - dcPin: Data/Command (DC) - resetPin: Reset (RST) - backlightPin: Backlight control (BL) - Set to -1 to use default SPI pins for the board or if not used.

uint16_t physicalWidth

Physical hardware width of the display.

Type: uint16_t

Access: Read-write

Notes:

  • Defines the actual resolution of the display hardware.

uint16_t physicalHeight

Physical hardware height of the display.

Type: uint16_t

Access: Read-write

Notes:

  • Defines the actual resolution of the display hardware.

uint16_t logicalWidth

Logical rendering width. This is the resolution the game "sees" and draws to.

Type: uint16_t

Access: Read-write

Notes:

  • If smaller than physicalWidth, the image will be scaled up.
  • Used for clipping, camera, and UI calculations.
  • Recommended values for ESP32: 160, 128, 96 (for 240 physical).

uint16_t logicalHeight

Logical rendering height. This is the resolution the game "sees" and draws to.

Type: uint16_t

Access: Read-write

Notes:

  • If smaller than physicalHeight, the image will be scaled up.
  • Used for clipping, camera, and UI calculations.

uint16_t width() (Deprecated)

Alias for logicalWidth. Maintained for backward compatibility.

uint16_t height() (Deprecated)

Alias for logicalHeight. Maintained for backward compatibility.

int xOffset

X offset for display alignment.

Type: int

Access: Read-write

Default: 0

Notes:

  • Used to adjust display position
  • Some displays need offset for proper alignment

int yOffset

Y offset for display alignment.

Type: int

Access: Read-write

Default: 0

Notes:

  • Used to adjust display position
  • Some displays need offset for proper alignment

DrawSurface& getDrawSurface() const

Gets the underlying DrawSurface implementation.

Returns:

  • DrawSurface&: Reference to the DrawSurface

Notes:

  • Passed in constructor, not a public member.
  • Advanced usage: typically not needed
  • Provides access to low-level display driver
  • Platform-specific implementation

Resolution Helpers

bool needsScaling() const

Checks if the logical resolution differs from the physical resolution.

Returns:

  • bool: true if scaling is active.

float getScaleX() const

Gets the horizontal scaling factor (physicalWidth / logicalWidth).

float getScaleY() const

Gets the vertical scaling factor (physicalHeight / logicalHeight).

Constructors

DisplayConfig(DisplayType type, const int rot, uint16_t physW, uint16_t physH, uint16_t logW, uint16_t logH, const int xOff = 0, const int yOff = 0, int clk = -1, int data = -1, int cs = -1, int dc = -1, int rst = -1, int bl = -1)

Extended constructor that allows defining separate physical and logical resolutions and custom pins.

Parameters:

  • type (DisplayType): The display type.
  • rot (int): Rotation (0-3 or degrees depending on implementation).
  • physW (uint16_t): Physical hardware width.
  • physH (uint16_t): Physical hardware height.
  • logW (uint16_t): Logical rendering width (0 = same as physical).
  • logH (uint16_t): Logical rendering height (0 = same as physical).
  • xOff (int, optional): X alignment offset.
  • yOff (int, optional): Y alignment offset.
  • clk, data, cs, dc, rst, bl (int, optional): Pin configuration (default -1).

Example:

// 128x128 game logic scaled to 240x240 display
pixelroot32::graphics::DisplayConfig config(
    pixelroot32::graphics::DisplayType::ST7789,
    0,    // rotation
    240, 240, // physical
    128, 128  // logical
);

DisplayConfig(DisplayType type, const int rot = 0, uint16_t w = 240, uint16_t h = 240, const int xOffset = 0, const int yOffset = 0)

Legacy constructor for backward compatibility. Sets both logical and physical resolutions to the same values.

Notes:

  • Automatically creates the appropriate DrawSurface for the platform
  • ESP32: Creates TFT_eSPI_Drawer based on display type
  • Native: Creates SDL2_Drawer

Example:

// ST7789 display, 240x240, no rotation
pixelroot32::graphics::DisplayConfig config(
    pixelroot32::graphics::DisplayType::ST7789
);

// ST7735 display, 128x128, rotated 90 degrees
pixelroot32::graphics::DisplayConfig config(
    pixelroot32::graphics::DisplayType::ST7735,
    90,   // rotation
    128,  // physical width
    128,  // physical height
    128,  // logical width
    128   // logical height
);

// Native/SDL2 (no specific display type)
pixelroot32::graphics::DisplayConfig config(
    pixelroot32::graphics::DisplayType::NONE,
    0,    // rotation
    128, 128, // physical
    128, 128  // logical
);

Usage Examples

ESP32 with ST7789

#ifdef PLATFORM_ESP32
#include "graphics/DisplayConfig.h"

void setup() {
    // Configure ST7789 display (240x240 physical, 128x128 logical)
    pixelroot32::graphics::DisplayConfig displayConfig(
        pixelroot32::graphics::DisplayType::ST7789,
        0,    // rotation
        240, 240, // physical
        128, 128  // logical
    );

    // Use with Engine
    pixelroot32::core::Engine engine(displayConfig);
    engine.init();
    engine.run();
}
#endif

ESP32 with ST7735

#ifdef PLATFORM_ESP32
    // Configure ST7735 display (128x128)
    pixelroot32::graphics::DisplayConfig displayConfig(
        pixelroot32::graphics::DisplayType::ST7735,
        0,    // rotation
        128, 128 // physical & logical
    );
#endif

Native/SDL2

#ifdef PLATFORM_NATIVE
    // Native display (SDL2 window)
    pixelroot32::graphics::DisplayConfig displayConfig(
        pixelroot32::graphics::DisplayType::NONE,
        0,    // rotation
        240, 240 // logical & physical
    );
#endif

Platform-Agnostic Setup

#include "graphics/DisplayConfig.h"
#include "core/Engine.h"

void setup() {
    pixelroot32::graphics::DisplayConfig displayConfig;

    #ifdef PLATFORM_ESP32
        displayConfig.type = pixelroot32::graphics::DisplayType::ST7789;
        displayConfig.physicalWidth = 240;
        displayConfig.physicalHeight = 240;
        displayConfig.logicalWidth = 160; // 160x160 logic
        displayConfig.logicalHeight = 160;
    #elif PLATFORM_NATIVE
        displayConfig.type = pixelroot32::graphics::DisplayType::NONE;
        displayConfig.logicalWidth = 128;
        displayConfig.logicalHeight = 128;
    #endif

    displayConfig.rotation = 0;

    pixelroot32::core::Engine engine(displayConfig);
    engine.init();
    engine.run();
}

Display Type Details

ST7789

  • Resolution: Typically 240x240 or 240x320
  • Interface: SPI
  • Driver: TFT_eSPI
  • Common sizes: 240x240, 240x320

ST7735

  • Resolution: Typically 128x128 or 128x160
  • Interface: SPI
  • Driver: TFT_eSPI
  • Common sizes: 128x128, 128x160

NONE (Native)

  • Platform: Native/SDL2
  • Driver: SDL2_Drawer
  • Resolution: Configurable (any size)
  • Window: Creates SDL2 window

Rotation

Display rotation values:

  • 0: Normal orientation
  • 90: Rotated 90 degrees clockwise
  • 180: Rotated 180 degrees
  • 270: Rotated 90 degrees counter-clockwise

Notes:

  • Rotation affects coordinate system
  • Some displays may not support all rotations
  • Test rotation on your specific hardware

Performance Considerations

  • Initialization: Display initialization happens once at startup
  • Driver selection: Automatic based on platform and type
  • Memory: DisplayConfig is small (few fields)

ESP32 Considerations

TFT_eSPI Configuration

DisplayConfig uses TFT_eSPI driver. Additional configuration may be needed in platformio.ini:

build_flags =
    -DUSER_SETUP_LOADED=1
    -DST7789_DRIVER=1
    -DTFT_WIDTH=240
    -DTFT_HEIGHT=240
    # ... pin configuration

Pin Configuration

GPIO pins must be configured separately (not in DisplayConfig):

  • MOSI: Data pin
  • SCLK: Clock pin
  • DC: Data/Command pin
  • RST: Reset pin
  • CS: Chip select pin (optional)

See Also