system/ulib/ddk/include/ddk/protocol/display-controller.h - zircon - Git at Google

 // Copyright 2018 The Fuchsia Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.

 // WARNING: This file is machine generated by fidlc.

 #pragma once

 #include <zircon/compiler.h>
 #include <zircon/device/audio.h>
 #include <zircon/types.h>

 __BEGIN_CDECLS;

 // Forward declarations

 typedef struct image_plane image_plane_t;
 typedef uint32_t client_t;
 // The client should convert the corresponding layer to a primary layer.
 #define CLIENT_USE_PRIMARY UINT32_C(1)
 // The client should compose all layers with MERGE_BASE and MERGE_SRC into a new,
 // single primary layer at the MERGE_BASE layer's z-order. The driver must accept
 // a fullscreen layer with the default pixel format, but may accept other layer
 // parameters.
 // MERGE_BASE should only be set on one layer per display. If it is set on multiple
 // layers, the client will arbitrarily pick one and change the rest to MERGE_SRC.
 #define CLIENT_MERGE_BASE UINT32_C(2)
 #define CLIENT_MERGE_SRC UINT32_C(4)
 // The client should pre-scale the image so that src_frame's dimensions are equal
 // to dest_frame's dimensions.
 #define CLIENT_FRAME_SCALE UINT32_C(8)
 // The client should pre-clip the image so that src_frame's dimensions are equal to
 // the image's dimensions.
 #define CLIENT_SRC_FRAME UINT32_C(16)
 // The client should pre-apply the transformation so TRANSFORM_IDENTITY can be used.
 #define CLIENT_TRANSFORM UINT32_C(32)
 // The client should apply the color conversion.
 #define CLIENT_COLOR_CONVERSION UINT32_C(64)
 // The client should apply the alpha transformation itself.
 #define CLIENT_ALPHA UINT32_C(128)

 typedef uint32_t config_display_t;
 // The display mode configuration is valid. Note that this is distinct from
 // whether or not the layer configuration is valid.
 #define CONFIG_DISPLAY_OK UINT32_C(0)
 // Error indicating that the hardware cannot simultaniously support the
 // requested number of displays.
 #define CONFIG_DISPLAY_TOO_MANY UINT32_C(1)
 // Error indicating that the hardware cannot simultaniously support the given
 // set of display modes. To support a mode, the display must be able to display
 // a single layer with width and height equal to the requested mode and the
 // preferred pixel format.
 #define CONFIG_DISPLAY_UNSUPPORTED_MODES UINT32_C(2)

 typedef uint32_t color_conversion_t;
 // If set, use the 0 vector for the color conversion preoffset
 #define COLOR_CONVERSION_PREOFFSET UINT32_C(1)
 // If set, use the identity matrix for the color conversion coefficients
 #define COLOR_CONVERSION_COEFFICIENTS UINT32_C(2)
 // If set, use the 0 vector for the color conversion postoffset
 #define COLOR_CONVERSION_POSTOFFSET UINT32_C(4)

 // constants for display_config's mode_flags field
 typedef uint32_t mode_flag_t;
 #define MODE_FLAG_VSYNC_POSITIVE UINT32_C(1)
 #define MODE_FLAG_HSYNC_POSITIVE UINT32_C(2)
 #define MODE_FLAG_INTERLACED UINT32_C(4)
 #define MODE_FLAG_ALTERNATING_VBLANK UINT32_C(8)
 #define MODE_FLAG_DOUBLE_CLOCKED UINT32_C(16)

 typedef struct display_mode display_mode_t;
 typedef struct display_config display_config_t;
 // Types of layers.
 typedef uint32_t layer_type_t;
 #define LAYER_TYPE_PRIMARY UINT32_C(0)
 #define LAYER_TYPE_CURSOR UINT32_C(1)
 #define LAYER_TYPE_COLOR UINT32_C(2)

 // Rotations are applied counter-clockwise, and are applied before reflections.
 typedef uint32_t frame_transform_t;
 #define FRAME_TRANSFORM_IDENTITY UINT32_C(0)
 #define FRAME_TRANSFORM_REFLECT_X UINT32_C(1)
 #define FRAME_TRANSFORM_REFLECT_Y UINT32_C(2)
 #define FRAME_TRANSFORM_ROT_90 UINT32_C(3)
 #define FRAME_TRANSFORM_ROT_180 UINT32_C(4)
 #define FRAME_TRANSFORM_ROT_270 UINT32_C(5)
 #define FRAME_TRANSFORM_ROT_90_REFLECT_X UINT32_C(6)
 #define FRAME_TRANSFORM_ROT_90_REFLECT_Y UINT32_C(7)

 typedef struct frame frame_t;
 typedef struct added_display_info added_display_info_t;
 typedef uint32_t zx_pixel_format_t;

 typedef struct cursor_info cursor_info_t;
 typedef struct color_layer color_layer_t;
 typedef struct image image_t;
 typedef struct cursor_layer cursor_layer_t;
 typedef uint8_t alpha_t;
 #define ALPHA_DISABLE UINT8_C(0)
 #define ALPHA_PREMULTIPLIED UINT8_C(1)
 #define ALPHA_HW_MULTIPLY UINT8_C(2)

 typedef struct primary_layer primary_layer_t;
 typedef union layer_config layer_config_t;
 typedef struct layer layer_t;
 typedef struct display_params display_params_t;
 typedef union panel panel_t;
 typedef struct added_display_args added_display_args_t;
 typedef struct display_controller_interface display_controller_interface_t;
 typedef struct display_controller_protocol display_controller_protocol_t;

 // Declarations

 // The image is linear and VMO backed.
 #define IMAGE_TYPE_SIMPLE UINT32_C(0)

 // A structure containing information about each plane of an image.
 struct image_plane {
     uint32_t byte_offset;
     uint32_t bytes_per_row;
 };

 // The video parameters which specify the display mode.
 struct display_mode {
     uint32_t pixel_clock_10khz;
     uint32_t h_addressable;
     uint32_t h_front_porch;
     uint32_t h_sync_pulse;
     uint32_t h_blanking;
     uint32_t v_addressable;
     uint32_t v_front_porch;
     uint32_t v_sync_pulse;
     uint32_t v_blanking;
     // A bitmask of MODE_FLAG_* values
     uint32_t flags;
 };

 struct display_config {
     // the display id to which the configuration applies
     uint64_t display_id;
     display_mode_t mode;
     // Bitmask of COLOR_CONVERSION_* flags
     uint32_t cc_flags;
     // Color conversion is applied to each pixel according to the formula:
     // (cc_coefficients * (pixel + cc_preoffsets)) + cc_postoffsets
     // where pixel is a column vector consiting of the pixel's 3 components.
     float cc_preoffsets[3];
     float cc_coefficients[3][3];
     float cc_postoffsets[3];
     layer_t** layer_list;
     size_t layer_count;
 };

 struct frame {
     // (|x_pos|, |y_pos|) specifies the position of the upper-left corner
     // of the frame.
     uint32_t x_pos;
     uint32_t y_pos;
     uint32_t width;
     uint32_t height;
 };

 // Out parameters will be populated before on_displays_changed returns.
 struct added_display_info {
     bool is_hdmi_out;
     bool is_standard_srgb_out;
     uint32_t audio_format_count;
     const char* manufacturer_name;
     // null-terminated
     char monitor_name[14];
     // null-terminated
     char monitor_serial[14];
 };

 // Info about valid cursor configuratoins.
 struct cursor_info {
     // The width and height of the cursor configuration, in pixels.
     uint32_t width;
     uint32_t height;
     zx_pixel_format_t format;
 };

 struct color_layer {
     zx_pixel_format_t format;
     // The color to use for the layer. The color is little-endian, and is
     // guaranteed to be of the appropriate size.
     uint8_t* color_list;
     size_t color_count;
 };

 // A structure containing information about an image.
 struct image {
     // The width and height of the image in pixels.
     uint32_t width;
     uint32_t height;
     // The pixel format of the image.
     zx_pixel_format_t pixel_format;
     // The type conveys information about what is providing the pixel data. If this is not
     // IMAGE_FORMAT_SIMPLE, it is up to the driver and buffer producer to agree on the meaning
     // of the value through some mechanism outside the scope of this API.
     uint32_t type;
     image_plane_t planes[4];
     // A driver-defined handle to the image. Each handle must be unique.
     uint64_t handle;
 };

 struct cursor_layer {
     image_t image;
     // The position of the top-left corner of the cursor's image. When being
     // applied to a display, the cursor is guaranteed to have at least one
     // pixel of overlap with the display.
     zx_status_t x_pos;
     zx_status_t y_pos;
 };

 #define INVALID_DISPLAY_ID UINT32_C(0)

 struct primary_layer {
     image_t image;
     // An ALPHA_* constant.
     // If |alpha_mode| == `ALPHA_DISABLED`, the layer is opaque and alpha_layer_val is ignored.
     // If |alpha_mode| == `PREMULTIPLIED` or `HW_MULTIPLY` and |alpha_layer_val| is NaN, the alpha
     // used when blending is determined by the per-pixel alpha channel.
     // If |alpha_mode| == `PREMULTIPLIED` or `HW_MULTIPLY` and |alpha_layer_val| is not NaN, the
     // alpha used when blending is the product of alpha_layer_val and any per-pixel alpha.
     // Additionally, if alpha_mode == PREMULTIPLIED, then the hardware must premultiply the color
     // channel with alpha_layer_val before blending.
     // If alpha_layer_val is not NaN, it will be in the range [0, 1].
     alpha_t alpha_mode;
     float alpha_layer_val;
     frame_transform_t transform_mode;
     // The source frame, where (0,0) is the top-left corner of the image. The
     // client guarantees that src_frame lies entirely within the image.
     frame_t src_frame;
     // The destination frame, where (0,0) is the top-left corner of the
     // composed output. The client guarantees that dest_frame lies entirely
     // within the composed output.
     frame_t dest_frame;
 };

 union layer_config {
     primary_layer_t primary;
     cursor_layer_t cursor;
     color_layer_t color;
 };

 struct layer {
     layer_type_t type;
     // z_index of the layer. See |check_configuration| and |apply_configuration|.
     uint32_t z_index;
     layer_config_t cfg;
 };

 // A fallback structure to convey display information without an edid.
 struct display_params {
     uint32_t width;
     uint32_t height;
     uint32_t refresh_rate_e2;
 };

 union panel {
     // The bus_id to use to read this display's edid from the device's i2c protocol.
     uint32_t i2c_bus_id;
     // The display's parameters if an edid is not present.
     display_params_t params;
 };

 // A structure containing information a connected display.
 struct added_display_args {
     uint64_t display_id;
     // A flag indicating whether or not the display has a valid edid.
     // If true, the device should expose an ZX_PROTOCOL_I2C_IMPL device through get_protocol, in
     // addition to the ZX_PROTOCOL_DISPLAY_CONTROLLER_IMPL protocol. Note that the i2c device
     // will be called from the on_displays_changed callback, so care should be taken to avoid
     // deadlocks or double-locking.
     // If no edid is present, then the meaning of display_config's mode structure is
     // undefined, and drivers should ignore it in check_configuration and apply_configuration.
     bool edid_present;
     panel_t panel;
     // A list of pixel formats supported by the display. The first entry is the
     // preferred pixel format.
     zx_pixel_format_t* pixel_format_list;
     size_t pixel_format_count;
     // A list of cursor configurations most likely to be accepted by the driver. Can
     // be null if cursor_count is 0.
     // The driver may reject some of these configurations in some circumstances, and
     // it may accept other configurations, but at least one of these configurations
     // should be valid at most times.
     cursor_info_t* cursor_info_list;
     size_t cursor_info_count;
 };

 typedef struct display_controller_interface_ops {
     void (*on_displays_changed)(void* ctx, const added_display_args_t* added_display_list,
                                 size_t added_display_count, const uint64_t* removed_display_list,
                                 size_t removed_display_count,
                                 added_display_info_t* out_display_info_list,
                                 size_t display_info_count, size_t* out_display_info_actual);
     void (*on_display_vsync)(void* ctx, uint64_t display_id, int64_t timestamp,
                              const uint64_t* handle_list, size_t handle_count);
     zx_status_t (*get_audio_format)(void* ctx, uint64_t display_id, uint32_t fmt_idx,
                                     audio_stream_format_range_t* out_fmt);
 } display_controller_interface_ops_t;

 // The client will not make any `ZX_PROTOCOL_DISPLAY_CONTROLLER_IMPL` calls into the device
 // during these callbacks.
 struct display_controller_interface {
     display_controller_interface_ops_t* ops;
     void* ctx;
 };

 // Callbacks which are invoked when displays are added or removed. |added_display_list| and
 // |removed_display_list| point to arrays of the display ids which were added and removed. If
 // |added_display_count| or |removed_display_count| is 0, the corresponding array can be NULL.
 // The driver must be done accessing any images which were on the removed displays.
 // The driver should call this function when the callback is registered if any displays
 // are present.
 static inline void display_controller_interface_on_displays_changed(
     const display_controller_interface_t* proto, const added_display_args_t* added_display_list,
     size_t added_display_count, const uint64_t* removed_display_list, size_t removed_display_count,
     added_display_info_t* out_display_info_list, size_t display_info_count,
     size_t* out_display_info_actual) {
     proto->ops->on_displays_changed(
         proto->ctx, added_display_list, added_display_count, removed_display_list,
         removed_display_count, out_display_info_list, display_info_count, out_display_info_actual);
 }
 // |timestamp| is the ZX_CLOCK_MONOTONIC timestamp at which the vsync occurred.
 // |handles| points to an array of image handles of each framebuffer being
 // displayed, in increasing z-order.
 static inline void
 display_controller_interface_on_display_vsync(const display_controller_interface_t* proto,
                                               uint64_t display_id, int64_t timestamp,
                                               const uint64_t* handle_list, size_t handle_count) {
     proto->ops->on_display_vsync(proto->ctx, display_id, timestamp, handle_list, handle_count);
 }
 static inline zx_status_t
 display_controller_interface_get_audio_format(const display_controller_interface_t* proto,
                                               uint64_t display_id, uint32_t fmt_idx,
                                               audio_stream_format_range_t* out_fmt) {
     return proto->ops->get_audio_format(proto->ctx, display_id, fmt_idx, out_fmt);
 }

 typedef struct display_controller_protocol_ops {
     void (*set_display_controller_interface)(void* ctx, const display_controller_interface_t* intf);
     zx_status_t (*import_vmo_image)(void* ctx, image_t* image, zx_handle_t vmo, size_t offset);
     void (*release_image)(void* ctx, image_t* image);
     uint32_t (*check_configuration)(void* ctx, const display_config_t** display_config_list,
                                     size_t display_config_count,
                                     uint32_t** out_layer_cfg_result_list,
                                     size_t* layer_cfg_result_count);
     void (*apply_configuration)(void* ctx, const display_config_t** display_config_list,
                                 size_t display_config_count);
     uint32_t (*compute_linear_stride)(void* ctx, uint32_t width, zx_pixel_format_t pixel_format);
     zx_status_t (*allocate_vmo)(void* ctx, uint64_t size, zx_handle_t* out_vmo);
 } display_controller_protocol_ops_t;

 // The client guarantees that check_configuration and apply_configuration are always
 // made from a single thread. The client makes no other threading guarantees.
 struct display_controller_protocol {
     display_controller_protocol_ops_t* ops;
     void* ctx;
 };

 // The function will only be called once, and it will be called before any other
 // functions are called.
 static inline void
 display_controller_set_display_controller_interface(const display_controller_protocol_t* proto,
                                                     const display_controller_interface_t* intf) {
     proto->ops->set_display_controller_interface(proto->ctx, intf);
 }
 // Imports a VMO backed image into the driver. The driver should set image->handle. The
 // driver does not own the vmo handle passed to this function.
 static inline zx_status_t
 display_controller_import_vmo_image(const display_controller_protocol_t* proto, image_t* image,
                                     zx_handle_t vmo, size_t offset) {
     return proto->ops->import_vmo_image(proto->ctx, image, vmo, offset);
 }
 // Releases any driver state associated with the given image. The client guarantees that
 // any images passed to apply_config will not be released until a vsync occurs with a
 // more recent image.
 static inline void display_controller_release_image(const display_controller_protocol_t* proto,
                                                     image_t* image) {
     proto->ops->release_image(proto->ctx, image);
 }
 // Validates the given configuration.
 // The configuration may not include all displays. Omiteed displays should be treated as
 // whichever of off or displaying a blank screen results in a more premissive validation.
 // All displays in a configuration will have at least one layer. The layers will be
 // arranged in increasing z-order, and their z_index fields will be set consecutively.
 // Whether or not the driver can accept the configuration cannot depend on the
 // particular image handles, as it must always be possible to present a new image in
 // place of another image with a matching configuration. It also cannot depend on the
 // cursor position, as that can be updated without another call to check_configuration.
 // display_cfg_result should be set to a CONFIG_DISPLAY_* error if the combination of
 // display modes is not supported.
 // layer_cfg_result points to an array of arrays. The primary length is display_count, the
 // secondary lengths are the corresponding display_cfg's layer_count. If display_cfg_result
 // is CONFIG_DISPLAY_OK, any errors in layer configuration should be returned as a CLIENT*
 // flag in the corresponding layer_cfg_result entry.
 // The driver must not retain references to the configuration after this function returns.
 // TODO: Fix me...
 static inline uint32_t display_controller_check_configuration(
     const display_controller_protocol_t* proto, const display_config_t** display_config_list,
     size_t display_config_count, uint32_t** out_layer_cfg_result_list,
     size_t* layer_cfg_result_count) {
     return proto->ops->check_configuration(proto->ctx, display_config_list, display_config_count,
                                            out_layer_cfg_result_list, layer_cfg_result_count);
 }
 // Applies the configuration.
 // All configurations passed to this function will be derived from configurations which
 // have been succesfully validated, with the only differences either being omitted layers
 // or different image handles. To account for any layers which are not present, the driver
 // must use the z_index values of the present layers to configure them as if the whole
 // configuration was present.
 // Unlike with check_configuration, displays included in the configuration are not
 // guaranteed to include any layers. Both omitted displays and displays with no layers
 // can either be turned off or set to display a blank screen, but for displays with no
 // layers there is a strong preference to display a blank screen instead of turn them off.
 // In either case, the driver must drop all references to old images and invoke the vsync
 // callback after doing so.
 // The driver must not retain references to the configuration after this function returns.
 static inline void
 display_controller_apply_configuration(const display_controller_protocol_t* proto,
                                        const display_config_t** display_config_list,
                                        size_t display_config_count) {
     proto->ops->apply_configuration(proto->ctx, display_config_list, display_config_count);
 }
 // Computes the stride (in pixels) necessary for a linear image with the given width
 // and pixel format. Returns 0 on error.
 static inline uint32_t
 display_controller_compute_linear_stride(const display_controller_protocol_t* proto, uint32_t width,
                                          zx_pixel_format_t pixel_format) {
     return proto->ops->compute_linear_stride(proto->ctx, width, pixel_format);
 }
 // Allocates a VMO of the requested size which can be used for images.
 static inline zx_status_t
 display_controller_allocate_vmo(const display_controller_protocol_t* proto, uint64_t size,
                                 zx_handle_t* out_vmo) {
     return proto->ops->allocate_vmo(proto->ctx, size, out_vmo);
 }

 __END_CDECLS;
	// Copyright 2018 The Fuchsia Authors. All rights reserved.
	// Use of this source code is governed by a BSD-style license that can be
	// found in the LICENSE file.

	// WARNING: This file is machine generated by fidlc.

	#pragma once

	#include <zircon/compiler.h>
	#include <zircon/device/audio.h>
	#include <zircon/types.h>

	__BEGIN_CDECLS;

	// Forward declarations

	typedef struct image_plane image_plane_t;
	typedef uint32_t client_t;
	// The client should convert the corresponding layer to a primary layer.
	#define CLIENT_USE_PRIMARY UINT32_C(1)
	// The client should compose all layers with MERGE_BASE and MERGE_SRC into a new,
	// single primary layer at the MERGE_BASE layer's z-order. The driver must accept
	// a fullscreen layer with the default pixel format, but may accept other layer
	// parameters.
	// MERGE_BASE should only be set on one layer per display. If it is set on multiple
	// layers, the client will arbitrarily pick one and change the rest to MERGE_SRC.
	#define CLIENT_MERGE_BASE UINT32_C(2)
	#define CLIENT_MERGE_SRC UINT32_C(4)
	// The client should pre-scale the image so that src_frame's dimensions are equal
	// to dest_frame's dimensions.
	#define CLIENT_FRAME_SCALE UINT32_C(8)
	// The client should pre-clip the image so that src_frame's dimensions are equal to
	// the image's dimensions.
	#define CLIENT_SRC_FRAME UINT32_C(16)
	// The client should pre-apply the transformation so TRANSFORM_IDENTITY can be used.
	#define CLIENT_TRANSFORM UINT32_C(32)
	// The client should apply the color conversion.
	#define CLIENT_COLOR_CONVERSION UINT32_C(64)
	// The client should apply the alpha transformation itself.
	#define CLIENT_ALPHA UINT32_C(128)

	typedef uint32_t config_display_t;
	// The display mode configuration is valid. Note that this is distinct from
	// whether or not the layer configuration is valid.
	#define CONFIG_DISPLAY_OK UINT32_C(0)
	// Error indicating that the hardware cannot simultaniously support the
	// requested number of displays.
	#define CONFIG_DISPLAY_TOO_MANY UINT32_C(1)
	// Error indicating that the hardware cannot simultaniously support the given
	// set of display modes. To support a mode, the display must be able to display
	// a single layer with width and height equal to the requested mode and the
	// preferred pixel format.
	#define CONFIG_DISPLAY_UNSUPPORTED_MODES UINT32_C(2)

	typedef uint32_t color_conversion_t;
	// If set, use the 0 vector for the color conversion preoffset
	#define COLOR_CONVERSION_PREOFFSET UINT32_C(1)
	// If set, use the identity matrix for the color conversion coefficients
	#define COLOR_CONVERSION_COEFFICIENTS UINT32_C(2)
	// If set, use the 0 vector for the color conversion postoffset
	#define COLOR_CONVERSION_POSTOFFSET UINT32_C(4)

	// constants for display_config's mode_flags field
	typedef uint32_t mode_flag_t;
	#define MODE_FLAG_VSYNC_POSITIVE UINT32_C(1)
	#define MODE_FLAG_HSYNC_POSITIVE UINT32_C(2)
	#define MODE_FLAG_INTERLACED UINT32_C(4)
	#define MODE_FLAG_ALTERNATING_VBLANK UINT32_C(8)
	#define MODE_FLAG_DOUBLE_CLOCKED UINT32_C(16)

	typedef struct display_mode display_mode_t;
	typedef struct display_config display_config_t;
	// Types of layers.
	typedef uint32_t layer_type_t;
	#define LAYER_TYPE_PRIMARY UINT32_C(0)
	#define LAYER_TYPE_CURSOR UINT32_C(1)
	#define LAYER_TYPE_COLOR UINT32_C(2)

	// Rotations are applied counter-clockwise, and are applied before reflections.
	typedef uint32_t frame_transform_t;
	#define FRAME_TRANSFORM_IDENTITY UINT32_C(0)
	#define FRAME_TRANSFORM_REFLECT_X UINT32_C(1)
	#define FRAME_TRANSFORM_REFLECT_Y UINT32_C(2)
	#define FRAME_TRANSFORM_ROT_90 UINT32_C(3)
	#define FRAME_TRANSFORM_ROT_180 UINT32_C(4)
	#define FRAME_TRANSFORM_ROT_270 UINT32_C(5)
	#define FRAME_TRANSFORM_ROT_90_REFLECT_X UINT32_C(6)
	#define FRAME_TRANSFORM_ROT_90_REFLECT_Y UINT32_C(7)

	typedef struct frame frame_t;
	typedef struct added_display_info added_display_info_t;
	typedef uint32_t zx_pixel_format_t;

	typedef struct cursor_info cursor_info_t;
	typedef struct color_layer color_layer_t;
	typedef struct image image_t;
	typedef struct cursor_layer cursor_layer_t;
	typedef uint8_t alpha_t;
	#define ALPHA_DISABLE UINT8_C(0)
	#define ALPHA_PREMULTIPLIED UINT8_C(1)
	#define ALPHA_HW_MULTIPLY UINT8_C(2)

	typedef struct primary_layer primary_layer_t;
	typedef union layer_config layer_config_t;
	typedef struct layer layer_t;
	typedef struct display_params display_params_t;
	typedef union panel panel_t;
	typedef struct added_display_args added_display_args_t;
	typedef struct display_controller_interface display_controller_interface_t;
	typedef struct display_controller_protocol display_controller_protocol_t;

	// Declarations

	// The image is linear and VMO backed.
	#define IMAGE_TYPE_SIMPLE UINT32_C(0)

	// A structure containing information about each plane of an image.
	struct image_plane {
	uint32_t byte_offset;
	uint32_t bytes_per_row;
	};

	// The video parameters which specify the display mode.
	struct display_mode {
	uint32_t pixel_clock_10khz;
	uint32_t h_addressable;
	uint32_t h_front_porch;
	uint32_t h_sync_pulse;
	uint32_t h_blanking;
	uint32_t v_addressable;
	uint32_t v_front_porch;
	uint32_t v_sync_pulse;
	uint32_t v_blanking;
	// A bitmask of MODE_FLAG_* values
	uint32_t flags;
	};

	struct display_config {
	// the display id to which the configuration applies
	uint64_t display_id;
	display_mode_t mode;
	// Bitmask of COLOR_CONVERSION_* flags
	uint32_t cc_flags;
	// Color conversion is applied to each pixel according to the formula:
	// (cc_coefficients * (pixel + cc_preoffsets)) + cc_postoffsets
	// where pixel is a column vector consiting of the pixel's 3 components.
	float cc_preoffsets[3];
	float cc_coefficients[3][3];
	float cc_postoffsets[3];
	layer_t** layer_list;
	size_t layer_count;
	};

	struct frame {
	// (\|x_pos\|, \|y_pos\|) specifies the position of the upper-left corner
	// of the frame.
	uint32_t x_pos;
	uint32_t y_pos;
	uint32_t width;
	uint32_t height;
	};

	// Out parameters will be populated before on_displays_changed returns.
	struct added_display_info {
	bool is_hdmi_out;
	bool is_standard_srgb_out;
	uint32_t audio_format_count;
	const char* manufacturer_name;
	// null-terminated
	char monitor_name[14];
	// null-terminated
	char monitor_serial[14];
	};

	// Info about valid cursor configuratoins.
	struct cursor_info {
	// The width and height of the cursor configuration, in pixels.
	uint32_t width;
	uint32_t height;
	zx_pixel_format_t format;
	};

	struct color_layer {
	zx_pixel_format_t format;
	// The color to use for the layer. The color is little-endian, and is
	// guaranteed to be of the appropriate size.
	uint8_t* color_list;
	size_t color_count;
	};

	// A structure containing information about an image.
	struct image {
	// The width and height of the image in pixels.
	uint32_t width;
	uint32_t height;
	// The pixel format of the image.
	zx_pixel_format_t pixel_format;
	// The type conveys information about what is providing the pixel data. If this is not
	// IMAGE_FORMAT_SIMPLE, it is up to the driver and buffer producer to agree on the meaning
	// of the value through some mechanism outside the scope of this API.
	uint32_t type;
	image_plane_t planes[4];
	// A driver-defined handle to the image. Each handle must be unique.
	uint64_t handle;
	};

	struct cursor_layer {
	image_t image;
	// The position of the top-left corner of the cursor's image. When being
	// applied to a display, the cursor is guaranteed to have at least one
	// pixel of overlap with the display.
	zx_status_t x_pos;
	zx_status_t y_pos;
	};

	#define INVALID_DISPLAY_ID UINT32_C(0)

	struct primary_layer {
	image_t image;
	// An ALPHA_* constant.
	// If \|alpha_mode\| == `ALPHA_DISABLED`, the layer is opaque and alpha_layer_val is ignored.
	// If \|alpha_mode\| == `PREMULTIPLIED` or `HW_MULTIPLY` and \|alpha_layer_val\| is NaN, the alpha
	// used when blending is determined by the per-pixel alpha channel.
	// If \|alpha_mode\| == `PREMULTIPLIED` or `HW_MULTIPLY` and \|alpha_layer_val\| is not NaN, the
	// alpha used when blending is the product of alpha_layer_val and any per-pixel alpha.
	// Additionally, if alpha_mode == PREMULTIPLIED, then the hardware must premultiply the color
	// channel with alpha_layer_val before blending.
	// If alpha_layer_val is not NaN, it will be in the range [0, 1].
	alpha_t alpha_mode;
	float alpha_layer_val;
	frame_transform_t transform_mode;
	// The source frame, where (0,0) is the top-left corner of the image. The
	// client guarantees that src_frame lies entirely within the image.
	frame_t src_frame;
	// The destination frame, where (0,0) is the top-left corner of the
	// composed output. The client guarantees that dest_frame lies entirely
	// within the composed output.
	frame_t dest_frame;
	};

	union layer_config {
	primary_layer_t primary;
	cursor_layer_t cursor;
	color_layer_t color;
	};

	struct layer {
	layer_type_t type;
	// z_index of the layer. See \|check_configuration\| and \|apply_configuration\|.
	uint32_t z_index;
	layer_config_t cfg;
	};

	// A fallback structure to convey display information without an edid.
	struct display_params {
	uint32_t width;
	uint32_t height;
	uint32_t refresh_rate_e2;
	};

	union panel {
	// The bus_id to use to read this display's edid from the device's i2c protocol.
	uint32_t i2c_bus_id;
	// The display's parameters if an edid is not present.
	display_params_t params;
	};

	// A structure containing information a connected display.
	struct added_display_args {
	uint64_t display_id;
	// A flag indicating whether or not the display has a valid edid.
	// If true, the device should expose an ZX_PROTOCOL_I2C_IMPL device through get_protocol, in
	// addition to the ZX_PROTOCOL_DISPLAY_CONTROLLER_IMPL protocol. Note that the i2c device
	// will be called from the on_displays_changed callback, so care should be taken to avoid
	// deadlocks or double-locking.
	// If no edid is present, then the meaning of display_config's mode structure is
	// undefined, and drivers should ignore it in check_configuration and apply_configuration.
	bool edid_present;
	panel_t panel;
	// A list of pixel formats supported by the display. The first entry is the
	// preferred pixel format.
	zx_pixel_format_t* pixel_format_list;
	size_t pixel_format_count;
	// A list of cursor configurations most likely to be accepted by the driver. Can
	// be null if cursor_count is 0.
	// The driver may reject some of these configurations in some circumstances, and
	// it may accept other configurations, but at least one of these configurations
	// should be valid at most times.
	cursor_info_t* cursor_info_list;
	size_t cursor_info_count;
	};

	typedef struct display_controller_interface_ops {
	void (on_displays_changed)(void ctx, const added_display_args_t* added_display_list,
	size_t added_display_count, const uint64_t* removed_display_list,
	size_t removed_display_count,
	added_display_info_t* out_display_info_list,
	size_t display_info_count, size_t* out_display_info_actual);
	void (on_display_vsync)(void ctx, uint64_t display_id, int64_t timestamp,
	const uint64_t* handle_list, size_t handle_count);
	zx_status_t (get_audio_format)(void ctx, uint64_t display_id, uint32_t fmt_idx,
	audio_stream_format_range_t* out_fmt);
	} display_controller_interface_ops_t;

	// The client will not make any `ZX_PROTOCOL_DISPLAY_CONTROLLER_IMPL` calls into the device
	// during these callbacks.
	struct display_controller_interface {
	display_controller_interface_ops_t* ops;
	void* ctx;
	};

	// Callbacks which are invoked when displays are added or removed. \|added_display_list\| and
	// \|removed_display_list\| point to arrays of the display ids which were added and removed. If
	// \|added_display_count\| or \|removed_display_count\| is 0, the corresponding array can be NULL.
	// The driver must be done accessing any images which were on the removed displays.
	// The driver should call this function when the callback is registered if any displays
	// are present.
	static inline void display_controller_interface_on_displays_changed(
	const display_controller_interface_t* proto, const added_display_args_t* added_display_list,
	size_t added_display_count, const uint64_t* removed_display_list, size_t removed_display_count,
	added_display_info_t* out_display_info_list, size_t display_info_count,
	size_t* out_display_info_actual) {
	proto->ops->on_displays_changed(
	proto->ctx, added_display_list, added_display_count, removed_display_list,
	removed_display_count, out_display_info_list, display_info_count, out_display_info_actual);
	}
	// \|timestamp\| is the ZX_CLOCK_MONOTONIC timestamp at which the vsync occurred.
	// \|handles\| points to an array of image handles of each framebuffer being
	// displayed, in increasing z-order.
	static inline void
	display_controller_interface_on_display_vsync(const display_controller_interface_t* proto,
	uint64_t display_id, int64_t timestamp,
	const uint64_t* handle_list, size_t handle_count) {
	proto->ops->on_display_vsync(proto->ctx, display_id, timestamp, handle_list, handle_count);
	}
	static inline zx_status_t
	display_controller_interface_get_audio_format(const display_controller_interface_t* proto,
	uint64_t display_id, uint32_t fmt_idx,
	audio_stream_format_range_t* out_fmt) {
	return proto->ops->get_audio_format(proto->ctx, display_id, fmt_idx, out_fmt);
	}

	typedef struct display_controller_protocol_ops {
	void (set_display_controller_interface)(void ctx, const display_controller_interface_t* intf);
	zx_status_t (import_vmo_image)(void ctx, image_t* image, zx_handle_t vmo, size_t offset);
	void (release_image)(void ctx, image_t* image);
	uint32_t (check_configuration)(void ctx, const display_config_t** display_config_list,
	size_t display_config_count,
	uint32_t** out_layer_cfg_result_list,
	size_t* layer_cfg_result_count);
	void (apply_configuration)(void ctx, const display_config_t** display_config_list,
	size_t display_config_count);
	uint32_t (compute_linear_stride)(void ctx, uint32_t width, zx_pixel_format_t pixel_format);
	zx_status_t (allocate_vmo)(void ctx, uint64_t size, zx_handle_t* out_vmo);
	} display_controller_protocol_ops_t;

	// The client guarantees that check_configuration and apply_configuration are always
	// made from a single thread. The client makes no other threading guarantees.
	struct display_controller_protocol {
	display_controller_protocol_ops_t* ops;
	void* ctx;
	};

	// The function will only be called once, and it will be called before any other
	// functions are called.
	static inline void
	display_controller_set_display_controller_interface(const display_controller_protocol_t* proto,
	const display_controller_interface_t* intf) {
	proto->ops->set_display_controller_interface(proto->ctx, intf);
	}
	// Imports a VMO backed image into the driver. The driver should set image->handle. The
	// driver does not own the vmo handle passed to this function.
	static inline zx_status_t
	display_controller_import_vmo_image(const display_controller_protocol_t* proto, image_t* image,
	zx_handle_t vmo, size_t offset) {
	return proto->ops->import_vmo_image(proto->ctx, image, vmo, offset);
	}
	// Releases any driver state associated with the given image. The client guarantees that
	// any images passed to apply_config will not be released until a vsync occurs with a
	// more recent image.
	static inline void display_controller_release_image(const display_controller_protocol_t* proto,
	image_t* image) {
	proto->ops->release_image(proto->ctx, image);
	}
	// Validates the given configuration.
	// The configuration may not include all displays. Omiteed displays should be treated as
	// whichever of off or displaying a blank screen results in a more premissive validation.
	// All displays in a configuration will have at least one layer. The layers will be
	// arranged in increasing z-order, and their z_index fields will be set consecutively.
	// Whether or not the driver can accept the configuration cannot depend on the
	// particular image handles, as it must always be possible to present a new image in
	// place of another image with a matching configuration. It also cannot depend on the
	// cursor position, as that can be updated without another call to check_configuration.
	// display_cfg_result should be set to a CONFIG_DISPLAY_* error if the combination of
	// display modes is not supported.
	// layer_cfg_result points to an array of arrays. The primary length is display_count, the
	// secondary lengths are the corresponding display_cfg's layer_count. If display_cfg_result
	// is CONFIG_DISPLAY_OK, any errors in layer configuration should be returned as a CLIENT*
	// flag in the corresponding layer_cfg_result entry.
	// The driver must not retain references to the configuration after this function returns.
	// TODO: Fix me...
	static inline uint32_t display_controller_check_configuration(
	const display_controller_protocol_t* proto, const display_config_t** display_config_list,
	size_t display_config_count, uint32_t** out_layer_cfg_result_list,
	size_t* layer_cfg_result_count) {
	return proto->ops->check_configuration(proto->ctx, display_config_list, display_config_count,
	out_layer_cfg_result_list, layer_cfg_result_count);
	}
	// Applies the configuration.
	// All configurations passed to this function will be derived from configurations which
	// have been succesfully validated, with the only differences either being omitted layers
	// or different image handles. To account for any layers which are not present, the driver
	// must use the z_index values of the present layers to configure them as if the whole
	// configuration was present.
	// Unlike with check_configuration, displays included in the configuration are not
	// guaranteed to include any layers. Both omitted displays and displays with no layers
	// can either be turned off or set to display a blank screen, but for displays with no
	// layers there is a strong preference to display a blank screen instead of turn them off.
	// In either case, the driver must drop all references to old images and invoke the vsync
	// callback after doing so.
	// The driver must not retain references to the configuration after this function returns.
	static inline void
	display_controller_apply_configuration(const display_controller_protocol_t* proto,
	const display_config_t** display_config_list,
	size_t display_config_count) {
	proto->ops->apply_configuration(proto->ctx, display_config_list, display_config_count);
	}
	// Computes the stride (in pixels) necessary for a linear image with the given width
	// and pixel format. Returns 0 on error.
	static inline uint32_t
	display_controller_compute_linear_stride(const display_controller_protocol_t* proto, uint32_t width,
	zx_pixel_format_t pixel_format) {
	return proto->ops->compute_linear_stride(proto->ctx, width, pixel_format);
	}
	// Allocates a VMO of the requested size which can be used for images.
	static inline zx_status_t
	display_controller_allocate_vmo(const display_controller_protocol_t* proto, uint64_t size,
	zx_handle_t* out_vmo) {
	return proto->ops->allocate_vmo(proto->ctx, size, out_vmo);
	}

	__END_CDECLS;