| // 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.scenic.allocation; |
| 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. |
| resource 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(fxbug.dev/24428): 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; |
| 33: ImageArgs2 image2; |
| 34: ImageArgs3 image3; |
| }; |
| |
| resource struct ImagePipeArgs { |
| request<fuchsia.images.ImagePipe> image_pipe_request; |
| }; |
| |
| /// `ImagePipe2` is a `Resource` that can be used as a `Texture` for a `Material`. |
| resource 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? |
| resource 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. |
| [Deprecated] |
| struct ImageArgs { |
| fuchsia.images.ImageInfo info; |
| |
| uint32 memory_id; // id of a `Memory` resource |
| uint32 memory_offset; // byte offset of image within `Memory` resource |
| }; |
| |
| /// An image mapped to a range of a `Memory` resource. |
| [Deprecated] |
| struct ImageArgs2 { |
| uint32 width; |
| uint32 height; |
| |
| /// 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. |
| uint32 buffer_collection_id; |
| /// The index of the VMO from the `BufferCollection` that backs this image. |
| uint32 buffer_collection_index; |
| }; |
| |
| /// An image that is backed by a `BufferCollection` registered with `Allocator`. |
| resource struct ImageArgs3 { |
| uint32 width; |
| uint32 height; |
| |
| /// 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. |
| fuchsia.scenic.allocation.BufferCollectionImportToken import_token; |
| /// The index of the VMO from the `BufferCollection` that backs this image. |
| uint32 buffer_collection_index; |
| }; |
| |
| /// A buffer mapped to a range of `Memory`. |
| // TODO: replace BufferArgs with BufferArgs2 that supports sysmem. |
| 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. |
| resource 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. |
| resource 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. |
| resource 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(fxbug.dev/23686): there is currently no way to create/attach a display. |
| struct CompositorArgs { |
| // TODO(fxbug.dev/23916): 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(fxbug.dev/23916): Clean up dummy args. |
| uint32 dummy = 0; |
| }; |
| |
| /// An ImagePipeCompositor draws its attached `LayerStack` into an image that is |
| /// presented on an image-pipe. |
| resource 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(fxbug.dev/23916): 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(fxbug.dev/23916): 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(fxbug.dev/23916): 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(fxbug.dev/23916): 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(fxbug.dev/23916): 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(fxbug.dev/23916): 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(fxbug.dev/23916): 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(fxbug.dev/23916): 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; |
| }; |