blob: 4ae5bc48dc58d60ff09d70b951f556785c2b932b [file] [log] [blame]
// Copyright 2019 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.scenic.internal;
// The set of error codes returned by Flatland::Present().
enum Error {
// TODO(36766): Unify with math types for other APIs.
struct Vec2 {
float32 x;
float32 y;
/// The return type of GraphLink::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 Link is presented, so that the client
/// may lay out content properly before their first call to Present().
table LayoutInfo {
/// The layout size of a Graph in logical pixels, defined by the parent’s call to
/// SetLinkProperties(). Clients should re-layout their content when this value changes.
1: Vec2 logical_size;
/// A protocol that provides information about a particular Link to the child client. Each Flatland
/// instance may only specify a single root transform, so other objects in the graph can only be
/// children of a single GraphLink. However, more than one GraphLink protocol may be active at a
/// time for a particular Flatland instance. Specifically, when a Flatland instance is transitioning
/// from using one Link to another, each Link will have a separate protocol instance, and more than
/// one protocol may receive certain updates.
protocol GraphLink {
/// A hanging get for receiving layout information. Clients may receive layout information
/// before the GraphLink operation has been presented. This allows children to layout their
/// content before their first call to Present(). In transition cases where two GraphLink
/// channels exist at the same time, both protocol instances will be receiving different layout
/// information.
GetLayout() -> (LayoutInfo info);
enum ContentLinkStatus {
/// The underlying Graph has connected its Link, called Present(), and the acquisition fences of
/// the Present() call have all be reached.
/// A protocol that provides information about a particular Link to the parent client. Flatland
/// instances may contain any number of ContentLinks, each of which may or may not be attached to
/// the Root Transform. Each ContentLink has its own protocol instance.
protocol ContentLink {
/// A hanging get for receiving the status of a Link. This provides information to the parent,
/// such as whether or not the child has successfully presented content through this Link.
GetStatus() -> (ContentLinkStatus status);
/// A typed wrapper for an eventpair, representing the child endpoint of a Link.
struct GraphLinkToken {
handle<eventpair> value;
/// A typed wrapper for an eventpair, representing the parent endpoint of a Link.
struct ContentLinkToken {
handle<eventpair> value;
/// The properties of a Link as defined by the parent. This data, along with the set of attached
/// Transforms, will be used to compute the LayoutInfo for the child of the Link.
table LinkProperties {
/// The size of the Link in logical pixels. This maps directly to the logical_size field in
/// LayoutInfo.
1: Vec2 logical_size;
/// A user-defined identifier for a particular transform. See CreateTransform() and
/// ReleaseTransform() for more information.
using TransformId = uint64;
/// A user-defined identifier for a particular Link. See CreateLink() for more information.
using LinkId = uint64;
/// 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 linked 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.
protocol Flatland {
/// Complete execution of all feed-forward operations.
/// If executing an operation produces an error (e.g., CreateTransform(0)), Present() will
/// return an error. Operations that produce errors are ignored. Future operations are still
/// executed.
/// TODO(36166): Present should stop execution, and kill the channel, when irrecoverable errors
/// are detected.
/// The client may only call Present() a certain number of times before it must wait for this
/// function to return. This number or presents remaining is the return value of this function.
/// The number of presents remaining will never drop without a corresponding call to Present()
/// by the client. However, it may stay the same, or even increase, with each return from
/// Present().
/// num_presents_remaining will always be >= 1. Present() will not return until the client is
/// allowed to call Present() again.
Present() -> (uint32 num_presents_remaining) error Error;
// ***** Graph management *****
/// A Link is a connection between the objects authored in this Graph, and the objects in
/// the Graph of another process. The parent process has control over how the linked content is
/// integrated into their Graph.
/// A link is formed by creating an event pair, passing one end to the parent (which calls
/// CreateLink()) and the other end to the child (which calls LinkToParent()).
/// Only nodes connected to the Root Transform in this Flatland instance will be rendered as
/// part of the parent's Graph.
/// Calling LinkToParent() a second time will disconnect the Root Transform from the existing
/// parent's Graph, and attach it to a new parent's Graph.
/// This function is feed-forward, meaning that the Root Transform will not be attached to the
/// parent Graph until Present() is called. However, Clients will receive information through
/// their GraphLinkListener (e.g., LayoutInfo) immediately after calling this function, even if
/// they have not called Present() or SetRoot(). This allows clients to wait for layout
/// information from their parent before calling Present(), if they wish.
LinkToParent(GraphLinkToken token, request<GraphLink> graph_link);
/// This function will reset all state on this interface.
// ***** Transforms *****
// Transform constructors.
/// 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 links to Transforms in other processes.
/// 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(TransformId transform_id);
// 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(TransformId parent_transform_id, TransformId child_transform_id);
/// Removes a child Transform from a parent Transform.
RemoveChild(TransformId parent_transform_id, TransformId child_transform_id);
/// Sets the Root Transform for the graph.
/// The sub-graph defined by the Root Transform and its children will be rendered as Content
/// in the linked parent Graph (see LinkToParent()). 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.
SetRootTransform(TransformId transform_id);
// ***** 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. Content can be resized using either
// scale attributes on transforms, or the appropriate Content mutators.
// Content constructors
/// A Link is a connection between the objects authored in this Graph, and the objects in
/// another process. The parent process has control over how the linked content is integrated
/// into their Graph through this Link object, and the object's associated Link properties.
CreateLink(LinkId link_id, ContentLinkToken token, LinkProperties properties,
request<ContentLink> content_link);
// Content mutators
/// Transforms are usually sufficient to change how content is presented. Links, however, have
/// special properties that are not part of the Transform hierarchy. Those properties can be set
/// using this function.
SetLinkProperties(LinkId link_id, LinkProperties properties);
// ***** Cleanup operations *****
/// Released Transforms and Content will be garbage collected by the system once they are no
/// longer necessary for rendering (i.e., there is no path from the Root Transform to the
/// object, all pending rendering has completed, and new Content is available).
/// However, once released, the id immediately goes out of scope for future function calls, and
/// can be reused by the client when creating new Transforms and Content.
/// It is an error to call Graph functions on a released id (unless that id has been reused to
/// construct a new object).
ReleaseTransform(TransformId transform_id);