Actions_3085S4_V2/zephyr/include/drivers/display.h

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

/**
 * @file
 * @brief Public API for display drivers and applications
 */

#ifndef ZEPHYR_INCLUDE_DRIVERS_DISPLAY_H_
#define ZEPHYR_INCLUDE_DRIVERS_DISPLAY_H_

/**
 * @brief Display Interface
 * @defgroup display_interface Display Interface
 * @ingroup display_interfaces
 * @{
 */

#include <device.h>
#include <stddef.h>
#include <zephyr/types.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief Display pixel formats
 *
 * Display pixel format enumeration.
 *
 * In case a pixel format consists out of multiple bytes the byte order is
 * big endian.
 */
enum display_pixel_format {
	PIXEL_FORMAT_RGB_888		= BIT(0),
	PIXEL_FORMAT_MONO01		= BIT(1), /* 0=Black 1=White */
	PIXEL_FORMAT_MONO10		= BIT(2), /* 1=Black 0=White */
	PIXEL_FORMAT_ARGB_8888		= BIT(3),
	PIXEL_FORMAT_RGB_565		= BIT(4),
	PIXEL_FORMAT_BGR_565		= BIT(5),

	PIXEL_FORMAT_BGR_888		= BIT(6),
	PIXEL_FORMAT_XRGB_8888		= BIT(7),
	PIXEL_FORMAT_BGRA_6666		= BIT(8),
	PIXEL_FORMAT_RGBA_6666		= BIT(9),
	PIXEL_FORMAT_BGRA_5658		= BIT(10),
	PIXEL_FORMAT_BGRA_5551		= BIT(11),

	PIXEL_FORMAT_I8		= BIT(12),
	PIXEL_FORMAT_I4		= BIT(13),
	PIXEL_FORMAT_I2		= BIT(14),
	PIXEL_FORMAT_I1		= BIT(15),

	PIXEL_FORMAT_A8		= BIT(16),
	PIXEL_FORMAT_A4		= BIT(17),
	PIXEL_FORMAT_A2		= BIT(18),
	PIXEL_FORMAT_A1		= BIT(19),
	PIXEL_FORMAT_A4_LE	= BIT(20), /* little endian */
	PIXEL_FORMAT_A1_LE	= BIT(21), /* little endian */
};

enum display_screen_info {
	/**
	 * If selected, one octet represents 8 pixels ordered vertically,
	 * otherwise ordered horizontally.
	 */
	SCREEN_INFO_MONO_VTILED		= BIT(0),
	/**
	 * If selected, the MSB represents the first pixel,
	 * otherwise MSB represents the last pixel.
	 */
	SCREEN_INFO_MONO_MSB_FIRST	= BIT(1),
	/**
	 * Electrophoretic Display.
	 */
	SCREEN_INFO_EPD			= BIT(2),
	/**
	 * Screen has two alternating ram buffers
	 */
	SCREEN_INFO_DOUBLE_BUFFER	= BIT(3),
	/**
	 * Screen has x alignment constrained to width.
	 */
	SCREEN_INFO_X_ALIGNMENT_WIDTH	= BIT(4),
	/**
	 * Screen has y alignment constrained to height.
	 */
	SCREEN_INFO_Y_ALIGNMENT_HEIGHT	= BIT(5),
	/**
	 * Screen has no ram buffers
	 */
	SCREEN_INFO_ZERO_BUFFER	= BIT(6),
	/**
	 * Screen shape is round
	 */
	SCREEN_INFO_ROUND_SHAPE	= BIT(7),
};

/**
 * @enum display_orientation
 * @brief Enumeration with possible display orientation
 *
 */
enum display_orientation {
	DISPLAY_ORIENTATION_NORMAL,
	DISPLAY_ORIENTATION_ROTATED_90,
	DISPLAY_ORIENTATION_ROTATED_180,
	DISPLAY_ORIENTATION_ROTATED_270,
};

/**
 * @struct display_capabilities
 * @brief Structure holding display capabilities
 *
 * @var uint16_t display_capabilities::x_resolution
 * Display resolution in the X direction
 *
 * @var uint16_t display_capabilities::y_resolution
 * Display resolution in the Y direction
 *
 * @var uint8_t display_capabilities::refresh_rate
 * Display refresh rate in Hz
 *
 * @var uint32_t display_capabilities::supported_pixel_formats
 * Bitwise or of pixel formats supported by the display
 *
 * @var uint32_t display_capabilities::screen_info
 * Information about display panel
 *
 * @var enum display_pixel_format display_capabilities::current_pixel_format
 * Currently active pixel format for the display
 *
 * @var enum display_orientation display_capabilities::current_orientation
 * Current display orientation
 */
/** @brief Structure holding display capabilities. */
struct display_capabilities {
	/** Display resolution in the X direction */
	uint16_t x_resolution;
	/** Display resolution in the Y direction */
	uint16_t y_resolution;
	/** Bitwise or of pixel formats supported by the display */
	uint32_t supported_pixel_formats;
	/** Information about display panel */
	uint32_t screen_info;
	/** Currently active pixel format for the display */
	enum display_pixel_format current_pixel_format;
	/** Current display orientation */
	enum display_orientation current_orientation;
	/** Display refresh rate in Hz */
	uint8_t refresh_rate;
};

/**
 * @struct display_buffer_descriptor
 * @brief Structure to describe display data buffer layout
 *
 * @var uint32_t display_buffer_descriptor::buf_size
 * Data buffer size in bytes
 *
 * @var uint32_t display_buffer_descriptor::pixel_format
 * Data buffer pixel format. if 0, fallback to the current pixel format for the display
 *
 * @var uint32_t display_buffer_descriptor::width
 * Data buffer row width in pixels
 *
 * @var uint16_t display_buffer_descriptor::height
 * Data buffer column height in pixels
 *
 * @var uint32_t display_buffer_descriptor::pitch
 * Number of bytes between consecutive rows in the data buffer
 *
 */
/** @brief Structure to describe display data buffer layout */
struct display_buffer_descriptor {
	/** Data buffer size in bytes */
	uint32_t buf_size;
	/** Data buffer pixel format */
	uint32_t pixel_format;
	/** Number of bytes between consecutive rows in the data buffer */
	uint32_t pitch;
	/** Data buffer row width in pixels */
	uint32_t width;
	/** Data buffer column height in pixels */
	uint16_t height;
};

/**
 * @struct display_callback
 * @brief Structure to register specific event callback
 *
 */
struct display_callback {
	/*
	 * (*vsync)() is called when a vsync event is received (called in isr),
	 * timestamp is measured in cycles.
	 */
	void (*vsync)(const struct display_callback * callback, uint32_t timestamp);
	/* (*complete)() is called when refresh complete (called in isr) */
	void (*complete)(const struct display_callback * callback);
	/* (*pm_notify) is called when pm state changed */
	void (*pm_notify)(const struct display_callback * callback, uint32_t pm_action);
};

/**
 * @typedef display_blanking_on_api
 * @brief Callback API to turn on display blanking
 * See display_blanking_on() for argument description
 */
typedef int (*display_blanking_on_api)(const struct device *dev);

/**
 * @typedef display_blanking_off_api
 * @brief Callback API to turn off display blanking
 * See display_blanking_off() for argument description
 */
typedef int (*display_blanking_off_api)(const struct device *dev);

/**
 * @typedef display_write_api
 * @brief Callback API for writing data to the display
 * See display_write() for argument description
 */
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 display_read_api
 * @brief Callback API for reading data from the display
 * See display_read() for argument description
 */
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 display_get_framebuffer_api
 * @brief Callback API to get framebuffer pointer
 * See display_get_framebuffer() for argument description
 */
typedef void *(*display_get_framebuffer_api)(const struct device *dev);

/**
 * @typedef display_set_brightness_api
 * @brief Callback API to set display brightness
 * See display_set_brightness() for argument description
 */
typedef int (*display_set_brightness_api)(const struct device *dev,
					  const uint8_t brightness);

/**
* @typedef display_get_brightness_api
* @brief Callback API to get display brightness
* See display_get_brightness() for argument description
*/
typedef int (*display_get_brightness_api)(const struct device *dev);

/**
 * @typedef display_set_contrast_api
 * @brief Callback API to set display contrast
 * See display_set_contrast() for argument description
 */
typedef int (*display_set_contrast_api)(const struct device *dev,
					const uint8_t contrast);

/**
 * @typedef display_get_capabilities_api
 * @brief Callback API to get display capabilities
 * See display_get_capabilities() for argument description
 */
typedef void (*display_get_capabilities_api)(const struct device *dev,
					     struct display_capabilities *
					     capabilities);

/**
 * @typedef display_set_pixel_format_api
 * @brief Callback API to set pixel format used by the display
 * See display_set_pixel_format() for argument description
 */
typedef int (*display_set_pixel_format_api)(const struct device *dev,
					    const enum display_pixel_format
					    pixel_format);

/**
 * @typedef display_set_orientation_api
 * @brief Callback API to set orientation used by the display
 * See display_set_orientation() for argument description
 */
typedef int (*display_set_orientation_api)(const struct device *dev,
					   const enum display_orientation
					   orientation);

/**
 * @typedef display_register_callback_api
 * @brief Callback API to register event callback
 * See display_register_callback() for argument description
 */
typedef int (*display_register_callback_api)(const struct device *dev,
					   const struct display_callback *callback);

/**
 * @typedef display_unregister_callback_api
 * @brief Callback API to unregister event callback
 * See display_unregister_callback() for argument description
 */
typedef int (*display_unregister_callback_api)(const struct device *dev,
					   const struct display_callback *callback);

/**
 * @brief Display driver API
 * API which a display driver should expose
 */
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_get_framebuffer_api get_framebuffer;
	display_set_brightness_api set_brightness;
	display_get_brightness_api get_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_callback_api register_callback;
	display_unregister_callback_api unregister_callback;
};

/**
 * @brief Write data to display
 *
 * @param dev Pointer to device structure
 * @param x x Coordinate of the upper left corner where to write the buffer
 * @param y y Coordinate of the upper left corner where to write the buffer
 * @param desc Pointer to a structure describing the buffer layout
 * @param buf Pointer to buffer array
 *
 * @retval 0 on success else negative errno code.
 */
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)
{
	struct display_driver_api *api =
		(struct display_driver_api *)dev->api;

	return api->write(dev, x, y, desc, buf);
}

/**
 * @brief Read data from display
 *
 * @param dev Pointer to device structure
 * @param x x Coordinate of the upper left corner where to read from
 * @param y y Coordinate of the upper left corner where to read from
 * @param desc Pointer to a structure describing the buffer layout
 * @param buf Pointer to buffer array
 *
 * @retval 0 on success else negative errno code.
 */
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)
{
	struct display_driver_api *api =
		(struct display_driver_api *)dev->api;

	return api->read(dev, x, y, desc, buf);
}

/**
 * @brief Get pointer to framebuffer for direct access
 *
 * @param dev Pointer to device structure
 *
 * @retval Pointer to frame buffer or NULL if direct framebuffer access
 * is not supported
 *
 */
static inline void *display_get_framebuffer(const struct device *dev)
{
	struct display_driver_api *api =
		(struct display_driver_api *)dev->api;

	return api->get_framebuffer(dev);
}

/**
 * @brief Turn display blanking on
 *
 * This function blanks the complete display.
 * The content of the frame buffer will be retained while blanking is enabled
 * and the frame buffer will be accessible for read and write operations.
 *
 * In case backlight control is supported by the driver the backlight is
 * turned off. The backlight configuration is retained and accessible for
 * configuration.
 *
 * In case the driver supports display blanking the initial state of the driver
 * would be the same as if this function was called.
 *
 * @param dev Pointer to device structure
 *
 * @retval 0 on success else negative errno code.
 */
static inline int display_blanking_on(const struct device *dev)
{
	struct display_driver_api *api =
		(struct display_driver_api *)dev->api;

	return api->blanking_on(dev);
}

/**
 * @brief Turn display blanking off
 *
 * Restore the frame buffer content to the display.
 * In case backlight control is supported by the driver the backlight
 * configuration is restored.
 *
 * @param dev Pointer to device structure
 *
 * @retval 0 on success else negative errno code.
 */
static inline int display_blanking_off(const struct device *dev)
{
	struct display_driver_api *api =
		(struct display_driver_api *)dev->api;

	return api->blanking_off(dev);
}

/**
 * @brief Set the brightness of the display
 *
 * Set the brightness of the display in steps of 1/256, where 255 is full
 * brightness and 0 is minimal.
 *
 * @param dev Pointer to device structure
 * @param brightness Brightness in steps of 1/256
 *
 * @retval 0 on success else negative errno code.
 */
static inline int display_set_brightness(const struct device *dev,
					 uint8_t brightness)
{
	struct display_driver_api *api =
		(struct display_driver_api *)dev->api;

	return api->set_brightness(dev, brightness);
}

 /**
  * @brief Get the brightness of the display
  *
  * Get the brightness of the display in steps of 1/256, where 255 is full
  * brightness and 0 is minimal.
  *
  * @param dev Pointer to device structure
  *
  * @retval 0~255 on success else negative errno code.
  */
 static inline int display_get_brightness(const struct device *dev)
 {
	 struct display_driver_api *api =
		 (struct display_driver_api *)dev->api;
 
	 return api->get_brightness(dev);
 }

/**
 * @brief Set the contrast of the display
 *
 * Set the contrast of the display in steps of 1/256, where 255 is maximum
 * difference and 0 is minimal.
 *
 * @param dev Pointer to device structure
 * @param contrast Contrast in steps of 1/256
 *
 * @retval 0 on success else negative errno code.
 */
static inline int display_set_contrast(const struct device *dev, uint8_t contrast)
{
	struct display_driver_api *api =
		(struct display_driver_api *)dev->api;

	return api->set_contrast(dev, contrast);
}

/**
 * @brief Get display capabilities
 *
 * @param dev Pointer to device structure
 * @param capabilities Pointer to capabilities structure to populate
 */
static inline void display_get_capabilities(const struct device *dev,
					    struct display_capabilities *
					    capabilities)
{
	struct display_driver_api *api =
		(struct display_driver_api *)dev->api;

	api->get_capabilities(dev, capabilities);
}

/**
 * @brief Set pixel format used by the display
 *
 * @param dev Pointer to device structure
 * @param pixel_format Pixel format to be used by display
 *
 * @retval 0 on success else negative errno code.
 */
static inline int
display_set_pixel_format(const struct device *dev,
			 const enum display_pixel_format pixel_format)
{
	struct display_driver_api *api =
		(struct display_driver_api *)dev->api;

	return api->set_pixel_format(dev, pixel_format);
}

/**
 * @brief Set display orientation
 *
 * @param dev Pointer to device structure
 * @param orientation Orientation to be used by display
 *
 * @retval 0 on success else negative errno code.
 */
static inline int display_set_orientation(const struct device *dev,
					  const enum display_orientation
					  orientation)
{
	struct display_driver_api *api =
		(struct display_driver_api *)dev->api;

	return api->set_orientation(dev, orientation);
}

/**
 * @brief Register display event callback
 *
 * @param dev Pointer to device structure
 * @param callback Pointer to structure containing the event callbacks
 *
 * @retval 0 on success else negative errno code.
 */
static inline int display_register_callback(const struct device *dev,
				const struct display_callback *callback)
{
	struct display_driver_api *api =
		(struct display_driver_api *)dev->api;

	if (api->register_callback) {
		return api->register_callback(dev, callback);
	}

	return -ENOSYS;
}

/**
 * @brief Unregister display event callback
 *
 * @param dev Pointer to device structure
 * @param callback Pointer to structure containing the event callbacks
 *
 * @retval 0 on success else negative errno code.
 */
static inline int display_unregister_callback(const struct device *dev,
				const struct display_callback *callback)
{
	struct display_driver_api *api =
		(struct display_driver_api *)dev->api;

	if (api->unregister_callback) {
		return api->unregister_callback(dev, callback);
	}

	return -ENOSYS;
}

#ifdef __cplusplus
}
#endif
/**
 * @}
 */

#endif /* ZEPHYR_INCLUDE_DRIVERS_DISPLAY_H_ */