Line data Source code
1 1 : /*
2 : * Copyright (c) 2017 Jan Van Winkel <jan.van_winkel@dxplore.eu>
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : /**
8 : * @file
9 : * @brief Public API for display drivers and applications
10 : */
11 :
12 : #ifndef ZEPHYR_INCLUDE_DRIVERS_DISPLAY_H_
13 : #define ZEPHYR_INCLUDE_DRIVERS_DISPLAY_H_
14 :
15 : /**
16 : * @brief Display Interface
17 : * @defgroup display_interface Display Interface
18 : * @since 1.14
19 : * @version 0.8.0
20 : * @ingroup io_interfaces
21 : * @{
22 : */
23 :
24 : #include <zephyr/device.h>
25 : #include <errno.h>
26 : #include <stddef.h>
27 : #include <zephyr/types.h>
28 : #include <zephyr/dt-bindings/display/panel.h>
29 :
30 : #ifdef __cplusplus
31 : extern "C" {
32 : #endif
33 :
34 : /**
35 : * @brief Display pixel formats
36 : *
37 : * Display pixel format enumeration.
38 : *
39 : * In case a pixel format consists out of multiple bytes the byte order is
40 : * big endian.
41 : */
42 1 : enum display_pixel_format {
43 : PIXEL_FORMAT_RGB_888 = BIT(0), /**< 24-bit RGB */
44 : PIXEL_FORMAT_MONO01 = BIT(1), /**< Monochrome (0=Black 1=White) */
45 : PIXEL_FORMAT_MONO10 = BIT(2), /**< Monochrome (1=Black 0=White) */
46 : PIXEL_FORMAT_ARGB_8888 = BIT(3), /**< 32-bit ARGB */
47 : /**
48 : * 16-bit RGB format packed into two bytes: 5 red bits [15:11], 6
49 : * green bits [10:5], 5 blue bits [4:0]. For example, in little-endian machine:
50 : *
51 : * @code{.unparsed}
52 : * 7......0 15.....8
53 : * | gggBbbbb RrrrrGgg | ...
54 : * @endcode
55 : *
56 : */
57 : PIXEL_FORMAT_RGB_565 = BIT(4),
58 : /**
59 : * 16-bit RGB format packed into two bytes: 5 blue bits [15:11], 6
60 : * green bits [10:5], 5 red bits [4:0]. For example, in little-endian machine:
61 : *
62 : * @code{.unparsed}
63 : * 7......0 15.....8
64 : * | gggRrrrr BbbbbGgg | ...
65 : * @endcode
66 : *
67 : */
68 : PIXEL_FORMAT_BGR_565 = BIT(5),
69 : PIXEL_FORMAT_L_8 = BIT(6), /**< 8-bit Grayscale/Luminance, equivalent to */
70 : /**< GRAY, GREY, GRAY8, Y8, R8, etc... */
71 : PIXEL_FORMAT_AL_88 = BIT(7), /**< 8-bit Grayscale/Luminance with alpha */
72 : };
73 :
74 : /**
75 : * @brief Bits required per pixel for display format
76 : *
77 : * This macro expands to the number of bits required for a given display
78 : * format. It can be used to allocate a framebuffer based on a given
79 : * display format type
80 : */
81 1 : #define DISPLAY_BITS_PER_PIXEL(fmt) \
82 : ((((fmt & PIXEL_FORMAT_RGB_888) >> 0) * 24U) + \
83 : (((fmt & PIXEL_FORMAT_MONO01) >> 1) * 1U) + \
84 : (((fmt & PIXEL_FORMAT_MONO10) >> 2) * 1U) + \
85 : (((fmt & PIXEL_FORMAT_ARGB_8888) >> 3) * 32U) + \
86 : (((fmt & PIXEL_FORMAT_RGB_565) >> 4) * 16U) + \
87 : (((fmt & PIXEL_FORMAT_BGR_565) >> 5) * 16U) + \
88 : (((fmt & PIXEL_FORMAT_L_8) >> 6) * 8U) + \
89 : (((fmt & PIXEL_FORMAT_AL_88) >> 7) * 16U))
90 :
91 : /**
92 : * @brief Display screen information
93 : */
94 1 : enum display_screen_info {
95 : /**
96 : * If selected, one octet represents 8 pixels ordered vertically,
97 : * otherwise ordered horizontally.
98 : */
99 : SCREEN_INFO_MONO_VTILED = BIT(0),
100 : /**
101 : * If selected, the MSB represents the first pixel,
102 : * otherwise MSB represents the last pixel.
103 : */
104 : SCREEN_INFO_MONO_MSB_FIRST = BIT(1),
105 : /**
106 : * Electrophoretic Display.
107 : */
108 : SCREEN_INFO_EPD = BIT(2),
109 : /**
110 : * Screen has two alternating ram buffers
111 : */
112 : SCREEN_INFO_DOUBLE_BUFFER = BIT(3),
113 : /**
114 : * Screen has x alignment constrained to width.
115 : */
116 : SCREEN_INFO_X_ALIGNMENT_WIDTH = BIT(4),
117 : };
118 :
119 : /**
120 : * @brief Enumeration with possible display orientation
121 : */
122 1 : enum display_orientation {
123 : DISPLAY_ORIENTATION_NORMAL, /**< No rotation */
124 : DISPLAY_ORIENTATION_ROTATED_90, /**< Rotated 90 degrees clockwise */
125 : DISPLAY_ORIENTATION_ROTATED_180, /**< Rotated 180 degrees clockwise */
126 : DISPLAY_ORIENTATION_ROTATED_270, /**< Rotated 270 degrees clockwise */
127 : };
128 :
129 : /** @brief Structure holding display capabilities. */
130 1 : struct display_capabilities {
131 : /** Display resolution in the X direction */
132 1 : uint16_t x_resolution;
133 : /** Display resolution in the Y direction */
134 1 : uint16_t y_resolution;
135 : /** Bitwise or of pixel formats supported by the display */
136 1 : uint32_t supported_pixel_formats;
137 : /** Information about display panel */
138 1 : uint32_t screen_info;
139 : /** Currently active pixel format for the display */
140 1 : enum display_pixel_format current_pixel_format;
141 : /** Current display orientation */
142 1 : enum display_orientation current_orientation;
143 : };
144 :
145 : /** @brief Structure to describe display data buffer layout */
146 1 : struct display_buffer_descriptor {
147 : /** Data buffer size in bytes */
148 1 : uint32_t buf_size;
149 : /** Data buffer row width in pixels */
150 1 : uint16_t width;
151 : /** Data buffer column height in pixels */
152 1 : uint16_t height;
153 : /** Number of pixels between consecutive rows in the data buffer */
154 1 : uint16_t pitch;
155 : /** Indicates that this is not the last write buffer of the frame */
156 1 : bool frame_incomplete;
157 : };
158 :
159 : /**
160 : * @typedef display_blanking_on_api
161 : * @brief Callback API to turn on display blanking
162 : * See display_blanking_on() for argument description
163 : */
164 1 : typedef int (*display_blanking_on_api)(const struct device *dev);
165 :
166 : /**
167 : * @typedef display_blanking_off_api
168 : * @brief Callback API to turn off display blanking
169 : * See display_blanking_off() for argument description
170 : */
171 1 : typedef int (*display_blanking_off_api)(const struct device *dev);
172 :
173 : /**
174 : * @typedef display_write_api
175 : * @brief Callback API for writing data to the display
176 : * See display_write() for argument description
177 : */
178 1 : typedef int (*display_write_api)(const struct device *dev, const uint16_t x,
179 : const uint16_t y,
180 : const struct display_buffer_descriptor *desc,
181 : const void *buf);
182 :
183 : /**
184 : * @typedef display_read_api
185 : * @brief Callback API for reading data from the display
186 : * See display_read() for argument description
187 : */
188 1 : typedef int (*display_read_api)(const struct device *dev, const uint16_t x,
189 : const uint16_t y,
190 : const struct display_buffer_descriptor *desc,
191 : void *buf);
192 :
193 : /**
194 : * @typedef display_clear
195 : * @brief Callback API for clearing the screen of the display
196 : * See display_clear() for argument description
197 : */
198 0 : typedef int (*display_clear_api)(const struct device *dev);
199 :
200 : /**
201 : * @typedef display_get_framebuffer_api
202 : * @brief Callback API to get framebuffer pointer
203 : * See display_get_framebuffer() for argument description
204 : */
205 1 : typedef void *(*display_get_framebuffer_api)(const struct device *dev);
206 :
207 : /**
208 : * @typedef display_set_brightness_api
209 : * @brief Callback API to set display brightness
210 : * See display_set_brightness() for argument description
211 : */
212 1 : typedef int (*display_set_brightness_api)(const struct device *dev,
213 : const uint8_t brightness);
214 :
215 : /**
216 : * @typedef display_set_contrast_api
217 : * @brief Callback API to set display contrast
218 : * See display_set_contrast() for argument description
219 : */
220 1 : typedef int (*display_set_contrast_api)(const struct device *dev,
221 : const uint8_t contrast);
222 :
223 : /**
224 : * @typedef display_get_capabilities_api
225 : * @brief Callback API to get display capabilities
226 : * See display_get_capabilities() for argument description
227 : */
228 1 : typedef void (*display_get_capabilities_api)(const struct device *dev,
229 : struct display_capabilities *
230 : capabilities);
231 :
232 : /**
233 : * @typedef display_set_pixel_format_api
234 : * @brief Callback API to set pixel format used by the display
235 : * See display_set_pixel_format() for argument description
236 : */
237 1 : typedef int (*display_set_pixel_format_api)(const struct device *dev,
238 : const enum display_pixel_format
239 : pixel_format);
240 :
241 : /**
242 : * @typedef display_set_orientation_api
243 : * @brief Callback API to set orientation used by the display
244 : * See display_set_orientation() for argument description
245 : */
246 1 : typedef int (*display_set_orientation_api)(const struct device *dev,
247 : const enum display_orientation
248 : orientation);
249 :
250 : /**
251 : * @brief Display driver API
252 : * API which a display driver should expose
253 : */
254 1 : __subsystem struct display_driver_api {
255 0 : display_blanking_on_api blanking_on;
256 0 : display_blanking_off_api blanking_off;
257 0 : display_write_api write;
258 0 : display_read_api read;
259 0 : display_clear_api clear;
260 0 : display_get_framebuffer_api get_framebuffer;
261 0 : display_set_brightness_api set_brightness;
262 0 : display_set_contrast_api set_contrast;
263 0 : display_get_capabilities_api get_capabilities;
264 0 : display_set_pixel_format_api set_pixel_format;
265 0 : display_set_orientation_api set_orientation;
266 : };
267 :
268 : /**
269 : * @brief Write data to display
270 : *
271 : * @param dev Pointer to device structure
272 : * @param x x Coordinate of the upper left corner where to write the buffer
273 : * @param y y Coordinate of the upper left corner where to write the buffer
274 : * @param desc Pointer to a structure describing the buffer layout
275 : * @param buf Pointer to buffer array
276 : *
277 : * @retval 0 on success else negative errno code.
278 : */
279 1 : static inline int display_write(const struct device *dev, const uint16_t x,
280 : const uint16_t y,
281 : const struct display_buffer_descriptor *desc,
282 : const void *buf)
283 : {
284 : struct display_driver_api *api =
285 : (struct display_driver_api *)dev->api;
286 :
287 : return api->write(dev, x, y, desc, buf);
288 : }
289 :
290 : /**
291 : * @brief Read data from display
292 : *
293 : * @param dev Pointer to device structure
294 : * @param x x Coordinate of the upper left corner where to read from
295 : * @param y y Coordinate of the upper left corner where to read from
296 : * @param desc Pointer to a structure describing the buffer layout
297 : * @param buf Pointer to buffer array
298 : *
299 : * @retval 0 on success else negative errno code.
300 : * @retval -ENOSYS if not implemented.
301 : */
302 1 : static inline int display_read(const struct device *dev, const uint16_t x,
303 : const uint16_t y,
304 : const struct display_buffer_descriptor *desc,
305 : void *buf)
306 : {
307 : struct display_driver_api *api =
308 : (struct display_driver_api *)dev->api;
309 :
310 : if (api->read == NULL) {
311 : return -ENOSYS;
312 : }
313 :
314 : return api->read(dev, x, y, desc, buf);
315 : }
316 :
317 : /**
318 : * @brief Clear the screen of the display device
319 : *
320 : * @param dev Pointer to device structure
321 : *
322 : * @retval 0 on success else negative errno code.
323 : * @retval -ENOSYS if not implemented.
324 : */
325 1 : static inline int display_clear(const struct device *dev)
326 : {
327 : struct display_driver_api *api =
328 : (struct display_driver_api *)dev->api;
329 :
330 : if (api->clear == NULL) {
331 : return -ENOSYS;
332 : }
333 :
334 : return api->clear(dev);
335 : }
336 :
337 : /**
338 : * @brief Get pointer to framebuffer for direct access
339 : *
340 : * @param dev Pointer to device structure
341 : *
342 : * @retval Pointer to frame buffer or NULL if direct framebuffer access
343 : * is not supported
344 : *
345 : */
346 1 : static inline void *display_get_framebuffer(const struct device *dev)
347 : {
348 : struct display_driver_api *api =
349 : (struct display_driver_api *)dev->api;
350 :
351 : if (api->get_framebuffer == NULL) {
352 : return NULL;
353 : }
354 :
355 : return api->get_framebuffer(dev);
356 : }
357 :
358 : /**
359 : * @brief Turn display blanking on
360 : *
361 : * This function blanks the complete display.
362 : * The content of the frame buffer will be retained while blanking is enabled
363 : * and the frame buffer will be accessible for read and write operations.
364 : *
365 : * In case backlight control is supported by the driver the backlight is
366 : * turned off. The backlight configuration is retained and accessible for
367 : * configuration.
368 : *
369 : * In case the driver supports display blanking the initial state of the driver
370 : * would be the same as if this function was called.
371 : *
372 : * @param dev Pointer to device structure
373 : *
374 : * @retval 0 on success else negative errno code.
375 : * @retval -ENOSYS if not implemented.
376 : */
377 1 : static inline int display_blanking_on(const struct device *dev)
378 : {
379 : struct display_driver_api *api =
380 : (struct display_driver_api *)dev->api;
381 :
382 : if (api->blanking_on == NULL) {
383 : return -ENOSYS;
384 : }
385 :
386 : return api->blanking_on(dev);
387 : }
388 :
389 : /**
390 : * @brief Turn display blanking off
391 : *
392 : * Restore the frame buffer content to the display.
393 : * In case backlight control is supported by the driver the backlight
394 : * configuration is restored.
395 : *
396 : * @param dev Pointer to device structure
397 : *
398 : * @retval 0 on success else negative errno code.
399 : * @retval -ENOSYS if not implemented.
400 : */
401 1 : static inline int display_blanking_off(const struct device *dev)
402 : {
403 : struct display_driver_api *api =
404 : (struct display_driver_api *)dev->api;
405 :
406 : if (api->blanking_off == NULL) {
407 : return -ENOSYS;
408 : }
409 :
410 : return api->blanking_off(dev);
411 : }
412 :
413 : /**
414 : * @brief Set the brightness of the display
415 : *
416 : * Set the brightness of the display in steps of 1/256, where 255 is full
417 : * brightness and 0 is minimal.
418 : *
419 : * @param dev Pointer to device structure
420 : * @param brightness Brightness in steps of 1/256
421 : *
422 : * @retval 0 on success else negative errno code.
423 : * @retval -ENOSYS if not implemented.
424 : */
425 1 : static inline int display_set_brightness(const struct device *dev,
426 : uint8_t brightness)
427 : {
428 : struct display_driver_api *api =
429 : (struct display_driver_api *)dev->api;
430 :
431 : if (api->set_brightness == NULL) {
432 : return -ENOSYS;
433 : }
434 :
435 : return api->set_brightness(dev, brightness);
436 : }
437 :
438 : /**
439 : * @brief Set the contrast of the display
440 : *
441 : * Set the contrast of the display in steps of 1/256, where 255 is maximum
442 : * difference and 0 is minimal.
443 : *
444 : * @param dev Pointer to device structure
445 : * @param contrast Contrast in steps of 1/256
446 : *
447 : * @retval 0 on success else negative errno code.
448 : * @retval -ENOSYS if not implemented.
449 : */
450 1 : static inline int display_set_contrast(const struct device *dev, uint8_t contrast)
451 : {
452 : struct display_driver_api *api =
453 : (struct display_driver_api *)dev->api;
454 :
455 : if (api->set_contrast == NULL) {
456 : return -ENOSYS;
457 : }
458 :
459 : return api->set_contrast(dev, contrast);
460 : }
461 :
462 : /**
463 : * @brief Get display capabilities
464 : *
465 : * @param dev Pointer to device structure
466 : * @param capabilities Pointer to capabilities structure to populate
467 : */
468 1 : static inline void display_get_capabilities(const struct device *dev,
469 : struct display_capabilities *
470 : capabilities)
471 : {
472 : struct display_driver_api *api =
473 : (struct display_driver_api *)dev->api;
474 :
475 : api->get_capabilities(dev, capabilities);
476 : }
477 :
478 : /**
479 : * @brief Set pixel format used by the display
480 : *
481 : * @param dev Pointer to device structure
482 : * @param pixel_format Pixel format to be used by display
483 : *
484 : * @retval 0 on success else negative errno code.
485 : * @retval -ENOSYS if not implemented.
486 : */
487 : static inline int
488 1 : display_set_pixel_format(const struct device *dev,
489 : const enum display_pixel_format pixel_format)
490 : {
491 : struct display_driver_api *api =
492 : (struct display_driver_api *)dev->api;
493 :
494 : if (api->set_pixel_format == NULL) {
495 : return -ENOSYS;
496 : }
497 :
498 : return api->set_pixel_format(dev, pixel_format);
499 : }
500 :
501 : /**
502 : * @brief Set display orientation
503 : *
504 : * @param dev Pointer to device structure
505 : * @param orientation Orientation to be used by display
506 : *
507 : * @retval 0 on success else negative errno code.
508 : * @retval -ENOSYS if not implemented.
509 : */
510 1 : static inline int display_set_orientation(const struct device *dev,
511 : const enum display_orientation
512 : orientation)
513 : {
514 : struct display_driver_api *api =
515 : (struct display_driver_api *)dev->api;
516 :
517 : if (api->set_orientation == NULL) {
518 : return -ENOSYS;
519 : }
520 :
521 : return api->set_orientation(dev, orientation);
522 : }
523 :
524 : #ifdef __cplusplus
525 : }
526 : #endif
527 :
528 : /**
529 : * @}
530 : */
531 :
532 : #endif /* ZEPHYR_INCLUDE_DRIVERS_DISPLAY_H_ */
|
