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 * @ingroup display_interfaces
19 * @{
20 */
21
22 #include <device.h>
23 #include <stddef.h>
24 #include <zephyr/types.h>
25
26 #ifdef __cplusplus
27 extern "C" {
28 #endif
29
30 /**
31 * @brief Display pixel formats
32 *
33 * Display pixel format enumeration.
34 *
35 * In case a pixel format consists out of multiple bytes the byte order is
36 * big endian.
37 */
38 enum display_pixel_format {
39 PIXEL_FORMAT_RGB_888 = BIT(0),
40 PIXEL_FORMAT_MONO01 = BIT(1), /* 0=Black 1=White */
41 PIXEL_FORMAT_MONO10 = BIT(2), /* 1=Black 0=White */
42 PIXEL_FORMAT_ARGB_8888 = BIT(3),
43 PIXEL_FORMAT_RGB_565 = BIT(4),
44 PIXEL_FORMAT_BGR_565 = BIT(5),
45 };
46
47 enum display_screen_info {
48 /**
49 * If selected, one octet represents 8 pixels ordered vertically,
50 * otherwise ordered horizontally.
51 */
52 SCREEN_INFO_MONO_VTILED = BIT(0),
53 /**
54 * If selected, the MSB represents the first pixel,
55 * otherwise MSB represents the last pixel.
56 */
57 SCREEN_INFO_MONO_MSB_FIRST = BIT(1),
58 /**
59 * Electrophoretic Display.
60 */
61 SCREEN_INFO_EPD = BIT(2),
62 /**
63 * Screen has two alternating ram buffers
64 */
65 SCREEN_INFO_DOUBLE_BUFFER = BIT(3),
66 /**
67 * Screen has x alignment constrained to width.
68 */
69 SCREEN_INFO_X_ALIGNMENT_WIDTH = BIT(4),
70 };
71
72 /**
73 * @enum display_orientation
74 * @brief Enumeration with possible display orientation
75 *
76 */
77 enum display_orientation {
78 DISPLAY_ORIENTATION_NORMAL,
79 DISPLAY_ORIENTATION_ROTATED_90,
80 DISPLAY_ORIENTATION_ROTATED_180,
81 DISPLAY_ORIENTATION_ROTATED_270,
82 };
83
84 /** @brief Structure holding display capabilities. */
85 struct display_capabilities {
86 /** Display resolution in the X direction */
87 uint16_t x_resolution;
88 /** Display resolution in the Y direction */
89 uint16_t y_resolution;
90 /** Bitwise or of pixel formats supported by the display */
91 uint32_t supported_pixel_formats;
92 /** Information about display panel */
93 uint32_t screen_info;
94 /** Currently active pixel format for the display */
95 enum display_pixel_format current_pixel_format;
96 /** Current display orientation */
97 enum display_orientation current_orientation;
98 };
99
100 /** @brief Structure to describe display data buffer layout */
101 struct display_buffer_descriptor {
102 /** Data buffer size in bytes */
103 uint32_t buf_size;
104 /** Data buffer row width in pixels */
105 uint16_t width;
106 /** Data buffer column height in pixels */
107 uint16_t height;
108 /** Number of pixels between consecutive rows in the data buffer */
109 uint16_t pitch;
110 };
111
112 /**
113 * @typedef display_blanking_on_api
114 * @brief Callback API to turn on display blanking
115 * See display_blanking_on() for argument description
116 */
117 typedef int (*display_blanking_on_api)(const struct device *dev);
118
119 /**
120 * @typedef display_blanking_off_api
121 * @brief Callback API to turn off display blanking
122 * See display_blanking_off() for argument description
123 */
124 typedef int (*display_blanking_off_api)(const struct device *dev);
125
126 /**
127 * @typedef display_write_api
128 * @brief Callback API for writing data to the display
129 * See display_write() for argument description
130 */
131 typedef int (*display_write_api)(const struct device *dev, const uint16_t x,
132 const uint16_t y,
133 const struct display_buffer_descriptor *desc,
134 const void *buf);
135
136 /**
137 * @typedef display_read_api
138 * @brief Callback API for reading data from the display
139 * See display_read() for argument description
140 */
141 typedef int (*display_read_api)(const struct device *dev, const uint16_t x,
142 const uint16_t y,
143 const struct display_buffer_descriptor *desc,
144 void *buf);
145
146 /**
147 * @typedef display_get_framebuffer_api
148 * @brief Callback API to get framebuffer pointer
149 * See display_get_framebuffer() for argument description
150 */
151 typedef void *(*display_get_framebuffer_api)(const struct device *dev);
152
153 /**
154 * @typedef display_set_brightness_api
155 * @brief Callback API to set display brightness
156 * See display_set_brightness() for argument description
157 */
158 typedef int (*display_set_brightness_api)(const struct device *dev,
159 const uint8_t brightness);
160
161 /**
162 * @typedef display_set_contrast_api
163 * @brief Callback API to set display contrast
164 * See display_set_contrast() for argument description
165 */
166 typedef int (*display_set_contrast_api)(const struct device *dev,
167 const uint8_t contrast);
168
169 /**
170 * @typedef display_get_capabilities_api
171 * @brief Callback API to get display capabilities
172 * See display_get_capabilities() for argument description
173 */
174 typedef void (*display_get_capabilities_api)(const struct device *dev,
175 struct display_capabilities *
176 capabilities);
177
178 /**
179 * @typedef display_set_pixel_format_api
180 * @brief Callback API to set pixel format used by the display
181 * See display_set_pixel_format() for argument description
182 */
183 typedef int (*display_set_pixel_format_api)(const struct device *dev,
184 const enum display_pixel_format
185 pixel_format);
186
187 /**
188 * @typedef display_set_orientation_api
189 * @brief Callback API to set orientation used by the display
190 * See display_set_orientation() for argument description
191 */
192 typedef int (*display_set_orientation_api)(const struct device *dev,
193 const enum display_orientation
194 orientation);
195
196 /**
197 * @brief Display driver API
198 * API which a display driver should expose
199 */
200 struct display_driver_api {
201 display_blanking_on_api blanking_on;
202 display_blanking_off_api blanking_off;
203 display_write_api write;
204 display_read_api read;
205 display_get_framebuffer_api get_framebuffer;
206 display_set_brightness_api set_brightness;
207 display_set_contrast_api set_contrast;
208 display_get_capabilities_api get_capabilities;
209 display_set_pixel_format_api set_pixel_format;
210 display_set_orientation_api set_orientation;
211 };
212
213 /**
214 * @brief Write data to display
215 *
216 * @param dev Pointer to device structure
217 * @param x x Coordinate of the upper left corner where to write the buffer
218 * @param y y Coordinate of the upper left corner where to write the buffer
219 * @param desc Pointer to a structure describing the buffer layout
220 * @param buf Pointer to buffer array
221 *
222 * @retval 0 on success else negative errno code.
223 */
display_write(const struct device * dev,const uint16_t x,const uint16_t y,const struct display_buffer_descriptor * desc,const void * buf)224 static inline int display_write(const struct device *dev, const uint16_t x,
225 const uint16_t y,
226 const struct display_buffer_descriptor *desc,
227 const void *buf)
228 {
229 struct display_driver_api *api =
230 (struct display_driver_api *)dev->api;
231
232 return api->write(dev, x, y, desc, buf);
233 }
234
235 /**
236 * @brief Read data from display
237 *
238 * @param dev Pointer to device structure
239 * @param x x Coordinate of the upper left corner where to read from
240 * @param y y Coordinate of the upper left corner where to read from
241 * @param desc Pointer to a structure describing the buffer layout
242 * @param buf Pointer to buffer array
243 *
244 * @retval 0 on success else negative errno code.
245 */
display_read(const struct device * dev,const uint16_t x,const uint16_t y,const struct display_buffer_descriptor * desc,void * buf)246 static inline int display_read(const struct device *dev, const uint16_t x,
247 const uint16_t y,
248 const struct display_buffer_descriptor *desc,
249 void *buf)
250 {
251 struct display_driver_api *api =
252 (struct display_driver_api *)dev->api;
253
254 return api->read(dev, x, y, desc, buf);
255 }
256
257 /**
258 * @brief Get pointer to framebuffer for direct access
259 *
260 * @param dev Pointer to device structure
261 *
262 * @retval Pointer to frame buffer or NULL if direct framebuffer access
263 * is not supported
264 *
265 */
display_get_framebuffer(const struct device * dev)266 static inline void *display_get_framebuffer(const struct device *dev)
267 {
268 struct display_driver_api *api =
269 (struct display_driver_api *)dev->api;
270
271 return api->get_framebuffer(dev);
272 }
273
274 /**
275 * @brief Turn display blanking on
276 *
277 * This function blanks the complete display.
278 * The content of the frame buffer will be retained while blanking is enabled
279 * and the frame buffer will be accessible for read and write operations.
280 *
281 * In case backlight control is supported by the driver the backlight is
282 * turned off. The backlight configuration is retained and accessible for
283 * configuration.
284 *
285 * In case the driver supports display blanking the initial state of the driver
286 * would be the same as if this function was called.
287 *
288 * @param dev Pointer to device structure
289 *
290 * @retval 0 on success else negative errno code.
291 */
display_blanking_on(const struct device * dev)292 static inline int display_blanking_on(const struct device *dev)
293 {
294 struct display_driver_api *api =
295 (struct display_driver_api *)dev->api;
296
297 return api->blanking_on(dev);
298 }
299
300 /**
301 * @brief Turn display blanking off
302 *
303 * Restore the frame buffer content to the display.
304 * In case backlight control is supported by the driver the backlight
305 * configuration is restored.
306 *
307 * @param dev Pointer to device structure
308 *
309 * @retval 0 on success else negative errno code.
310 */
display_blanking_off(const struct device * dev)311 static inline int display_blanking_off(const struct device *dev)
312 {
313 struct display_driver_api *api =
314 (struct display_driver_api *)dev->api;
315
316 return api->blanking_off(dev);
317 }
318
319 /**
320 * @brief Set the brightness of the display
321 *
322 * Set the brightness of the display in steps of 1/256, where 255 is full
323 * brightness and 0 is minimal.
324 *
325 * @param dev Pointer to device structure
326 * @param brightness Brightness in steps of 1/256
327 *
328 * @retval 0 on success else negative errno code.
329 */
display_set_brightness(const struct device * dev,uint8_t brightness)330 static inline int display_set_brightness(const struct device *dev,
331 uint8_t brightness)
332 {
333 struct display_driver_api *api =
334 (struct display_driver_api *)dev->api;
335
336 return api->set_brightness(dev, brightness);
337 }
338
339 /**
340 * @brief Set the contrast of the display
341 *
342 * Set the contrast of the display in steps of 1/256, where 255 is maximum
343 * difference and 0 is minimal.
344 *
345 * @param dev Pointer to device structure
346 * @param contrast Contrast in steps of 1/256
347 *
348 * @retval 0 on success else negative errno code.
349 */
display_set_contrast(const struct device * dev,uint8_t contrast)350 static inline int display_set_contrast(const struct device *dev, uint8_t contrast)
351 {
352 struct display_driver_api *api =
353 (struct display_driver_api *)dev->api;
354
355 return api->set_contrast(dev, contrast);
356 }
357
358 /**
359 * @brief Get display capabilities
360 *
361 * @param dev Pointer to device structure
362 * @param capabilities Pointer to capabilities structure to populate
363 */
display_get_capabilities(const struct device * dev,struct display_capabilities * capabilities)364 static inline void display_get_capabilities(const struct device *dev,
365 struct display_capabilities *
366 capabilities)
367 {
368 struct display_driver_api *api =
369 (struct display_driver_api *)dev->api;
370
371 api->get_capabilities(dev, capabilities);
372 }
373
374 /**
375 * @brief Set pixel format used by the display
376 *
377 * @param dev Pointer to device structure
378 * @param pixel_format Pixel format to be used by display
379 *
380 * @retval 0 on success else negative errno code.
381 */
382 static inline int
display_set_pixel_format(const struct device * dev,const enum display_pixel_format pixel_format)383 display_set_pixel_format(const struct device *dev,
384 const enum display_pixel_format pixel_format)
385 {
386 struct display_driver_api *api =
387 (struct display_driver_api *)dev->api;
388
389 return api->set_pixel_format(dev, pixel_format);
390 }
391
392 /**
393 * @brief Set display orientation
394 *
395 * @param dev Pointer to device structure
396 * @param orientation Orientation to be used by display
397 *
398 * @retval 0 on success else negative errno code.
399 */
display_set_orientation(const struct device * dev,const enum display_orientation orientation)400 static inline int display_set_orientation(const struct device *dev,
401 const enum display_orientation
402 orientation)
403 {
404 struct display_driver_api *api =
405 (struct display_driver_api *)dev->api;
406
407 return api->set_orientation(dev, orientation);
408 }
409
410 #ifdef __cplusplus
411 }
412 #endif
413
414 /**
415 * @}
416 */
417
418 #endif /* ZEPHYR_INCLUDE_DRIVERS_DISPLAY_H_ */
419
