Color dithering

RGB-to-palette dithering helpers for display drivers. More...

Files
file	color_dither.h
	Color dithering helpers for display drivers.

Data Structures
struct	display_color_dither_state
	Runtime state owned by the color dithering helper for one display device instance. More...

Macros
#define	DISPLAY_COLOR_DITHER_DEFINE(inst)
	Define color dithering backing storage for one display driver instance.
#define	DISPLAY_COLOR_DITHER_INIT(inst)
	Initialize a driver's display_color_dither_state member for one display driver instance.

Functions
int	display_color_dither_prepare (const struct device *dev, struct display_color_dither_state *state, const struct display_buffer_descriptor **desc, const void **buf, struct display_buffer_descriptor *scratch)
	Prepare a write buffer for a PIXEL_FORMAT_I_4 native path.
void	display_color_dither_patch_caps (struct display_color_dither_state *state, struct display_capabilities *caps)
	Add helper-managed RGB formats to display capabilities.
int	display_color_dither_set_input_format (struct display_color_dither_state *state, enum display_pixel_format pf)
	Select the helper input pixel format.
bool	display_color_dither_is_active (const struct display_color_dither_state *state, enum display_pixel_format current_pixel_format)
	Report whether the helper is actively converting input to native I_4.

Detailed Description

RGB-to-palette dithering helpers for display drivers.

These helpers let a driver whose native write path consumes PIXEL_FORMAT_I_4 also accept configured RGB input formats. The helper converts each RGB write buffer to packed PIXEL_FORMAT_I_4 using the driver's color palette before the native write code runs.

A driver uses the helper at four points:

• Embed per-instance state by adding a display_color_dither_state member to the driver's data.
• Define and initialize backing storage with DISPLAY_COLOR_DITHER_DEFINE and DISPLAY_COLOR_DITHER_INIT.
• Call display_color_dither_prepare at the start of the display_driver_api.write() operation.
• Call display_color_dither_patch_caps after filling display capabilities in the driver's display_driver_api.get_capabilities() operation.
• Call display_color_dither_set_input_format from the display_driver_api.set_pixel_format()

Typical integration:

#include <zephyr/drivers/display/color_dither.h>
 
struct foo_data {
        struct display_color_dither_state color_dither;
        // ... other fields for driver state ...
};
 
static int foo_write(const struct device *dev,
                     const uint16_t x, const uint16_t y,
                     const struct display_buffer_descriptor *desc,
                     const void *buf)
{
        struct display_buffer_descriptor scratch;
        struct foo_data *data = dev->data;
        int ret = display_color_dither_prepare(dev, &data->color_dither, &desc, &buf,
                                               &scratch);
 
        if (ret < 0) {
                return ret;
        }
        // ...existing I_4-only body, unchanged...
}
 
static void foo_get_capabilities(const struct device *dev, struct display_capabilities *caps)
{
        struct foo_data *data = dev->data;
 
        // ... existing population of caps (advertising I_4, plus maybe other formats) ...
        display_color_dither_patch_caps(&data->color_dither, caps);
}
 
static int foo_set_pixel_format(const struct device *dev,
                                enum display_pixel_format pf)
{
        struct foo_data *data = dev->data;
 
        // Let the color dithering helper know which input format to expect.
        return display_color_dither_set_input_format(&data->color_dither, pf);
}
 
// In the driver instance definition, define backing storage before data:
#define FOO_DEFINE(inst)                                                               \
        DISPLAY_COLOR_DITHER_DEFINE(inst);                                             \
        static struct foo_data foo_data_##inst = {                                     \
                .color_dither = DISPLAY_COLOR_DITHER_INIT(inst),                       \
        };                                                                             \
        DEVICE_DT_INST_DEFINE(inst, ...);

When CONFIG_DISPLAY_COLOR_DITHER is disabled, the backing-storage macro is empty, display_color_dither_set_input_format() accepts only native PIXEL_FORMAT_I_4, and the other inline helpers leave driver behavior unchanged.

Macro Definition Documentation

DISPLAY_COLOR_DITHER_DEFINE

#define DISPLAY_COLOR_DITHER_DEFINE

(

inst

)

#include <zephyr/drivers/display/color_dither.h>

Value:

static uint8_t color_dither_buf_##inst[COLOR_DITHER_I4_BYTES(DT_INST_PROP(inst, width),    \
                                                             DT_INST_PROP(inst, height))]; \
COLOR_DITHER_ERRDIFF_DEFINE(inst, DT_INST_PROP(inst, width))

Define color dithering backing storage for one display driver instance.

Use once for each driver instance that can use the helper. This allocates the conversion buffer and optional error-diffusion rows. Buffer dimensions come from the instance's width and height devicetree properties.

Attention

Available only when the following Kconfig option is enabled: CONFIG_DISPLAY_COLOR_DITHER.

Parameters

inst	DT instance index.

DISPLAY_COLOR_DITHER_INIT

#define DISPLAY_COLOR_DITHER_INIT

(

inst

)

#include <zephyr/drivers/display/color_dither.h>

Value:

{                                                                                          \
        .input_format = COLOR_DITHER_DEFAULT_FMT,                                          \
        .converted_buf = color_dither_buf_##inst,                                          \
        .converted_buf_size = sizeof(color_dither_buf_##inst),                             \
        .err_rows =                                                                        \
                {                                                                          \
                        COLOR_DITHER_ERRDIFF_R0(inst),                                     \
                        COLOR_DITHER_ERRDIFF_R1(inst),                                     \
                        COLOR_DITHER_ERRDIFF_R2(inst),                                     \
                },                                                                         \
        .err_row_len = COLOR_DITHER_ERRDIFF_LEN(DT_INST_PROP(inst, width)),                \
}

Initialize a driver's display_color_dither_state member for one display driver instance.

Use in the driver data initializer after DISPLAY_COLOR_DITHER_DEFINE has defined the backing storage for the same instance. When CONFIG_DISPLAY_COLOR_DITHER is disabled this expands to an empty initializer (the state member is then zero-sized), so it can be used unconditionally.

Parameters

inst	DT instance index.

Function Documentation

display_color_dither_is_active()

bool display_color_dither_is_active	(	const struct display_color_dither_state *	state,
		enum display_pixel_format	current_pixel_format )

#include <zephyr/drivers/display/color_dither.h>

Report whether the helper is actively converting input to native I_4.

Attention

Available only when the following Kconfig option is enabled: CONFIG_DISPLAY_COLOR_DITHER.

Parameters

state	Color dithering state embedded in the driver data.
current_pixel_format	Pixel format the driver currently reports to callers.

Return values

true	The helper is converting current_pixel_format down to PIXEL_FORMAT_I_4.
false	The native I_4 write path is in effect (no helper conversion).

display_color_dither_patch_caps()

void display_color_dither_patch_caps	(	struct display_color_dither_state *	state,
		struct display_capabilities *	caps )

#include <zephyr/drivers/display/color_dither.h>

Add helper-managed RGB formats to display capabilities.

Call at the end of the driver's display_driver_api.get_capabilities() operation, after the driver has filled its native capabilities and color palette.

This adds the RGB formats enabled by Kconfig to the list of supported pixel formats in display_capabilities::supported_pixel_formats.

When the helper is actively converting, it also reports the helper-managed input format in display_capabilities::current_pixel_format.

Attention

Available only when the following Kconfig option is enabled: CONFIG_DISPLAY_COLOR_DITHER.

Parameters

state	Color dithering state embedded in the driver data.
caps	Capabilities to patch.

display_color_dither_prepare()

int display_color_dither_prepare	(	const struct device *	dev,
		struct display_color_dither_state *	state,
		const struct display_buffer_descriptor **	desc,
		const void **	buf,
		struct display_buffer_descriptor *	scratch )

#include <zephyr/drivers/display/color_dither.h>

Prepare a write buffer for a PIXEL_FORMAT_I_4 native path.

Call at the start of the driver's display_driver_api.write() operation.

If state->input_format is an RGB input format, this converts buf to packed PIXEL_FORMAT_I_4 and updates desc and buf to point at the converted data.

If state->input_format is PIXEL_FORMAT_I_4, or when the state has no conversion buffer, the inputs are left unchanged.

Attention

Available only when the following Kconfig option is enabled: CONFIG_DISPLAY_COLOR_DITHER.

Parameters

dev	Display device. Used to read the driver's color palette.
state	Color dithering state embedded in the driver data.
desc	Address of the write callback's descriptor pointer.
buf	Address of the write callback's buffer pointer.
scratch	Scratch descriptor storage owned by the caller.

Return values

0	The write can continue.
-EINVAL	The input descriptor is invalid for the selected format.
-ENOMEM	The conversion buffer is too small.
-ENOTSUP	The selected format or palette cannot be converted.

display_color_dither_set_input_format()

int display_color_dither_set_input_format	(	struct display_color_dither_state *	state,
		enum display_pixel_format	pf )

#include <zephyr/drivers/display/color_dither.h>

Select the helper input pixel format.

Call from the driver's display_driver_api.set_pixel_format() operation.

A pf value of PIXEL_FORMAT_I_4 selects the driver's native I_4 write path without helper conversion.

A pf value of a configured RGB format instructs the helper to convert the input to packed PIXEL_FORMAT_I_4 before the driver's native write path runs.

Attention

Available only when the following Kconfig option is enabled: CONFIG_DISPLAY_COLOR_DITHER.

Parameters

state	Color dithering state embedded in the driver data.
pf	Pixel format requested by the caller.

Return values

0	Success, including native PIXEL_FORMAT_I_4 without helper conversion.
-ENOTSUP	The helper is disabled, state has no conversion buffer, or pf is unsupported for RGB-to-I_4 conversion.