summaryrefslogtreecommitdiffstats
path: root/quantum/painter/qp.h
blob: e1c14d156cabb61277270e61c873675454920565 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
// Copyright 2021 Nick Brassel (@tzarc)
// SPDX-License-Identifier: GPL-2.0-or-later

#pragma once

#include <stdint.h>
#include <stdbool.h>

#include "deferred_exec.h"

////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// Quantum Painter global configurables (add to your keyboard's config.h)

#ifndef QUANTUM_PAINTER_NUM_IMAGES
/**
 * @def This controls the maximum number of images that Quantum Painter can load at any one time. Images can be loaded
 *      using \ref qp_load_image_mem, and can be unloaded by calling \ref qp_close_image. Increasing this number in
 *      order to load more images increases the amount of RAM required. Image data is not held in RAM, just metadata.
 */
#    define QUANTUM_PAINTER_NUM_IMAGES 8
#endif // QUANTUM_PAINTER_NUM_IMAGES

#ifndef QUANTUM_PAINTER_NUM_FONTS
/**
 * @def This controls the maximum number of fonts that Quantum Painter can load. Fonts can be loaded using
 *      \ref qp_load_font_mem, and can be unloaded by calling \ref qp_close_font. Increasing this number in order to
 *      load more fonts increases the amount of RAM required. Font data is not held in RAM, unless
 *      \ref QUANTUM_PAINTER_LOAD_FONTS_TO_RAM is set to TRUE.
 */
#    define QUANTUM_PAINTER_NUM_FONTS 4
#endif // QUANTUM_PAINTER_NUM_FONTS

#ifndef QUANTUM_PAINTER_LOAD_FONTS_TO_RAM
/**
 * @def This controls whether or not fonts should be cached in RAM. Under normal circumstances, fonts can have quite
 *      random access patterns, and due to timing of flash memory or external storage, it may be a significant speedup
 *      moving the font into RAM before use. Defaults to "off", but if it's enabled it will fallback to reading from the
 *      original location if corresponding RAM could not be allocated (such as being too large).
 */
#    define QUANTUM_PAINTER_LOAD_FONTS_TO_RAM FALSE
#endif

#ifndef QUANTUM_PAINTER_CONCURRENT_ANIMATIONS
/**
 * @def This controls the maximum number of animations that Quantum Painter can play simultaneously. Increasing this
 *      number in order to play more animations at the same time increases the amount of RAM required.
 */
#    define QUANTUM_PAINTER_CONCURRENT_ANIMATIONS 4
#endif // QUANTUM_PAINTER_CONCURRENT_ANIMATIONS

#ifndef QUANTUM_PAINTER_PIXDATA_BUFFER_SIZE
/**
 * @def This controls the maximum size of the pixel data buffer used for single blocks of transmission. Larger buffers
 *      means more data is processed at one time, with less frequent transmissions, at the cost of RAM.
 */
#    define QUANTUM_PAINTER_PIXDATA_BUFFER_SIZE 32
#endif

#ifndef QUANTUM_PAINTER_SUPPORTS_256_PALETTE
/**
 * @def This controls whether 256-color palettes are supported. This has relatively hefty requirements on RAM -- at
 *      least 1kB extra is required just to store the palette information, with more required for other metadata.
 */
#    define QUANTUM_PAINTER_SUPPORTS_256_PALETTE FALSE
#endif

////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// Quantum Painter types

/**
 * @typedef A handle to a Quantum Painter device, such as an LCD or OLED. Most Quantum Painter APIs require this
 *          argument in order to perform operations on the display.
 */
typedef const void *painter_device_t;

/**
 * @typedef The desired rotation of a panel. Used as a parameter to \ref qp_init, and can be queried by
 *          \ref qp_get_geometry.
 */
typedef enum { QP_ROTATION_0, QP_ROTATION_90, QP_ROTATION_180, QP_ROTATION_270 } painter_rotation_t;

/**
 * @typedef A descriptor for a Quantum Painter image.
 */
typedef struct painter_image_desc_t {
    uint16_t width;       ///< Image width
    uint16_t height;      ///< Image height
    uint16_t frame_count; ///< Number of frames in this image
} painter_image_desc_t;

/**
 * @typedef A handle to a Quantum Painter image.
 */
typedef const painter_image_desc_t *painter_image_handle_t;

/**
 * @typedef A descriptor for a Quantum Painter font.
 */
typedef struct painter_font_desc_t {
    uint8_t line_height; ///< The number of pixels in height for each line
} painter_font_desc_t;

/**
 * @typedef A handle to a Quantum Painter font.
 */
typedef const painter_font_desc_t *painter_font_handle_t;

////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// Quantum Painter External API

/**
 * Initialize a device and set its rotation.
 *
 * @param device[in] the handle of the device to initialize
 * @param rotation[in] the rotation to use
 * @return true if initialization succeeded
 * @return false if initialization failed
 */
bool qp_init(painter_device_t device, painter_rotation_t rotation);

/**
 * Controls whether a display is on or off.
 *
 * @note If backlighting is used to control brightness (such as for an LCD), it will need to be handled external to
 *       Quantum Painter.
 *
 * @param device[in] the handle of the device to control
 * @param power_on[in] whether or not the device should be on
 * @return true if controlling the power state succeeded
 * @return false if controlling the power state failed
 */
bool qp_power(painter_device_t device, bool power_on);

/**
 * Clears a device's screen.
 *
 * @param device[in] the handle of the device to control
 * @return true if clearing the screen succeeded
 * @return false if clearing the screen failed
 */
bool qp_clear(painter_device_t device);

/**
 * Transmits any outstanding data to the screen in order to persist all changes to the display.
 *
 * @note Drivers without internal framebuffers will likely ignore this API.
 *
 * @param device[in] the handle of the device to control
 * @return true if flushing changes to the screen succeeded
 * @return false if flushing changes to the screen failed
 */
bool qp_flush(painter_device_t device);

/**
 * Retrieves the size, rotation, and offsets for the display.
 *
 * @note Any arguments of NULL will be ignored.
 *
 * @param device[in] the handle of the device to control
 * @param width[out] the device's width
 * @param height[out] the device's height
 * @param rotation[out] the device's rotation
 * @param offset_x[out] the device's x-offset applied while drawing
 * @param offset_y[out] the device's y-offset applied while drawing
 */
void qp_get_geometry(painter_device_t device, uint16_t *width, uint16_t *height, painter_rotation_t *rotation, uint16_t *offset_x, uint16_t *offset_y);

/**
 * Allows repositioning of the viewport if the panel geometry offsets are non-zero.
 *
 * @param device[in] the handle of the device to control
 * @param offset_x[in] the device's x-offset applied while drawing
 * @param offset_y[in] the device's y-offset applied while drawing
 */
void qp_set_viewport_offsets(painter_device_t device, uint16_t offset_x, uint16_t offset_y);

/**
 * Sets a pixel to the specified color.
 *
 * @param device[in] the handle of the device to control
 * @param x[in] the x-position to draw onto the device
 * @param y[in] the y-position to draw onto the device
 * @param hue[in] the hue to use, with 0-360 mapped to 0-255
 * @param sat[in] the saturation to use, with 0-100% mapped to 0-255
 * @param val[in] the value to use, with 0-100% mapped to 0-255
 * @return true if setting the pixel succeeded
 * @return false if setting the pixel failed
 */
bool qp_setpixel(painter_device_t device, uint16_t x, uint16_t y, uint8_t hue, uint8_t sat, uint8_t val);

/**
 * Draws a line using the specified color.
 *
 * @param device[in] the handle of the device to control
 * @param x0[in] the device's x-position to start
 * @param y0[in] the device's y-position to start
 * @param x1[in] the device's x-position to finish
 * @param y1[in] the device's y-position to finish
 * @param hue[in] the hue to use, with 0-360 mapped to 0-255
 * @param sat[in] the saturation to use, with 0-100% mapped to 0-255
 * @param val[in] the value to use, with 0-100% mapped to 0-255
 * @return true if drawing the line succeeded
 * @return false if drawing the line failed
 */
bool qp_line(painter_device_t device, uint16_t x0, uint16_t y0, uint16_t x1, uint16_t y1, uint8_t hue, uint8_t sat, uint8_t val);

/**
 * Draws a rectangle using the specified color, optionally filled.
 *
 * @param device[in] the handle of the device to control
 * @param left[in] the device's x-position to start
 * @param top[in] the device's y-position to start
 * @param right[in] the device's x-position to finish
 * @param bottom[in] the device's y-position to finish
 * @param hue[in] the hue to use, with 0-360 mapped to 0-255
 * @param sat[in] the saturation to use, with 0-100% mapped to 0-255
 * @param val[in] the value to use, with 0-100% mapped to 0-255
 * @param filled[in] whether the rectangle should be filled
 * @return true if drawing the rectangle succeeded
 * @return false if drawing the rectangle failed
 */
bool qp_rect(painter_device_t device, uint16_t left, uint16_t top, uint16_t right, uint16_t bottom, uint8_t hue, uint8_t sat, uint8_t val, bool filled);

/**
 * Draws a circle using the specified color, optionally filled.
 *
 * @param device[in] the handle of the device to control
 * @param x[in] the x-position of the centre of the circle to draw onto the device
 * @param y[in] the y-position of the centre of the circle to draw onto the device
 * @param radius[in] the radius of the circle to draw
 * @param hue[in] the hue to use, with 0-360 mapped to 0-255
 * @param sat[in] the saturation to use, with 0-100% mapped to 0-255
 * @param val[in] the value to use, with 0-100% mapped to 0-255
 * @param filled[in] whether the circle should be filled
 * @return true if drawing the circle succeeded
 * @return false if drawing the circle failed
 */
bool qp_circle(painter_device_t device, uint16_t x, uint16_t y, uint16_t radius, uint8_t hue, uint8_t sat, uint8_t val, bool filled);

/**
 * Draws a ellipse using the specified color, optionally filled.
 *
 * @param device[in] the handle of the device to control
 * @param x[in] the x-position of the centre of the ellipse to draw onto the device
 * @param y[in] the y-position of the centre of the ellipse to draw onto the device
 * @param sizex[in] the horizontal size of the ellipse
 * @param sizey[in] the vertical size of the ellipse
 * @param hue[in] the hue to use, with 0-360 mapped to 0-255
 * @param sat[in] the saturation to use, with 0-100% mapped to 0-255
 * @param val[in] the value to use, with 0-100% mapped to 0-255
 * @param filled[in] whether the ellipse should be filled
 * @return true if drawing the ellipse succeeded
 * @return false if drawing the ellipse failed
 */
bool qp_ellipse(painter_device_t device, uint16_t x, uint16_t y, uint16_t sizex, uint16_t sizey, uint8_t hue, uint8_t sat, uint8_t val, bool filled);

/**
 * Sets up the location on the display to stream raw pixel data to the display, using \ref qp_pixdata.
 *
 * @note This is for advanced uses only, and should not be required for normal Quantum Painter functionality.
 *
 * @param device[in] the handle of the device to control
 * @param left[in] the device's x-position to start
 * @param top[in] the device's y-position to start
 * @param right[in] the device's x-position to finish
 * @param bottom[in] the device's y-position to finish
 * @return true if setting the viewport succeeded
 * @return false if setting the viewport failed
 */
bool qp_viewport(painter_device_t device, uint16_t left, uint16_t top, uint16_t right, uint16_t bottom);

/**
 * Streams raw pixel data (in the native panel format) to the area previously set by \ref qp_viewport.
 *
 * @note This is for advanced uses only, and should not be required for normal Quantum Painter functionality.
 *
 * @param device[in] the handle of the device to control
 * @param pixel_data[in] pointer to buffer data
 * @param native_pixel_count[in] the number of pixels to transmit
 * @return true if streaming of data succeeded
 * @return false if streaming of data failed
 */
bool qp_pixdata(painter_device_t device, const void *pixel_data, uint32_t native_pixel_count);

/**
 * Loads an image into memory.
 *
 * @note Images can be unloaded by calling \ref qp_close_image.
 *
 * @param buffer[in] the image data to load
 * @return an image handle usable with \ref qp_drawimage, \ref qp_drawimage_recolor, \ref qp_animate, and
 *         \ref qp_animate_recolor.
 * @return NULL if loading the image failed
 */
painter_image_handle_t qp_load_image_mem(const void *buffer);

/**
 * Closes an image handle when no longer in use.
 *
 * @param image[in] the handle of the image to unload
 * @return true if unloading the image succeeded
 * @return false if unloading the image failed
 */
bool qp_close_image(painter_image_handle_t image);

/**
 * Draws an image to the display.
 *
 * @param device[in] the handle of the device to control
 * @param x[in] the x-position where the image should be drawn onto the device
 * @param y[in] the y-position where the image should be drawn onto the device
 * @param image[in] the handle of the image to draw
 * @return true if drawing the image succeeded
 * @return false if drawing the image failed
 */
bool qp_drawimage(painter_device_t device, uint16_t x, uint16_t y, painter_image_handle_t image);

/**
 * Draws an image to the display, recoloring monochrome images to the desired foreground/background.
 *
 * @param device[in] the handle of the device to control
 * @param x[in] the x-position where the image should be drawn onto the device
 * @param y[in] the y-position where the image should be drawn onto the device
 * @param image[in] the handle of the image to draw
 * @param hue_fg[in] the foreground hue to use, with 0-360 mapped to 0-255
 * @param sat_fg[in] the foreground saturation to use, with 0-100% mapped to 0-255
 * @param val_fg[in] the foreground value to use, with 0-100% mapped to 0-255
 * @param hue_bg[in] the background hue to use, with 0-360 mapped to 0-255
 * @param sat_bg[in] the background saturation to use, with 0-100% mapped to 0-255
 * @param val_bg[in] the background value to use, with 0-100% mapped to 0-255
 * @return true if drawing the image succeeded
 * @return false if drawing the image failed
 */
bool qp_drawimage_recolor(painter_device_t device, uint16_t x, uint16_t y, painter_image_handle_t image, uint8_t hue_fg, uint8_t sat_fg, uint8_t val_fg, uint8_t hue_bg, uint8_t sat_bg, uint8_t val_bg);

/**
 * Draws an animation to the display.
 *
 * @param device[in] the handle of the device to control
 * @param x[in] the x-position where the image should be drawn onto the device
 * @param y[in] the y-position where the image should be drawn onto the device
 * @param image[in] the handle of the image to draw
 * @return the \ref deferred_token to use with \ref qp_stop_animation in order to stop animating
 * @return INVALID_DEFERRED_TOKEN if animating the image failed
 */
deferred_token qp_animate(painter_device_t device, uint16_t x, uint16_t y, painter_image_handle_t image);

/**
 * Draws an animation to the display, recoloring monochrome images to the desired foreground/background.
 *
 * @param device[in] the handle of the device to control
 * @param x[in] the x-position where the image should be drawn onto the device
 * @param y[in] the y-position where the image should be drawn onto the device
 * @param image[in] the handle of the image to draw
 * @param hue_fg[in] the foreground hue to use, with 0-360 mapped to 0-255
 * @param sat_fg[in] the foreground saturation to use, with 0-100% mapped to 0-255
 * @param val_fg[in] the foreground value to use, with 0-100% mapped to 0-255
 * @param hue_bg[in] the background hue to use, with 0-360 mapped to 0-255
 * @param sat_bg[in] the background saturation to use, with 0-100% mapped to 0-255
 * @param val_bg[in] the background value to use, with 0-100% mapped to 0-255
 * @return the \ref deferred_token to use with \ref qp_stop_animation in order to stop animating
 * @return INVALID_DEFERRED_TOKEN if animating the image failed
 */
deferred_token qp_animate_recolor(painter_device_t device, uint16_t x, uint16_t y, painter_image_handle_t image, uint8_t hue_fg, uint8_t sat_fg, uint8_t val_fg, uint8_t hue_bg, uint8_t sat_bg, uint8_t val_bg);

/**
 * Cancels a running animation.
 *
 * @param anim_token[in] the animation token returned by \ref qp_animate, or \ref qp_animate_recolor.
 */
void qp_stop_animation(deferred_token anim_token);

/**
 * Loads a font into memory.
 *
 * @note Fonts can be unloaded by calling \ref qp_close_font.
 *
 * @param buffer[in] the font data to load
 * @return an image handle usable with \ref qp_textwidth, \ref qp_drawtext, and \ref qp_drawtext_recolor.
 * @return NULL if loading the font failed
 */
painter_font_handle_t qp_load_font_mem(const void *buffer);

/**
 * Closes a font handle when no longer in use.
 *
 * @param font[in] the handle of the font to unload
 * @return true if unloading the font succeeded
 * @return false if unloading the font failed
 */
bool qp_close_font(painter_font_handle_t font);

/**
 * Measures the width (in pixels) of the supplied string, given the specified font.
 *
 * @param font[in] the handle of the font
 * @param str[in] the string to measure
 * @return the width (in pixels) needed to draw the specified string
 */
int16_t qp_textwidth(painter_font_handle_t font, const char *str);

/**
 * Draws text to the display.
 *
 * @param device[in] the handle of the device to control
 * @param x[in] the x-position where the text should be drawn onto the device
 * @param y[in] the y-position where the text should be drawn onto the device
 * @param font[in] the handle of the font
 * @param str[in] the string to draw
 * @return the width (in pixels) used when drawing the specified string
 */
int16_t qp_drawtext(painter_device_t device, uint16_t x, uint16_t y, painter_font_handle_t font, const char *str);

/**
 * Draws text to the display, recoloring monochrome fonts to the desired foreground/background.
 *
 * @param device[in] the handle of the device to control
 * @param x[in] the x-position where the text should be drawn onto the device
 * @param y[in] the y-position where the text should be drawn onto the device
 * @param font[in] the handle of the font
 * @param str[in] the string to draw
 * @param hue_fg[in] the foreground hue to use, with 0-360 mapped to 0-255
 * @param sat_fg[in] the foreground saturation to use, with 0-100% mapped to 0-255
 * @param val_fg[in] the foreground value to use, with 0-100% mapped to 0-255
 * @param hue_bg[in] the background hue to use, with 0-360 mapped to 0-255
 * @param sat_bg[in] the background saturation to use, with 0-100% mapped to 0-255
 * @param val_bg[in] the background value to use, with 0-100% mapped to 0-255
 * @return the width (in pixels) used when drawing the specified string
 */
int16_t qp_drawtext_recolor(painter_device_t device, uint16_t x, uint16_t y, painter_font_handle_t font, const char *str, uint8_t hue_fg, uint8_t sat_fg, uint8_t val_fg, uint8_t hue_bg, uint8_t sat_bg, uint8_t val_bg);

////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// Quantum Painter Drivers

#ifdef QUANTUM_PAINTER_ILI9163_ENABLE
#    include "qp_ili9163.h"
#endif // QUANTUM_PAINTER_ILI9163_ENABLE

#ifdef QUANTUM_PAINTER_ILI9341_ENABLE
#    include "qp_ili9341.h"
#endif // QUANTUM_PAINTER_ILI9341_ENABLE

#ifdef QUANTUM_PAINTER_ST7789_ENABLE
#    include "qp_st7789.h"
#endif // QUANTUM_PAINTER_ST7789_ENABLE

#ifdef QUANTUM_PAINTER_GC9A01_ENABLE
#    include "qp_gc9a01.h"
#endif // QUANTUM_PAINTER_GC9A01_ENABLE

#ifdef QUANTUM_PAINTER_SSD1351_ENABLE
#    include "qp_ssd1351.h"
#endif // QUANTUM_PAINTER_SSD1351_ENABLE