system/fidl/display/display-controller.fidl

// 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.display;

// Invalid id for displays, images, and events.
const uint64 invalidId = 0;

// A display mode configuration.
struct Mode {
  // Resolution in pixels.
  uint32 horizontal_resolution;
  uint32 vertical_resolution;
  // Vertical refresh rate in Hz * 100
  uint32 refresh_rate_e2;

  // Bitfield of flags defined below which further specify the mode.
  uint32 flags;
};

// === Mode flags ===

// Flag for interlaced display modes.
const int32 modeInterlaced = 0x1;

// Info contains the information about a particular attached display.
struct Info {
  uint64 id;

  // Modes supported by the attached display. The first entry is the
  // preferred mode.
  vector<Mode> modes;
  // zx_pixel_format_t constants supported by the attached display. The
  // first entry is the preferred mode.
  vector<uint32> pixel_format;
};

// An ImageConfig accompanies image data and defines how to interpret that data.
struct ImageConfig {
  // The width and height of the image in pixels.
  uint32 width;
  uint32 height;

  // A zx_pixel_format_t constant that defines the pixel format of the data.
  int32 pixel_format;

  // Type conveys information about what is providing the pixel data. If this
  // is not typeSimple, it is up to the driver and image producer to
  // agree on the meaning of the value through some mechanism outside the scope
  // of this API.
  uint32 type = typeSimple;
};
const uint32 typeSimple = 0;

// Rotations are applied counter-clockwise, and are applied before reflections.
enum Transform : uint8 {
  IDENTITY = 0;
  REFLECT_X = 1;
  REFLECT_Y = 2;
  ROT_90 = 3;
  ROT_180 = 4;
  ROT_270 = 5;
  ROT_90_REFLECT_X = 6;
  ROT_90_REFLECT_Y = 7;
};

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

enum ClientCompositionOp : uint8 {
  // The client should convert the corresponding layer to a primary layer.
  CLIENT_USE_PRIMARY = 0;
  // 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 will only be set on one layer per display.
  CLIENT_MERGE_BASE = 1;
  // The client should pre-scale the image so that src_frame's dimensions are equal
  // to dest_frame's dimensions.
  CLIENT_MERGE_SRC = 2;
  // The client should pre-clip the image so that src_frame's dimensions are equal to
  // the image's dimensions.
  CLIENT_FRAME_SCALE = 3;
  // The client should pre-clip the image so that src_frame's dimensions are equal to
  // the image's dimensions.
  CLIENT_SRC_FRAME = 4;
  // The client should pre-apply the transformation so TRANSFORM_IDENTITY can be used.
  CLIENT_TRANSFORM = 5;
};

enum ConfigError : uint8 {
  OK = 0;
  // The requested layer configuration is invalid.
  INVALID_CONFIG = 1;
};

struct ConfigResult {
  uint64 display_id;

  // There was an unrecoverable error with the configuration. If this is set,
  // then layers and client_ops will be empty.
  ConfigError error;

  // If present, layers and client_ops are parallel vectors which specify all
  // (layer, ClientCompositionOp) on the the display specified by display_id.
  vector<uint64> layers;
  vector<ClientCompositionOp> client_ops;
};

// Interface for accessing the display hardware.
//
// The driver supports two simultaneous clients - a primary client and a virtcon
// client. The primary client is obtained by directly opening the devfs device,
// while the virtcon client is obtained by opening a 'virtcon' child of the
// device.
interface Controller {
  // 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.
  1: -> DisplaysChanged(vector<Info> added, vector<uint64> removed);

  // Imports a VMO backed image. If tiling is not typeSimple, it is up to
  // the driver and client to agree on its meaning through some mechanism
  // outside the scope of this API.
  2: ImportVmoImage(ImageConfig image_config, handle<vmo> vmo, int32 offset) -> (status res, uint64 image_id);

  // Releases an image. It is safe to call this on an image which is currently
  // in use, but the resources associated with such an image will not be
  // released until the image is no longer in use.
  3: ReleaseImage(uint64 image_id);

  // Imports an event into the driver and associates it with the given id.
  //
  // Id must not be equal to invalidId and must uniquely identify the underlying
  // event. It is not well defined 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.
  4: ImportEvent(handle<event> event, uint64 id);

  // 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.
  5: ReleaseEvent(uint64 id);

  // 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.
  6: CreateLayer() -> (status res, uint64 layer_id);

  // Destroys the given layer. A layer is considered in use from the time it
  // is passed to SetDisplayLayers until a subsequent call to SetDisplayLayers
  // removes it from its display or until its display is removed. It is illegal
  // to destroy a layer which is in use or in a pending configuration.
  7: DestroyLayer(uint64 layer_id);

  // 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.
  18: SetDisplayMode(uint64 display_id, Mode mode);

  // 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.
  8: SetDisplayLayers(uint64 display_id, vector<uint64> layer_ids);

  // 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).
  //
  // If the image configuration changes due to applying this operation, the
  // image currently being displayed and any pending images will be dropped
  // before the next frame, regardless of whether or not the layer's new image
  // is ready to be displayed.
  9: SetLayerPrimaryConfig(uint64 layer_id, ImageConfig image_config);

  // Sets the layer transform, scaling, and positioning. Calling this on a
  // non-primary layer is illegal.
  //
  // |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 CONFIG_ERROR if any of these
  // conditions is violated.
  10: SetLayerPrimaryPosition(uint64 layer_id, Transform transform, Frame src_frame, Frame dest_frame);

  // Sets the image for the layer. It is illegal to call this with an
  // image which doesn't match the layer's pending ImageConfig.
  //
  // 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 present_event_id is valid, then the driver will signal the event when
  // the image is presented. If signal_event_id is valid, then the driver will
  // signal the event when the image is no longer being presented.
  //
  // The driver will queue the images that are not yet ready. When an image is
  // ready, any older images which are not yet ready will be dropped and their
  // present and signal events will immediately be signaled. The driver also
  // does not attempt to synchronize with vsync. If multiple images are ready
  // within one vsync period, then only the last image will actually be
  // displayed.
  //
  // An image cannot be used for multiple layers simultaneously, nor can an
  // image be given back to the display controller while it is still in use.
  // An image is considered used when it is part of a pending configuration or
  // from when its configuration is applied until its signal_event_id is
  // signaled.
  11: SetLayerImage(uint64 layer_id, uint64 image_id, uint64 wait_event_id, uint64 present_event_id, uint64 signal_event_id);

  // Attempts to validate the current configuration.
  //
  // When CheckConfig is called, the driver will validate the pending
  // configuration. Any errors or client configuration will be returned in
  // the res vector. If the vector is empty, the configuration is valid.
  //
  // Most SetX operation require re-validating the configuration. The exception
  // are SetLayerCursorPosition and SetLayerImage - these operations do not
  // modify the configuration in a way which requires revalidation.
  //
  // If discard is true, the pending changes will be discarded after validation.
  12: CheckConfig(bool discard) -> (vector<ConfigResult> res);

  // 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.
  13: ApplyConfig();

  // Sets whether or not this client has ownership of the display. This call
  // will silently fail if called from the primary client.
  14: SetOwnership(bool active);

  // 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.
  15: -> ClientOwnershipChange(bool has_ownership);

  // Computes the stride (in pixels) necessary for a linear image with the
  // given width and pixel format. Returns 0 on error.
  16: ComputeLinearImageStride(uint32 width, int32 pixel_format) -> (uint32 stride);

  // Allocates a VMO of the requested size which can be used for images.
  // TODO: move this into a seperate video buffer management system.
  17: AllocateVmo(uint64 size) -> (status res, handle<vmo>? vmo);

  // TODO(stevensd): Renumber method ordinals in declaration order
  // 18: SetDisplayMode

  // TODO(stevensd): Delete this when nothing uses it anymore
  100: SetDisplayImage(uint64 display, uint64 image_id, uint64 wait_event_id, uint64 present_event_id, uint64 signal_event_id);
};