display.h

Go to the documentation of this file.

/*
 * Copyright (c) 2017 Jan Van Winkel <jan.van_winkel@dxplore.eu>
 * SPDX-FileCopyrightText: 2026 Abderrahmane JARMOUNI
 *
 * SPDX-License-Identifier: Apache-2.0
 */

 
#ifndef ZEPHYR_INCLUDE_DRIVERS_DISPLAY_H_
#define ZEPHYR_INCLUDE_DRIVERS_DISPLAY_H_

 
#include <zephyr/device.h>
#include <errno.h>
#include <stddef.h>
#include <zephyr/types.h>
#include <zephyr/dt-bindings/display/panel.h>
 
#ifdef __cplusplus
extern "C" {
#endif

enum display_pixel_format {
        PIXEL_FORMAT_RGB_888            = BIT(0), 

        PIXEL_FORMAT_MONO01             = BIT(1), 
        PIXEL_FORMAT_MONO10             = BIT(2), 

        PIXEL_FORMAT_ARGB_8888          = BIT(3), 

        PIXEL_FORMAT_RGB_565            = BIT(4),

        PIXEL_FORMAT_RGB_565X           = BIT(5),

        PIXEL_FORMAT_L_8                = BIT(6), 

        PIXEL_FORMAT_AL_88              = BIT(7), 

        PIXEL_FORMAT_XRGB_8888 = BIT(8), 

        PIXEL_FORMAT_BGR_888 = BIT(9), 

        PIXEL_FORMAT_ABGR_8888 = BIT(10), 

        PIXEL_FORMAT_RGBA_8888 = BIT(11), 

        PIXEL_FORMAT_BGRA_8888 = BIT(12), 

        PIXEL_FORMAT_I_4 = BIT(13), 

        PIXEL_FORMAT_L_4 = BIT(14), 
};

#define DISPLAY_BITS_PER_PIXEL(fmt)                                             \
        ((((fmt & PIXEL_FORMAT_RGB_888) >> 0) * 24U) +                          \
        (((fmt & PIXEL_FORMAT_MONO01) >> 1) * 1U) +                             \
        (((fmt & PIXEL_FORMAT_MONO10) >> 2) * 1U) +                             \
        (((fmt & PIXEL_FORMAT_ARGB_8888) >> 3) * 32U) +                         \
        (((fmt & PIXEL_FORMAT_RGB_565) >> 4) * 16U) +                           \
        (((fmt & PIXEL_FORMAT_RGB_565X) >> 5) * 16U) +                          \
        (((fmt & PIXEL_FORMAT_L_8) >> 6) * 8U) +                                \
        (((fmt & PIXEL_FORMAT_AL_88) >> 7) * 16U) +                             \
        (((fmt & PIXEL_FORMAT_XRGB_8888) >> 8) * 32U) +                         \
        (((fmt & PIXEL_FORMAT_BGR_888) >> 9) * 24U) +                           \
        (((fmt & PIXEL_FORMAT_ABGR_8888) >> 10) * 32U) +                        \
        (((fmt & PIXEL_FORMAT_RGBA_8888) >> 11) * 32U) +                        \
        (((fmt & PIXEL_FORMAT_BGRA_8888) >> 12) * 32U) +                        \
        (((fmt & PIXEL_FORMAT_I_4) >> 13) * 4U) +                               \
        (((fmt & PIXEL_FORMAT_L_4) >> 14) * 4U))

enum display_screen_info {
        SCREEN_INFO_MONO_VTILED         = BIT(0),
        SCREEN_INFO_MONO_MSB_FIRST      = BIT(1),
        SCREEN_INFO_EPD                 = BIT(2),
        SCREEN_INFO_DOUBLE_BUFFER       = BIT(3),
        SCREEN_INFO_X_ALIGNMENT_WIDTH   = BIT(4),
};

enum display_orientation {
        DISPLAY_ORIENTATION_NORMAL,      
        DISPLAY_ORIENTATION_ROTATED_90,  
        DISPLAY_ORIENTATION_ROTATED_180, 
        DISPLAY_ORIENTATION_ROTATED_270, 
};
 
#if defined(CONFIG_DISPLAY_COLOR_PALETTE) || defined(__DOXYGEN__)

struct display_palette_color {
        uint8_t b;
        uint8_t g;
        uint8_t r;
        uint8_t a;
};
 
#endif /* defined(CONFIG_DISPLAY_COLOR_PALETTE) || defined(__DOXYGEN__) */

struct display_capabilities {
        uint16_t x_resolution;
        uint16_t y_resolution;
        uint32_t supported_pixel_formats;
        uint32_t screen_info;
        enum display_pixel_format current_pixel_format;
        enum display_orientation current_orientation;
        uint32_t supported_events;
#if defined(CONFIG_DISPLAY_COLOR_PALETTE) || defined(__DOXYGEN__)
        struct display_palette_color color_palette[CONFIG_DISPLAY_COLOR_PALETTE_MAX_SIZE];
#endif /* defined(CONFIG_DISPLAY_COLOR_PALETTE) || defined(__DOXYGEN__) */
};

struct display_buffer_descriptor {
        uint32_t buf_size;
        uint16_t width;
        uint16_t height;
        uint16_t pitch;
        bool frame_incomplete;
};

struct display_event_data {
        uint64_t timestamp;
        union {
                int line;
                int buffer_id;
        } info;
};

enum display_event {
        DISPLAY_EVENT_LINE_INT = BIT(0),
        DISPLAY_EVENT_VSYNC = BIT(1),
        DISPLAY_EVENT_FRAME_DONE = BIT(2),
        DISPLAY_EVENT_FIFO_UNDERFLOW = BIT(3),
};

enum display_event_result {
        DISPLAY_EVENT_RESULT_CONTINUE = 0,
        DISPLAY_EVENT_RESULT_HANDLED = 1,
};

typedef enum display_event_result (*display_event_cb_t)(const struct device *dev,
                                  uint32_t evt,
                                  const struct display_event_data *data,
                                  void *user_data);


typedef int (*display_blanking_on_api)(const struct device *dev);

typedef int (*display_blanking_off_api)(const struct device *dev);

typedef int (*display_write_api)(const struct device *dev, const uint16_t x,
                                 const uint16_t y,
                                 const struct display_buffer_descriptor *desc,
                                 const void *buf);

typedef int (*display_read_api)(const struct device *dev, const uint16_t x,
                                const uint16_t y,
                                const struct display_buffer_descriptor *desc,
                                void *buf);

typedef int (*display_clear_api)(const struct device *dev);

typedef void *(*display_get_framebuffer_api)(const struct device *dev);

typedef int (*display_set_brightness_api)(const struct device *dev,
                                          const uint8_t brightness);

typedef int (*display_set_contrast_api)(const struct device *dev,
                                        const uint8_t contrast);

typedef void (*display_get_capabilities_api)(const struct device *dev,
                                             struct display_capabilities *
                                             capabilities);

typedef int (*display_set_pixel_format_api)(const struct device *dev,
                                            const enum display_pixel_format
                                            pixel_format);

typedef int (*display_set_orientation_api)(const struct device *dev,
                                           const enum display_orientation
                                           orientation);

typedef int (*display_register_event_cb_api)(const struct device *dev,
                                             display_event_cb_t cb, void *user_data,
                                             uint32_t event_mask, bool in_isr,
                                             uint32_t *out_reg_handle);

typedef int (*display_unregister_event_cb_api)(const struct device *dev, uint32_t reg_handle);

__subsystem struct display_driver_api {
        display_blanking_on_api blanking_on;
        display_blanking_off_api blanking_off;
        display_write_api write;
        display_read_api read;
        display_clear_api clear;
        display_get_framebuffer_api get_framebuffer;
        display_set_brightness_api set_brightness;
        display_set_contrast_api set_contrast;
        display_get_capabilities_api get_capabilities;
        display_set_pixel_format_api set_pixel_format;
        display_set_orientation_api set_orientation;
        display_register_event_cb_api register_event_cb;
        display_unregister_event_cb_api unregister_event_cb;
};


static inline int display_write(const struct device *dev, const uint16_t x,
                                const uint16_t y,
                                const struct display_buffer_descriptor *desc,
                                const void *buf)
{
        return DEVICE_API_GET(display, dev)->write(dev, x, y, desc, buf);
}

static inline int display_read(const struct device *dev, const uint16_t x,
                               const uint16_t y,
                               const struct display_buffer_descriptor *desc,
                               void *buf)
{
        const struct display_driver_api *api = DEVICE_API_GET(display, dev);
 
        if (api->read == NULL) {
                return -ENOSYS;
        }
 
        return api->read(dev, x, y, desc, buf);
}

static inline int display_clear(const struct device *dev)
{
        const struct display_driver_api *api = DEVICE_API_GET(display, dev);
 
        if (api->clear == NULL) {
                return -ENOSYS;
        }
 
        return api->clear(dev);
}

static inline void *display_get_framebuffer(const struct device *dev)
{
        const struct display_driver_api *api = DEVICE_API_GET(display, dev);
 
        if (api->get_framebuffer == NULL) {
                return NULL;
        }
 
        return api->get_framebuffer(dev);
}

static inline int display_blanking_on(const struct device *dev)
{
        const struct display_driver_api *api = DEVICE_API_GET(display, dev);
 
        if (api->blanking_on == NULL) {
                return -ENOSYS;
        }
 
        return api->blanking_on(dev);
}

static inline int display_blanking_off(const struct device *dev)
{
        const struct display_driver_api *api = DEVICE_API_GET(display, dev);
 
        if (api->blanking_off == NULL) {
                return -ENOSYS;
        }
 
        return api->blanking_off(dev);
}

static inline int display_set_brightness(const struct device *dev,
                                         uint8_t brightness)
{
        const struct display_driver_api *api = DEVICE_API_GET(display, dev);
 
        if (api->set_brightness == NULL) {
                return -ENOSYS;
        }
 
        return api->set_brightness(dev, brightness);
}

static inline int display_set_contrast(const struct device *dev, uint8_t contrast)
{
        const struct display_driver_api *api = DEVICE_API_GET(display, dev);
 
        if (api->set_contrast == NULL) {
                return -ENOSYS;
        }
 
        return api->set_contrast(dev, contrast);
}

static inline void display_get_capabilities(const struct device *dev,
                                            struct display_capabilities *
                                            capabilities)
{
        __ASSERT(capabilities != NULL, "display_capabilities struct is NULL");
        memset(capabilities, 0, sizeof(struct display_capabilities));
        DEVICE_API_GET(display, dev)->get_capabilities(dev, capabilities);
}

static inline int
display_set_pixel_format(const struct device *dev,
                         const enum display_pixel_format pixel_format)
{
        const struct display_driver_api *api = DEVICE_API_GET(display, dev);
 
        if (api->set_pixel_format == NULL) {
                return -ENOSYS;
        }
 
        return api->set_pixel_format(dev, pixel_format);
}

static inline int display_set_orientation(const struct device *dev,
                                          const enum display_orientation
                                          orientation)
{
        const struct display_driver_api *api = DEVICE_API_GET(display, dev);
 
        if (api->set_orientation == NULL) {
                return -ENOSYS;
        }
 
        return api->set_orientation(dev, orientation);
}

static inline int display_register_event_cb(const struct device *dev,
                                            display_event_cb_t cb, void *user_data,
                                            uint32_t event_mask, bool in_isr,
                                            uint32_t *out_reg_handle)
{
        __ASSERT(cb != NULL, "Registration failed: callback function pointer is NULL");
 
        const struct display_driver_api *api = DEVICE_API_GET(display, dev);
        struct display_capabilities caps;
 
        if (api->register_event_cb == NULL) {
                return -ENOSYS;
        }
 
        api->get_capabilities(dev, &caps);
        if (!caps.supported_events) {
                return -ENOSYS;
        }
        if (event_mask == 0 || (~caps.supported_events & event_mask)) {
                return -EINVAL;
        }
 
        return api->register_event_cb(dev, cb, user_data, event_mask, in_isr, out_reg_handle);
}

static inline int display_unregister_event_cb(const struct device *dev, uint32_t reg_handle)
{
        const struct display_driver_api *api = DEVICE_API_GET(display, dev);
 
        if (api->unregister_event_cb == NULL || api->register_event_cb == NULL) {
                return -ENOSYS;
        }
 
        return api->unregister_event_cb(dev, reg_handle);
}
 
#ifdef __cplusplus
}
#endif

 
#endif /* ZEPHYR_INCLUDE_DRIVERS_DISPLAY_H_ */