PROTOCOLS
GraphLink
Defined in fuchsia.ui.scenic.internal/flatland.fidl
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.
GetLayout
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.
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.
Request
| Name | Type |
|---|
Response
| Name | Type |
|---|---|
info |
LayoutInfo
|
GetStatus
A hanging get for receiving the status of the Link. This provides global connectivity information to the child.
This hanging get will only fire when the GraphLinkStatus is different than the previously returned GraphLinkStatus.
Request
| Name | Type |
|---|
Response
| Name | Type |
|---|---|
status |
GraphLinkStatus
|
ContentLink
Defined in fuchsia.ui.scenic.internal/flatland.fidl
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.
GetStatus
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.
This hanging get will only fire when the ContentLinkStatus is different than the previously returned ContentLinkStatus.
Request
| Name | Type |
|---|
Response
| Name | Type |
|---|---|
status |
ContentLinkStatus
|
Flatland
Defined in fuchsia.ui.scenic.internal/flatland.fidl
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.
Present
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.
Request
| Name | Type |
|---|
Response
| Name | Type |
|---|---|
result |
Flatland_Present_Result
|
LinkToParent
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.
Request
| Name | Type |
|---|---|
token |
GraphLinkToken
|
graph_link |
request<GraphLink>
|
UnlinkFromParent
Disconnects this Graph from its parent Graph and returns the GraphLinkToken used to establish the link. This token can then be used to establish a new link with the Parent graph.
To clear the existing content from the screen without unlinking the current Graph, use SetRootTransform(0) instead.
Despite having a return type, this function is still feed-forward Like LinkToParent() and requires a call to Present() to be executed. The GraphLinkToken will be returned after the presented operations have been executed.
Request
| Name | Type |
|---|
Response
| Name | Type |
|---|---|
token |
GraphLinkToken
|
ClearGraph
This function will reset all state on this interface.
Request
| Name | Type |
|---|
CreateTransform
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).
Request
| Name | Type |
|---|---|
transform_id |
TransformId
|
SetTranslation
All Transform objects support all attributes.
Geometric attributes are applied in the following order:
- Translation (relative to the parent's coordinate space)
- Orientation (around the new origin as defined by the translation)
- Scale (relative to the new rotated origin)
- Crop (in the scaled coordinate space)
Sets the translation on a Transform. The order of geometric attribute application is addressed above.
Request
| Name | Type |
|---|---|
transform_id |
TransformId
|
translation |
Vec2
|
SetOrientation
Sets the orientation on a Transform. The order of geometric attribute application is addressed in the documentation for SetTranslation().
Request
| Name | Type |
|---|---|
transform_id |
TransformId
|
orientation |
Orientation
|
SetScale
Sets the scale on a Transform. The order of geometric attribute application is addressed in the documentation for SetTranslation().
Request
| Name | Type |
|---|---|
transform_id |
TransformId
|
scale |
Vec2
|
AddChild
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.
Request
| Name | Type |
|---|---|
parent_transform_id |
TransformId
|
child_transform_id |
TransformId
|
RemoveChild
Removes a child Transform from a parent Transform.
Request
| Name | Type |
|---|---|
parent_transform_id |
TransformId
|
child_transform_id |
TransformId
|
SetRootTransform
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.
Request
| Name | Type |
|---|---|
transform_id |
TransformId
|
CreateLink
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.
LinkProperties must have logical_size set. This is the initial size that will drive the
layout of the child.
Request
| Name | Type |
|---|---|
link_id |
LinkId
|
token |
ContentLinkToken
|
properties |
LinkProperties
|
content_link |
request<ContentLink>
|
SetLinkOnTransform
Setting a Link on a Transform makes the content from the Link visible in the render tree as long as the Transform is visible from the root Transform. The contents of the Link will be rendered before, and therefore "behind", any content attached to the descendants of the Transform.
Request
| Name | Type |
|---|---|
link_id |
LinkId
|
transform_id |
TransformId
|
SetLinkProperties
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.
Request
| Name | Type |
|---|---|
link_id |
LinkId
|
properties |
LinkProperties
|
ReleaseTransform
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). The only exceptions are Link objects (see ReleaseLink() for more details).
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).
Request
| Name | Type |
|---|---|
transform_id |
TransformId
|
ReleaseLink
Releasing a Link removes the attached sub-Graph from the scene, even if the Link is still connected to a Transform. Unlike other Content, Links are garbage collected by the system during the next Present() because a released Link is guaranteed to provide no renderable content.
Use SetLinkOnTransform(transform_id, 0) to clean up references to deleted Links.
Despite having a return type, this function is still feed-forward Like LinkToParent() and requires a call to Present() to be executed. The ContentLinkToken will be returned after the presented operations have been executed.
Request
| Name | Type |
|---|---|
id |
LinkId
|
Response
| Name | Type |
|---|---|
token |
ContentLinkToken
|
Snapshot
Defined in fuchsia.ui.scenic.internal/snapshot.fidl
Defines an internal interface to take snapshots of the entire scene graph. This is only to be used by trusted clients.
TakeSnapshot
Takes a snapshot of the entire scene-graph, starting with the first compositor found. A separate buffer is returned for each compositor, with an empty array being returned if no compositors were found at all.
Request
| Name | Type |
|---|
Response
| Name | Type |
|---|---|
snapshots |
vector<SnapshotResult>
|
STRUCTS
Flatland_Present_Response
Defined in fuchsia.ui.scenic.internal/flatland.fidl
| Name | Type | Description | Default |
|---|---|---|---|
num_presents_remaining |
uint32
|
No default |
Vec2
Defined in fuchsia.ui.scenic.internal/flatland.fidl
| Name | Type | Description | Default |
|---|---|---|---|
x |
float32
|
No default | |
y |
float32
|
No default |
GraphLinkToken
Defined in fuchsia.ui.scenic.internal/flatland.fidl
A typed wrapper for an eventpair, representing the child endpoint of a Link.
| Name | Type | Description | Default |
|---|---|---|---|
value |
handle<eventpair>
|
No default |
ContentLinkToken
Defined in fuchsia.ui.scenic.internal/flatland.fidl
A typed wrapper for an eventpair, representing the parent endpoint of a Link.
| Name | Type | Description | Default |
|---|---|---|---|
value |
handle<eventpair>
|
No default |
SnapshotResult
Defined in fuchsia.ui.scenic.internal/snapshot.fidl
| Name | Type | Description | Default |
|---|---|---|---|
success |
bool
|
No default | |
buffer |
fuchsia.mem/Buffer
|
No default |
ENUMS
Error
Type: uint32
Defined in fuchsia.ui.scenic.internal/flatland.fidl
| Name | Value | Description |
|---|---|---|
BAD_OPERATION |
0 |
Orientation
Type: uint32
Defined in fuchsia.ui.scenic.internal/flatland.fidl
| Name | Value | Description |
|---|---|---|
CCW_0_DEGREES |
0 |
|
CCW_90_DEGREES |
1 |
|
CCW_180_DEGREES |
2 |
|
CCW_270_DEGREES |
3 |
GraphLinkStatus
Type: uint32
Defined in fuchsia.ui.scenic.internal/flatland.fidl
GraphLinks will be informed when they are actively attached to a output display (either directly, or through a chain of parent links) and when they are not. Until they are connected to a display, some pieces of information (such as pixel scale) may be unavailable.
| Name | Value | Description |
|---|---|---|
CONNECTED_TO_DISPLAY |
0 |
|
DISCONNECTED_FROM_DISPLAY |
1 |
ContentLinkStatus
Type: uint32
Defined in fuchsia.ui.scenic.internal/flatland.fidl
| Name | Value | Description |
|---|---|---|
CONTENT_HAS_PRESENTED |
0 |
The underlying Graph has connected its Link, called Present(), the acquisition fences of the Present() call have all be reached, and the Graph's content has been rendered to an output device. |
TABLES
LayoutInfo
Defined in fuchsia.ui.scenic.internal/flatland.fidl
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().
| Ordinal | Name | Type | Description |
|---|---|---|---|
| 1 | logical_size |
Vec2
|
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. |
LinkProperties
Defined in fuchsia.ui.scenic.internal/flatland.fidl
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.
| Ordinal | Name | Type | Description |
|---|---|---|---|
| 1 | logical_size |
Vec2
|
The size of the Link in logical pixels. This maps directly to the logical_size field in LayoutInfo. |
UNIONS
Flatland_Present_Result
Defined in fuchsia.ui.scenic.internal/flatland.fidl
| Name | Type | Description |
|---|---|---|
response |
Flatland_Present_Response
|
|
err |
Error
|
TYPE ALIASES
| Name | Value | Description |
|---|---|---|
| TransformId |
uint64 |
A user-defined identifier for a particular transform. See CreateTransform() and ReleaseTransform() for more information. |
| LinkId |
uint64 |
A user-defined identifier for a particular Link. See CreateLink() for more information. |