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.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.
union ResourceArgs {
    // Memory resources.
    1: MemoryArgs memory;
    2: ImageArgs image;
    3: ImagePipeArgs image_pipe;
    4: BufferArgs buffer;

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

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

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

    // Materials.
    15: MaterialArgs material;

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

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

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

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

    // TODO(SCN-1225): Move these where they belong.  They're added to the end
    // of the struct temporarily until we transition to xunions.
    28: PointLightArgs point_light;
    29: reserved;
    30: reserved;
    31: ViewArgs3 view3;
    32: ImagePipe2Args image_pipe2;
};

struct ImagePipeArgs {
    request<fuchsia.images.ImagePipe> image_pipe_request;
};

/// `ImagePipe2` is a `Resource` that can be used as a `Texture` for a `Material`.
struct ImagePipe2Args {
    request<fuchsia.images.ImagePipe2> image_pipe_request;
};

/// `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?
struct MemoryArgs {
    // The VMO which backs this memory.
    zx.handle:VMO vmo;

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

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

/// An image mapped to a range of a `Memory` resource.
// TODO: more precise and extensive docs.
struct ImageArgs {
    fuchsia.images.ImageInfo info;

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

/// A buffer mapped to a range of `Memory`.
struct BufferArgs {
    uint32 memory_id; // id of a `Memory` resource
    uint32 memory_offset; // byte offset of buffer within `Memory` resource
    uint32 num_bytes;
};

/// 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.
struct ViewArgs {
    fuchsia.ui.views.ViewToken token;
    string? debug_name;
};

/// 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.
struct ViewArgs3 {
    fuchsia.ui.views.ViewToken token;
    /// `control_ref.reference` must have default eventpair rights (i.e., with
    /// signaling), minus ZX_RIGHT_DUPLICATE.
    fuchsia.ui.views.ViewRefControl control_ref;
    /// `view_ref.reference` must have basic rights (i.e., no signaling).
    fuchsia.ui.views.ViewRef view_ref;
    string? debug_name;
};

/// 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.
struct ViewHolderArgs {
    fuchsia.ui.views.ViewHolderToken token;
    string? debug_name;
};

/// A Compositor draws its `LayerStack` into a framebuffer provided by its
/// attached `Display`, if any.  If no display is attached, nothing is rendered.
// TODO(fxb/23686): there is currently no way to create/attach a display.
struct CompositorArgs {
    // TODO(SCN-694): Clean up dummy args.
    uint32 dummy = 0;
};

/// A DisplayCompositor draws its attached `LayerStack` into an image that is
/// presented on a display.
struct DisplayCompositorArgs {
    // TODO(SCN-694): Clean up dummy args.
    uint32 dummy = 0;
};

/// An ImagePipeCompositor draws its attached `LayerStack` into an image that is
/// presented on an image-pipe.
struct ImagePipeCompositorArgs {
    fuchsia.images.ImagePipe target;
};

/// 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
struct LayerStackArgs {
    // TODO(SCN-694): Clean up dummy args.
    uint32 dummy = 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
struct LayerArgs {
    // TODO(SCN-694): Clean up dummy args.
    uint32 dummy = 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
struct SceneArgs {
    // TODO(SCN-694): Clean up dummy args.
    uint32 dummy = 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
struct CameraArgs {
    // The scene that the camera is viewing.
    uint32 scene_id;
};

/// 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
struct StereoCameraArgs {
    // The scene that the camera is viewing.
    uint32 scene_id;
};

/// A Renderer renders a Scene via a Camera.
///
/// Supported commands:
/// - SetCamera
/// - SetRendererParam
struct RendererArgs {
    // TODO(SCN-694): Clean up dummy args.
    uint32 dummy = 0;
};

/// An AmbientLight is a Light that is is assumed to be everywhere in the scene,
/// in all directions.
///
/// Supported commands:
/// - SetLightColor
struct AmbientLightArgs {
    // TODO(SCN-694): Clean up dummy args.
    uint32 dummy = 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
struct DirectionalLightArgs {
    // TODO(SCN-694): Clean up dummy args.
    uint32 dummy = 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
struct PointLightArgs {
    // TODO(SCN-694): Clean up dummy args.
    uint32 dummy = 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 ImagePipe.
/// - SetColorCmd: sets the color.
struct MaterialArgs {
    // TODO(SCN-694): Clean up dummy args.
    uint32 dummy = 0;
};

/// Describes a typed, client-modifiable value.
struct VariableArgs {
    ValueType type;
    Value initial_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".
enum ImportSpec {
    NODE = 0;
};