sdk/fidl/fuchsia.hardware.display/coordinator.fidl - fuchsia - 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.
 library fuchsia.hardware.display;

 using fuchsia.hardware.display.types;
 using fuchsia.images2;
 using fuchsia.sysmem;
 using zx;

 /// Maximum number of fences supported by
 /// [`fuchsia.hardware.display/Coordinator.ApplyConfig2`].
 const APPLY_CONFIG_MAX_SIGNAL_FENCES uint64 = 32;

 /// Interface for accessing the display hardware.
 ///
 /// A display configuration can be separated into two parts: the layer layout and
 /// the layer contents. The layout includes all parts of a configuration other
 /// than the image handles. The active configuration is composed of the most
 /// recently applied layout and an active image from each layer - see
 /// SetLayerImage for details on how the active image is defined. Note the
 /// requirement that each layer has an active image. Whenever a new active
 /// configuration is available, it is immediately given to the hardware. This
 /// allows the layout and each layer's contents to advance independently when
 /// possible.
 ///
 /// Performing illegal actions on the interface will result in the interface
 /// being closed.
 closed protocol Coordinator {
     // Event fired when displays are added or removed. This event will be fired
     // when the callback is registered if there are any connected displays.
     //
     // A display change always invalidates the current configuration. When a
     // client receives this event, they must either apply a new configuration
     // or revalidate and reapply their current configuration.
     strict -> OnDisplaysChanged(struct {
         added vector<Info>:MAX;
         removed vector<fuchsia.hardware.display.types.DisplayId>:MAX;
     });

     /// Imports a Buffer-Collection backed image.
     ///
     /// `image_metadata` must be compatible with the arguments passed to
     /// [`fuchsia.hardware.display/Coordinator.SetBufferCollectionConstraints`]
     /// on the `buffer_collection_id`.
     ///
     /// Returns `ZX_ERR_NOT_SUPPORTED` if the display hardware doesn't support
     /// `image_config`.
     /// Returns `ZX_ERR_ALREADY_EXISTS` if `image_id` was used in a successful
     /// `ImportImage()` without a corresponding `ReleaseImage()`.
     strict ImportImage(struct {
         image_metadata fuchsia.hardware.display.types.ImageMetadata;
         buffer_id BufferId;
         image_id ImageId;
     }) -> () error zx.Status;


     /// Releases an imported image.
     ///
     /// `image_id` must be already imported by
     /// [`fuchsia.hardware.display/Coordinator.ImportImage`].
     ///
     /// The image must not be the capture target of an ongoing capture specified
     /// in [`fuchsia.hardware.display/Coordinator.StartCapture`].
     ///
     /// When an image is released, it is immediately removed from any pending
     /// or active configurations, and any fences associated with the image are
     /// dropped. The resources associated with the image will be released as
     /// soon as the image is no longer in use.
     //
     // TODO(https://fxbug.dev/42080380): The precondition on capture image
     // exists because capture images have different constraints on image reuse
     // compared with non-capture images. We should have a unified design on
     // image reuse for both capture and non-capture images.
     strict ReleaseImage(struct {
         image_id ImageId;
     });

     /// Imports an event into the driver and associates it with the given id.
     ///
     /// It is illegal for id to be equal to INVALID_DISP_ID, and it is undefined to
     /// import one event with two different ids or to import two different events
     /// with the same id (note that ids map well to koids).
     ///
     /// If a client is reusing events, they must clear the signal
     /// before referencing the id again.
     strict ImportEvent(resource struct {
         event zx.Handle:EVENT;
         id EventId;
     });

     /// Releases the event imported with the given id.
     ///
     /// If any images are currently using the given event, the event
     /// will still be waited up or signaled as appropriate before its
     /// resources are released. It is an error to reuse an ID while the
     /// active config has references to it.
     strict ReleaseEvent(struct {
         id EventId;
     });

     // Creates a new layer.
     //
     // Layers are not associated with a particular display, but they can only be
     // shown on at most one display at any given time.  A layer is considered in
     // use from the time it is passed to SetDisplayLayers until a subsequent
     // configuration is applied which does not include the layer or until its
     // display is removed.
     strict CreateLayer() -> (struct {
         layer_id LayerId;
     }) error zx.Status;

     // Destroys the given layer.
     //
     // It is illegal to destroy a layer which does not exist or which is in use.
     strict DestroyLayer(struct {
         layer_id LayerId;
     });

     // Sets the display mode for the given display.
     //
     // It is illegal to pass a display mode which was not part of the display's Info.
     strict SetDisplayMode(struct {
         display_id fuchsia.hardware.display.types.DisplayId;
         mode Mode;
     });

     // Set the color conversion applied to the display. The conversion is applied to
     // to each pixel according to the formula:
     //
     // (coefficients * (pixel + preoffsets)) + postoffsets
     //
     // where pixel is a column vector consisting of the pixel's 3 components.
     //
     // `coefficients` is passed in row-major order. If the first entry of an array is NaN, the
     // array is treated as the identity element for the relevant operation.
     // Hardware that support color correction generally accept a limited range of coefficient
     // values. Coefficients in the range of [-2, 2] inclusive will be accepted by most
     // hardware. The hardware driver will clamp values that are outside its acceptable range.
     //
     // `preoffsets`, `postoffsets`: Clients are encourged to produce color correction values that
     // do not depend on pre and post offsets since some hardware do not have support for that.
     // For cases where pre and post offset values need to be used, the range should be limited to
     // (-1, 1) exclusive as confirmed by CheckConfig API. Values outside this range will be
     // rejected.
     //
     // Clients are encouraged to use the CheckConfig API to confirm support for correction and to
     // validate their color correction input values.
     //
     // This a stateful call. Once color conversion values have been succesfully applied via a call
     // to ApplyConfig() they will remain in place until changed and another ApplyConfig() call is
     // successful. If SetDisplayColorConversion() is called and then the config is discarded, then
     // the last successfully applied state is restored.
     strict SetDisplayColorConversion(struct {
         display_id fuchsia.hardware.display.types.DisplayId;
         preoffsets array<float32, 3>;
         coefficients array<float32, 9>;
         postoffsets array<float32, 3>;
     });

     // Sets which layers are on a display. The list is in increasing z-order.
     //
     // It is illegal to use a layer on multiple displays concurrently. If a layer
     // needs to be moved between displays, it must be removed from the first display's
     // pending config before being added to the second display's pending config. It
     // is also illegal to pass an invalid layer id.
     strict SetDisplayLayers(struct {
         display_id fuchsia.hardware.display.types.DisplayId;
         layer_ids vector<LayerId>:MAX;
     });

     // Configures the layer as a primary layer with no image and the default
     // config (no src_frame cropping, the identity transform, positioned in the
     // top-left corner of the composed output, and no scaling).
     //
     // See the documentation on SetLayerImage for details on how this method
     // affects the layer's contents.
     //
     // It is illegal to pass an invalid layer id.
     strict SetLayerPrimaryConfig(struct {
         layer_id LayerId;
         image_metadata fuchsia.hardware.display.types.ImageMetadata;
     });

     // Sets the layer transform, scaling, and positioning.
     //
     // `src_frame` must be non-empty and must fit entirely within the source
     // image. `dest_frame` must be non-empty and must fit entirely within the
     // composed output. CheckConfig will return INVALID_CONFIG if any of these
     // conditions is violated.
     //
     // Calling this on a non-primary layer or passing an invalid transform
     // is illegal.
     strict SetLayerPrimaryPosition(struct {
         layer_id LayerId;
         transform fuchsia.hardware.display.types.Transform;
         src_frame fuchsia.hardware.display.types.Frame;
         dest_frame fuchsia.hardware.display.types.Frame;
     });

     // Sets the alpha mode of the plane.
     //
     // If `mode` == DISABLED, the layer is opaque and `val` is ignored.
     //
     // If `mode` == PREMULTIPLIED or HW_MULTIPLY and `val` is NaN, the alpha
     // used when blending is determined by the per-pixel alpha channel.
     //
     // If `mode` == PREMULTIPLIED or HW_MULTIPLY and `val` is not NaN, the
     // alpha used when blending is the product of `val` and any per-pixel
     // alpha. Additionally, if `mode` == PREMULTIPLIED, then the hardware
     // premultiplies the color channel with `val` before blending.
     //
     // It is illegal to call this on a non-primary layer, to pass an
     // invalid mode, or to pass a value of `val` which is not NaN or
     // in the range [0, 1].
     strict SetLayerPrimaryAlpha(struct {
         layer_id LayerId;
         mode fuchsia.hardware.display.types.AlphaMode;
         val float32;
     });

     // Configures the layer as a color layer with the given color in
     // `pixel_format`.
     //
     // `color_bytes` vector is little-endian and of the exact size of one pixel
     // in `pixel_format`.
     //
     // It is illegal to call this on an invalid layer or for the length of
     // color_bytes to mismatch the size of the supplied format.
     strict SetLayerColorConfig(struct {
         layer_id LayerId;
         pixel_format fuchsia.images2.PixelFormat;
         color_bytes vector<uint8>:MAX;
     });

     // Sets the image for the layer.
     //
     // If wait_event_id corresponds to an imported event, the driver will
     // wait for ZX_EVENT_SIGNALED on the object before presenting the image.
     //
     // If signal_event_id is valid, then the driver will signal the event with
     // ZX_EVENT_SIGNALED when the image is no longer being presented.
     //
     // A layer's active image is the most recently applied image which either has
     // no wait event or whose wait event has been signaled. Whenever a new image
     // becomes active, any older images which never became active are dropped, and
     // their signal events will be fired as soon as their wait events are
     // signaled. The driver also does not have any concept like 'target vsync',
     // meaning that if multiple images become active within one vsync period, then
     // only the last image will actually be displayed.
     //
     // By default, the driver retains an active image until a new image becomes
     // active. However, setting a layer's ImageConfig with SetLayerPrimaryConfig
     // resets the layer's active and pending images, even if the new ImageConfig
     // matches the old ImageConfig.
     //
     // An image cannot be used for multiple layers simultaneously, nor can an
     // image be given back to the display coordinator while it is still in use.
     // An image is considered in use when it is part of a pending configuration
     // or from when its configuration is applied until its signal_event_id is
     // signaled.
     //
     // It is illegal to call this with an invalid layer or image id, to
     // call it on a color layer, or to call it with an image and layer whose
     // ImageConfigs do not match. It is illegal to apply a configuration
     // with an image layer that has no image (note that is is not illegal to
     // validate such a configuration). It is illegal to reuse a wait event which
     // another layer that has not been presented is waiting on.
     strict SetLayerImage(struct {
         layer_id LayerId;
         image_id ImageId;
         wait_event_id EventId;
         signal_event_id EventId;
     });

     // Attempts to validate the current configuration.
     //
     // When CheckConfig is called, the driver will validate the pending
     // configuration. If res is UNSUPPORTED_CONFIG, then ops will be
     // non-empty.
     //
     // Most SetX operations require revalidating the configuration. The
     // following operations do not require revalidation.
     // * SetLayerImage()
     //
     // If discard is true, the pending changes will be discarded after validation.
     strict CheckConfig(struct {
         discard bool;
     }) -> (struct {
         res fuchsia.hardware.display.types.ConfigResult;
         ops vector<ClientCompositionOp>:MAX;
     });

     // Applies any pending changes to the current configuration. This will
     // not apply pending changes to layers which are not on any display.
     //
     // If the pending configuration cannot be applied, this call will silently
     // fail, so the client should ensure its configuration is valid with
     // CheckConfig.
     strict ApplyConfig();

     // TODO(https://fxbug.dev/42152065): This is a temporary solution to support old
     // ApplyConfig() with new OnVsync() events. Remove this once the migration
     // is done.
     //
     /// Gets the stamp provided with the latest configuration the client
     /// submitted (by calling ApplyConfig()) and the display core driver
     /// accepted; the display configuration may not have been rendered yet
     /// because of pending image availability or pending layer changes.
     /// If no configuration was applied before, returns `INVALID_CONFIG_STAMP_VALUE`.
     strict GetLatestAppliedConfigStamp() -> (struct {
         stamp fuchsia.hardware.display.types.ConfigStamp;
     });

     /// Applies any pending changes to the current configuration. This will
     /// not apply pending changes to layers which are not on any display.
     ///
     /// For each event in `signal_fences`, once the pending configuration is
     /// applied to and contents are displayed on all the displays connected to
     /// the Coordinator, it will be signaled immediately.
     ///
     /// Arguments
     ///
     ///   `signal_fences`:
     ///     Stores all fence events that will be signaled once the configuration
     ///     is applied.
     ///
     /// Error handling
     ///
     ///     If the input is invalid, for example:
     ///         - `signal_fences` contains invalid events
     ///     or the pending configuration cannot be applied, this call will
     ///     silently fail, so the client should ensure its configuration is
     ///     valid with CheckConfig().
     //
     // TODO(https://fxbug.dev/42072277): The current ApplyConfig2() API could cause delay
     // when there are multiple displays with different refresh rates and vsync
     // phases. In order to better support multiple displays, we should support
     // fences to be signaled when configuration is applied to a subset of
     // displays.
     //
     // TODO(https://fxbug.dev/42072361): `signal_fences` should be renamed. The field
     // should be named to better indicate the timing and semantics when it is
     // signaled by the display driver.
     strict ApplyConfig2(resource struct {
         signal_fences vector<zx.Handle:EVENT>:APPLY_CONFIG_MAX_SIGNAL_FENCES;
     });

     // Sets whether or not vsync events will be given to this client. Defaults
     // to false.
     strict EnableVsync(struct {
         enable bool;
     });

     // This API is used by the client to acknowledge receipt of vsync messages.
     // The cookie sent should match the cookie received via vsync message (OnVsync).
     // A cookie can only be acknowledged once. Using invalid cookies, or previously
     // acknowledged cookies will not be accepted by the driver.
     strict AcknowledgeVsync(struct {
         cookie uint64;
     });

     /// Event sent for every vsync.
     ///
     /// Arguments
     ///
     /// - `display_id` identifies the display on which the vsync occurred.
     ///
     /// - `timestamp` indicates the time the vsync occurred.
     ///
     /// - `applied_config_stamp` is the stamp of the latest configuration that
     ///   is *fully* applied to the display. For example, if a configuration
     ///   contains images that are still waiting to be ready, the configuration
     ///   will be only partially applied (without the pending image), and thus
     ///   the stamp of this configuration will not appear in Vsync messages
     ///   unless that image becomes ready and display coordinator reapplies
     ///   the configuration fully with the pending image.
     ///
     ///   The `value` of the stamp MUST NOT be INVALID_CONFIG_STAMP_VALUE.
     ///
     /// - `cookie` is a unique number returned by the driver.
     ///
     ///   Cookie is used to acknowledge the receipt of vsync events using
     ///   `AcknowledgeVsync` API.
     ///
     ///   When cookie has a value of zero, no acknowledgement is required by the
     ///   client. A non-zero valued cookie requires immediate acknowledgement by
     ///   client. Failure to acknowledge vsync events will result in driver
     ///   suspending vsync event notification. All vsync messages containing a
     ///   non-zero cookie require acknowledgement regardless of whether client
     ///   has applied a (new) configuration or not (via ApplyConfig).
     ///
     ///   If a client fails to acknowledge vsync messages, the driver will store
     ///   incoming hardware-generated vsyncs in a circular buffer and send them
     ///   to the client once it resumes acknowledgement. Due to limited size of
     ///   buffer, only the most recently received vsyncs will be stored and
     ///   older ones will be dropped.
     strict -> OnVsync(resource struct {
         display_id fuchsia.hardware.display.types.DisplayId;
         timestamp uint64;
         applied_config_stamp fuchsia.hardware.display.types.ConfigStamp;
         cookie uint64;
     });

     /// Sets the visibility behavior of the virtcon.
     ///
     /// This must only be called from the Virtcon client.
     strict SetVirtconMode(struct {
         mode VirtconMode;
     });

     // Event fired when the client gains or loses ownership of the displays.
     //
     // New clients should assume they do not have ownership of the display
     // until this event informs them otherwise.
     strict -> OnClientOwnershipChange(struct {
         has_ownership bool;
     });

     // Import a sysmem buffer collection token. `buffer_collection_id` must not
     // already be in use.
     strict ImportBufferCollection(resource struct {
         buffer_collection_id BufferCollectionId;
         buffer_collection_token client_end:fuchsia.sysmem.BufferCollectionToken;
     }) -> () error zx.Status;

     // Release an imported buffer collection.
     strict ReleaseBufferCollection(struct {
         buffer_collection_id BufferCollectionId;
     });

     // Takes an imported buffer collection and sets the constraints
     // on it so that it can be imported with a specific config.
     // TODO(https://fxbug.dev/42166207): Update this API to better support
     // optional fields.
     strict SetBufferCollectionConstraints(struct {
         buffer_collection_id BufferCollectionId;
         buffer_usage fuchsia.hardware.display.types.ImageBufferUsage;
     }) -> () error zx.Status;

     /// Returns true if Capture is supported on the platform.
     strict IsCaptureSupported() -> (struct {
         supported bool;
     }) error zx.Status;

     /// Starts capture. Client must provide a valid signal_event_id and
     /// image_id. signal_event_id must have been imported into the driver
     /// using ImportEvent FIDL API. Image_id is the id from ImportImageForCapture.
     /// The client will get notified once capture is complete via signal_event_id.
     /// Returns ZX_ERR_NOT_SUPPORTED if coordinator does not support capture
     strict StartCapture(struct {
         signal_event_id EventId;
         image_id ImageId;
     }) -> () error zx.Status;

     /// Set the minimum value of rgb channels. Valid range [0 255] inclusive. Returns
     /// ZX_ERR_NOT_SUPPORTED when the display hardware does not support this feature.
     /// This API is meant to address backlight bleeding that may occur on some hardware
     /// that have a specific type of panel and hardware assembly. The evolution of this
     /// API is highly hardware and product dependant and therefore as products evolve, this
     /// API may change or support for this API may become non-existent. Therefore, this
     /// API should be used with caution.
     ///
     /// Unlike other calls in this API, SetMiniumRgb is applied immediately, and does not
     /// wait for ApplyConfig(). It is, however, still stateful.
     strict SetMinimumRgb(struct {
         minimum_rgb uint8;
     }) -> () error zx.Status;

     /// Power off/on the display panel.
     ///
     /// This function takes effect immediately. Clients don't need to call
     /// `ApplyConfig()` to commit this command.
     ///
     /// Once a display is turned off, it will not deliver vsync events, which
     /// may include the vsync event for the most recently applied config.
     ///
     /// Staged display control commands (e.g. SetDisplayLayer) will not be
     /// affected. They are still applied to the display device when client calls
     /// `ApplyConfig()`, but the contents will be shown on display panel only
     /// after client powers on the display again.
     ///
     /// Newly added displays are turned on by default.
     ///
     /// Returns ZX_ERR_NOT_FOUND if `display_id` is invalid when Coordinator
     /// handles this method.
     /// Returns ZX_ERR_NOT_SUPPORTED if the display driver IC doesn't support
     /// turning on/off displays.
     strict SetDisplayPower(struct {
         display_id fuchsia.hardware.display.types.DisplayId;
         power_on bool;
     }) -> () error zx.Status;
 };
	// 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.
	library fuchsia.hardware.display;

	using fuchsia.hardware.display.types;
	using fuchsia.images2;
	using fuchsia.sysmem;
	using zx;

	/// Maximum number of fences supported by
	/// [`fuchsia.hardware.display/Coordinator.ApplyConfig2`].
	const APPLY_CONFIG_MAX_SIGNAL_FENCES uint64 = 32;

	/// Interface for accessing the display hardware.
	///
	/// A display configuration can be separated into two parts: the layer layout and
	/// the layer contents. The layout includes all parts of a configuration other
	/// than the image handles. The active configuration is composed of the most
	/// recently applied layout and an active image from each layer - see
	/// SetLayerImage for details on how the active image is defined. Note the
	/// requirement that each layer has an active image. Whenever a new active
	/// configuration is available, it is immediately given to the hardware. This
	/// allows the layout and each layer's contents to advance independently when
	/// possible.
	///
	/// Performing illegal actions on the interface will result in the interface
	/// being closed.
	closed protocol Coordinator {
	// Event fired when displays are added or removed. This event will be fired
	// when the callback is registered if there are any connected displays.
	//
	// A display change always invalidates the current configuration. When a
	// client receives this event, they must either apply a new configuration
	// or revalidate and reapply their current configuration.
	strict -> OnDisplaysChanged(struct {
	added vector<Info>:MAX;
	removed vector<fuchsia.hardware.display.types.DisplayId>:MAX;
	});

	/// Imports a Buffer-Collection backed image.
	///
	/// `image_metadata` must be compatible with the arguments passed to
	/// [`fuchsia.hardware.display/Coordinator.SetBufferCollectionConstraints`]
	/// on the `buffer_collection_id`.
	///
	/// Returns `ZX_ERR_NOT_SUPPORTED` if the display hardware doesn't support
	/// `image_config`.
	/// Returns `ZX_ERR_ALREADY_EXISTS` if `image_id` was used in a successful
	/// `ImportImage()` without a corresponding `ReleaseImage()`.
	strict ImportImage(struct {
	image_metadata fuchsia.hardware.display.types.ImageMetadata;
	buffer_id BufferId;
	image_id ImageId;
	}) -> () error zx.Status;


	/// Releases an imported image.
	///
	/// `image_id` must be already imported by
	/// [`fuchsia.hardware.display/Coordinator.ImportImage`].
	///
	/// The image must not be the capture target of an ongoing capture specified
	/// in [`fuchsia.hardware.display/Coordinator.StartCapture`].
	///
	/// When an image is released, it is immediately removed from any pending
	/// or active configurations, and any fences associated with the image are
	/// dropped. The resources associated with the image will be released as
	/// soon as the image is no longer in use.
	//
	// TODO(https://fxbug.dev/42080380): The precondition on capture image
	// exists because capture images have different constraints on image reuse
	// compared with non-capture images. We should have a unified design on
	// image reuse for both capture and non-capture images.
	strict ReleaseImage(struct {
	image_id ImageId;
	});

	/// Imports an event into the driver and associates it with the given id.
	///
	/// It is illegal for id to be equal to INVALID_DISP_ID, and it is undefined to
	/// import one event with two different ids or to import two different events
	/// with the same id (note that ids map well to koids).
	///
	/// If a client is reusing events, they must clear the signal
	/// before referencing the id again.
	strict ImportEvent(resource struct {
	event zx.Handle:EVENT;
	id EventId;
	});

	/// Releases the event imported with the given id.
	///
	/// If any images are currently using the given event, the event
	/// will still be waited up or signaled as appropriate before its
	/// resources are released. It is an error to reuse an ID while the
	/// active config has references to it.
	strict ReleaseEvent(struct {
	id EventId;
	});

	// Creates a new layer.
	//
	// Layers are not associated with a particular display, but they can only be
	// shown on at most one display at any given time. A layer is considered in
	// use from the time it is passed to SetDisplayLayers until a subsequent
	// configuration is applied which does not include the layer or until its
	// display is removed.
	strict CreateLayer() -> (struct {
	layer_id LayerId;
	}) error zx.Status;

	// Destroys the given layer.
	//
	// It is illegal to destroy a layer which does not exist or which is in use.
	strict DestroyLayer(struct {
	layer_id LayerId;
	});

	// Sets the display mode for the given display.
	//
	// It is illegal to pass a display mode which was not part of the display's Info.
	strict SetDisplayMode(struct {
	display_id fuchsia.hardware.display.types.DisplayId;
	mode Mode;
	});

	// Set the color conversion applied to the display. The conversion is applied to
	// to each pixel according to the formula:
	//
	// (coefficients * (pixel + preoffsets)) + postoffsets
	//
	// where pixel is a column vector consisting of the pixel's 3 components.
	//
	// `coefficients` is passed in row-major order. If the first entry of an array is NaN, the
	// array is treated as the identity element for the relevant operation.
	// Hardware that support color correction generally accept a limited range of coefficient
	// values. Coefficients in the range of [-2, 2] inclusive will be accepted by most
	// hardware. The hardware driver will clamp values that are outside its acceptable range.
	//
	// `preoffsets`, `postoffsets`: Clients are encourged to produce color correction values that
	// do not depend on pre and post offsets since some hardware do not have support for that.
	// For cases where pre and post offset values need to be used, the range should be limited to
	// (-1, 1) exclusive as confirmed by CheckConfig API. Values outside this range will be
	// rejected.
	//
	// Clients are encouraged to use the CheckConfig API to confirm support for correction and to
	// validate their color correction input values.
	//
	// This a stateful call. Once color conversion values have been succesfully applied via a call
	// to ApplyConfig() they will remain in place until changed and another ApplyConfig() call is
	// successful. If SetDisplayColorConversion() is called and then the config is discarded, then
	// the last successfully applied state is restored.
	strict SetDisplayColorConversion(struct {
	display_id fuchsia.hardware.display.types.DisplayId;
	preoffsets array<float32, 3>;
	coefficients array<float32, 9>;
	postoffsets array<float32, 3>;
	});

	// Sets which layers are on a display. The list is in increasing z-order.
	//
	// It is illegal to use a layer on multiple displays concurrently. If a layer
	// needs to be moved between displays, it must be removed from the first display's
	// pending config before being added to the second display's pending config. It
	// is also illegal to pass an invalid layer id.
	strict SetDisplayLayers(struct {
	display_id fuchsia.hardware.display.types.DisplayId;
	layer_ids vector<LayerId>:MAX;
	});

	// Configures the layer as a primary layer with no image and the default
	// config (no src_frame cropping, the identity transform, positioned in the
	// top-left corner of the composed output, and no scaling).
	//
	// See the documentation on SetLayerImage for details on how this method
	// affects the layer's contents.
	//
	// It is illegal to pass an invalid layer id.
	strict SetLayerPrimaryConfig(struct {
	layer_id LayerId;
	image_metadata fuchsia.hardware.display.types.ImageMetadata;
	});

	// Sets the layer transform, scaling, and positioning.
	//
	// `src_frame` must be non-empty and must fit entirely within the source
	// image. `dest_frame` must be non-empty and must fit entirely within the
	// composed output. CheckConfig will return INVALID_CONFIG if any of these
	// conditions is violated.
	//
	// Calling this on a non-primary layer or passing an invalid transform
	// is illegal.
	strict SetLayerPrimaryPosition(struct {
	layer_id LayerId;
	transform fuchsia.hardware.display.types.Transform;
	src_frame fuchsia.hardware.display.types.Frame;
	dest_frame fuchsia.hardware.display.types.Frame;
	});

	// Sets the alpha mode of the plane.
	//
	// If `mode` == DISABLED, the layer is opaque and `val` is ignored.
	//
	// If `mode` == PREMULTIPLIED or HW_MULTIPLY and `val` is NaN, the alpha
	// used when blending is determined by the per-pixel alpha channel.
	//
	// If `mode` == PREMULTIPLIED or HW_MULTIPLY and `val` is not NaN, the
	// alpha used when blending is the product of `val` and any per-pixel
	// alpha. Additionally, if `mode` == PREMULTIPLIED, then the hardware
	// premultiplies the color channel with `val` before blending.
	//
	// It is illegal to call this on a non-primary layer, to pass an
	// invalid mode, or to pass a value of `val` which is not NaN or
	// in the range [0, 1].
	strict SetLayerPrimaryAlpha(struct {
	layer_id LayerId;
	mode fuchsia.hardware.display.types.AlphaMode;
	val float32;
	});

	// Configures the layer as a color layer with the given color in
	// `pixel_format`.
	//
	// `color_bytes` vector is little-endian and of the exact size of one pixel
	// in `pixel_format`.
	//
	// It is illegal to call this on an invalid layer or for the length of
	// color_bytes to mismatch the size of the supplied format.
	strict SetLayerColorConfig(struct {
	layer_id LayerId;
	pixel_format fuchsia.images2.PixelFormat;
	color_bytes vector<uint8>:MAX;
	});

	// Sets the image for the layer.
	//
	// If wait_event_id corresponds to an imported event, the driver will
	// wait for ZX_EVENT_SIGNALED on the object before presenting the image.
	//
	// If signal_event_id is valid, then the driver will signal the event with
	// ZX_EVENT_SIGNALED when the image is no longer being presented.
	//
	// A layer's active image is the most recently applied image which either has
	// no wait event or whose wait event has been signaled. Whenever a new image
	// becomes active, any older images which never became active are dropped, and
	// their signal events will be fired as soon as their wait events are
	// signaled. The driver also does not have any concept like 'target vsync',
	// meaning that if multiple images become active within one vsync period, then
	// only the last image will actually be displayed.
	//
	// By default, the driver retains an active image until a new image becomes
	// active. However, setting a layer's ImageConfig with SetLayerPrimaryConfig
	// resets the layer's active and pending images, even if the new ImageConfig
	// matches the old ImageConfig.
	//
	// An image cannot be used for multiple layers simultaneously, nor can an
	// image be given back to the display coordinator while it is still in use.
	// An image is considered in use when it is part of a pending configuration
	// or from when its configuration is applied until its signal_event_id is
	// signaled.
	//
	// It is illegal to call this with an invalid layer or image id, to
	// call it on a color layer, or to call it with an image and layer whose
	// ImageConfigs do not match. It is illegal to apply a configuration
	// with an image layer that has no image (note that is is not illegal to
	// validate such a configuration). It is illegal to reuse a wait event which
	// another layer that has not been presented is waiting on.
	strict SetLayerImage(struct {
	layer_id LayerId;
	image_id ImageId;
	wait_event_id EventId;
	signal_event_id EventId;
	});

	// Attempts to validate the current configuration.
	//
	// When CheckConfig is called, the driver will validate the pending
	// configuration. If res is UNSUPPORTED_CONFIG, then ops will be
	// non-empty.
	//
	// Most SetX operations require revalidating the configuration. The
	// following operations do not require revalidation.
	// * SetLayerImage()
	//
	// If discard is true, the pending changes will be discarded after validation.
	strict CheckConfig(struct {
	discard bool;
	}) -> (struct {
	res fuchsia.hardware.display.types.ConfigResult;
	ops vector<ClientCompositionOp>:MAX;
	});

	// Applies any pending changes to the current configuration. This will
	// not apply pending changes to layers which are not on any display.
	//
	// If the pending configuration cannot be applied, this call will silently
	// fail, so the client should ensure its configuration is valid with
	// CheckConfig.
	strict ApplyConfig();

	// TODO(https://fxbug.dev/42152065): This is a temporary solution to support old
	// ApplyConfig() with new OnVsync() events. Remove this once the migration
	// is done.
	//
	/// Gets the stamp provided with the latest configuration the client
	/// submitted (by calling ApplyConfig()) and the display core driver
	/// accepted; the display configuration may not have been rendered yet
	/// because of pending image availability or pending layer changes.
	/// If no configuration was applied before, returns `INVALID_CONFIG_STAMP_VALUE`.
	strict GetLatestAppliedConfigStamp() -> (struct {
	stamp fuchsia.hardware.display.types.ConfigStamp;
	});

	/// Applies any pending changes to the current configuration. This will
	/// not apply pending changes to layers which are not on any display.
	///
	/// For each event in `signal_fences`, once the pending configuration is
	/// applied to and contents are displayed on all the displays connected to
	/// the Coordinator, it will be signaled immediately.
	///
	/// Arguments
	///
	/// `signal_fences`:
	/// Stores all fence events that will be signaled once the configuration
	/// is applied.
	///
	/// Error handling
	///
	/// If the input is invalid, for example:
	/// - `signal_fences` contains invalid events
	/// or the pending configuration cannot be applied, this call will
	/// silently fail, so the client should ensure its configuration is
	/// valid with CheckConfig().
	//
	// TODO(https://fxbug.dev/42072277): The current ApplyConfig2() API could cause delay
	// when there are multiple displays with different refresh rates and vsync
	// phases. In order to better support multiple displays, we should support
	// fences to be signaled when configuration is applied to a subset of
	// displays.
	//
	// TODO(https://fxbug.dev/42072361): `signal_fences` should be renamed. The field
	// should be named to better indicate the timing and semantics when it is
	// signaled by the display driver.
	strict ApplyConfig2(resource struct {
	signal_fences vector<zx.Handle:EVENT>:APPLY_CONFIG_MAX_SIGNAL_FENCES;
	});

	// Sets whether or not vsync events will be given to this client. Defaults
	// to false.
	strict EnableVsync(struct {
	enable bool;
	});

	// This API is used by the client to acknowledge receipt of vsync messages.
	// The cookie sent should match the cookie received via vsync message (OnVsync).
	// A cookie can only be acknowledged once. Using invalid cookies, or previously
	// acknowledged cookies will not be accepted by the driver.
	strict AcknowledgeVsync(struct {
	cookie uint64;
	});

	/// Event sent for every vsync.
	///
	/// Arguments
	///
	/// - `display_id` identifies the display on which the vsync occurred.
	///
	/// - `timestamp` indicates the time the vsync occurred.
	///
	/// - `applied_config_stamp` is the stamp of the latest configuration that
	/// is fully applied to the display. For example, if a configuration
	/// contains images that are still waiting to be ready, the configuration
	/// will be only partially applied (without the pending image), and thus
	/// the stamp of this configuration will not appear in Vsync messages
	/// unless that image becomes ready and display coordinator reapplies
	/// the configuration fully with the pending image.
	///
	/// The `value` of the stamp MUST NOT be INVALID_CONFIG_STAMP_VALUE.
	///
	/// - `cookie` is a unique number returned by the driver.
	///
	/// Cookie is used to acknowledge the receipt of vsync events using
	/// `AcknowledgeVsync` API.
	///
	/// When cookie has a value of zero, no acknowledgement is required by the
	/// client. A non-zero valued cookie requires immediate acknowledgement by
	/// client. Failure to acknowledge vsync events will result in driver
	/// suspending vsync event notification. All vsync messages containing a
	/// non-zero cookie require acknowledgement regardless of whether client
	/// has applied a (new) configuration or not (via ApplyConfig).
	///
	/// If a client fails to acknowledge vsync messages, the driver will store
	/// incoming hardware-generated vsyncs in a circular buffer and send them
	/// to the client once it resumes acknowledgement. Due to limited size of
	/// buffer, only the most recently received vsyncs will be stored and
	/// older ones will be dropped.
	strict -> OnVsync(resource struct {
	display_id fuchsia.hardware.display.types.DisplayId;
	timestamp uint64;
	applied_config_stamp fuchsia.hardware.display.types.ConfigStamp;
	cookie uint64;
	});

	/// Sets the visibility behavior of the virtcon.
	///
	/// This must only be called from the Virtcon client.
	strict SetVirtconMode(struct {
	mode VirtconMode;
	});

	// Event fired when the client gains or loses ownership of the displays.
	//
	// New clients should assume they do not have ownership of the display
	// until this event informs them otherwise.
	strict -> OnClientOwnershipChange(struct {
	has_ownership bool;
	});

	// Import a sysmem buffer collection token. `buffer_collection_id` must not
	// already be in use.
	strict ImportBufferCollection(resource struct {
	buffer_collection_id BufferCollectionId;
	buffer_collection_token client_end:fuchsia.sysmem.BufferCollectionToken;
	}) -> () error zx.Status;

	// Release an imported buffer collection.
	strict ReleaseBufferCollection(struct {
	buffer_collection_id BufferCollectionId;
	});

	// Takes an imported buffer collection and sets the constraints
	// on it so that it can be imported with a specific config.
	// TODO(https://fxbug.dev/42166207): Update this API to better support
	// optional fields.
	strict SetBufferCollectionConstraints(struct {
	buffer_collection_id BufferCollectionId;
	buffer_usage fuchsia.hardware.display.types.ImageBufferUsage;
	}) -> () error zx.Status;

	/// Returns true if Capture is supported on the platform.
	strict IsCaptureSupported() -> (struct {
	supported bool;
	}) error zx.Status;

	/// Starts capture. Client must provide a valid signal_event_id and
	/// image_id. signal_event_id must have been imported into the driver
	/// using ImportEvent FIDL API. Image_id is the id from ImportImageForCapture.
	/// The client will get notified once capture is complete via signal_event_id.
	/// Returns ZX_ERR_NOT_SUPPORTED if coordinator does not support capture
	strict StartCapture(struct {
	signal_event_id EventId;
	image_id ImageId;
	}) -> () error zx.Status;

	/// Set the minimum value of rgb channels. Valid range [0 255] inclusive. Returns
	/// ZX_ERR_NOT_SUPPORTED when the display hardware does not support this feature.
	/// This API is meant to address backlight bleeding that may occur on some hardware
	/// that have a specific type of panel and hardware assembly. The evolution of this
	/// API is highly hardware and product dependant and therefore as products evolve, this
	/// API may change or support for this API may become non-existent. Therefore, this
	/// API should be used with caution.
	///
	/// Unlike other calls in this API, SetMiniumRgb is applied immediately, and does not
	/// wait for ApplyConfig(). It is, however, still stateful.
	strict SetMinimumRgb(struct {
	minimum_rgb uint8;
	}) -> () error zx.Status;

	/// Power off/on the display panel.
	///
	/// This function takes effect immediately. Clients don't need to call
	/// `ApplyConfig()` to commit this command.
	///
	/// Once a display is turned off, it will not deliver vsync events, which
	/// may include the vsync event for the most recently applied config.
	///
	/// Staged display control commands (e.g. SetDisplayLayer) will not be
	/// affected. They are still applied to the display device when client calls
	/// `ApplyConfig()`, but the contents will be shown on display panel only
	/// after client powers on the display again.
	///
	/// Newly added displays are turned on by default.
	///
	/// Returns ZX_ERR_NOT_FOUND if `display_id` is invalid when Coordinator
	/// handles this method.
	/// Returns ZX_ERR_NOT_SUPPORTED if the display driver IC doesn't support
	/// turning on/off displays.
	strict SetDisplayPower(struct {
	display_id fuchsia.hardware.display.types.DisplayId;
	power_on bool;
	}) -> () error zx.Status;
	};