Skip to main content
Version: v2.4.0 (Current)

🎨 Bit Depth (BPP)

In the context of Artok and embedded systems, Bit Depth (Bits Per Pixel) determines how much memory each pixel occupies and how many colors can be displayed simultaneously. Choosing the right BPP is the most important decision for balancing visual quality against hardware constraints.

⚙️ Supported Color Depths​

Artok supports several standard color formats, configurable within the Project Settings.

FormatBPPMax ColorsBest For...
1-bit12 (Monochrome)E-Ink displays, OLEDs, and low-power IoT.
8-bit8256 (Palette)Simple icons, navigation menus, and maps.
16-bit1665,535 (RGB565)Most MCU displays (standard for STM32/ESP32).
24-bit2416.7 MillionHigh-end Embedded Linux / Automotive UIs.
32-bit3216.7M + AlphaUIs requiring true transparency and anti-aliasing.

🛠 Memory Math (RAM Usage)​

To calculate the RAM required for a single full-screen frame buffer, use this formula: Width × Height × (BPP ÷ 8) = Bytes

Example: 320x240 Display

  • 16-bit (RGB565): 320 × 240 × 2 = 153,600 Bytes (~150 KB)
  • 32-bit (ARGB8888): 320 × 240 × 4 = 307,200 Bytes (~300 KB)
DOUBLE BUFFERING

If you enable "Double Buffering" for tear-free animations, you must multiply the result by 2.

🎨 Transparency and Alpha​

  • Alpha Blending: Requires at least 8-bit alpha (found in 32-bit mode) or 1-bit "chroma keying" (transparent color) in lower BPP modes.
  • Anti-aliasing: To have smooth, rounded edges on fonts and circles, the engine needs enough bit depth to calculate "shades" between the object and the background.

🚀 Optimization Strategies​

If your project is running out of Flash (Storage) or RAM (Memory):

  1. Reduce Global BPP: Dropping from 32-bit to 16-bit (RGB565) immediately cuts memory usage by 50% with minimal loss in quality for small screens.
  2. Per-Asset Overrides: The Asset Packer allows you to keep the system at 16-bit but compress simple icons down to 8-bit Indexed or 4-bit Alpha maps.
  3. Dithering: Enable dithering in the Studio to simulate more colors on low-BPP hardware, reducing "banding" in gradients.

⚡ Runtime API (Lua)​

While BPP is usually a build-time setting, you can query the system status in Lua to adjust UI complexity.

-- Check the current system color depth
local depth = system:get_color_depth()

if depth < 16 then
    -- Disable complex gradients for low-spec hardware
    btn_main:set_style_bg_grad_dir(LV_GRAD_DIR_NONE)
    app:notify("Low Color Mode Active")
end
HARDWARE LIMIT

Your physical display controller (LCD Driver) must support the BPP you select. If you set Artok to 32-bit but your screen is wired for 16-bit RGB565, the colors will appear distorted or "inverted."

🚀 Next Steps​