// 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.mem;
using zx;

/// Commands that are used to modify the state of a `Session`.
type Command = strict resource union {
    1: create_resource CreateResourceCmd;
    2: release_resource ReleaseResourceCmd;
    3: export_resource ExportResourceCmdDeprecated;
    4: import_resource ImportResourceCmdDeprecated;

    /// Tagging commands.
    5: set_tag SetTagCmd;

    /// Grouping commands.
    6: detach DetachCmd;

    /// Spatial commands.
    7: set_translation SetTranslationCmd;
    8: set_scale SetScaleCmd;
    9: set_rotation SetRotationCmd;
   10: set_anchor SetAnchorCmd;
   11: set_size SetSizeCmd;
   12: set_opacity SetOpacityCmd;

   13: send_size_change_hint_hack SendSizeChangeHintCmdHACK;

    /// Node-specific commands.
   14: add_child AddChildCmd; // TODO: Should we require a DetachCmd before
    /// re-parenting?
   15: add_part AddPartCmd;
   16: detach_children DetachChildrenCmd;
   17: set_shape SetShapeCmd;
   18: set_material SetMaterialCmd;
   19: set_clip SetClipCmd;
   20: set_hit_test_behavior SetHitTestBehaviorCmd;
   21: set_view_properties SetViewPropertiesCmd;
   22: take_snapshot_cmd TakeSnapshotCmdDEPRECATED;

    /// Camera and lighting commands.
   23: set_camera SetCameraCmd;
   24: set_camera_transform SetCameraTransformCmd;
   25: set_camera_projection SetCameraProjectionCmd;
   26: set_stereo_camera_projection SetStereoCameraProjectionCmd;
   27: set_camera_pose_buffer SetCameraPoseBufferCmd;
   28: set_light_color SetLightColorCmd;
   29: set_light_direction SetLightDirectionCmd;
   30: add_light AddLightCmd;
   31: detach_light DetachLightCmd;
   32: detach_lights DetachLightsCmd;

   33: set_texture SetTextureCmd;
   34: set_color SetColorCmd;

    /// Mesh commands.
   35: bind_mesh_buffers BindMeshBuffersCmd;

    /// Layer and renderer commands.
   36: add_layer AddLayerCmd;
   37: remove_layer RemoveLayerCmd;
   38: remove_all_layers RemoveAllLayersCmd;
   39: set_layer_stack SetLayerStackCmd;
   40: set_renderer SetRendererCmd;
   41: set_renderer_param SetRendererParamCmd;

    /// Events.
   42: set_event_mask SetEventMaskCmd;

    /// Diagnostic commands.
   43: set_label SetLabelCmd;

    /// Debugging commands.
   44: set_disable_clipping SetDisableClippingCmd;

    // TODO(fxbug.dev/24238): Remove this.
   45: set_import_focus SetImportFocusCmdDEPRECATED;

    // TODO(fxbug.dev/24428): Move these where they belong.  They're added to the end of
    // the struct temporarily until we transition to xunions.
   46: set_clip_planes SetClipPlanesCmd;
   47: set_point_light_position SetPointLightPositionCmd;
   48: set_point_light_falloff SetPointLightFalloffCmd;
   49: scene__add_ambient_light SceneAddAmbientLightCmd;
   50: scene__add_directional_light SceneAddDirectionalLightCmd;
   51: scene__add_point_light SceneAddPointLightCmd;

   52: set_display_color_conversion SetDisplayColorConversionCmdHACK;

   53: set_display_rotation SetDisplayRotationCmdHACK;

   54: set_enable_view_debug_bounds SetEnableDebugViewBoundsCmd;
   55: set_view_holder_bounds_color SetViewHolderBoundsColorCmd;

   56: set_camera_clip_space_transform SetCameraClipSpaceTransformCmd;

   57: set_display_minimum_rgb SetDisplayMinimumRgbCmdHACK;

   58: set_semantic_visibility SetSemanticVisibilityCmd;
};

/// Instructs the compositor to create the specified `Resource`, and to register
/// it in a table so that it can be referenced by subsequent commands.
type CreateResourceCmd = resource struct {
    /// An ID that is currently not used within the session.
    id uint32;
    resource ResourceArgs;
};

/// Releases the client's reference to the resource; it is then illegal to use
/// the ID in subsequent Commands.  Other references to the resource may exist,
/// so releasing the resource does not result in its immediate destruction; it is
/// only destroyed once the last reference is released.  For example, the
/// resource may be required to render an in-progress frame, or it may be
/// referred to by another resource).  However, the ID will be immediately
/// unregistered, and may be reused to create a new resource.
type ReleaseResourceCmd = struct {
    /// ID of the resource to be dereferenced.
    id uint32;
};

/// Create an external reference to the specified resource, which can then be
/// imported into another Session by passing a handle to `token`'s peer to
/// ImportResourceCmd; see that comment for more details.
///
/// The importing client is typically in a different process than the exporter.
/// No specific mechanism is provided for transferring a token from an exporter
/// to an importer; collaborators may choose any out-of-band API they wish to do
/// so.
type ExportResourceCmdDeprecated = resource struct {
    id uint32;
    token zx.Handle:EVENTPAIR;
};

/// Import a resource that was exported via ExportResourceCmd().  `token` is
/// a handle to the eventpair peer that was used to export the resource, and
/// `spec` describes the type of the imported resource, and the commands which
/// can legally be applied to it.  Afterward, `id` can be used to refer to the
/// resource in an Command, similarly (but not identically: see below) to a
/// resource that was created in the session.  For example, you can add children
/// to an imported EntityNode via AddChildCmd.
///
/// However, note that the importer does not gain full access to the imported
/// resource, but rather to an attenuated subset of its capabilities.  For
/// example, you cannot use a DetachCmd to detach an imported EntityNode from
/// its parent.
///
/// Unlike ExportResourceCmd, there is no configurable timeout.  There is an
/// expectation that the exported resource will become available in a short
/// amount of time.  TODO: this needs elaboration... e.g. we might notify via the
/// SessionListener when we know that the link will never be made (e.g. if the
/// peer of the import token is destroyed).
///
// TODO: describe how the imported resource behaves if the exported resource
// isn't yet available, or becomes unavailable (e.g. an imported Material might
// act as a plain white texture).
type ImportResourceCmdDeprecated = resource struct {
    id uint32;
    token zx.Handle:EVENTPAIR;
    spec ImportSpec;
};

/// Sets/clears a node's tag value.
///
/// A session can apply a tag value to any node to which it has access, including
/// imported nodes.  These tags are private to the session and cannot be read
/// or modified by other sessions.  When multiple sessions import the same node,
/// each session will only observe its own tag values.
///
/// Hit test results for a session only include nodes which the session has
/// tagged with a non-zero value.  Therefore a session can use tag values to
/// associate nodes with their functional purpose when picked.
///
/// Constraints:
/// - `node_id` refs a `Node`.
/// - `tag_value` is the tag value to assign, or 0 to remove the tag.
type SetTagCmd = struct {
    node_id uint32;
    tag_value uint32;
};

/// Detaches a parentable object from its parent (e.g. a node from a parent node,
/// or a layer from a layer stack).  It is illegal to apply this command to a
/// non-parentable object.  No-op if the target object currently has no parent.
///
/// Constraints:
/// - `id` refs a parentable object
///
/// Discussion:
/// For nodes, this command will detach a node from its parent, regardless of
/// whether it is a part or a child of its parent.
type DetachCmd = struct {
    id uint32;
};

/// Sets a Resource's (typically a Node's) translation.
///
/// Constraints:
/// - `id` refs a Resource with the has_transform characteristic.
type SetTranslationCmd = struct {
    id uint32;
    value Vector3Value;
};

/// Sets a Resource's (typically a Node's) scale.
///
/// Constraints:
/// - `id` refs a Resource with the has_transform characteristic.
type SetScaleCmd = struct {
    id uint32;
    value Vector3Value;
};

/// Sets a Resource's (typically a Node's) rotation.
///
/// Constraints:
/// - `id` refs a Resource with the has_transform characteristic.
///
/// Discussion:
/// Quaternions represent any rotation in a 3D coordinate system. Consisting of
/// [a,b,c,d], [a] represents the amount of rotation that should be applied and
/// [b,c,d] represents the vector around which the rotation is applied. This
/// conforms to the semantics of glm::quat.
type SetRotationCmd = struct {
    id uint32;
    value QuaternionValue;
};

/// Sets a Resource's (typically a Node's) anchor point.
///
/// Constraints:
/// - `id` refs a Resource with the has_transform characteristic.
type SetAnchorCmd = struct {
    id uint32;
    value Vector3Value;
};

/// Sets an object's size.
///
/// Constraints:
/// - `id` refs a resizeable object.
/// - some objects that support this command may have additional constraints
///   (e.g. in some cases `depth` must be zero).
type SetSizeCmd = struct {
    id uint32;
    value Vector2Value;
};

/// Sets a node's opacity.
///
/// Constraints:
/// - `node_id` refs a `Node` with the has_opacity characteristic.
/// - `opacity` is in the range [0, 1].
type SetOpacityCmd = struct {
    node_id uint32;
    opacity float32;
};

/// Sends a hint about a pending size change to the given node and all nodes
/// below. This is generally sent before an animation.
///
/// `width_change_factor` and `height_change_factor` is how much bigger or smaller
/// the item is expected to be in the near future. This one number encapsulate
/// both changes in scale, as well as changes to layout width and height.
type SendSizeChangeHintCmdHACK = struct {
    node_id uint32;
    width_change_factor float32;
    height_change_factor float32;
};

/// Add a node as a child to another node.
///
/// Constraints:
/// - `id` refs a Node with the has_children characteristic.
/// - `child_id` refs any Node.
///
/// Discussion:
/// The child node is first removed from its existing parent, as if DetachCmd
/// was applied first.
type AddChildCmd = struct {
    node_id uint32;
    child_id uint32;
};

/// Add a node as a part of another node.  The implications of being a part
/// rather than a child differ based on the type of the part.  However, one
/// implication is constant: removing all of a node's children (e.g. via
/// DetachChildrenCmd) does not affect its parts.  This is similar to the
/// "shadow DOM" in a web browser: the controls of a <video> element are
/// implemented as using the shadow DOM, and do no show up amongst the children
/// of that element.
///
/// Constraints:
/// - `id` refs a Node with the has_parts characteristic.
/// - `part_id` refs any Node.
///
/// Discussion:
/// The part node is first removed from its existing parent, as if DetachCmd
/// was applied first.
type AddPartCmd = struct {
    node_id uint32;
    part_id uint32;
};

/// Detaches all of a node's children (but not its parts).
type DetachChildrenCmd = struct {
    node_id uint32;
};

// TODO: add "Shape/Material Compatibility section"
/// Sets/clears a node's shape.
///
/// Constraints:
/// - `node_id` refs a `Node` with the has_shape characteristic.
/// - `shape_id` refs a `Shape`, or nothing.
/// - if this command causes the target to have both a `Shape` and a `Material`,
///   then these must be compatible with each other (see README.md regarding
///   "Shape/Material Compatibility").
///
/// Discussion:
/// In order to be painted, a node requires both a `Shape` and a `Material`.
/// Without a material, a node can still participate in hit-testing and clipping.
/// Without a shape, a node cannot do any of the above.
type SetShapeCmd = struct {
    node_id uint32;
    shape_id uint32;
};

// TODO: add "Shape/Material Compatibility section"
/// Sets/clears a node's material.
///
/// Constraints:
/// - `node_id` refs a `Node` with the has_material characteristic.
/// - `material_id` refs a `Material`, or nothing.
/// - if this command causes the target to have both a `Shape` and a `Material`,
///   then these must be compatible with each other (see README.md regarding
///   "Shape/Material Compatibility").
///
/// Discussion:
/// In order to be painted, a node requires both a `Shape` and a `Material`.
/// Without a material, a node can still participate in hit-testing and clipping.
/// Without a shape, a node cannot do any of the above.
type SetMaterialCmd = struct {
    node_id uint32;
    material_id uint32;
};

/// Sets/clears a node's clip.  DEPRECATED: use SetClipPlanesCmd.
///
/// Constraints:
/// - `node_id` refs a `Node` with the has_clip characteristic.
/// - `clip_id` a `Node` with the is_clip characteristic, or nothing.  If the
///   referenced node is not rooted, then it will have no effect (since its
///   full world-transform cannot be determined).
/// - `clip_to_self` If false, children are only clipped to the region specified
///   by `clip_id`.  If true, children are additionally clipped to the node's
///   shape (as determined by its ShapeNode parts).
///
/// Discussion:
/// If a node has a clip, it will be applied to both the parts and the children
/// of the node.  Under some circumstances (TBD), a clip will not be applicable
/// to a node; in such cases it will be as though no clip has been specified for
/// the node.
// TODO: elaborate on the circumstances under which a clip is inapplicable.
// For example, consider a 3D space that looks through a portal into a 2D space
// that uses a clip for a circular reveal.  It would not be meaningful to clip
// objects on the outside (i.e. in the 3D space).
type SetClipCmd = struct {
    node_id uint32;
    clip_id uint32;
    clip_to_self bool;
};

/// Sets a node's hit test behavior.
///
/// Discussion:
/// By default, hit testing is performed on the node's content, its parts,
/// and its children.
type SetHitTestBehaviorCmd = struct {
    node_id uint32;
    hit_test_behavior HitTestBehavior;
};

/// Sets a node's semantic visibility.
///
/// Discussion:
/// By default, all nodes are semantically visible. Semantically invisible nodes and their children
/// are ignored by hit tests performed for accessibility.
type SetSemanticVisibilityCmd = struct {
    node_id uint32;
    @allow_deprecated_struct_defaults
    visible bool = true;
};

/// Sets the properties for a ViewHolder's attached View.
///
/// Constraints:
/// - `view_holder_id` refs a `ViewHolder`.
type SetViewPropertiesCmd = struct {
    view_holder_id uint32;
    properties ViewProperties;
};

protocol SnapshotCallbackDEPRECATED {
    OnData(resource struct {
        data fuchsia.mem.Buffer;
    });
};

type TakeSnapshotCmdDEPRECATED = resource struct {
    node_id uint32;
    callback client_end:SnapshotCallbackDEPRECATED;
};

/// Sets a renderer's camera.
///
/// Constraints:
/// - `renderer_id` refs a `Renderer`.
/// - `camera_id` refs a `Camera`, or stops rendering by passing zero.
/// - `matrix` is a value or variable of type kMatrix4x4.
type SetCameraCmd = struct {
    renderer_id uint32;
    camera_id uint32;
};

/// Sets a camera's view matrix.
/// This operation can be applied to both Cameras and StereoCameras.
///
/// Constraints:
/// - `camera_id` refs a `Camera`.
/// - `eye_position` is the position of the eye.
/// - `eye_look_at` is the point is the scene the that eye is pointed at.
/// - `eye_up` defines the camera's "up" vector.
type SetCameraTransformCmd = struct {
    camera_id uint32;
    eye_position Vector3Value;
    eye_look_at Vector3Value;
    eye_up Vector3Value;
};

/// Sets a camera's projection matrix.
/// This operation cannot be applied to a StereoCamera.
///
/// Constraints:
/// - `camera_id` refs a `Camera` that is not a `StereoCamera`.
/// - `fovy` is the Y-axis field of view, in radians.
///
/// NOTE: A default orthographic projection is specified by setting `fovy` to
/// zero.  In this case, the camera transform is ignored.
type SetCameraProjectionCmd = struct {
    camera_id uint32;
    fovy FloatValue; // Y-axis field of view, in radians.
};

/// Sets a StereoCamera's projection matrices.
/// This operation can only be applied to a StereoCamera.
///
/// Constraints:
/// - `camera_id` refs a `StereoCamera`.
/// - `left_projection` is the projection matrix for the left eye.
/// - `right_projection` is the projection matrix for the right eye.
///
/// These projection matrices may also contain a transform in camera space for
/// their eye if needed.
type SetStereoCameraProjectionCmd = struct {
    camera_id uint32;
    left_projection Matrix4Value;
    right_projection Matrix4Value;
};

/// Sets a camera's 2D clip-space transform.
///
/// Constraints:
/// - `camera_id` refs a `Camera`.
/// - `translation` is the desired translation, in Vulkan NDC.
/// - `scale` is the scale factor to apply on the x/y plane before translation.
type SetCameraClipSpaceTransformCmd = struct {
    camera_id uint32;
    translation vec2;
    scale float32;
};

/// Sets the "pose buffer" for the camera identified by `camera_id`.
/// This operation can be applied to both Cameras and StereoCameras.
///
/// This will override any position and rotation set for the camera and will
/// make it take its position and rotation from the pose buffer each frame
/// based on the presentation time for that frame.
///
/// A pose buffer represents a ring buffer of poses for a fixed number of time
/// points in the future. Each entry in the buffer identified by `buffer_id` is
/// a quaternion and a position layed out as follows:
///
/// struct Pose {
///   // Quaternion
///   float32 a;
///   float32 b;
///   float32 c;
///   float32 d;
///
///   // Position
///   float32 x;
///   float32 y;
///   float32 z;
///
///   // Reserved/Padding
///   byte[4] reserved;
/// }
///
/// The buffer can be thought of as a packed array of `num_entries` Pose structs
/// and is required to be at least num_entries * sizeof(Pose) bytes.
///
/// The quaternions and positions are specified in the space of the camera's
/// parent node.
///
/// `base_time` is a base time point expressed in nanoseconds in the
/// `CLOCK_MONOTONIC` timebase and `time_interval` is the time in nanoseconds
/// between entries in the buffer. `base_time` must be in the past.
///
/// For a given point in time `t` expressed in nanoseconds in the
/// `CLOCK_MONOTONIC` timebase the index of the corresponding pose in
/// the pose buffer can be computed as follows:
///
/// index(t) = ((t - base_time) / time_interval) % num_entries
///
/// poses[index(t)] is valid for t over the time interval (t - time_interval, t]
/// and should be expected to updated continuously without synchronization
/// for the duration of that interval. If a single pose value is needed for
/// multiple non-atomic operations a value should be latched and stored outside
/// the pose buffer.
///
/// Because the poses are not protected by any synchronization primitives it is
/// possible that when a pose is latched it will be only partially updated, and
/// the pose being read will contain some components from the pose before it is
/// updated and some components from the updated pose. The safety of using these
/// "torn" poses relies on two things:
///
/// 1) Sequential poses written to poses[index(t)] are very similar to each
/// other numerically, so that if some components are taken from the first and
/// some are taken from another the result is numerically similar to both
///
/// 2) The space of positions and quaternions is locally flat at the scale of
/// changes between sequential updates, which guarantees that two poses which
/// are numerically similar also represent semantically similar poses (i.e.
/// there are no discontinuities which will cause a small numerical change in
/// the position or quaterninon to cause a large change in the encoded pose)
/// For positions this is guaranteed because Scenic uses a Euclidean 3-space
/// which is globally flat and for quaternions this is guaranteed because
/// quaternions encode rotation as points on a unit 4-sphere, and spheres are
/// locally flat. For more details on the encoding of rotations in quaterions
/// see https://en.wikipedia.org/wiki/Quaternions_and_spatial_rotation
///
/// This commanderation is intended for late latching camera pose to support
/// low-latency motion-tracked rendering.
type SetCameraPoseBufferCmd = struct {
    camera_id uint32;
    buffer_id uint32;
    num_entries uint32;
    base_time int64;
    time_interval uint64;
};

/// Sets the color of the Light identified by `light_id`.
type SetLightColorCmd = struct {
    light_id uint32;
    color ColorRgbValue;
};

/// Sets the direction of the DirectionalLight identified by `light_id`.
type SetLightDirectionCmd = struct {
    light_id uint32;
    direction Vector3Value;
};

/// DEPRECATED
/// Adds the light specified by `light_id` specified by `light_id` to the scene
/// identified by `scene_id`.
type AddLightCmd = struct {
    scene_id uint32;
    light_id uint32;
};

/// Detach the light specified by `light_id` from the scene that it is attached
/// to, if any.
type DetachLightCmd = struct {
    light_id uint32;
};

/// Detach all lights from the scene specified by `scene_id`.
type DetachLightsCmd = struct {
    scene_id uint32;
};

/// Sets/clears a material's texture.
///
/// Constraints:
/// - `material_id` refs a `Material`.
/// - `texture_id` refs a `Image`, `ImagePipe2`, or nothing.
///
/// If no texture is provided (i.e. `texture_id` is zero), a solid color is used.
/// If a texture is provided, then the value sampled from the texture is
/// multiplied by the color.
type SetTextureCmd = struct {
    material_id uint32;
    texture_id uint32; // Refers to an Image resource.  May be zero (no texture).
};

/// Sets a material's color.
///
/// Constraints:
/// - `material_id` refs a `Material`.
///
/// If a texture is set on the material, then the value sampled from the texture
/// is multiplied by the color.
type SetColorCmd = struct {
    material_id uint32;
    color ColorRgbaValue;
};

/// Set a mesh's indices and vertices.
///
/// `mesh_id` refs the Mesh to be updated.
/// `index_buffer_id` refs a Buffer that contains the mesh indices.
/// `index_format` defines how the index buffer data is to be interpreted.
/// `index_offset` number of bytes from the start of the index Buffer.
/// `index_count` number of indices.
/// `vertex_buffer_id` refs a Buffer that contains the mesh vertices.
/// `vertex_format` defines how the vertex buffer data is to be interpreted.
/// `vertex_offset` number of bytes from the start of the vertex Buffer.
/// `vertex_count` number of vertices.
/// `bounding_box` must contain all vertices within the specified range.
///
/// The MeshVertexFormat defines which per-vertex attributes are provided by the
/// mesh, and the size of each attribute (and therefore the size of each vertex).
/// The attributes are ordered within the vertex in the same order that they
/// appear within the MeshVertexFormat struct.  For example, if the values are
/// kVector3, kNone and kVector2, then:
///   - each vertex has a position and UV-coordinates, but no surface normal.
///   - the 3D position occupies bytes 0-11 (3 dimensions * 4 bytes per float32).
///   - the UV coords occupy bytes 12-19, since no surface normal is provided.
type MeshIndexFormat = strict enum {
    // TODO(fxbug.dev/23519): only kUint32 is currently supported.
    kUint16 = 1;
    kUint32 = 2;
};

type MeshVertexFormat = struct {
    /// kVector2 or kVector3.
    position_type ValueType;
    /// kVector2 or kVector3 (must match position_type), or kNone.
    normal_type ValueType;
    /// kVector2 or kNone.
    tex_coord_type ValueType;
};

type BindMeshBuffersCmd = struct {
    mesh_id uint32;
    index_buffer_id uint32;
    index_format MeshIndexFormat;
    index_offset uint64;
    index_count uint32;
    vertex_buffer_id uint32;
    vertex_format MeshVertexFormat;
    vertex_offset uint64;
    vertex_count uint32;
    bounding_box BoundingBox;
};

/// Add a layer to a layer stack.
/// Constraints:
/// - `layer_stack_id` refs a `LayerStack`.
/// - `layer_id` refs a `Layer`.
/// - The layer must not already belong to a different stack; it must first be
///   detached.
type AddLayerCmd = struct {
    layer_stack_id uint32;
    layer_id uint32;
};

/// Remove a layer from a layer stack.
/// Constraints:
/// - `layer_stack_id` refs a `LayerStack`.
/// - `layer_id` refs a `Layer`.
/// - The layer must belong to this stack.
type RemoveLayerCmd = struct {
    layer_stack_id uint32;
    layer_id uint32;
};

/// Remove all layers from a layer stack.
/// Constraints
/// - `layer_stack_id` refs a `LayerStack`.
type RemoveAllLayersCmd = struct {
    layer_stack_id uint32;
};

/// Set a compositor's layer stack, replacing the current stack (if any).
/// Constraints:
/// - `compositor_id` refs a `DisplayCompositor`.
/// - `layer_stack_id` refs a `LayerStack`.
type SetLayerStackCmd = struct {
    compositor_id uint32;
    layer_stack_id uint32;
};

/// Set a layer's renderer, replacing the current renderer (if any).
/// Constraints:
/// - `layer_id` refs a `Layer`.
/// - `renderer_id` refs a `Renderer`.
type SetRendererCmd = struct {
    layer_id uint32;
    renderer_id uint32;
};

/// Sets a parameter that affects how a renderer renders a scene.
///
/// `renderer_id` refs the Renderer that is being modified.
/// `param` describes the parameter that should be set, and to what.
type SetRendererParamCmd = struct {
    renderer_id uint32;
    param RendererParam;
};

/// Sets which events a resource should deliver to the session listener.
/// This command replaces any prior event mask for the resource.
///
/// The initial event mask for a resource is zero, meaning no events are
/// reported.
///
/// Constraints:
/// - `resource_id` is a valid resource id
/// - `event_mask` is zero or a combination of `k*EventMask` bits OR'ed together.
type SetEventMaskCmd = struct {
    id uint32;
    event_mask uint32;
};

/// Maximum length for a resource label.
const kLabelMaxLength uint32 = 32;

/// Sets/clears a label to help developers identify the purpose of the resource
/// when using diagnostic tools.
///
/// The label serves no functional purpose in the scene graph.  It exists only
/// to help developers understand its structure.  The scene manager may truncate
/// or discard labels at will.
///
/// Constraints:
/// - The label's maximum length is `kLabelMaxLength` characters.
/// - Setting the label to an empty string clears it.
type SetLabelCmd = struct {
    id uint32;
    label string;
};

/// Set whether clipping should be disabled for the specified renderer.  For a
/// newly-created renderer, clipping will NOT be disabled (i.e. it will be
/// enabled).
///
/// NOTE: this disables visual clipping only; objects are still clipped for the
/// purposes of hit-testing.
///
/// `renderer_id` refs the target renderer.
/// `disable_clipping` specifies whether the clipping should be disabled.
type SetDisableClippingCmd = struct {
    renderer_id uint32;
    disable_clipping bool;
};

// TODO(fxbug.dev/24238): Remove this.
type SetImportFocusCmdDEPRECATED = struct {};

/// Sets the list of clip planes that apply to a Node and all of its children.  Replaces
/// the list set by any previous SetClipPlanesCmd.
///
/// - `node_id` refs a `Node` with the has_clip characteristic.
/// - `clip_planes` is the new list of oriented clip planes.
type SetClipPlanesCmd = struct {
    node_id uint32;
    clip_planes vector<Plane3>;
};

/// Sets the position of the PointLight identified by `light_id`.
type SetPointLightPositionCmd = struct {
    light_id uint32;
    position Vector3Value;
};

/// Sets the falloff factor of the PointLight identified by `light_id`.
/// A value of 1.0 corresponds to the physically-based "inverse-square law"
/// (see Wikipedia).  Other values can be used for artistic effect, e.g. a
/// value of 0.0 means that the radiance of a surface is not dependant on
/// its distance from the light.
///
// TODO(fxbug.dev/23755): need to formalize the units of light intensity and distance used
// to compute fall-off.  Currently the unit is pips; consequently a falloff of 1.0
// causes light to attenuate far too rapidly.  Meters would be more appropriate.
type SetPointLightFalloffCmd = struct {
    light_id uint32;
    falloff FloatValue;
};

/// Adds the light specified by `light_id` specified by `light_id` to the scene
/// identified by `scene_id`.
type SceneAddAmbientLightCmd = struct {
    scene_id uint32;
    light_id uint32;
};

/// Adds the light specified by `light_id` specified by `light_id` to the scene
/// identified by `scene_id`.
type SceneAddDirectionalLightCmd = struct {
    scene_id uint32;
    light_id uint32;
};

/// Adds the light specified by `light_id` specified by `light_id` to the scene
/// identified by `scene_id`.
type SceneAddPointLightCmd = struct {
    scene_id uint32;
    light_id uint32;
};

/// Set the color conversion applied to the compositor's display.
/// The conversion is applied to to each pixel according to the formula:
///
/// (matrix * (pixel + preoffsets)) + postoffsets
///
/// where pixel is a column vector consisting of the pixel's 3 components.
///
/// `matrix` is passed in row-major order. Clients will be responsible
/// for passing default values, when needed.
/// Default values are not currently supported in fidl.
/// Default Values:
///   preoffsets = [0 0 0]
///   matrix = [1 0 0 0 1 0 0 0 1]
///   postoffsets = [0 0 0]
type SetDisplayColorConversionCmdHACK = struct {
    compositor_id uint32;
    preoffsets array<float32, 3>;
    matrix array<float32, 9>;
    postoffsets array<float32, 3>;
};

/// Depending on the device, the display might be rotated
/// with respect to what the lower level device controller
/// considers the physical orientation of pixels. The
/// compositors and layers must be in alignment with the
/// underlying physical orientation which means that for
/// certain operations like screenshotting, they cannot
/// provide results with the accurate orientation unless
/// they have information about how the higher-level display
/// is orienting the screen. The only legal values for the
/// rotation are 0, 90, 180, and 270, which are each
///  applied counterclockwise.
type SetDisplayRotationCmdHACK = struct {
    compositor_id uint32;
    rotation_degrees uint32;
};

// Enable (or disable) debug wireframe rendering for the specified
// view and its immediately embedded views (i.e. any view whose
// nearest ancestor view is this one).
type SetEnableDebugViewBoundsCmd = struct {
    view_id uint32;
    enable bool;
};

// This command determines the color to be set on a view holders
// debug wireframe bounding box.
type SetViewHolderBoundsColorCmd = struct {
    view_holder_id uint32;
    color ColorRgbValue;
};

// This command sets the minimum RGB value for all displays, which
// all pixel values are clamped to.
type SetDisplayMinimumRgbCmdHACK = struct {
    min_value uint8;
};