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

/// These are all of the types of resources that can be created within a
/// |Session|.
union ResourceArgs {
    // Memory resources.
    MemoryArgs memory;
    ImageArgs image;
    ImagePipeArgs image_pipe;
    BufferArgs buffer;

    // Views.
    ViewArgs view;
    ViewHolderArgs view_holder;

    // Shapes (see shapes.fidl).
    RectangleArgs rectangle;
    RoundedRectangleArgs rounded_rectangle;
    CircleArgs circle;
    MeshArgs mesh;

    // Nodes (see nodes.fidl).
    ShapeNodeArgs shape_node;
    ClipNodeArgs clip_node;
    EntityNodeArgs entity_node;
    OpacityNodeArgsHACK opacity_node;

    // Materials.
    MaterialArgs material;

    // Layers.
    CompositorArgs compositor;
    DisplayCompositorArgs display_compositor;
    ImagePipeCompositorArgs image_pipe_compositor;
    LayerStackArgs layer_stack;
    LayerArgs layer;

    // Scene representation and display.
    SceneArgs scene;
    CameraArgs camera;
    StereoCameraArgs stereo_camera;
    RendererArgs renderer;

    // Lighting.
    AmbientLightArgs ambient_light;
    DirectionalLightArgs directional_light;

    // A value that can be used in place of a constant value.
    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.
    PointLightArgs point_light;
    ViewArgs2 view2;
    ViewHolderArgs2 view_holder2;
};

struct ImagePipeArgs {
    request<fuchsia.images.ImagePipe> 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.
    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;
};

struct ViewArgs2 {
    fuchsia.ui.views.ViewToken token;
    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;
};

struct ViewHolderArgs2 {
    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(SCN-452): 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;
};