add docusaurus, convert notes/tips, ids

2026-09-30 13:58:57 +02:00 · 2023-04-18 12:35:09 -04:00
parent e0a09ff728
commit 2cef3465e8
180 changed files with 15192 additions and 785 deletions
@@ -1,4 +1,4 @@
-# Quantum Painter :id=quantum-painter
+# Quantum Painter {#quantum-painter}

 Quantum Painter is the standardised API for graphical displays. It currently includes support for basic drawing primitives, as well as custom images, animations, and fonts.

@@ -13,7 +13,11 @@ QUANTUM_PAINTER_DRIVERS += ......

 You will also likely need to select an appropriate driver in `rules.mk`, which is listed below.

-!> Quantum Painter is not currently integrated with system-level operations such as disabling displays after a configurable timeout, or when the keyboard goes into suspend. Users will need to handle this manually at the current time.
+:::caution
+
+Quantum Painter is not currently integrated with system-level operations such as disabling displays after a configurable timeout, or when the keyboard goes into suspend. Users will need to handle this manually at the current time.
+
+:::

 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.

@@ -30,7 +34,7 @@ Supported devices:
 | ST7789         | RGB LCD            | 240x320, 240x240 | SPI + D/C + RST | `QUANTUM_PAINTER_DRIVERS += st7789_spi`     |
 | RGB565 Surface | Virtual            | User-defined     | None            | `QUANTUM_PAINTER_DRIVERS += rgb565_surface` |

-## Quantum Painter Configuration :id=quantum-painter-config
+## Quantum Painter Configuration {#quantum-painter-config}

 | Option                                   | Default | Purpose                                                                                                                                     |
 |------------------------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------|
@@ -45,7 +49,7 @@ Supported devices:

 Drivers have their own set of configurable options, and are described in their respective sections.

-## Quantum Painter CLI Commands :id=quantum-painter-cli
+## Quantum Painter CLI Commands {#quantum-painter-cli}

 <!-- tabs:start -->

@@ -180,7 +184,7 @@ Writing /home/qmk/qmk_firmware/keyboards/my_keeb/generated/noto11.qff.c...

 <!-- tabs:end -->

-## Quantum Painter Display Drivers :id=quantum-painter-drivers
+## Quantum Painter Display Drivers {#quantum-painter-drivers}

 <!-- tabs:start -->

@@ -350,7 +354,11 @@ The maximum number of displays can be configured by changing the following in yo

 Native color format rgb565 is compatible with ST7735

-!> Some ST7735 devices are known to have different drawing offsets -- despite being a 132x162 pixel display controller internally, some display panels are only 80x160, or smaller. These may require an offset to be applied; see `qp_set_viewport_offsets` above for information on how to override the offsets if they aren't correctly rendered.
+:::caution
+
+Some ST7735 devices are known to have different drawing offsets -- despite being a 132x162 pixel display controller internally, some display panels are only 80x160, or smaller. These may require an offset to be applied; see `qp_set_viewport_offsets` above for information on how to override the offsets if they aren't correctly rendered.
+
+:::

 #### ** ST7789 **

@@ -378,7 +386,11 @@ The maximum number of displays can be configured by changing the following in yo

 Native color format rgb565 is compatible with ST7789

-!> Some ST7789 devices are known to have different drawing offsets -- despite being a 240x320 pixel display controller internally, some display panels are only 240x240, or smaller. These may require an offset to be applied; see `qp_set_viewport_offsets` above for information on how to override the offsets if they aren't correctly rendered.
+:::caution
+
+Some ST7789 devices are known to have different drawing offsets -- despite being a 240x320 pixel display controller internally, some display panels are only 240x240, or smaller. These may require an offset to be applied; see `qp_set_viewport_offsets` above for information on how to override the offsets if they aren't correctly rendered.
+
+:::

 <!-- tabs:end -->

@@ -386,7 +398,11 @@ Native color format rgb565 is compatible with ST7789

 Quantum Painter has surface drivers which are able to target a buffer in RAM. In general, surfaces keep track of the "dirty" region -- the area that has been drawn to since the last flush -- so that when transferring to the display they can transfer the minimal amount of data to achieve the end result.

-!> These generally require significant amounts of RAM, so at large sizes and/or higher bit depths, they may not be usable on all MCUs.
+:::caution
+
+These generally require significant amounts of RAM, so at large sizes and/or higher bit depths, they may not be usable on all MCUs.
+
+:::

 <!-- tabs:start -->

@@ -435,13 +451,17 @@ bool qp_rgb565_surface_draw(painter_device_t surface, painter_device_t display,

 The `surface` is the surface to copy out from. The `display` is the target display to draw into. `x` and `y` are the target location to draw the surface pixel data. Under normal circumstances, the location should be consistent, as the dirty region is calculated with respect to the `x` and `y` coordinates -- changing those will result in partial, overlapping draws.

-?> Calling `qp_flush()` on the surface resets its dirty region. Copying the surface contents to the display also automatically resets the dirty region.
+:::tip
+
+Calling `qp_flush()` on the surface resets its dirty region. Copying the surface contents to the display also automatically resets the dirty region.
+
+:::

 <!-- tabs:end -->

 <!-- tabs:end -->

-## Quantum Painter Drawing API :id=quantum-painter-api
+## Quantum Painter Drawing API {#quantum-painter-api}

 All APIs require a `painter_device_t` 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.

@@ -456,7 +476,11 @@ To use any of the APIs, you need to include `qp.h`:

 The coordinate system used in Quantum Painter generally accepts `left`, `top`, `right`, and `bottom` 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 `255` -- for any value or geometry extent that matches `256`, this would be represented as a `0`, instead.

-?> Drawing a horizontal line 8 pixels long, starting from 4 pixels inside the left side of the display, will need `left=4`, `right=11`.
+:::tip
+
+Drawing a horizontal line 8 pixels long, starting from 4 pixels inside the left side of the display, will need `left=4`, `right=11`.
+
+:::

 All color data matches the standard QMK HSV triplet definitions:

@@ -464,7 +488,11 @@ All color data matches the standard QMK HSV triplet definitions:
 * Saturation is of the range `0...255` and is internally mapped to 0...100% saturation.
 * Value is of the range `0...255` and is internally mapped to 0...100% brightness.

-?> Colors used in Quantum Painter are not subject to the RGB lighting CIE curve, if it is enabled.
+:::tip
+
+Colors used in Quantum Painter are not subject to the RGB lighting CIE curve, if it is enabled.
+
+:::

 ### ** Device Control **

@@ -494,7 +522,11 @@ bool qp_power(painter_device_t device, bool power_on);

 The `qp_power` function instructs the display whether or not the display panel should be on or off.

-!> If there is a separate backlight controlled through the normal QMK backlight API, this is not controlled by the `qp_power` function and needs to be manually handled elsewhere.
+:::caution
+
+If there is a separate backlight controlled through the normal QMK backlight API, this is not controlled by the `qp_power` function and needs to be manually handled elsewhere.
+
+:::

 ```c
 static uint8_t last_backlight = 255;
@@ -533,7 +565,11 @@ bool qp_flush(painter_device_t device);

 The `qp_flush` function ensures that all drawing operations are "pushed" to the display. This should be done as the last operation whenever a sequence of draws occur, and guarantees that any changes are applied.

-!> Some display panels may seem to work even without a call to `qp_flush` -- this may be because the driver cannot queue drawing operations and needs to display them immediately when invoked. In general, calling `qp_flush` at the end is still considered "best practice".
+:::caution
+
+Some display panels may seem to work even without a call to `qp_flush` -- this may be because the driver cannot queue drawing operations and needs to display them immediately when invoked. In general, calling `qp_flush` at the end is still considered "best practice".
+
+:::

 ```c
 void housekeeping_task_user(void) {
@@ -561,7 +597,11 @@ bool qp_setpixel(painter_device_t device, uint16_t x, uint16_t y, uint8_t hue, u

 The `qp_setpixel` can be used to set a specific pixel on the screen to the supplied color.

-?> Using `qp_setpixel` for large amounts of drawing operations is inefficient and should be avoided unless they cannot be achieved with other drawing APIs.
+:::tip
+
+Using `qp_setpixel` for large amounts of drawing operations is inefficient and should be avoided unless they cannot be achieved with other drawing APIs.
+
+:::

 ```c
 void housekeeping_task_user(void) {
@@ -694,7 +734,11 @@ The `qp_load_image_mem` function loads a QGF image from memory or flash.

 See the [CLI Commands](quantum_painter.md?id=quantum-painter-cli) for instructions on how to convert images to [QGF](quantum_painter_qgf.md).

-?> The total number of images available to load at any one time is controlled by the configurable option `QUANTUM_PAINTER_NUM_IMAGES` in the table above. If more images are required, the number should be increased in `config.h`.
+:::tip
+
+The total number of images available to load at any one time is controlled by the configurable option `QUANTUM_PAINTER_NUM_IMAGES` in the table above. If more images are required, the number should be increased in `config.h`.
+
+:::

 Image information is available through accessing the handle:

@@ -801,7 +845,11 @@ The `qp_load_font_mem` function loads a QFF font from memory or flash.

 See the [CLI Commands](quantum_painter.md?id=quantum-painter-cli) for instructions on how to convert TTF fonts to [QFF](quantum_painter_qff.md).

-?> The total number of fonts available to load at any one time is controlled by the configurable option `QUANTUM_PAINTER_NUM_FONTS` in the table above. If more fonts are required, the number should be increased in `config.h`.
+:::tip
+
+The total number of fonts available to load at any one time is controlled by the configurable option `QUANTUM_PAINTER_NUM_FONTS` in the table above. If more fonts are required, the number should be increased in `config.h`.
+
+:::

 Font information is available through accessing the handle:

@@ -885,7 +933,11 @@ bool qp_pixdata(painter_device_t device, const void *pixel_data, uint32_t native

 The `qp_pixdata` function allows raw pixel data to be streamed to the display. It requires a native pixel count rather than the number of bytes to transfer, to ensure display panel data alignment is respected. E.g. for display panels using RGB565 internal format, sending 10 pixels will result in 20 bytes of transfer.

-!> Under normal circumstances, users will not need to manually call either `qp_viewport` or `qp_pixdata`. These allow for writing of raw pixel information, in the display panel's native format, to the area defined by the viewport.
+:::caution
+
+Under normal circumstances, users will not need to manually call either `qp_viewport` or `qp_pixdata`. These allow for writing of raw pixel information, in the display panel's native format, to the area defined by the viewport.
+
+:::

 <!-- tabs:end -->