| // 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 { |
| BAD_OPERATION = 0; |
| }; |
| |
| // 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. |
| CONTENT_HAS_PRESENTED = 0; |
| }; |
| |
| /// 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. |
| ClearGraph(); |
| |
| // ***** 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); |
| }; |