sdk/fidl/fuchsia.ui.gfx/resources.fidl

// Copyright 2017 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.ui.gfx;

using fuchsia.images;
using fuchsia.ui.composition;
using fuchsia.ui.views;
using zx;

/// These are all of the types of resources that can be created within a
/// `Session`. Add new fields only to the bottom of the list.
@available(deprecated=13, removed=17, legacy=true)
type ResourceArgs = strict resource union {
    // Memory resources.
    1: memory MemoryArgs;
    2: image ImageArgs;
    4: buffer BufferArgs;

    // Views.
    5: view ViewArgs;
    6: view_holder ViewHolderArgs;

    // Shapes (see shapes.fidl).
    7: rectangle RectangleArgs;
    8: rounded_rectangle RoundedRectangleArgs;
    9: circle CircleArgs;
    10: mesh MeshArgs;

    // Nodes (see nodes.fidl).
    11: shape_node ShapeNodeArgs;
    12: clip_node ClipNodeArgs;
    13: entity_node EntityNodeArgs;
    14: opacity_node OpacityNodeArgsHACK;

    // Materials.
    15: material MaterialArgs;

    // Layers.
    16: compositor CompositorArgs;
    17: display_compositor DisplayCompositorArgs;
    19: layer_stack LayerStackArgs;
    20: layer LayerArgs;

    // Scene representation and display.
    21: scene SceneArgs;
    22: camera CameraArgs;
    23: stereo_camera StereoCameraArgs;
    24: renderer RendererArgs;

    // Lighting.
    25: ambient_light AmbientLightArgs;
    26: directional_light DirectionalLightArgs;

    // A value that can be used in place of a constant value.
    27: variable VariableArgs;

    // TODO(https://fxbug.dev/42098623): Move these where they belong.  They're added to the end
    // of the struct temporarily until we transition to xunions.
    28: point_light PointLightArgs;
    31: view3 ViewArgs3;
    32: image_pipe2 ImagePipe2Args;
    33: image2 ImageArgs2;
    34: image3 ImageArgs3;
};

/// `ImagePipe2` is a `Resource` that can be used as a `Texture` for a `Material`.
@available(deprecated=13, removed=17, legacy=true)
type ImagePipe2Args = resource struct {
    image_pipe_request server_end:fuchsia.images.ImagePipe2;
};

/// `Memory` is a `Resource` that wraps a client-provided Zircon vmo to register
/// it with Scenic.
// TODO: specify resizing behavior.  Who can resize?  Client/Scenic/both/none?
@available(deprecated=13, removed=17, legacy=true)
type MemoryArgs = resource struct {
    /// The VMO which backs this memory.
    vmo zx.Handle:VMO;

    /// The amount of memory from `vmo` that should be utilized.
    allocation_size uint64;

    /// The type of memory stored in the VMO, namely whether it's GPU memory or
    /// host memory.
    memory_type fuchsia.images.MemoryType;
};

/// An image mapped to a range of a `Memory` resource.
// TODO: more precise and extensive docs.
@available(deprecated=13, removed=17, legacy=true)
type ImageArgs = struct {
    info fuchsia.images.ImageInfo;

    memory_id uint32; // id of a `Memory` resource
    memory_offset uint32; // byte offset of image within `Memory` resource
};

/// An image mapped to a range of a `Memory` resource.
@available(deprecated=13, removed=17, legacy=true)
type ImageArgs2 = struct {
    width uint32;
    height uint32;

    /// The id of a `BufferCollection`. Before creating this resource, the
    /// buffer collection should be registered on the same `Session` with
    /// `RegisterBufferCollection` and it should have its contraints set.
    /// Once the buffers are allocated successfully (e.g. after calling
    /// `WaitForBuffersAllocated`), the collection's id can be used to create
    /// the image resource.
    buffer_collection_id uint32;
    /// The index of the VMO from the `BufferCollection` that backs this image.
    buffer_collection_index uint32;
};

/// An image that is backed by a `BufferCollection` registered with `Allocator`.
@available(deprecated=13, removed=17, legacy=true)
type ImageArgs3 = resource struct {
    width uint32;
    height uint32;

    /// Image creation requires an allocated `BufferCollection` registered with Allocator.
    /// `import_token` should be the other end of a BufferCollectionExportToken that is
    /// successfully registered. All clients of the specified BufferCollection must have set
    /// their constraints and buffers should be allocated before calling.
    import_token fuchsia.ui.composition.BufferCollectionImportToken;
    /// The index of the VMO from the `BufferCollection` that backs this image.
    buffer_collection_index uint32;
};

/// A buffer mapped to a range of `Memory`.
// TODO: replace BufferArgs with BufferArgs2 that supports sysmem.
@available(deprecated=13, removed=17, legacy=true)
type BufferArgs = struct {
    memory_id uint32; // id of a `Memory` resource
    memory_offset uint32; // byte offset of buffer within `Memory` resource
    num_bytes uint32;
};

/// Represents the root of a subgraph within a larger scene graph.  Nodes can be
/// attached to the `View` as children, and these Nodes will have the `View`s'
/// coordinate transform applied to their own, in addition to being clipped to
/// the `View`s' bounding box.
/// See `ViewProperties`.
///
/// Each `View` is linked to a paired `ViewHolder` via a shared token pair.
///
/// Usually the `View` and its associated `ViewHolder` exist in separate
/// processes.  By combining them, the UI for an entire system can be built
/// using content contributed from many different processes.
@available(deprecated=13, removed=17, legacy=true)
type ViewArgs = resource struct {
    token fuchsia.ui.views.ViewToken;
    debug_name string:optional;
};

/// Represents the root of a subgraph within a larger scene graph.  Nodes can be
/// attached to the `View` as children, and these Nodes will have the `View`s'
/// coordinate transform applied to their own, in addition to being clipped to
/// the `View`s' bounding box.
/// See `ViewProperties`.
///
/// Each `View` is linked to a paired `ViewHolder` via a shared token pair.
///
/// Usually the `View` and its associated `ViewHolder` exist in separate
/// processes.  By combining them, the UI for an entire system can be built
/// using content contributed from many different processes.
///
/// Clients self-identify their `View` with a `ViewRef`, which is a stable
/// identifier that may be cloned and passed to other components in a
/// feed-forward style. It is accompanied by a `ViewRefControl`, which Scenic
/// uses to signal `View` destruction across the system; the `ViewRefControl`
/// must be unique - do not clone it.
@available(deprecated=13, removed=17, legacy=true)
type ViewArgs3 = resource struct {
    token fuchsia.ui.views.ViewToken;
    /// `control_ref.reference` must have default eventpair rights (i.e., with
    /// signaling), minus ZX_RIGHT_DUPLICATE.
    control_ref fuchsia.ui.views.ViewRefControl;
    /// `view_ref.reference` must have basic rights (i.e., no signaling).
    view_ref fuchsia.ui.views.ViewRef;
    debug_name string:optional;
};

/// Represents an attachment point for a subgraph within a larger scene graph.
/// The `ViewHolder` can be attached to a Node as a child, and the contents of
/// the linked `View` will become a child of the Node as well.
///
/// Each `ViewHolder` is linked to a paired `View` via a shared token pair.
///
/// Usually the `ViewHolder` and its associated `View` exist in separate
/// processes.  By combining them, the UI for an entire system can be built
/// using content contributed from many different processes.
@available(deprecated=13, removed=17, legacy=true)
type ViewHolderArgs = resource struct {
    token fuchsia.ui.views.ViewHolderToken;
    debug_name string:optional;
};

/// A Compositor draws its `LayerStack` into a framebuffer provided by its
/// attached `Display`, if any.  If no display is attached, nothing is rendered.
// TODO(https://fxbug.dev/42097798): there is currently no way to create/attach a display.
@available(deprecated=13, removed=17, legacy=true)
type CompositorArgs = struct {
    @allow_deprecated_struct_defaults
    dummy uint32 = 0;
};

/// A DisplayCompositor draws its attached `LayerStack` into an image that is
/// presented on a display.
@available(deprecated=13, removed=17, legacy=true)
type DisplayCompositorArgs = struct {
    @allow_deprecated_struct_defaults
    dummy uint32 = 0;
};

/// A LayerStack is a stack of layers that are attached to a Compositor, which
/// draws them in order of increasing Z-order (or rather, presents the illusion
/// of drawing them in that order: it may apply any optimizations that don't
/// affect the output).
///
/// Supported commands:
/// - AddLayer
@available(deprecated=13, removed=17, legacy=true)
type LayerStackArgs = struct {
    @allow_deprecated_struct_defaults
    dummy uint32 = 0;
};

/// A Layer is a 2-dimensional image that is drawn by a Compositor.  The
/// contents of each Layer in a Layerstack are independent of each other.
/// A layer is not drawn unless it has a camera, texture, or color.
///
/// Supported commands:
/// - Detach
/// - SetCamera
/// - SetColor
/// - SetTexture
/// - SetSize (depth must be zero)
/// - SetSize
/// - SetTranslation (z component determines the relative Z-ordering of layers)
/// - SetRotation (must rotate around Z-axis)
/// - SetScale
@available(deprecated=13, removed=17, legacy=true)
type LayerArgs = struct {
    @allow_deprecated_struct_defaults
    dummy uint32 = 0;
};

/// A Scene is the root of a scene-graph, and defines the rendering environment
/// (lighting, etc.) for the tree of nodes beneath it.
///
/// Supported commands:
/// - Add/RemoveLight
/// - AddChild
@available(deprecated=13, removed=17, legacy=true)
type SceneArgs = struct {
    @allow_deprecated_struct_defaults
    dummy uint32 = 0;
};

/// A Camera is used to render a Scene from a particular viewpoint.  This is
/// achieved by setting a Renderer to use the camera.
///
/// The following commands may be applied to a Camera:
/// - SetCameraTransform
/// - SetCameraProjection
/// - SetCameraPoseBuffer
@available(deprecated=13, removed=17, legacy=true)
type CameraArgs = struct {
    /// The scene that the camera is viewing.
    scene_id uint32;
};

/// A StereoCamera is a Camera that renders the scene in side-by-side stereo.
///
/// Any command which can be applied to a Camera can also be applied to a
/// StereoCamera.
/// Additional supported commands:
/// - SetStereoCameraProjection
@available(deprecated=13, removed=17, legacy=true)
type StereoCameraArgs = struct {
    /// The scene that the camera is viewing.
    scene_id uint32;
};

/// A Renderer renders a Scene via a Camera.
///
/// Supported commands:
/// - SetCamera
/// - SetRendererParam
@available(deprecated=13, removed=17, legacy=true)
type RendererArgs = struct {
    @allow_deprecated_struct_defaults
    dummy uint32 = 0;
};

/// An AmbientLight is a Light that is is assumed to be everywhere in the scene,
/// in all directions.
///
/// Supported commands:
/// - SetLightColor
@available(deprecated=13, removed=17, legacy=true)
type AmbientLightArgs = struct {
    @allow_deprecated_struct_defaults
    dummy uint32 = 0;
};

/// A DirectionalLight is a Light that is emitted from a point at infinity.
///
/// Although the light is directional, the light has some amount of angular
/// dispersion (i.e., the light is not fully columnated). For simplicity, we
/// assume the dispersion of the light source is symmetric about the light's
/// primary direction.
///
/// Supported commands:
/// - SetLightColor
/// - SetLightDirection
@available(deprecated=13, removed=17, legacy=true)
type DirectionalLightArgs = struct {
    @allow_deprecated_struct_defaults
    dummy uint32 = 0;
};

/// A PointLight is a Light that emits light in all directions.  By default, the
/// intensity of the light falls off according to the physically based
/// "inverse-square law" (see Wikipedia), although it can be adjusted to other
/// values for artistic effect.
///
/// Supported commands:
/// - SetLightColor
/// - SetPointLightPosition
/// - SetPointLightFalloff
@available(deprecated=13, removed=17, legacy=true)
type PointLightArgs = struct {
    @allow_deprecated_struct_defaults
    dummy uint32 = 0;
};

/// Simple texture-mapped material.
///
/// Supported commands:
/// - SetTextureCmd: sets the texture, or it can be left as zero (no texture).
///   The texture can be an Image or ImagePipe2.
/// - SetColorCmd: sets the color.
@available(deprecated=13, removed=17, legacy=true)
type MaterialArgs = struct {
    @allow_deprecated_struct_defaults
    dummy uint32 = 0;
};

/// Describes a typed, client-modifiable value.
@available(deprecated=13, removed=17, legacy=true)
type VariableArgs = struct {
    type ValueType;
    initial_value Value; // Must match type.  Must not be a variable_id.
};

/// Describes an exported resource that is to be imported by an
/// ImportResourceCmd.
///
/// NOTE: Currently just an enum of importable resource types, but may later be
/// expanded to express concepts like "meshes with a particular vertex format".
@available(deprecated=13, removed=17, legacy=true)
type ImportSpec = strict enum {
    NODE = 0;
};