<spanclass="line"><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">QUANTUM_PAINTER_DRIVERS += ......</span></span></code></pre></div><p>You will also likely need to select an appropriate driver in <code>rules.mk</code>, which is listed below.</p><divclass="warning custom-block"><pclass="custom-block-title">WARNING</p><p>Quantum Painter is not currently integrated with system-level operations such as when the keyboard goes into suspend. Users will need to handle this manually at the current time.</p></div><p>The QMK CLI can be used to convert from normal images such as PNG files or animated GIFs, as well as fonts from TTF files.</p><p>Supported devices:</p><table><thead><tr><th>Display Panel</th><th>Panel Type</th><th>Size</th><th>Comms Transport</th><th>Driver</th></tr></thead><tbody><tr><td>GC9A01</td><td>RGB LCD (circular)</td><td>240x240</td><td>SPI + D/C + RST</td><td><code>QUANTUM_PAINTER_DRIVERS += gc9a01_spi</code></td></tr><tr><td>ILI9163</td><td>RGB LCD</td><td>128x128</td><td>SPI + D/C + RST</td><td><code>QUANTUM_PAINTER_DRIVERS += ili9163_spi</code></td></tr><tr><td>ILI9341</td><td>RGB LCD</td><td>240x320</td><td>SPI + D/C + RST</td><td><code>QUANTUM_PAINTER_DRIVERS += ili9341_spi</code></td></tr><tr><td>ILI9486</td><td>RGB LCD</td><td>320x480</td><td>SPI + D/C + RST</td><td><code>QUANTUM_PAINTER_DRIVERS += ili9486_spi</code></td></tr><tr><td>ILI9488</td><td>RGB LCD</td><td>320x480</td><td>SPI + D/C + RST</td><td><code>QUANTUM_PAINTER_DRIVERS += ili9488_spi</code></td></tr><tr><td>SSD1351</td><td>RGB OLED</td><td>128x128</td><td>SPI + D/C + RST</td><td><code>QUANTUM_PAINTER_DRIVERS += ssd1351_spi</code></td></tr><tr><td>ST7735</td><td>RGB LCD</td><td>132x162, 80x160</td><td>SPI + D/C + RST</td><td><code>QUANTUM_PAINTER_DRIVERS += st7735_spi</code></td></tr><tr><td>ST7789</td><td>RGB LCD</td><td>240x320, 240x240</td><td>SPI + D/C + RST</td><td><code>QUANTUM_PAINTER_DRIVERS += st7789_spi</code></td></tr><tr><td>SH1106 (SPI)</td><td>Monochrome OLED</td><td>128x64</td><td>SPI + D/C + RST</td><td><code>QUANTUM_PAINTER_DRIVERS += sh1106_spi</code></td></tr><tr><td>SH1106 (I2C)</td><td>Monochrome OLED</td><td>128x64</td><td>I2C</td><td><code>QUANTUM_PAINTER_DRIVERS += sh1106_i2c</code></td></tr><tr><td>SSD1306 (SPI)</td><td>Monochrome OLED</td><td>128x64</td><td>SPI + D/C + RST</td><td><code>QUANTUM_PAINTER_DRIVERS += sh1106_spi</code></td></tr><tr><td>SSD1306 (I2C)</td><td>Monochrome OLED</td><td>128x32</td><td>I2C</td><td><code>QUANTUM_PAINTER_DRIVERS += sh1106_i2c</code></td></tr><tr><td>Surface</td><td>Virtual</td><td>User-defined</td><td>None</td><td><code>QUANTUM_PAINTER_DRIVERS += surface</code></td></tr></tbody></table><h2id="quantum-painter-config"tabindex="-1">Quantum Painter Configuration <aclass="header-anchor"href="#quantum-painter-config"aria-label="Permalink to "Quantum Painter Configuration {#quantum-painter-config}""></a></h2><table><thead><tr><th>Option</th><th>Default</th><th>Purpose</th></tr></thead><tbody><tr><td><code>QUANTUM_PAINTER_DISPLAY_TIMEOUT</code></td><td><code>30000</code></td><td>This controls the amount of time (in milliseconds) that all displays will remain on after the last user input. If set to <code>0</code>, the display will remain on indefinitely.</td></tr><tr><td><code>QUANTUM_PAINTER_TASK_THROTTLE</code></td><td><code>1</code></td><td>This controls the amount of time (in milliseconds) that the Quantum Painter internal task will wait between each execution. Affects animations, display timeout, and LVGL timing if enabled.</td></tr><tr><td><code>QUANTUM_PAINTER_NUM_IMAGES</code></td><td><code>8</code></td><td>The maximum number of images/animations that can be loaded at any one time.</td></tr><tr><td><code>QUANTUM_PAINTER_NUM_FONTS</code></td><td><code>4</code></td><td>The maximum number of fonts that can be loaded at any one time.</td></tr><tr><td><code>QUANTUM_PAINTER_CONCURRENT_ANIMATIONS</code></td><td><code>4</code></td><td>The maximum number of animations that can be executed at the same time.</td></tr><tr><td><code>QUANTUM_PAINTER_LOAD_FONTS
<spanclass="line"><span></span></span>
<spanclass="line"><span>options:</span></span>
<spanclass="line"><span> -h, --help show this help message and exit</span></span>
<spanclass="line"><span> -w, --raw Writes out the QGF file as raw data instead of c/h combo.</span></span>
<spanclass="line"><span> -d, --no-deltas Disables the use of delta frames when encoding animations.</span></span>
<spanclass="line"><span> -r, --no-rle Disables the use of RLE when encoding images.</span></span>
<spanclass="line"><span> -f FORMAT, --format FORMAT</span></span>
<spanclass="line"><span> -v, --verbose Turns on verbose output.</span></span></code></pre></div><p>The <code>INPUT</code> argument can be any image file loadable by Python's Pillow module. Common formats include PNG, or Animated GIF.</p><p>The <code>OUTPUT</code> argument needs to be a directory, and will default to the same directory as the input argument.</p><p>The <code>FORMAT</code> argument can be any of the following:</p><table><thead><tr><th>Format</th><th>Meaning</th></tr></thead><tbody><tr><td><code>rgb888</code></td><td>16,777,216 colors in 8-8-8 RGB format (requires <code>QUANTUM_PAINTER_SUPPORTS_NATIVE_COLORS</code>)</td></tr><tr><td><code>rgb565</code></td><td>65,536 colors in 5-6-5 RGB format (requires <code>QUANTUM_PAINTER_SUPPORTS_NATIVE_COLORS</code>)</td></tr><tr><td><code>pal256</code></td><td>256-color palette (requires <code>QUANTUM_PAINTER_SUPPORTS_256_PALETTE</code>)</td></tr><tr><td><code>pal16</code></td><td>16-color palette</td></tr><tr><td><code>pal4</code></td><td>4-color palette</td></tr><tr><td><code>pal2</code></td><td>2-color palette</td></tr><tr><td><code>mono256</code></td><td>256-shade grayscale (requires <code>QUANTUM_PAINTER_SUPPORTS_256_PALETTE</code>)</td></tr><tr><td><code>mono16</code></td><td>16-shade grayscale</td></tr><tr><td><code>mono4</code></td><td>4-shade grayscale</td></tr><tr><td><code>mono2</code></td><td>2-shade grayscale</td></tr></tbody></table><p><strong>Examples</strong>:</p><divclass="language- vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang"></span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><span>$ cd /home/qmk/qmk_firmware/keyboards/my_keeb</span></span>
<spanclass="line"><span>Writing /home/qmk/qmk_firmware/keyboards/my_keeb/generated/my_image.qgf.c...</span></span></code></pre></div><!--]--></div><!----><!----><!--]--></div><h2id="quantum-painter-drivers"tabindex="-1">Quantum Painter Display Drivers <aclass="header-anchor"href="#quantum-painter-drivers"aria-label="Permalink to "Quantum Painter Display Drivers {#quantum-painter-drivers}""></a></h2><divclass="plugin-tabs"><divclass="plugin-tabs--tab-list"role="tablist"><!--[--><buttonid="tab-LCD-9"role="tab"class="plugin-tabs--tab"aria-selected="true"aria-controls="panel-LCD-9"tabindex="0">LCD</button><buttonid="tab-OLED-9"role="tab"class="plugin-tabs--tab"aria-selected="false"aria-controls="panel-OLED-9"tabindex="-1">OLED</button><buttonid="tab-Surface-9"role="tab"class="plugin-tabs--tab"aria-selected="false"aria-controls="panel-Surface-9"tabindex="-1">Surface</button><!--]--></div><!--[--><divid="panel-LCD-9"class="plugin-tabs--content"role="tabpanel"tabindex="0"aria-labelledby="tab-LCD-9"data-v-b2b19630><!--[--><p>Most TFT display panels use a 5-pin interface -- SPI SCK, SPI MOSI, SPI CS, D/C, and RST pins.</p><p>For these displays, QMK's <code>spi_master</code> must already be correctly configured for the platform you're building for.</p><p>The pin assignments for SPI CS, D/C, and RST are specified during device construction.</p><divclass="plugin-tabs"><divclass="plugin-tabs--tab-list"role="tablist"><!--[--><buttonid="tab-GC9A01-10"role="tab"class="plugin-tabs--tab"aria-selected="true"aria-controls="panel-GC9A01-10"tabindex="0">GC9A01</button><buttonid="tab-ILI9163-10"role="tab"class="plugin-tabs--tab"aria-selected="false"aria-controls="panel-ILI9163-10"tabindex="-1">ILI9163</button><buttonid="tab-ILI9341-10"role="tab"class="plugin-tabs--tab"aria-selected="false"aria-controls="panel-ILI9341-10"tabindex="-1">ILI9341</button><buttonid="tab-ILI9486-10"role="tab"class="plugin-tabs--tab"aria-selected="false"aria-controls="panel-ILI9486-10"tabindex="-1">ILI9486</button><buttonid="tab-ILI9488-10"role="tab"class="plugin-tabs--tab"aria-selected="false"aria-controls="panel-ILI9488-10"tabindex="-1">ILI9488</button><buttonid="tab-ST7735-10"role="tab"class="plugin-tabs--tab"aria-selected="false"aria-controls="panel-ST7735-10"tabindex="-1">ST7735</button><buttonid="tab-ST7789-10"role="tab"class="plugin-tabs--tab"aria-selected="false"aria-controls="panel-ST7789-10"tabindex="-1">ST7789</button><!--]--></div><!--[--><divid="panel-GC9A01-10"class="plugin-tabs--content"role="tabpanel"tabindex="0"aria-labelledby="tab-GC9A01-10"data-v-b2b19630><!--[--><p>Enabling support for the GC9A01 in Quantum Painter is done by adding the following to <code>rules.mk</code>:</p><divclass="language-make vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">make</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">QUANTUM_PAINTER_ENABLE = yes</span></span>
<spanclass="line"><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">QUANTUM_PAINTER_DRIVERS += gc9a01_spi</span></span></code></pre></div><p>Creating a GC9A01 device in firmware can then be done with the following API:</p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">painter_device_t</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> qp_gc9a01_make_spi_device</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">uint16_t</span><spanstyle="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> panel_width</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">uint16_t</span><spanstyle="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> panel_height</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">pin_t</span><spanstyle="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> chip_select_pin</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">pin_t</span><spanstyle="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> dc_pin</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">pin_t</span><spanstyle="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> reset_pin</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">uint16_t</span><spanstyle="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> spi_divisor</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">int</span><spanstyle="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> spi_mode</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span></code></pre></div><p>The device handle returned from the <code>qp_gc9a01_make_spi_device</code> function can be used to perform all other drawing operations.</p><p>The maximum number of displays can be configured by changing the following in your <code>config.h</code> (default is 1):</p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// 3 displays:</span></span>
<spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">#define</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> GC9A01_NUM_DEVICES</span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 3</span></span></code></pre></div><p>Native color format rgb565 is compatible with GC9A01</p><!--]--></div><!----><!----><!----><!----><!----><!----><!--]--></div><!--]--></div><!----><!----><!--]--></div><h2id="quantum-painter-api"tabindex="-1">Quantum Painter Drawing API <aclass="header-anchor"href="#quantum-painter-api"aria-label="Permalink to "Quantum Painter Drawing API {#quantum-painter-api}""></a></h2><p>All APIs require a <code>painter_device_t</code> object as their first parameter -- this object comes from the specific device initialisation, and instructions on creating it can be found in each driver's respective section.</p><p>To use any of the APIs, you need to include <code>qp.h</code>:</p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">#include</span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"><qp.h></span></span></code></pre></div><divclass="plugin-tabs"><divclass="plugin-tabs--tab-list"role="tablist"><!--[--><buttonid="tab-General Notes-11"role="tab"class="plugin-tabs--tab"aria-selected="true"aria-controls="panel-General Notes-11"tabindex="0">General Notes</button><buttonid="tab-Device Control-11"role="tab"class="plugin-tabs--tab"aria-selected="false"aria-controls="panel-Device Control-11"tabindex="-1">Device Control</button><buttonid="tab-Drawing Primitives-11"role="tab"class="plugin-tabs--tab"aria-selected="false"aria-controls="panel-Drawing Primitives-11"tabindex="-1">Drawing Primitives</button><buttonid="tab-Image Functions-11"role="tab"class="plugin-tabs--tab"aria-selected="false"aria-controls="panel-Image Functions-11"tabindex="-1">Image Functions</button><buttonid="tab-Font Functions-11"role="tab"class="plugin-tabs--tab"aria-selected="false"aria-controls="panel-Font Functions-11"tabindex="-1">Font Functions</button><buttonid="tab-Advanced Functions-11"role="tab"class="plugin-tabs--tab"aria-selected="false"aria-controls="panel-Advanced Functions-11"tabindex="-1">Advanced Functions</button><!--]--></div><!--[--><divid="panel-General Notes-11"class="plugin-tabs--content"role="tabpanel"tabindex="0"aria-labelledby="tab-General Notes-11"data-v-b2b19630><!--[--><p>The coordinate system used in Quantum Painter generally accepts <code>left</code>, <code>top</code>, <code>right</code>, and <code>bottom</code> instead of x/y/width/height, and each coordinate is inclusive of where pixels should be drawn. This is required as some datatypes used by display panels have a maximum value of <code>255</code> -- for any value or geometry extent that matches <code>256</code>, this would be represented as a <code>0</code>, instead.</p><divclass="tip custom-block"><pclass="custom-block-title">TIP</p><p>Drawing a horizontal line 8 pixels long, starting from 4 pixels inside the left side of the display, will need <code>left=4</code>, <code>right=11</code>.</p></div><p>All color data matches the standard QMK HSV triplet definitions:</p><ul><li>Hue is of the range <code>0...255</code> and is internally mapped to 0...360 degrees.</li><li>Saturation is of the range <code>0...255</code> and is internally mapped to 0...100% saturation.</li><li>Value is of the range <code>0...255</code> and is internally mapped to 0...100% brightness.</li></ul><divclass="tip custom-block"><pclass="custom-block-title">TIP</p><p>Colors used in Quantum Painter are not subject to the RGB lighting CIE curve, if it is enabled.</p></div><!--]--></div><!----><!----><!----><!----><!----><!--]--></div></div></div></main><footerclass="VPDocFooter"data-v-39a288b8data-v-09de1c0f><!--[--><!--]--><!----><navclass="prev-next
