// Copyright 2021 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.composition;

using fuchsia.math;
using fuchsia.scenic.scheduling;
using fuchsia.ui.pointer;
using fuchsia.ui.views;
using zx;

/// The set of error codes returned in [`OnError`]. Everything except NO_ERROR, causes Flatland
/// channel to be closed.
type FlatlandError = strict enum {
    /// Indicates that the parameters used the function calls are invalid.
    BAD_OPERATION = 1;
    /// Indicates that `additional_present_credits` field was not properly processed and the client
    /// queued more [`Present`]s than allowed.
    NO_PRESENTS_REMAINING = 2;
    /// Indicates that the client has overwritten hanging gets in the protocols returned.
    BAD_HANGING_GET = 3;
};

type Orientation = strict enum {
    CCW_0_DEGREES = 1;
    CCW_90_DEGREES = 2;
    CCW_180_DEGREES = 3;
    CCW_270_DEGREES = 4;
};

/// The set of possible blending functions to choose from when determining how an image should
/// be composited on top of other images.
type BlendMode = strict enum {
    /// Indicates that the source pixels replace the destination pixels. In other words,
    /// the source pixels are treated as opaque, regardless of what alpha values are set.
    SRC = 1;
    /// The source pixels are drawn over the destination pixels. The final pixel color
    /// that is displayed is calculated as: C_src + (1.0 - alpha_src) * C_dst).
    SRC_OVER = 2;
};

type ColorRgba = struct {
    red float32;
    green float32;
    blue float32;
    alpha float32;
};

/// The return type of [`GetLayout`]. This table contains most of the information necessary
/// for a client to decide how to layout their content in a Flatland instance. This data may be
/// provided to the client before the command that creates the View is presented, so that the
/// client may lay out content properly before their first call to [`Present`].
type LayoutInfo = table {
    /// The layout size of a View in logical pixels, defined by the parent's call to
    /// [`SetViewportProperties`]. Clients should re-layout their content when this value changes.
    1: logical_size fuchsia.math.SizeU;
    /// The ratio from physical display pixels to logical pixels, defined by the sizes and scale
    /// transforms of the parent: each logical pixel is displayed on-screen by one or more physical
    /// pixels, as determined by this scale.  Clients should not necessarily re-layout their content
    /// when this value changes.
    2: pixel_scale fuchsia.math.SizeU;
};

/// ParentViewportWatchers will be informed when they are actively attached to a output display
/// (either directly, or through a chain of parent Viewports) and when they are not. Until they are
/// connected to a display, some pieces of information (such as pixel scale) may be unavailable.
type ParentViewportStatus = strict enum {
    CONNECTED_TO_DISPLAY = 1;
    DISCONNECTED_FROM_DISPLAY = 2;
};

/// A protocol that provides information about the parent Viewport attached to a Flatland instance's
/// sole View.  Although Flatland instances can have at most one view, it is possible to have
/// multiple ParentViewportWatchers during the brief transition period when replacing the instance's
/// View with another, e.g. via [`CreateView`].  During this period, certain updates may be
/// duplicated and sent to each ParentViewportWatcher connection.
///
/// A ParentViewportWatcher will remain connected as long as the corresponding parent Viewport
/// exists; the connection will also be closed if the parents's ViewportCreationToken is dropped
/// without using it to create a Viewport.
protocol ParentViewportWatcher {
    /// A hanging get for receiving layout information. Clients may receive layout information
    /// before the ParentViewportWatcher operation has been presented. This allows children to
    /// layout their content before their first call to [`Present`]. In transition cases where two
    /// ParentViewportWatcher channels exist at the same time, both protocol instances will be
    /// receiving different layout information.
    ///
    /// This hanging get will only fire when the LayoutInfo is different than the previously
    /// returned LayoutInfo. Note that, since LayoutInfo is a table, only some fields may have
    /// changed.
    ///
    /// It is invalid to call `GetLayout` while a previous call is still pending. Doing so will
    /// cause both this channel and the Flatland channel that handed out ParentViewportWatcher to be
    /// closed.
    GetLayout() -> (struct {
        info LayoutInfo;
    });

    /// A hanging get for receiving the status of the parent Viewport. This provides global
    /// connectivity information to the child.
    ///
    /// This hanging get will only fire when the ParentViewportStatus is different than the
    /// previously returned ParentViewportStatus.
    ///
    /// It is invalid to call `GetStatus` while a previous call is still pending. Doing so will
    /// cause both this channel and the Flatland channel that handed out ParentViewportWatcher to be
    /// closed.
    GetStatus() -> (struct {
        status ParentViewportStatus;
    });
};

type ChildViewStatus = strict enum {
    /// The underlying Flatland instance has connected its View, called [`Present`], and the
    /// acquisition fences of the [`Present`] call have all be reached, indicating that it has some
    /// content ready to be displayed, and NOT that the child content has actually been shown on the
    /// screen (a common use case is for the parent to wait for the child content to be ready before
    /// attaching the child to the global scene graph).
    // TODO(fxbug.dev/87800): rename to CONTENT_IS_AVAILABLE.
    CONTENT_HAS_PRESENTED = 1;
};

/// A protocol that provides information about a particular child View which is attached to the
/// Viewport owned by the parent client; connections to this protocol are estabished in
/// [`CreateViewport`].  Since a Flatland instance may contain any number of Viewports, each of
/// which may or may not be attached to a transform, the client can maintain connections to an
/// equal number of ChildViewWatcher instances.
///
/// Each ChildViewWatcher instance will remain connected as long as the corresponding child View
/// exists; the connection will also be closed if the child's ViewCreationToken is dropped without
/// using it to create a View.
protocol ChildViewWatcher {
    /// A hanging get for receiving the status of a View. This provides information to the parent,
    /// such as whether or not the child has successfully presented content through this View.
    ///
    /// This hanging get will only fire when the ChildViewStatus is different than the previously
    /// returned ChildViewStatus.  This can happen immediately, and even if the creator of the
    /// Viewport hasn't yet called Present() after calling CreateViewport().  This allows the parent
    /// to know that the child has content ready to display before the parent modifies their own
    /// local scene graph to incorporate the child content.
    ///
    /// It is invalid to call `GetStatus` while a previous call is still pending. Doing so will
    /// cause both this channel and the Flatland channel that handed out ChildViewWatcher to be
    /// closed.
    GetStatus() -> (struct {
        status ChildViewStatus;
    });

    /// Hanging get to receive the ViewRef of the child View. This will only fire when the View ref
    /// is different from the previously-returned View ref. Note: currently the View ref will not
    /// change after it is first received, but this will change if/when the API changes to allow
    /// relinking of views.
    ///
    /// The ViewRef is not returned until the View is included in the View tree, in other words when
    /// there is a chain of ancestor transforms all the way back up to the root of the scene graph,
    /// i.e. the display.
    ///
    /// It is invalid to call `GetViewRef` while a previous call is still pending. Doing so will
    /// cause both this channel and the Flatland channel that handed out ChildViewWatcher to be
    /// closed.
    ///
    /// A `GetViewRef` call will hang if the View was created using `CreateView`, but returns the
    /// View if the View was created using CreateView2. This is because `CreateView` does not mint
    /// a ViewRef for that View.
    GetViewRef() -> (resource struct {
        view_ref fuchsia.ui.views.ViewRef;
    });
};

/// The properties of a Viewport as defined by the parent. This data, along with the set of attached
/// Transforms, will be used to compute the LayoutInfo for the View of the Viewport.
/// `ViewportProperties` must have `logical_size` set at least once. This is the initial size that
/// will drive the layout of the child.
type ViewportProperties = table {
    /// The size of the Viewport in logical pixels. This maps directly to the logical_size field in
    /// LayoutInfo.
    1: logical_size fuchsia.math.SizeU;
};

/// The properties of an Image as defined by the client. These properties determine how an Image
/// uses the backing BufferCollection. See [`CreateImage`] for more information.
type ImageProperties = table {
    /// The size of the Image in pixels.
    1: size fuchsia.math.SizeU;
};

/// A user-defined identifier for a particular transform. See [`CreateTransform`] and
/// [`ReleaseTransform`] for more information.
type TransformId = struct {
    value uint64;
};

/// A user-defined identifier for a particular piece of Content. See Content creation functions
/// (e.g. [`CreateViewport`], [`CreateImage`]) for more information.
type ContentId = struct {
    value uint64;
};

// A maximum of 16 fences is enough for the current usage of these APIs.
const MAX_PRESENT_ARGS_FENCE_COUNT int32 = 16;
// TODO(fxbug.dev/85551): delete.
const MAX_ACQUIRE_RELEASE_FENCE_COUNT int32 = 16;

/// Arguments passed into [`Present`]. All arguments are optional, and if an
/// argument is omitted Flatland will use a reasonable default, specified below.
type PresentArgs = resource table {
    /// `requested_presentation_time` specifies the time on or after which the client would like the
    /// enqueued operations to take visible effect (light up pixels on the screen), expressed in
    /// nanoseconds in the `CLOCK_MONOTONIC` timebase.
    ///
    /// The default `requested_presentation_time` is 0.
    ///
    /// Using a `requested_presentation_time` in the present or past (such as 0) schedules enqueued
    /// operations to take visible effect as soon as possible, during the next frame to be prepared.
    ///
    /// Using a `requested_presentation_time` in the future schedules the enqueued operations to
    /// take visible effect on or as closely as possible after the stated time, but no earlier.
    ///
    /// Each rendered frame has a target presentation time. This is when Flatland aims to have the
    /// frame presented to the user. Before rendering a frame, Flatland applies all
    /// enqueued operations associated with all squashable calls to [`Present`] whose
    /// `requested_presentation_time` is on or before the frame's target presentation time.
    ///
    1: requested_presentation_time zx.time;

    /// Flatland will wait until all of a Flatland instance's `acquire_fences` are ready before it
    /// will execute the presented commands. Not signaling `acquire_fences` will block the current
    /// [`Present`] as well as the following ones even if their `acquire_fences` are signaled.
    ///
    /// The default `acquire_fences` value is the empty vector.
    // TODO(fxbug.dev/85551): delete.
    2: acquire_fences vector<zx.handle:EVENT>:MAX_PRESENT_ARGS_FENCE_COUNT;

    /// Flatland will signal all `release_fences` when the resources and shared buffers from this
    /// [`Present`] are no longer in use. Callers should not modify shared resources, such as
    /// BufferCollections, until after these fences are signaled.
    ///
    /// If an error occurs, release fences are not necessarily fired as Flatland can close the
    /// client's instance at any point.
    ///
    /// The default `release_fences` value is the empty vector.
    // TODO(fxbug.dev/85551): delete.
    3: release_fences vector<zx.handle:EVENT>:MAX_PRESENT_ARGS_FENCE_COUNT;

    /// If `unsquashable` is true, then the update is guaranteed to be uniquely shown for at
    /// least one vsync interval.
    ///
    /// If `unsquashable` is false, then the update can be combined with those that come after
    /// it.
    ///
    /// If absent, `unsquashable` is false.
    4: unsquashable bool;

    /// Flatland will wait until all of a Flatland instance's `server_wait_fences` are ready before
    /// it will execute the presented commands. Not signaling `server_wait_fences` will block the
    /// current [`Present`] as well as the following ones even if their `server_wait_fences` are
    /// signaled.
    ///
    /// The default `server_wait_fences` value is the empty vector.
    // TODO(fxbug.dev/85551): change ordinal to 2.
    5: server_wait_fences vector<zx.handle:EVENT>:MAX_PRESENT_ARGS_FENCE_COUNT;

    /// (read this one carefully, it may be counter-intuitive)
    ///
    /// Flatland will signal all `server_signal_fences` when the resources and shared buffers from
    /// *the previous* [`Present`] are no longer in use. Callers should not modify shared resources,
    /// such as BufferCollections, until after these fences are signaled. Otherwise, there may be
    /// graphical artifacts such as tearing, caused by the client modifying content which is still
    /// visible on screen.
    ///
    /// The following example explains why the fences correspond to the previous frame's resources,
    /// not the current frame.  Consider an app which uses a separate image for a pop-up dialog,
    /// which will disappear immediately if the user taps elsewhere.  The app cannot tell whether
    /// the image will be removed next frame because, if this happens, it will be due to user input
    /// which has not yet occurred.  Since the image will probably continue to be presented next
    /// frame, it wouldn't make sense to provide a fence this frame.
    ///
    /// If an error occurs, Flatland may close the channel without signaling these fences.  Clients
    /// may immediately release shared buffers, but they should not immediately modify such buffers,
    /// because they may still be displayed on screen.  There is currently no good signal available
    /// to the client about when it is safe to reuse shared buffers.
    ///
    /// The default `server_signal_fences` value is the empty vector.
    // TODO(fxbug.dev/85551): change ordinal to 3.
    // TODO(fxbug.dev/85563): when fixed, update documentation re: when it is safe to modify buffers
    //                        upon channel closure.
    6: server_signal_fences vector<zx.handle:EVENT>:MAX_PRESENT_ARGS_FENCE_COUNT;
};

/// A user-defined identifier for future presentation info. A maximum of 8
/// future presentation counts is enough for the current usage of these APIs.
alias FuturePresentationInfos = vector<fuchsia.scenic.scheduling.PresentationInfo>:8;

/// Fields that a client needs in order to produce its next frame, returned in
/// [`OnNextFrameBegin`]. Each field is guaranteed to be  set and contain valid information.
type OnNextFrameBeginValues = table {
    /// The number of *additional* [`Present`] calls allowed to the client so that they
    /// can call [`Present`] further times. This is a delta in the present
    /// credit budget, not the absolute number of present credits.
    1: additional_present_credits uint32;
    /// Information about future presentation and latch times that a client may aim for
    /// precise scheduling behavior.
    2: future_presentation_infos FuturePresentationInfos;
};

/// The protocol endpoints bound to a Flatland ViewCreationToken. These protocols operate on the
/// View that ViewCreationToken created in the Flatland session.
type ViewBoundProtocols = resource table {
    /// Learn when a View gains focus.
    ///
    /// Server-bound ViewRef. The [`view_ref_focused`] client does not specify the ViewRef
    /// explicitly; instead, the server implementation uses the ViewRef used in View creation for
    /// reporting focus movement on/off this View.
    1: view_ref_focused server_end:fuchsia.ui.views.ViewRefFocused;

    /// Enable a View to request focus transfer to a child (target) View.
    ///
    /// Server-bound ViewRef. The [`view_focuser`] client does not specify the "requestor" ViewRef
    /// explicitly, only the "target" ViewRef. Instead, the server implementation uses the ViewRef
    /// used in View creation as the "requestor" ViewRef.
    2: view_focuser server_end:fuchsia.ui.views.Focuser;

    /// Receive touch events that are associated with a View.
    3: touch_source server_end:fuchsia.ui.pointer.TouchSource;

    /// Receive mouse events that are associated with a View.
    4: mouse_source server_end:fuchsia.ui.pointer.MouseSource;
};

/// A maximum of 64 hit regions is enough for the expected usage of these APIs.
const MAX_HIT_REGION_COUNT int32 = 64;

/// The kind of hit test interaction expected for a hit region.
type HitTestInteraction = flexible enum : uint8 {
    /// The natural default behavior is for a hit region to interact with both regular hit testing
    /// and accessibility hit testing.
    DEFAULT = 0;

    /// Some use cases require that a hit region to interact with regular hit testing, but not
    /// interact with accessibility hit testing. Here, "semantics" refers to accessibility's
    /// semantic tree data, which describes UI elements in a View.
    SEMANTICALLY_INVISIBLE = 1;
};

/// An interactive area of a View, placed in the coordinate space of a specific Transform.
type HitRegion = struct {
    /// The position and size of this hit region, in the coordinate space of the Transform that owns
    /// this hit region.
    region fuchsia.math.RectF;

    /// The interaction behavior specified for this hit region.
    /// To specify "no interaction at all", remove this hit region from the owning Transform.
    hit_test HitTestInteraction;
};

/// Each Flatland instance contains a Graph, which consists of a set of objects, and the
/// relationships between those objects. The client can specify a subset of those objects
/// (specifically, the directed acyclic graph starting at the root transform) to be presented as
/// content to some kind of output -- usually, a display.
///
/// Flatland Graphs are both hierarchical, and distributed. Graphs from different Flatland instances
/// may be connected together, allowing multiple processes to be involved in authoring content for a
/// particular output.
///
/// All functions in this protocol are feed-forward. The operations they represent are not fully
/// executed until [`Present`] is called.
@discoverable
protocol Flatland {
    /// Complete execution of all feed-forward operations.
    ///
    /// If executing an operation produces an error (e.g., CreateTransform(0)), an [`OnError`] event
    /// is emitted. Operations that produce errors are ignored and the channel is closed.
    ///
    /// If the execution is completed successfully, [`OnNextFrameBegin`] emits NO_ERROR along
    /// with other valid fields.
    ///
    /// The client may only call [`Present`] when they have a non-zero number of present credits,
    /// which are tracked by the server. The server may increment the number of credits when it
    /// fires the [`OnNextFrameBegin`] event, which informs the client when it receives additional
    /// present credits. Each [`Present`] call uses one present credit and decrements the server
    /// count by one. If the client calls [`Present`] with no present credits, the server will
    /// return a `NO_PRESENTS_REMAINING` error.
    ///
    /// The client should assume that prior to receiving any [`OnNextFrameBegin`] events, they have
    /// one present credit.
    ///
    /// Every [`Present`] call results in one [`OnNextFrameBegin`] event, and one
    /// [`OnFramePresented`] event, typically in that order.
    ///
    /// When the commands flushed by [`Present`] make it to display, an [`OnFramePresented`] event
    /// is fired. This event includes information pertaining to all [`Present`]s that had content
    /// that were part of that frame.
    ///
    /// See [`fuchsia.ui.composition/PresentArgs`] documentation above for more detailed information
    /// on what arguments are passed in and their role.
    Present(resource struct {
        args PresentArgs;
    });

    /// This event is fired when clients should expect minimal resource contention. Clients may use
    /// the timing of this event to begin their rendering work, using the information returned to
    /// inform their scheduling decisions.
    ///
    /// Importantly, OnNextFrameBegin is only fired when the client has one or more present credits,
    /// including what is returned in this event. It is therefore safe to present once every time
    /// this event fires.
    ///
    /// - response `values` the table of information a client needs to produce its next frame. See
    /// [`OnNextFrameBeginValues`] for more information.
    -> OnNextFrameBegin(struct {
        values OnNextFrameBeginValues;
    });

    /// This event is fired whenever a set of one or more [`Present`]s are presented simultaneously,
    /// and are therefore no longer in flight.
    ///
    /// This event signifies that the commands enqueued before the [`Present`] have taken effect in
    /// the scene graph, and are globally visible.
    ///
    /// Clients do NOT have to implement a handler for this event for basic frame scheduling, unless
    /// they explicitly want feedback on prior frame presentation. All future frame information is
    /// given in the [`OnNextFrameBegin`] event.
    ///
    /// TODO(fxbug.dev/63305): remove `num_presents_allowed` from this event.
    -> OnFramePresented(struct {
        frame_presented_info fuchsia.scenic.scheduling.FramePresentedInfo;
    });

    /// If an error occurs after a [`Present`], an `OnError` event will fire with associated
    /// information.
    ///
    /// FlatlandErrors will close the connection with the client.
    ///
    /// - response `error` the error a client may receive after performing some invalid operations.
    -> OnError(struct {
        error FlatlandError;
    });

    // ***** View management *****

    /// Two Flatland instances may be connected in a parent-child relationship. The parent endpoint
    /// is held in a Viewport, and the child endpoint is held in a View. The parent Flatland
    /// instance that creates a Viewport has control over how the child's View is integrated into
    /// its own View.
    ///
    /// The lifecycle of a parent-child connection starts with two endpoints of a channel object:
    /// a ViewportCreationToken and a ViewCreationToken. Out-of-band protocols pass the
    /// ViewportCreationToken to the parent, which calls [`CreateViewport`], and the
    /// ViewCreationToken to the child, which calls [`CreateView`].
    ///
    /// Only nodes connected to the Root Transform in this Flatland instance will be rendered into
    /// the parent's Viewport.
    ///
    /// Calling [`CreateView`] a second time will disconnect the Root Transform from the existing
    /// parent's Viewport, and attach it to a new parent's Viewport. In other words, each View can
    /// only have one parent.
    ///
    /// This function is queued, meaning that the Root Transform will not be attached to the
    /// parent Viewport until [`Present`] is called. However, clients will receive information
    /// through their ParentViewportWatcher (e.g., LayoutInfo) immediately after calling this
    /// function, even if they have not called [`Present`] or [`SetRootTransform`]. This allows
    /// clients to wait for layout information from their parent before calling [`Present`].
    ///
    /// Any illegal operations on ParentViewportWatcher will cause both ParentViewportWatcher
    /// channel and this Flatland channel to be torn down.
    ///
    /// Lifecycle note. The lifetime of the ParentViewportWatcher channel is bound by the peer
    /// ViewportCreationToken. When the ViewportCreationToken dies, this ParentViewportWatcher
    /// channel is destroyed.
    ///
    /// Views created using `CreateView` will not be associated with a ViewRef.
    CreateView(resource struct {
        token fuchsia.ui.views.ViewCreationToken;
        parent_viewport_watcher server_end:ParentViewportWatcher;
    });

    /// Identical to [`CreateView`], except it allows association of View identity (ViewRef) and
    /// view-bound protocols.
    @transitional
    CreateView2(resource struct {
        /// A typed wrapper for a channel, representing the child endpoint of the connection
        /// between two Flatland instances.
        token fuchsia.ui.views.ViewCreationToken;
        /// The ViewRef to strongly associate with [`token`].
        view_identity fuchsia.ui.views.ViewIdentityOnCreation;
        /// The protocol endpoints that are strongly bound to the ViewRef in [`view_identity`].
        /// The protocols are bound when the view is created and installed in the view tree.
        protocols ViewBoundProtocols;
        parent_viewport_watcher server_end:ParentViewportWatcher;
    });

    // ***** Transforms *****

    /// Creates a new Transform node. Transforms are a hierarchical piece of a Flatland graph. They
    /// can have children, and can reference Content. A sub-graph represented by a Transform and its
    /// descendants can be rendered to a display.
    ///
    /// Transforms are kept alive, even when released, as long as they are children of either an
    /// unreleased Transform, or the Root Transform.
    ///
    /// Each Transform can have a single piece of attached Content. Common types of Content include
    /// bitmaps, asynchronous streams of images, and Viewports to Views hosted in other Flatland
    /// instances.
    ///
    /// Transforms have attributes. Child Transforms inherit the combined attributes of their
    /// parents. Content attached to a Transform is also affected by that Transform's attributes.
    ///
    /// When a sub-graph of Transforms is rendered, Content will be rendered back-to-front, starting
    /// with the Content on the root transform, and continuing recursively through all of its child
    /// Transforms in the order the children were added. See [`AddChild`] for more information.
    ///
    /// Zero is not a valid transform id. All other values are valid, assuming they are not already
    /// in use (see [`ReleaseTransform`] for more details).
    CreateTransform(struct {
        transform_id TransformId;
    });

    // ***** Transform Attributes *****

    /// All Transform objects support all attributes.
    ///
    /// Geometric attributes are applied in the following order:
    /// 1. Scale (relative to the parent transform's coordinate space)
    /// 2. Orientation (relative to the parent transform's coordinate space)
    /// 3. Translation (relative to the parent transforms's coordinate space,
    ///    unaffected by scale applied to the current transform).
    /// 4. Clipping (relative to the current transform's coordinate space)
    ///
    /// The effects of each of these attributes are cumulative. This means the transform's position
    /// in the view space, and its clip boundary, will be calculated based on that chain of
    /// geometric attributes going up to the root transform.
    ///
    /// For instance, in a nested hierarchy such as the following:
    ///     [Root-Transform -> Transform1 -> Transform2 -> CurrentTransform]
    /// If Transform1 is translated by [2,0] and Transform2 is translated by [0,1] then the
    /// view-space position of CurrentTransform will be [2,1].
    ///
    /// Sets the translation on a Transform. The order of geometric attribute application is
    /// addressed above.
    SetTranslation(struct {
        transform_id TransformId;
        translation fuchsia.math.Vec;
    });

    /// Sets the orientation on a Transform. The order of geometric attribute application is
    /// addressed in the documentation for [`SetTranslation`].
    SetOrientation(struct {
        transform_id TransformId;
        orientation Orientation;
    });

    /// Sets the scale on a transform. The order of geometric attribute application is
    /// addressed above. The (x,y) values in the VecF |scale| refer to the scale factor in the
    /// x-axis (width) and y-axis (height) respectively. Scale values must be normal 32-bit
    /// floating point values: https://en.wikipedia.org/wiki/Normal_number_%28computing%29
    SetScale(struct {
        transform_id TransformId;
        scale fuchsia.math.VecF;
    });

    /// Sets an opacity in linear space to be applied to a transform and its descendents,
    /// which include other transforms and content. Opacity values must be in the range
    /// of [0.0, 1.0], where 0.0 is completely transparent and 1.0 is completely opaque.
    /// Attempting to call this function with values outside that range will result in
    /// an error. A transform's opacity value is multiplied with that of its parent. This
    /// effect works differently from group opacity. Using group opacity, child nodes are
    /// rendered together first, and then have the parent's opacity applied as a post-effect.
    /// Here, opacity is applied to each child individually. This may result in a very
    /// different effect.
    SetOpacity(struct {
        transform_id TransformId;
        value float32;
    });

    /// Sets the bounds, expressed in the local coordinate space of the transform, that
    /// constrains the region that content attached to this transform can be rendered to.
    /// If the content's area exceeds the clip bounds, the area outside the bounds will
    /// not be rendered. These bounds are valid for all children of this transform node as
    /// well, which includes nested Flatland instances and their node hierarchies.
    /// If a child transform attempts to set clip bounds larger than that of its parent,
    /// it will be clipped to the parent's clip bounds. The default state is for a transform
    /// to be unclipped, meaning it will not have any bounds placed on its render region.
    /// The clip width/height must be positive. Negative values will result in an error.
    /// Passing in an empty box to the |rect| parameter will remove the clip bounds.
    SetClipBoundary(struct {
        transform_id TransformId;
        rect box<fuchsia.math.Rect>;
    });

    // ***** Transform management *****

    /// Adds a child Transform to a parent Transform. The new child Transform, and any Content
    /// attached to it or its children, will be rendered on top of the parent's Content, as well as
    /// any previously added children.
    AddChild(struct {
        parent_transform_id TransformId;
        child_transform_id TransformId;
    });

    /// Removes a child Transform from a parent Transform.
    RemoveChild(struct {
        parent_transform_id TransformId;
        child_transform_id TransformId;
    });

    /// Sets the Root Transform for the graph.
    ///
    /// The sub-graph defined by the Root Transform and its children will be rendered as View
    /// in the connected parent's Viewport (see [`CreateView`]). Any parents of the Root Transform
    /// in this Graph will be ignored.
    ///
    /// The Root Transform, and all children of the Root Transform, are kept alive if they are
    /// released (see [`ReleaseTransform`] for more details).
    ///
    /// There is only ever one Root. Since 0 is not a valid transform id (see [`CreateTransform`]),
    /// calling SetRootTransform(0) clears the current Root, destroying any previously released
    /// objects that are not referenced by the new root.
    ///
    /// Setting the root transform installs a full screen hit region on the root transform. Clients
    /// may remove this hit region if they don't want users to be able to interact with the root
    /// transform's content. For additional details on hit regions, see the [`SetHitRegions`]
    /// documentation.
    ///
    /// Default hit region rules
    ///
    ///   A default hit region follows these rules:
    ///   - When [`SetRootTransform`](T) is called, T receives a maximal hit region, covering the
    ///   entire view.
    ///   - If [`SetHitRegions`] is called on T, either before or after [`SetRootTransform`](T),
    ///   then no default hit region is active and the client specified hit regions are used.
    ///   - If a transform is no longer the root transform, i.e., [`SetRootTransform`](U) is
    ///   called, then the original transform no longer has its default hit region.
    ///   - Clients can remove or modify the root transform's hit regions the same way they would
    ///   reset any other transform's hit regions, by calling [`SetHitRegions`] with the appropriate
    ///   vector.
    SetRootTransform(struct {
        transform_id TransformId;
    });

    /// Sets the interactive areas for a Transform. By default, Content is not interactive; hit
    /// regions must be placed for a user to interact with the Content in a View. Because hit
    /// regions are described in the Flatland protocol, a Flatland instance can synchronize Content
    /// and hit regions.
    ///
    /// Each hit region is placed in the coordinate space of the owning Transform, and may or may
    /// not interact with different types of hit testing, depending on its [`HitTestInteraction`]
    /// type. When there are multiple hit regions that intersect with a hit test, the precedence
    /// rules given below dictate which hit region has interacted with the hit test. Only Transforms
    /// that transitively connect to the root Transform have their hit regions interact with a hit
    /// test.
    ///
    /// To reset a Transform to "no hit testing": send an empty vector.
    ///
    /// Note that root transforms get a default hit region installed by Flatland. For more details,
    /// see the [`SetRootTransform`] documentation.
    ///
    /// Precedence rules
    ///   Within a Transform, if multiple hit regions overlap, the hit test examines each
    ///   intersecting hit region for a possible interaction. Thus, for a regular hit test R and an
    ///   accessibility hit test A, where R and A both intersect two hit regions D ([`DEFAULT`]) and
    ///   S ([`SEMANTICALLY_INVISIBLE`]) on the same Transform, (1) R interacts with both D and S,
    ///   and (2) A only interacts with D. Generally, hit regions that overlap in a single Transform
    ///   can cause confusing behavior.
    ///
    ///   Within a View, for a given hit test, the front-most Transform's hit regions take
    ///   precedence over those behind. This follows the expected reverse "render order" of
    ///   Transforms (described in [`CreateTransform`]), where a user expects to interact with
    ///   Content that is visible, or front-most.
    ///
    ///   Across Flatland instances, for a given hit test, the front-most instance's front-most
    ///   Transform's hit regions take precedence over those behind. This follows the expected
    ///   reverse "render order" of views, where a user expects to interact with the View that is
    ///   visible, or front-most. For example, if a child View owns Content that is rendered over
    ///   the parent View, the user expects to interact with the child's Content.
    SetHitRegions(struct {
        transform_id TransformId;
        regions vector<HitRegion>:MAX_HIT_REGION_COUNT;
    });

    // ***** Content *****
    //
    // Content comes in many forms, but most content can be treated conceptually as a bitmap.
    // Content is attached to Transforms. Each Transform can have, at most, one piece of attached
    // Content. Content will inherit all of the attributes from its attached Transform (which
    // inherits the attributes of its parent Transform, and so on).
    //
    // Content is contained within a unit rectangle, with the top-left corner at the origin of the
    // coordinate space defined by the attached Transform.

    /// The Viewport and View pair, together, represent the connection between two Flatland
    /// instances. The Viewport is created in the parent, and the View is created in the child. The
    /// parent has control over how the child's View is integrated into its own View.
    ///
    /// Any illegal operations on ChildViewWatcher will cause both ChildViewWatcher channel and this
    /// Flatland channel to be torn down.
    ///
    /// `ViewportProperties` must have logical_size set. This is the initial size that will drive
    /// the layout of the child. The logical_size is also used as the default Content size, but
    /// subsequent changes to the logical_size will have no effect on the Content size.
    ///
    /// The logical_size must have positive X and Y components.
    ///
    /// Zero is not a valid ContentId. All other values are valid, assuming they are not already
    /// in use for another piece of Content (see [`ReleaseViewport`] for more details).
    ///
    /// Lifecycle note. The lifetime of the ChildViewWatcher channel is bound by the peer
    /// ViewCreationToken. When the ViewCreationToken dies, this ChildViewWatcher channel is
    /// destroyed.
    CreateViewport(resource struct {
        viewport_id ContentId;
        /// A typed wrapper for a channel, representing the parent endpoint of the connection
        /// between two Flatland instances.
        token fuchsia.ui.views.ViewportCreationToken;
        properties ViewportProperties;
        child_view_watcher server_end:ChildViewWatcher;
    });

    /// An Image is a bitmap backed by a specific VMO in a BufferCollection.
    ///
    /// Image creation requires an allocated BufferCollection registered with Allocator. This
    /// function will fail unless all clients of the specified BufferCollection have set their
    /// constraints.
    ///
    /// The Image must reference a valid VMO index and must have ImageProperties that fall within
    /// the constraints specified by the backing BufferCollection (i.e. width and height within a
    /// valid range, etc.)
    ///
    /// Zero is not a valid Image id. All other values are valid, assuming they are not already in
    /// use for another piece of Content (see [`ReleaseImage`] for more details).
    CreateImage(resource struct {
        image_id ContentId;
        import_token BufferCollectionImportToken;
        vmo_index uint32;
        properties ImageProperties;
    });

    /// This function is used to determine the region (in texel space) of an image that will be used
    /// by Flatland when rendering. The image to be sampled is referenced by [`image_id`] and the
    /// sample region is specified by [`rect`] which itself is comprised of an origin point (x,y) as
    /// well as a width and height, in unnormalized coordinates. It is illegal to call this function
    /// on non-image content, or to sample a region outside of the texel space of the image. In
    /// other words, the region specifed by [`rect`] must not exceed the ranges (0, image_width) and
    /// (0, image_height). If (rect.x + rect.width > image_width) or (rect.y + rect.height >
    /// image_height) or if any of the values are negative, this will result in an error.
    SetImageSampleRegion(struct {
        image_id ContentId;
        rect fuchsia.math.RectF;
    });

    /// The content size for an Image is the size of the rectangle in the parent's logical
    /// coordinate space that the image occupies. This combined with the global translation of the
    /// transform it is attached to determines the size and location of where the content is
    /// rendered on the display.
    SetImageDestinationSize(struct {
        image_id ContentId;
        size fuchsia.math.SizeU;
    });

    /// Determines the blend function to use when rendering the image specified by
    /// |image_id|. The image must be a valid image that was previously created with
    /// a call to |CreateImage|. For details on the different blend functions that are
    /// available, please refer to the BlendMode enum.
    SetImageBlendingFunction(struct {
        image_id ContentId;
        blend_mode BlendMode;
    });

    /// Sets an opacity in linear space to be applied to a flatland image. Opacity values must
    /// be in the range [0.0, 1.0].
    SetImageOpacity(struct {
        image_id ContentId;
        val float32;
    });

    /// Creates a solid-color rectangle. By default a filled-rect does not have a defined
    /// color or size. It is necessary to call |SetSolidFill| to specify a color and size
    /// before a filled rect can be used for rendering. Not doing so will result the
    // rectangle having a default size of (0,0) and so it will not show up when rendering.
    CreateFilledRect(resource struct {
        rect_id ContentId;
    });


    /// Defines the color and size of a filled rect. |rect_id| must refer to content that
    /// was created via a call to CreateFilledRect. The color is not premultiplied.
    SetSolidFill(resource struct {
        rect_id ContentId;
        color ColorRgba;
        size fuchsia.math.SizeU;
    });

    /// Automatically garbage collects the rectangle when it is no longer needed for
    /// rendering. |rect_id| must have been instantiated with a call to
    /// |CreateFilledRect|. Once released, the ID immediately goes out of scope and is free
    /// to be used again.
    ReleaseFilledRect(struct {
        rect_id ContentId;
    });

    // ***** Content management *****

    /// Setting a piece of Content on a Transform makes that Content visible in the render tree as
    /// long as the Transform is visible from the root Transform. The Content will be rendered
    /// before, and therefore "behind", any Content attached to the descendants of the Transform.
    ///
    /// Because each Transform can have, at most, a single piece of Content on it, calling this
    /// function on a Transform that already has Content will replace that Content.
    ///
    /// A Content may be set on more than one Transform.
    ///
    /// Calling this function with a Content id of 0 will remove any Content currently on the
    /// Transform.
    SetContent(struct {
        transform_id TransformId;
        content_id ContentId;
    });

    // ***** Content mutators *****

    /// Transforms are usually sufficient to change how Content is presented. Viewports, however,
    /// have special properties that are not part of the Transform hierarchy. Those properties can
    /// be set using this function.
    ///
    /// The logical_size must have positive X and Y components.
    SetViewportProperties(struct {
        viewport_id ContentId;
        properties ViewportProperties;
    });

    // ***** Cleanup operations *****

    /// Released Transforms will be garbage collected by the system once they are no longer
    /// necessary for rendering. For Transforms, this means there is no path from any unreleased
    /// Transform to the newly-released Transform.
    ///
    /// Once released, the id immediately goes out of scope for future function calls and can be
    /// reused when creating new Transforms.
    ///
    /// It is an error to call functions with a released id (unless that id has been reused to
    /// construct a new Transform).
    ReleaseTransform(struct {
        transform_id TransformId;
    });

    // Releases the View, which disconnects this Flatland instance from its parent Flatland
    // instance.
    //
    // To clear the existing content from the screen without releasing the current View, use
    // SetRootTransform(0) instead.
    //
    // Despite having a return type, this function is still feed-forward Like [`CreateView`] and
    // requires a call to [`Present`] to be executed. The ViewCreationToken will be returned after
    // the presented operations have been executed.
    // TODO(fxbug.dev/81576): Consider re-linking. We can return the ViewCreationToken used to
    // establish the View. This token can then be used to establish a new View with the parent
    // Viewport.
    ReleaseView();

    /// Releases a Viewport from the scene, even if the Viewport is still connected to a Transform.
    /// Unlike other resources, Viewports are garbage collected by the system during the next
    /// [`Present`] because a removed Viewport is guaranteed to provide no renderable content.
    ///
    /// Use SetContent(transform_id, 0) to clean up references to released Viewports.
    ///
    /// Despite having a return type, this function is still feed-forward like [`CreateView`] and
    /// requires a call to [`Present`] to be executed. The ViewportCreationToken will be returned
    /// after the presented operations have been executed.
    ReleaseViewport(struct {
        viewport_id ContentId;
    }) -> (resource struct {
        token fuchsia.ui.views.ViewportCreationToken;
    });

    /// Released Images will be garbage collected by the system once they are no longer necessary
    /// for rendering. For Images, this means the Image is no longer attached to any Transform and
    /// any pending rendering that references the Image is complete.
    ///
    /// Use SetContent(transform_id, 0) to clean up references to released Images.
    ///
    /// Once released, the id immediately goes out of scope for future function calls and can be
    /// reused when creating new Images.
    ///
    /// It is an error to call functions with a released id (unless that id has been reused to
    /// construct a new Image).
    ReleaseImage(struct {
        image_id ContentId;
    });

    /// This function will reset all state on this interface. This includes destroying all existing
    /// View and Viewports without returning the associated Token to the caller.
    Clear();

    // ***** Debug operations *****

    /// Set debug name of the current client that can be used by Flatland to print as a prefix to
    /// logs to help client distinguish what is theirs. [`name`] can be an arbitrary string, but the
    /// current process name (see fsl::GetCurrentProcessName()) is a good default.
    SetDebugName(struct {
        name string:64;
    });
};

// TODO(fxbug.dev/76643):  In the future this will be replaced with something
// that allows control over which hardware display to use.  This API is sufficient for the purpose
// of initial bringup of Flatland.
/// This API connects to the singleton "primary display", and allows a tree of Flatland content to
/// be attached underneath.  Only one FlatlandDisplay client connection is allowed at one time.
@discoverable
protocol FlatlandDisplay {
    // TODO(fxbug.dev/76643): Consider whether this should be:
    //   SetContent(ViewportCreationToken token) -> (ViewportCreationToken? previous_token);
    // ... this way, whoever is using the display can keep track of multiple different pieces
    // of content, and choose which to display.  OTOH, an argument could be made that this API
    // should be kept as simple as possible, and if one wanted to do this sort of thing they should
    // create their own Flatland instance and do the content management there.
    SetContent(resource struct {
        token fuchsia.ui.views.ViewportCreationToken;
        child_view_watcher server_end:ChildViewWatcher;
    });
};