Skip to content

Color

Color constants and palette management system.

Description

The Color enum provides color constants that map to palette indices. The engine supports both legacy mode (single global palette) and dual palette mode (separate palettes for backgrounds and sprites).

Colors are resolved to 16-bit RGB565 values based on the active palette(s).

Namespace

namespace pixelroot32::graphics {
    enum class Color : uint8_t {
        // ...
    };
}

Color Enum Values

Standard Colors (PR32 Palette Indices)

  • Color::Black (0)
  • Color::White (1)
  • Color::Navy (2)
  • Color::Blue (3)
  • Color::Cyan (4)
  • Color::DarkGreen (5)
  • Color::Green (6)
  • Color::LightGreen (7)
  • Color::Yellow (8)
  • Color::Orange (9)
  • Color::LightRed (10)
  • Color::Red (11)
  • Color::DarkRed (12)
  • Color::Purple (13)
  • Color::Magenta (14)
  • Color::Gray (15)

Color Aliases

For compatibility, several aliases map to the closest available color:

  • Color::DarkBlue → Navy
  • Color::LightBlue → Blue
  • Color::Teal → Cyan
  • Color::Olive → DarkGreen
  • Color::Gold → Yellow
  • Color::Brown → DarkRed
  • Color::Pink → Magenta
  • Color::LightPurple → Magenta
  • Color::Maroon → DarkRed
  • Color::MidGray → Gray
  • Color::LightGray → Gray
  • Color::DarkGray → Gray
  • Color::Silver → Gray

Special Colors

  • Color::Transparent (255): Not a real color; must be handled by renderer (results in no-op)
  • Color::DebugRed → Red
  • Color::DebugGreen → Green
  • Color::DebugBlue → Blue

PaletteType Enum

Built-in palette types:

  • PaletteType::NES: NES color palette
  • PaletteType::GB: Game Boy (4 shades of green)
  • PaletteType::GBC: Game Boy Color palette
  • PaletteType::PICO8: PICO-8 palette
  • PaletteType::PR32: PixelRoot32 default palette

PaletteContext Enum

Context for palette selection in dual palette mode:

  • PaletteContext::Background: For backgrounds, tilemaps, and background primitives
  • PaletteContext::Sprite: For sprites, characters, and gameplay elements

Palette Functions

void setPalette(PaletteType palette)

Selects the active color palette (legacy mode). Sets both background and sprite palettes to the same value.

Parameters: - palette (PaletteType): The palette to use

Notes: - Does not enable dual palette mode - All rendering uses the same palette - Use for simple games with single palette

Example: 

pixelroot32::graphics::setPalette(pixelroot32::graphics::PaletteType::NES);

void setCustomPalette(const uint16_t* palette)

Sets a custom color palette (legacy mode). Sets both background and sprite palettes to the same value.

Parameters: - palette (const uint16_t*): Pointer to an array of 16 uint16_t RGB565 color values

Notes: - Array must remain valid (use static/global storage) - Engine does not copy the palette - Does not enable dual palette mode

Example: 

static const uint16_t MY_PALETTE[16] = {
    0x0000,  // Black
    0xFFFF,  // White
    0x001F,  // Blue
    // ... 13 more colors
};

pixelroot32::graphics::setCustomPalette(MY_PALETTE);

void enableDualPaletteMode(bool enable)

Enables or disables dual palette mode.

Parameters: - enable (bool): true to enable dual palette mode, false for legacy mode

Notes: - When enabled: backgrounds and sprites use separate palettes - When disabled: single palette for all rendering (legacy mode)

Example: 

pixelroot32::graphics::enableDualPaletteMode(true);

void setBackgroundPalette(PaletteType palette)

Sets the background palette (for backgrounds, tilemaps, etc.).

Parameters: - palette (PaletteType): The palette type to use for backgrounds

Notes: - Only used in dual palette mode - Affects tilemaps, background primitives, etc.

Example: 

pixelroot32::graphics::enableDualPaletteMode(true);
pixelroot32::graphics::setBackgroundPalette(pixelroot32::graphics::PaletteType::NES);

void setSpritePalette(PaletteType palette)

Sets the sprite palette (for sprites, characters, etc.).

Parameters: - palette (PaletteType): The palette type to use for sprites

Notes: - Only used in dual palette mode - Affects sprites, characters, gameplay elements

Example: 

pixelroot32::graphics::setSpritePalette(pixelroot32::graphics::PaletteType::GB);

void setDualPalette(PaletteType bgPalette, PaletteType spritePalette)

Sets both background and sprite palettes at once. Automatically enables dual palette mode.

Parameters: - bgPalette (PaletteType): The palette type to use for backgrounds - spritePalette (PaletteType): The palette type to use for sprites

Example: 

pixelroot32::graphics::setDualPalette(
    pixelroot32::graphics::PaletteType::NES,  // Background
    pixelroot32::graphics::PaletteType::GB     // Sprites
);

void setBackgroundCustomPalette(const uint16_t* palette)

Sets a custom background palette.

Parameters: - palette (const uint16_t*): Pointer to an array of 16 uint16_t RGB565 color values

Notes: - Array must remain valid (use static/global storage) - Only used in dual palette mode

Example: 

static const uint16_t BG_PALETTE[16] = { /* ... */ };
pixelroot32::graphics::enableDualPaletteMode(true);
pixelroot32::graphics::setBackgroundCustomPalette(BG_PALETTE);

void setSpriteCustomPalette(const uint16_t* palette)

Sets a custom sprite palette.

Parameters: - palette (const uint16_t*): Pointer to an array of 16 uint16_t RGB565 color values

Notes: - Array must remain valid (use static/global storage) - Only used in dual palette mode

Example: 

static const uint16_t SPRITE_PALETTE[16] = { /* ... */ };
pixelroot32::graphics::setSpriteCustomPalette(SPRITE_PALETTE);

void setDualCustomPalette(const uint16_t bgPalette, const uint16_t spritePal)

Sets both background and sprite custom palettes at once. Automatically enables dual palette mode.

Parameters: - bgPalette (const uint16_t): Pointer to background palette array (16 RGB565 values) - spritePal (const uint16_t): Pointer to sprite palette array (16 RGB565 values)

Example: 

static const uint16_t BG_PAL[16] = { /* ... */ };
static const uint16_t SPRITE_PAL[16] = { /* ... */ };
pixelroot32::graphics::setDualCustomPalette(BG_PAL, SPRITE_PAL);

uint16_t resolveColor(Color color)

Resolves a Color enum to its corresponding 16-bit color value (legacy mode).

Parameters: - color (Color): The Color enum value

Returns: - uint16_t: The 16-bit RGB565 color value

Notes: - Uses the current active palette (single palette mode) - Color::Transparent must not be resolved (handled by renderer) - Typically called internally by renderer

Example: 

uint16_t rgb565 = pixelroot32::graphics::resolveColor(pixelroot32::graphics::Color::Red);

uint16_t resolveColor(Color color, PaletteContext context)

Resolves a Color enum with context (dual palette mode).

Parameters: - color (Color): The Color enum value - context (PaletteContext): The palette context (Background or Sprite)

Returns: - uint16_t: The 16-bit RGB565 color value

Notes: - Uses the appropriate palette based on context - In legacy mode, context is ignored - Color::Transparent must not be resolved

Example: 

uint16_t bgColor = pixelroot32::graphics::resolveColor(
    pixelroot32::graphics::Color::Blue,
    pixelroot32::graphics::PaletteContext::Background
);

RGB565 Format

Colors are stored as 16-bit RGB565 values:

  • Bits 15-11: Red (5 bits, 0-31)
  • Bits 10-5: Green (6 bits, 0-63)
  • Bits 4-0: Blue (5 bits, 0-31)

Conversion Example: 

// Convert RGB to RGB565
uint16_t rgb565 = ((r >> 3) << 11) | ((g >> 2) << 5) | (b >> 3);

Usage Examples

Legacy Mode (Single Palette)

// Set single palette for all rendering
pixelroot32::graphics::setPalette(pixelroot32::graphics::PaletteType::NES);

// Use colors
renderer.drawSprite(sprite, 100, 100, pixelroot32::graphics::Color::Red);
renderer.drawFilledRectangle(10, 10, 50, 50, pixelroot32::graphics::Color::Blue);

Dual Palette Mode

// Enable dual palette mode
pixelroot32::graphics::enableDualPaletteMode(true);

// Set different palettes for backgrounds and sprites
pixelroot32::graphics::setBackgroundPalette(pixelroot32::graphics::PaletteType::NES);
pixelroot32::graphics::setSpritePalette(pixelroot32::graphics::PaletteType::GB);

// Or use convenience function
pixelroot32::graphics::setDualPalette(
    pixelroot32::graphics::PaletteType::NES,
    pixelroot32::graphics::PaletteType::GB
);

Custom Palettes

// Define custom palette (RGB565 values)
static const uint16_t CUSTOM_PALETTE[16] = {
    0x0000,  // 0: Black
    0xFFFF,  // 1: White
    0x001F,  // 2: Blue
    0x07E0,  // 3: Green
    0xF800,  // 4: Red
    // ... 11 more colors
};

// Use in legacy mode
pixelroot32::graphics::setCustomPalette(CUSTOM_PALETTE);

// Or use in dual palette mode
pixelroot32::graphics::enableDualPaletteMode(true);
pixelroot32::graphics::setBackgroundCustomPalette(CUSTOM_PALETTE);
pixelroot32::graphics::setSpriteCustomPalette(CUSTOM_PALETTE);

Performance Considerations

  • Color resolution: Fast lookup operation
  • Palette switching: Changing palettes is fast (just pointer assignment)
  • Memory: Palettes are stored in flash (const arrays) for best performance
  • Dual mode: Slightly more overhead than legacy mode, but minimal

ESP32 Considerations

  • Flash storage: Store custom palettes in flash (const/constexpr)
  • Memory: Palettes are small (16 uint16_t = 32 bytes)
  • Palette switching: Avoid switching palettes every frame

See Also