Google Git
Sign in
fuchsia / reference-docs / main / . / f10 / sdk / fidl / fuchsia.ui.composition / README.md
blob: f3c7190df228f42955b8ff7ba679023727fe80ad [file] [log] [blame] [view]
<link rel="stylesheet" href="../style.css" />
[TOC]
# fuchsia.ui.composition
<div class="fidl-version-div"><span class="fidl-attribute fidl-version">Added: 7</span></div>
## **PROTOCOLS**
## Allocator {#Allocator}
*Defined in [fuchsia.ui.composition/allocator.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/allocator.fidl;l=100)*
### RegisterBufferCollection {#Allocator.RegisterBufferCollection}
<p>A BufferCollection is a set of VMOs created by Sysmem and shared by a number of
participants, one of which is the Flatland Renderer. Some content, such as Images, use a
BufferCollection as their backing memory.</p>
<p>See <a class='link' href='#RegisterBufferCollectionArgs'>RegisterBufferCollectionArgs</a> for information on each argument.</p>
#### Request {#Allocator.RegisterBufferCollection_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>args</code></td>
<td>
<code><a class='link' href='#RegisterBufferCollectionArgs'>RegisterBufferCollectionArgs</a></code>
</td>
</tr>
</table>
#### Response {#Allocator.RegisterBufferCollection_Response}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>result</code></td>
<td>
<code><a class='link' href='#Allocator_RegisterBufferCollection_Result'>Allocator_RegisterBufferCollection_Result</a></code>
</td>
</tr>
</table>
## ChildViewWatcher {#ChildViewWatcher}
*Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=189)*
<p>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
<a class='link' href='#CreateViewport'>CreateViewport</a>. 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.</p>
<p>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.</p>
### GetStatus {#ChildViewWatcher.GetStatus}
<p>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.</p>
<p>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.</p>
<p>It is invalid to call <code>GetStatus</code> 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.</p>
#### Request {#ChildViewWatcher.GetStatus_Request}
&lt;EMPTY&gt;
#### Response {#ChildViewWatcher.GetStatus_Response}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>status</code></td>
<td>
<code><a class='link' href='#ChildViewStatus'>ChildViewStatus</a></code>
</td>
</tr>
</table>
### GetViewRef {#ChildViewWatcher.GetViewRef}
<p>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.</p>
<p>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.</p>
<p>It is invalid to call <code>GetViewRef</code> 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.</p>
<p>A <code>GetViewRef</code> call will hang if the View was created using <code>CreateView</code>, but returns the
View if the View was created using CreateView2. This is because <code>CreateView</code> does not mint
a ViewRef for that View.</p>
#### Request {#ChildViewWatcher.GetViewRef_Request}
&lt;EMPTY&gt;
#### Response {#ChildViewWatcher.GetViewRef_Response}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>view_ref</code></td>
<td>
<code><a class='link' href='../fuchsia.ui.views/'>fuchsia.ui.views</a>/<a class='link' href='../fuchsia.ui.views/#ViewRef'>ViewRef</a></code>
</td>
</tr>
</table>
## Flatland {#Flatland}
*Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=430)*
<p>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.</p>
<p>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.</p>
<p>All functions in this protocol are feed-forward. The operations they represent are not fully
executed until <a class='link' href='#Present'>Present</a> is called.</p>
### AddChild {#Flatland.AddChild}
<p>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.</p>
#### Request {#Flatland.AddChild_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>parent_transform_id</code></td>
<td>
<code><a class='link' href='#TransformId'>TransformId</a></code>
</td>
</tr>
<tr>
<td><code>child_transform_id</code></td>
<td>
<code><a class='link' href='#TransformId'>TransformId</a></code>
</td>
</tr>
</table>
### Clear {#Flatland.Clear}
<p>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.</p>
#### Request {#Flatland.Clear_Request}
&lt;EMPTY&gt;
### CreateFilledRect {#Flatland.CreateFilledRect}
<p>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</p>
#### Request {#Flatland.CreateFilledRect_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>rect_id</code></td>
<td>
<code><a class='link' href='#ContentId'>ContentId</a></code>
</td>
</tr>
</table>
### CreateImage {#Flatland.CreateImage}
<p>An Image is a bitmap backed by a specific VMO in a BufferCollection.</p>
<p>Image creation requires an allocated BufferCollection registered with Allocator. This
function will fail unless all clients of the specified BufferCollection have set their
constraints.</p>
<p>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.)</p>
<p>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 <a class='link' href='#ReleaseImage'>ReleaseImage</a> for more details).</p>
#### Request {#Flatland.CreateImage_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>image_id</code></td>
<td>
<code><a class='link' href='#ContentId'>ContentId</a></code>
</td>
</tr>
<tr>
<td><code>import_token</code></td>
<td>
<code><a class='link' href='#BufferCollectionImportToken'>BufferCollectionImportToken</a></code>
</td>
</tr>
<tr>
<td><code>vmo_index</code></td>
<td>
<code>uint32</code>
</td>
</tr>
<tr>
<td><code>properties</code></td>
<td>
<code><a class='link' href='#ImageProperties'>ImageProperties</a></code>
</td>
</tr>
</table>
### CreateTransform {#Flatland.CreateTransform}
<p>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.</p>
<p>Transforms are kept alive, even when released, as long as they are children of either an
unreleased Transform, or the Root Transform.</p>
<p>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.</p>
<p>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.</p>
<p>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 <a class='link' href='#AddChild'>AddChild</a> for more information.</p>
<p>Zero is not a valid transform id. All other values are valid, assuming they are not already
in use (see <a class='link' href='#ReleaseTransform'>ReleaseTransform</a> for more details).</p>
#### Request {#Flatland.CreateTransform_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>transform_id</code></td>
<td>
<code><a class='link' href='#TransformId'>TransformId</a></code>
</td>
</tr>
</table>
### CreateView {#Flatland.CreateView}
<p>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.</p>
<p>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 <a class='link' href='#CreateViewport'>CreateViewport</a>, and the
ViewCreationToken to the child, which calls <a class='link' href='#CreateView'>CreateView</a>.</p>
<p>Only nodes connected to the Root Transform in this Flatland instance will be rendered into
the parent's Viewport.</p>
<p>Calling <a class='link' href='#CreateView'>CreateView</a> 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.</p>
<p>This function is queued, meaning that the Root Transform will not be attached to the
parent Viewport until <a class='link' href='#Present'>Present</a> is called. However, clients will receive information
through their ParentViewportWatcher (e.g., LayoutInfo) immediately after calling this
function, even if they have not called <a class='link' href='#Present'>Present</a> or <a class='link' href='#SetRootTransform'>SetRootTransform</a>. This allows
clients to wait for layout information from their parent before calling <a class='link' href='#Present'>Present</a>.</p>
<p>Any illegal operations on ParentViewportWatcher will cause both ParentViewportWatcher
channel and this Flatland channel to be torn down.</p>
<p>Lifecycle note. The lifetime of the ParentViewportWatcher channel is bound by the peer
ViewportCreationToken. When the ViewportCreationToken dies, this ParentViewportWatcher
channel is destroyed.</p>
<p>Views and subgraphs of Views created using <code>CreateView</code> will not be represented in the
ViewTree, and hence will not be able to participate in any ViewTree-dependent interactions
such as touch, mouse or focus.
The Flatland protocol provides no way for Views in the subgraph of a View created with
<code>CreateView</code> to know that they are excluded from the ViewTree.</p>
#### Request {#Flatland.CreateView_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>token</code></td>
<td>
<code><a class='link' href='../fuchsia.ui.views/'>fuchsia.ui.views</a>/<a class='link' href='../fuchsia.ui.views/#ViewCreationToken'>ViewCreationToken</a></code>
</td>
</tr>
<tr>
<td><code>parent_viewport_watcher</code></td>
<td>
<code>server_end&lt;<a class='link' href='#ParentViewportWatcher'>ParentViewportWatcher</a>&gt;</code>
</td>
</tr>
</table>
### CreateView2 {#Flatland.CreateView2}
<p>Identical to <a class='link' href='#CreateView'>CreateView</a>, except it allows association of View identity (ViewRef) and
view-bound protocols.</p>
#### Request {#Flatland.CreateView2_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>token</code></td>
<td>
<code><a class='link' href='../fuchsia.ui.views/'>fuchsia.ui.views</a>/<a class='link' href='../fuchsia.ui.views/#ViewCreationToken'>ViewCreationToken</a></code>
</td>
</tr>
<tr>
<td><code>view_identity</code></td>
<td>
<code><a class='link' href='../fuchsia.ui.views/'>fuchsia.ui.views</a>/<a class='link' href='../fuchsia.ui.views/#ViewIdentityOnCreation'>ViewIdentityOnCreation</a></code>
</td>
</tr>
<tr>
<td><code>protocols</code></td>
<td>
<code><a class='link' href='#ViewBoundProtocols'>ViewBoundProtocols</a></code>
</td>
</tr>
<tr>
<td><code>parent_viewport_watcher</code></td>
<td>
<code>server_end&lt;<a class='link' href='#ParentViewportWatcher'>ParentViewportWatcher</a>&gt;</code>
</td>
</tr>
</table>
### CreateViewport {#Flatland.CreateViewport}
<p>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.</p>
<p>Any illegal operations on ChildViewWatcher will cause both ChildViewWatcher channel and this
Flatland channel to be torn down.</p>
<p><code>ViewportProperties</code> 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.</p>
<p><code>ViewportProperties</code> may have inset field not set. In that case, the default value of
(0, 0, 0, 0) is used.</p>
<p>The logical_size must have positive X and Y components.</p>
<p>Zero is not a valid ContentId. All other values are valid, assuming they are not already
in use for another piece of Content (see <a class='link' href='#ReleaseViewport'>ReleaseViewport</a> for more details).</p>
<p>Lifecycle note. The lifetime of the ChildViewWatcher channel is bound by the peer
ViewCreationToken. When the ViewCreationToken dies, this ChildViewWatcher channel is
destroyed.</p>
#### Request {#Flatland.CreateViewport_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>viewport_id</code></td>
<td>
<code><a class='link' href='#ContentId'>ContentId</a></code>
</td>
</tr>
<tr>
<td><code>token</code></td>
<td>
<code><a class='link' href='../fuchsia.ui.views/'>fuchsia.ui.views</a>/<a class='link' href='../fuchsia.ui.views/#ViewportCreationToken'>ViewportCreationToken</a></code>
</td>
</tr>
<tr>
<td><code>properties</code></td>
<td>
<code><a class='link' href='#ViewportProperties'>ViewportProperties</a></code>
</td>
</tr>
<tr>
<td><code>child_view_watcher</code></td>
<td>
<code>server_end&lt;<a class='link' href='#ChildViewWatcher'>ChildViewWatcher</a>&gt;</code>
</td>
</tr>
</table>
### OnError {#Flatland.OnError}
<p>If an error occurs after a <a class='link' href='#Present'>Present</a>, an <code>OnError</code> event will fire with associated
information.</p>
<p>FlatlandErrors will close the connection with the client.</p>
<ul>
<li>response <code>error</code> the error a client may receive after performing some invalid operations.</li>
</ul>
#### Response {#Flatland.OnError_Response}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>error</code></td>
<td>
<code><a class='link' href='#FlatlandError'>FlatlandError</a></code>
</td>
</tr>
</table>
### OnFramePresented {#Flatland.OnFramePresented}
<p>This event is fired whenever a set of one or more <a class='link' href='#Present'>Present</a>s are presented simultaneously,
and are therefore no longer in flight.</p>
<p>This event signifies that the commands enqueued before the <a class='link' href='#Present'>Present</a> have taken effect in
the scene graph, and are globally visible.</p>
<p>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 <a class='link' href='#OnNextFrameBegin'>OnNextFrameBegin</a> event.</p>
<p>TODO(fxbug.dev/63305): remove <code>num_presents_allowed</code> from this event.</p>
#### Response {#Flatland.OnFramePresented_Response}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>frame_presented_info</code></td>
<td>
<code><a class='link' href='../fuchsia.scenic.scheduling/'>fuchsia.scenic.scheduling</a>/<a class='link' href='../fuchsia.scenic.scheduling/#FramePresentedInfo'>FramePresentedInfo</a></code>
</td>
</tr>
</table>
### OnNextFrameBegin {#Flatland.OnNextFrameBegin}
<p>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.</p>
<p>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.</p>
<ul>
<li>response <code>values</code> the table of information a client needs to produce its next frame. See
<a class='link' href='#OnNextFrameBeginValues'>OnNextFrameBeginValues</a> for more information.</li>
</ul>
#### Response {#Flatland.OnNextFrameBegin_Response}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>values</code></td>
<td>
<code><a class='link' href='#OnNextFrameBeginValues'>OnNextFrameBeginValues</a></code>
</td>
</tr>
</table>
### Present {#Flatland.Present}
<p>Complete execution of all feed-forward operations.</p>
<p>If executing an operation produces an error (e.g., CreateTransform(0)), an <a class='link' href='#OnError'>OnError</a> event
is emitted. Operations that produce errors are ignored and the channel is closed.</p>
<p>If the execution is completed successfully, <a class='link' href='#OnNextFrameBegin'>OnNextFrameBegin</a> emits NO_ERROR along
with other valid fields.</p>
<p>The client may only call <a class='link' href='#Present'>Present</a> 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 <a class='link' href='#OnNextFrameBegin'>OnNextFrameBegin</a> event, which informs the client when it receives additional
present credits. Each <a class='link' href='#Present'>Present</a> call uses one present credit and decrements the server
count by one. If the client calls <a class='link' href='#Present'>Present</a> with no present credits, the server will
return a <code>NO_PRESENTS_REMAINING</code> error.</p>
<p>The client should assume that prior to receiving any <a class='link' href='#OnNextFrameBegin'>OnNextFrameBegin</a> events, they have
one present credit.</p>
<p>Every <a class='link' href='#Present'>Present</a> call results in one <a class='link' href='#OnNextFrameBegin'>OnNextFrameBegin</a> event, and one
<a class='link' href='#OnFramePresented'>OnFramePresented</a> event, typically in that order.</p>
<p>When the commands flushed by <a class='link' href='#Present'>Present</a> make it to display, an <a class='link' href='#OnFramePresented'>OnFramePresented</a> event
is fired. This event includes information pertaining to all <a class='link' href='#Present'>Present</a>s that had content
that were part of that frame.</p>
<p>See <a class='link' href='../fuchsia.ui.composition/'>fuchsia.ui.composition</a>/<a class='link' href='../fuchsia.ui.composition/#PresentArgs'>PresentArgs</a> documentation above for more detailed information
on what arguments are passed in and their role.</p>
#### Request {#Flatland.Present_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>args</code></td>
<td>
<code><a class='link' href='#PresentArgs'>PresentArgs</a></code>
</td>
</tr>
</table>
### ReleaseFilledRect {#Flatland.ReleaseFilledRect}
<p>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.</p>
#### Request {#Flatland.ReleaseFilledRect_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>rect_id</code></td>
<td>
<code><a class='link' href='#ContentId'>ContentId</a></code>
</td>
</tr>
</table>
### ReleaseImage {#Flatland.ReleaseImage}
<p>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.</p>
<p>Use SetContent(transform_id, 0) to clean up references to released Images.</p>
<p>Once released, the id immediately goes out of scope for future function calls and can be
reused when creating new Images.</p>
<p>It is an error to call functions with a released id (unless that id has been reused to
construct a new Image).</p>
#### Request {#Flatland.ReleaseImage_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>image_id</code></td>
<td>
<code><a class='link' href='#ContentId'>ContentId</a></code>
</td>
</tr>
</table>
### ReleaseTransform {#Flatland.ReleaseTransform}
<p>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.</p>
<p>Once released, the id immediately goes out of scope for future function calls and can be
reused when creating new Transforms.</p>
<p>It is an error to call functions with a released id (unless that id has been reused to
construct a new Transform).</p>
#### Request {#Flatland.ReleaseTransform_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>transform_id</code></td>
<td>
<code><a class='link' href='#TransformId'>TransformId</a></code>
</td>
</tr>
</table>
### ReleaseView {#Flatland.ReleaseView}
#### Request {#Flatland.ReleaseView_Request}
&lt;EMPTY&gt;
### ReleaseViewport {#Flatland.ReleaseViewport}
<p>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
<a class='link' href='#Present'>Present</a> because a removed Viewport is guaranteed to provide no renderable content.</p>
<p>Use SetContent(transform_id, 0) to clean up references to released Viewports.</p>
<p>Despite having a return type, this function is still feed-forward like <a class='link' href='#CreateView'>CreateView</a> and
requires a call to <a class='link' href='#Present'>Present</a> to be executed. The ViewportCreationToken will be returned
after the presented operations have been executed.</p>
#### Request {#Flatland.ReleaseViewport_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>viewport_id</code></td>
<td>
<code><a class='link' href='#ContentId'>ContentId</a></code>
</td>
</tr>
</table>
#### Response {#Flatland.ReleaseViewport_Response}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>token</code></td>
<td>
<code><a class='link' href='../fuchsia.ui.views/'>fuchsia.ui.views</a>/<a class='link' href='../fuchsia.ui.views/#ViewportCreationToken'>ViewportCreationToken</a></code>
</td>
</tr>
</table>
### RemoveChild {#Flatland.RemoveChild}
<p>Removes a child Transform from a parent Transform.</p>
#### Request {#Flatland.RemoveChild_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>parent_transform_id</code></td>
<td>
<code><a class='link' href='#TransformId'>TransformId</a></code>
</td>
</tr>
<tr>
<td><code>child_transform_id</code></td>
<td>
<code><a class='link' href='#TransformId'>TransformId</a></code>
</td>
</tr>
</table>
### SetClipBoundary {#Flatland.SetClipBoundary}
<p>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.</p>
#### Request {#Flatland.SetClipBoundary_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>transform_id</code></td>
<td>
<code><a class='link' href='#TransformId'>TransformId</a></code>
</td>
</tr>
<tr>
<td><code>rect</code></td>
<td>
<code><a class='link' href='../fuchsia.math/'>fuchsia.math</a>/<a class='link' href='../fuchsia.math/#Rect'>Rect</a>?</code>
</td>
</tr>
</table>
### SetContent {#Flatland.SetContent}
<p>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 &quot;behind&quot;, any Content attached to the descendants of the Transform.</p>
<p>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.</p>
<p>A Content may be set on more than one Transform.</p>
<p>Calling this function with a Content id of 0 will remove any Content currently on the
Transform.</p>
#### Request {#Flatland.SetContent_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>transform_id</code></td>
<td>
<code><a class='link' href='#TransformId'>TransformId</a></code>
</td>
</tr>
<tr>
<td><code>content_id</code></td>
<td>
<code><a class='link' href='#ContentId'>ContentId</a></code>
</td>
</tr>
</table>
### SetDebugName {#Flatland.SetDebugName}
<p>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. <a class='link' href='#name'>name</a> can be an arbitrary string, but the
current process name (see fsl::GetCurrentProcessName()) is a good default.</p>
#### Request {#Flatland.SetDebugName_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>name</code></td>
<td>
<code>string[64]</code>
</td>
</tr>
</table>
### SetHitRegions {#Flatland.SetHitRegions}
<p>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.</p>
<p>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 <a class='link' href='#HitTestInteraction'>HitTestInteraction</a>
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.</p>
<p>To reset a Transform to &quot;no hit testing&quot;: send an empty vector.</p>
<p>Note that root transforms get a default hit region installed by Flatland. For more details,
see the <a class='link' href='#SetRootTransform'>SetRootTransform</a> documentation.</p>
<p>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 (<a class='link' href='#DEFAULT'>DEFAULT</a>) and
S (<a class='link' href='#SEMANTICALLY_INVISIBLE'>SEMANTICALLY_INVISIBLE</a>) 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.</p>
<p>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 &quot;render order&quot; of
Transforms (described in <a class='link' href='#CreateTransform'>CreateTransform</a>), where a user expects to interact with
Content that is visible, or front-most.</p>
<p>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 &quot;render order&quot; 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.</p>
#### Request {#Flatland.SetHitRegions_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>transform_id</code></td>
<td>
<code><a class='link' href='#TransformId'>TransformId</a></code>
</td>
</tr>
<tr>
<td><code>regions</code></td>
<td>
<code>vector&lt;<a class='link' href='#HitRegion'>HitRegion</a>&gt;[64]</code>
</td>
</tr>
</table>
### SetImageBlendingFunction {#Flatland.SetImageBlendingFunction}
<p>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. If this function is not called,
then the default blendmode is BlendMode::SRC.</p>
#### Request {#Flatland.SetImageBlendingFunction_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>image_id</code></td>
<td>
<code><a class='link' href='#ContentId'>ContentId</a></code>
</td>
</tr>
<tr>
<td><code>blend_mode</code></td>
<td>
<code><a class='link' href='#BlendMode'>BlendMode</a></code>
</td>
</tr>
</table>
### SetImageDestinationSize {#Flatland.SetImageDestinationSize}
<p>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.</p>
<p>If this method is not called, the default image destination size is the width and height set
at ImageProperties from <a class='link' href='#CreateImage'>CreateImage</a>. The destination size will be affected by scaling if
<a class='link' href='#SetScale'>SetScale</a> is used on the attached Transform or its parents.</p>
#### Request {#Flatland.SetImageDestinationSize_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>image_id</code></td>
<td>
<code><a class='link' href='#ContentId'>ContentId</a></code>
</td>
</tr>
<tr>
<td><code>size</code></td>
<td>
<code><a class='link' href='../fuchsia.math/'>fuchsia.math</a>/<a class='link' href='../fuchsia.math/#SizeU'>SizeU</a></code>
</td>
</tr>
</table>
### SetImageFlip {#Flatland.SetImageFlip}
<p>Sets the image flip to be applied to a flatland image. This call must be performed after a
successful |CreateImage| call. If an invalid |image_id| is supplied, the channel will be
closed due to FlatlandError::BAD_OPERATION. This flip will be applied to the Image before
parent Transform Orientations. If this function is not called, then the default flip value
is ImageFlip::NONE.</p>
<div class="fidl-version-div"><span class="fidl-attribute fidl-version">Added: 10</span></div>
#### Request {#Flatland.SetImageFlip_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>image_id</code></td>
<td>
<code><a class='link' href='#ContentId'>ContentId</a></code>
</td>
</tr>
<tr>
<td><code>flip</code></td>
<td>
<code><a class='link' href='#ImageFlip'>ImageFlip</a></code>
</td>
</tr>
</table>
### SetImageOpacity {#Flatland.SetImageOpacity}
<p>Sets an opacity in linear space to be applied to a flatland image. Opacity values must
be in the range [0.0, 1.0].</p>
#### Request {#Flatland.SetImageOpacity_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>image_id</code></td>
<td>
<code><a class='link' href='#ContentId'>ContentId</a></code>
</td>
</tr>
<tr>
<td><code>val</code></td>
<td>
<code>float32</code>
</td>
</tr>
</table>
### SetImageSampleRegion {#Flatland.SetImageSampleRegion}
<p>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 <a class='link' href='#image_id'>image_id</a> and the
sample region is specified by <a class='link' href='#rect'>rect</a> 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 <a class='link' href='#rect'>rect</a> must not exceed the ranges (0, image_width) and
(0, image_height). If (rect.x + rect.width &gt; image_width) or (rect.y + rect.height &gt;
image_height) or if any of the values are negative, this will result in an error.</p>
<p>If this method is not called, the default sample region is the rectangle with origin at
(0, 0) and width and height set at ImageProperties from <a class='link' href='#CreateImage'>CreateImage</a>.</p>
#### Request {#Flatland.SetImageSampleRegion_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>image_id</code></td>
<td>
<code><a class='link' href='#ContentId'>ContentId</a></code>
</td>
</tr>
<tr>
<td><code>rect</code></td>
<td>
<code><a class='link' href='../fuchsia.math/'>fuchsia.math</a>/<a class='link' href='../fuchsia.math/#RectF'>RectF</a></code>
</td>
</tr>
</table>
### SetOpacity {#Flatland.SetOpacity}
<p>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.</p>
#### Request {#Flatland.SetOpacity_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>transform_id</code></td>
<td>
<code><a class='link' href='#TransformId'>TransformId</a></code>
</td>
</tr>
<tr>
<td><code>value</code></td>
<td>
<code>float32</code>
</td>
</tr>
</table>
### SetOrientation {#Flatland.SetOrientation}
<p>Sets the orientation on a Transform. The order of geometric attribute application is
addressed in the documentation for <a class='link' href='#SetTranslation'>SetTranslation</a>. In Flatland, the +X axis is
to the right and the +Y axis is down. There is no notion of a Z axis. CCW is defined
from the POV of the user, as if a skeuomorphoic clock is displayed on the screen.</p>
#### Request {#Flatland.SetOrientation_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>transform_id</code></td>
<td>
<code><a class='link' href='#TransformId'>TransformId</a></code>
</td>
</tr>
<tr>
<td><code>orientation</code></td>
<td>
<code><a class='link' href='#Orientation'>Orientation</a></code>
</td>
</tr>
</table>
### SetRootTransform {#Flatland.SetRootTransform}
<p>Sets the Root Transform for the graph.</p>
<p>The sub-graph defined by the Root Transform and its children will be rendered as View
in the connected parent's Viewport (see <a class='link' href='#CreateView'>CreateView</a>). Any parents of the Root Transform
in this Graph will be ignored.</p>
<p>The Root Transform, and all children of the Root Transform, are kept alive if they are
released (see <a class='link' href='#ReleaseTransform'>ReleaseTransform</a> for more details).</p>
<p>There is only ever one Root. Since 0 is not a valid transform id (see <a class='link' href='#CreateTransform'>CreateTransform</a>),
calling SetRootTransform(0) clears the current Root, destroying any previously released
objects that are not referenced by the new root.</p>
<p>Note that every View has a clip boundary equivalent to its logical size. Anything outside
that clip boundary will not be rendered. Hence, the Root Transform has a useful coordinate
space of (0, 0) to (logical_size.width, logical_size.height), where (0, 0) is the upper left
corner.</p>
<p>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 <a class='link' href='#SetHitRegions'>SetHitRegions</a>
documentation.</p>
<p>Default hit region rules</p>
<p>A default hit region follows these rules:</p>
<ul>
<li>When <a class='link' href='#SetRootTransform'>SetRootTransform</a>(T) is called, T receives a maximal hit region, covering the
entire view.</li>
<li>If <a class='link' href='#SetHitRegions'>SetHitRegions</a> is called on T, either before or after <a class='link' href='#SetRootTransform'>SetRootTransform</a>(T),
then no default hit region is active and the client specified hit regions are used.</li>
<li>If a transform is no longer the root transform, i.e., <a class='link' href='#SetRootTransform'>SetRootTransform</a>(U) is
called, then the original transform no longer has its default hit region.</li>
<li>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 <a class='link' href='#SetHitRegions'>SetHitRegions</a> with the appropriate
vector.</li>
</ul>
#### Request {#Flatland.SetRootTransform_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>transform_id</code></td>
<td>
<code><a class='link' href='#TransformId'>TransformId</a></code>
</td>
</tr>
</table>
### SetScale {#Flatland.SetScale}
<p>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</p>
#### Request {#Flatland.SetScale_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>transform_id</code></td>
<td>
<code><a class='link' href='#TransformId'>TransformId</a></code>
</td>
</tr>
<tr>
<td><code>scale</code></td>
<td>
<code><a class='link' href='../fuchsia.math/'>fuchsia.math</a>/<a class='link' href='../fuchsia.math/#VecF'>VecF</a></code>
</td>
</tr>
</table>
### SetSolidFill {#Flatland.SetSolidFill}
<p>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. Color values
must be within the range [0,1] inclusive, and normal 32-bit
floating point values: https://en.wikipedia.org/wiki/Normal_number_%28computing%29. Values
that do not conform to these specifications will cause the channel to close.
The rectangle's top left corner will be at (0, 0) in its transform's coordinate space.
Hence, its bottom right corner will be at (size.width, size.height).</p>
#### Request {#Flatland.SetSolidFill_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>rect_id</code></td>
<td>
<code><a class='link' href='#ContentId'>ContentId</a></code>
</td>
</tr>
<tr>
<td><code>color</code></td>
<td>
<code><a class='link' href='#ColorRgba'>ColorRgba</a></code>
</td>
</tr>
<tr>
<td><code>size</code></td>
<td>
<code><a class='link' href='../fuchsia.math/'>fuchsia.math</a>/<a class='link' href='../fuchsia.math/#SizeU'>SizeU</a></code>
</td>
</tr>
</table>
### SetTranslation {#Flatland.SetTranslation}
<p>All Transform objects support all attributes.</p>
<p>Geometric attributes are applied in the following order:</p>
<ol>
<li>Scale (relative to the parent transform's coordinate space)</li>
<li>Orientation (relative to the parent transform's coordinate space)</li>
<li>Translation (relative to the parent transforms's coordinate space,
unaffected by scale applied to the current transform).</li>
<li>Clipping (relative to the current transform's coordinate space)</li>
</ol>
<p>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.</p>
<p>For instance, in a nested hierarchy such as the following:
[Root-Transform -&gt; Transform1 -&gt; Transform2 -&gt; 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].</p>
<p>Sets the translation on a Transform. The order of geometric attribute application is
addressed above.</p>
#### Request {#Flatland.SetTranslation_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>transform_id</code></td>
<td>
<code><a class='link' href='#TransformId'>TransformId</a></code>
</td>
</tr>
<tr>
<td><code>translation</code></td>
<td>
<code><a class='link' href='../fuchsia.math/'>fuchsia.math</a>/<a class='link' href='../fuchsia.math/#Vec'>Vec</a></code>
</td>
</tr>
</table>
### SetViewportProperties {#Flatland.SetViewportProperties}
<p>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.</p>
#### Request {#Flatland.SetViewportProperties_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>viewport_id</code></td>
<td>
<code><a class='link' href='#ContentId'>ContentId</a></code>
</td>
</tr>
<tr>
<td><code>properties</code></td>
<td>
<code><a class='link' href='#ViewportProperties'>ViewportProperties</a></code>
</td>
</tr>
</table>
## FlatlandDisplay {#FlatlandDisplay}
*Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=1007)*
<p>This API connects to the singleton &quot;primary display&quot;, and allows a tree of Flatland content to
be attached underneath. Only one FlatlandDisplay client connection is allowed at one time.</p>
### SetContent {#FlatlandDisplay.SetContent}
#### Request {#FlatlandDisplay.SetContent_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>token</code></td>
<td>
<code><a class='link' href='../fuchsia.ui.views/'>fuchsia.ui.views</a>/<a class='link' href='../fuchsia.ui.views/#ViewportCreationToken'>ViewportCreationToken</a></code>
</td>
</tr>
<tr>
<td><code>child_view_watcher</code></td>
<td>
<code>server_end&lt;<a class='link' href='#ChildViewWatcher'>ChildViewWatcher</a>&gt;</code>
</td>
</tr>
</table>
### SetDevicePixelRatio {#FlatlandDisplay.SetDevicePixelRatio}
<p>Sets the ratio of display's physical pixels to device independent pixels that should be used
for the tree of Flatland content that are attached to this display. See
<a class='link' href='#LayoutInfo.device_pixel_ratio'>LayoutInfo.device_pixel_ratio</a> for details.</p>
<p>The default value is (1.0, 1.0). The valid values are 1.0 and above.</p>
<div class="fidl-version-div"><span class="fidl-attribute fidl-version">Added: 9</span></div>
#### Request {#FlatlandDisplay.SetDevicePixelRatio_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>device_pixel_ratio</code></td>
<td>
<code><a class='link' href='../fuchsia.math/'>fuchsia.math</a>/<a class='link' href='../fuchsia.math/#VecF'>VecF</a></code>
</td>
</tr>
</table>
## ParentViewportWatcher {#ParentViewportWatcher}
*Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=138)*
<p>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 <a class='link' href='#CreateView'>CreateView</a>. During this period, certain updates may be
duplicated and sent to each ParentViewportWatcher connection.</p>
<p>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.</p>
### GetLayout {#ParentViewportWatcher.GetLayout}
<p>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 <a class='link' href='#Present'>Present</a>. In transition cases where two
ParentViewportWatcher channels exist at the same time, both protocol instances will be
receiving different layout information.</p>
<p>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.</p>
<p>It is invalid to call <code>GetLayout</code> 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.</p>
#### Request {#ParentViewportWatcher.GetLayout_Request}
&lt;EMPTY&gt;
#### Response {#ParentViewportWatcher.GetLayout_Response}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>info</code></td>
<td>
<code><a class='link' href='#LayoutInfo'>LayoutInfo</a></code>
</td>
</tr>
</table>
### GetStatus {#ParentViewportWatcher.GetStatus}
<p>A hanging get for receiving the status of the parent Viewport. This provides global
connectivity information to the child.</p>
<p>This hanging get will only fire when the ParentViewportStatus is different than the
previously returned ParentViewportStatus.</p>
<p>It is invalid to call <code>GetStatus</code> 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.</p>
#### Request {#ParentViewportWatcher.GetStatus_Request}
&lt;EMPTY&gt;
#### Response {#ParentViewportWatcher.GetStatus_Response}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>status</code></td>
<td>
<code><a class='link' href='#ParentViewportStatus'>ParentViewportStatus</a></code>
</td>
</tr>
</table>
## ScreenCapture {#ScreenCapture}
*Defined in [fuchsia.ui.composition/screen_capture.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/screen_capture.fidl;l=74)*
<p>This protocol provides a low-level ScreenCapture API for clients to use.
ScreenCapture clients should familiarize themselves with the
<a class='link' href='../fuchsia.sysmem/'>fuchsia.sysmem</a>/<a class='link' href='../fuchsia.sysmem/#BufferCollection'>BufferCollection</a> and <a class='link' href='../fuchsia.ui.composition/'>fuchsia.ui.composition</a>/<a class='link' href='../fuchsia.ui.composition/#Allocator'>Allocator</a> protocols
as those are necessary to create the BufferCollections and images ScreenCapture uses.</p>
### Configure {#ScreenCapture.Configure}
<p>Clients should first use the Allocator protocol to register a
BufferCollection. This function will fail with BAD_OPERATION unless all clients of the
BufferCollection have set their constraints.</p>
<p>Afterwards, clients should create and configure the images that will
eventually be rendered to using this method. All the buffers in the
collection from 0 to (buffer_count-1) may be used for screen capture.</p>
<p>Clients are responsible for determining the rotation of the display,
and applying the corrective rotation. For instance, if the display is
mounted 90 degrees clockwise (the &quot;top&quot; is on the right, when looking
at the display), then the client should specify a 270 degree rotation
to account for it.</p>
<p>Similarly, the clients are responsible for specifying a buffer big
enough for the rotated image. If the buffer is too small, a best effort
attempt will be made to render the image.</p>
<p>Finally, clients request the server to render the current screen to the
shared buffers using <a class='link' href='#GetNextFrame'>GetNextFrame</a>.</p>
<p><a class='link' href='#Configure'>Configure</a> can be called again with a new BufferCollectionImportToken
if the client wishes to change any of the configuration settings. In
this case all the buffers from the previous call to <a class='link' href='#Configure'>Configure</a> will
be released.</p>
#### Request {#ScreenCapture.Configure_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>payload</code></td>
<td>
<code><a class='link' href='#ScreenCaptureConfig'>ScreenCaptureConfig</a></code>
</td>
</tr>
</table>
#### Response {#ScreenCapture.Configure_Response}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>result</code></td>
<td>
<code><a class='link' href='#ScreenCapture_Configure_Result'>ScreenCapture_Configure_Result</a></code>
</td>
</tr>
</table>
### GetNextFrame {#ScreenCapture.GetNextFrame}
<p>Following a successful call to <a class='link' href='#Configure'>Configure</a>, clients can call
GetNextFrame. This will populate a buffer with the most recent frame.</p>
<p>Clients should wait on the zx::event they pass for successful
completion of the screenshot. It is not guaranteed that the screenshot
will be completed by the time this function returns.</p>
<p>The requested image will be in the BufferCollection that the client set
up in the VMO at the index specified by buffer_id.</p>
<p>When ScreenCapture is used to provide a stream, the rate that the
client calls GetNextFrame will drive the frame rate.</p>
<p>Errors:
BAD_OPERATION if Configure was not called, or not called successfully
MISSING_ARGS if a required argument is not present
BUFFER_FULL if all buffers in the BufferCollection are in use. In this case, ReleaseFrame
must be called to make a buffer available before this function can be called successfully.</p>
#### Request {#ScreenCapture.GetNextFrame_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>payload</code></td>
<td>
<code><a class='link' href='#GetNextFrameArgs'>GetNextFrameArgs</a></code>
</td>
</tr>
</table>
#### Response {#ScreenCapture.GetNextFrame_Response}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>result</code></td>
<td>
<code><a class='link' href='#ScreenCapture_GetNextFrame_Result'>ScreenCapture_GetNextFrame_Result</a></code>
</td>
</tr>
</table>
### ReleaseFrame {#ScreenCapture.ReleaseFrame}
<p>Once the client no longer needs an image, they can call ReleaseFrame on
the VMO index of the buffer so that the server can reuse it in the future.</p>
#### Request {#ScreenCapture.ReleaseFrame_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>buffer_id</code></td>
<td>
<code>uint32</code>
</td>
</tr>
</table>
#### Response {#ScreenCapture.ReleaseFrame_Response}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>result</code></td>
<td>
<code><a class='link' href='#ScreenCapture_ReleaseFrame_Result'>ScreenCapture_ReleaseFrame_Result</a></code>
</td>
</tr>
</table>
## Screenshot {#Screenshot}
*Defined in [fuchsia.ui.composition/screenshot.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/screenshot.fidl;l=20)*
<p>Collects the current graphical content of a display.</p>
<div class="fidl-version-div"><span class="fidl-attribute fidl-version">Added: HEAD</span></div>
### Take {#Screenshot.Take}
<p>Collects the current graphical content of a display in a specified buffer <code>format</code> in the
sRGB color space. Note that the sRGB color space is non-linear, meaning that unit tests
doing pixel equality checks making use of non-fully saturated colors should convert to a
linear color space.</p>
<p>TODO(fxbug.dev/114595): Link to fuchsia.dev documentation when it's up.</p>
<p>Screenshot is taken immediately, populated with the display's content from the most recent
VSYNC.</p>
<p>If the client calls <a class='link' href='#Take'>Take</a> a second time before a first <a class='link' href='#Take'>Take</a> call returns, the server
will close the Screenshot connection with a ZX_ERR_SHOULD_WAIT epitaph.</p>
<p>If capture fails due to an internal error, the server will close the Screenshot connection
with a ZX_ERR_INTERNAL epitaph.</p>
#### Request {#Screenshot.Take_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>payload</code></td>
<td>
<code><a class='link' href='#ScreenshotTakeRequest'>ScreenshotTakeRequest</a></code>
</td>
</tr>
</table>
#### Response {#Screenshot.Take_Response}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>payload</code></td>
<td>
<code><a class='link' href='#ScreenshotTakeResponse'>ScreenshotTakeResponse</a></code>
</td>
</tr>
</table>
## **STRUCTS**
### Allocator_RegisterBufferCollection_Response {#Allocator_RegisterBufferCollection_Response data-text="Allocator_RegisterBufferCollection_Response"}
*Defined in [fuchsia.ui.composition/allocator.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/allocator.fidl;l=108)*
&lt;EMPTY&gt;
### BufferCollectionExportToken [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#BufferCollectionExportToken data-text="BufferCollectionExportToken"}
*Defined in [fuchsia.ui.composition/allocator.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/allocator.fidl;l=15)*
<p>A typed wrapper for an eventpair, representing the registry endpoint of a buffer collection.</p>
<table>
<tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
<tr id="BufferCollectionExportToken.value">
<td><code>value</code></td>
<td>
<code>handle&lt;eventpair&gt;</code>
</td>
<td></td>
<td>No default</td>
</tr>
</table>
### BufferCollectionImportToken [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#BufferCollectionImportToken data-text="BufferCollectionImportToken"}
*Defined in [fuchsia.ui.composition/allocator.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/allocator.fidl;l=21)*
<p>A typed wrapper for an eventpair, representing the Image import endpoint of a buffer
collection.</p>
<table>
<tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
<tr id="BufferCollectionImportToken.value">
<td><code>value</code></td>
<td>
<code>handle&lt;eventpair&gt;</code>
</td>
<td></td>
<td>No default</td>
</tr>
</table>
### ColorRgba {#ColorRgba data-text="ColorRgba"}
*Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=50)*
<p>Represents a color with alpha channel.
Values are unorm (i.e. the valid range is [0,1]), and are in linear color
space. They are not gamma-corrected nor premultiplied.</p>
<table>
<tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
<tr id="ColorRgba.red">
<td><code>red</code></td>
<td>
<code>float32</code>
</td>
<td></td>
<td>No default</td>
</tr>
<tr id="ColorRgba.green">
<td><code>green</code></td>
<td>
<code>float32</code>
</td>
<td></td>
<td>No default</td>
</tr>
<tr id="ColorRgba.blue">
<td><code>blue</code></td>
<td>
<code>float32</code>
</td>
<td></td>
<td>No default</td>
</tr>
<tr id="ColorRgba.alpha">
<td><code>alpha</code></td>
<td>
<code>float32</code>
</td>
<td></td>
<td>No default</td>
</tr>
</table>
### ContentId {#ContentId data-text="ContentId"}
*Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=257)*
<p>A user-defined identifier for a particular piece of Content. See Content creation functions
(e.g. <a class='link' href='#CreateViewport'>CreateViewport</a>, <a class='link' href='#CreateImage'>CreateImage</a>) for more information.</p>
<table>
<tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
<tr id="ContentId.value">
<td><code>value</code></td>
<td>
<code>uint64</code>
</td>
<td></td>
<td>No default</td>
</tr>
</table>
### HitRegion {#HitRegion data-text="HitRegion"}
*Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=408)*
<p>An interactive area of a View, placed in the coordinate space of a specific Transform.</p>
<table>
<tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
<tr id="HitRegion.region">
<td><code>region</code></td>
<td>
<code><a class='link' href='../fuchsia.math/'>fuchsia.math</a>/<a class='link' href='../fuchsia.math/#RectF'>RectF</a></code>
</td>
<td><p>The position and size of this hit region, in the coordinate space of the Transform that owns
this hit region.</p>
</td>
<td>No default</td>
</tr>
<tr id="HitRegion.hit_test">
<td><code>hit_test</code></td>
<td>
<code><a class='link' href='#HitTestInteraction'>HitTestInteraction</a></code>
</td>
<td><p>The interaction behavior specified for this hit region.
To specify &quot;no interaction at all&quot;, remove this hit region from the owning Transform.</p>
</td>
<td>No default</td>
</tr>
</table>
### ScreenCapture_Configure_Response {#ScreenCapture_Configure_Response data-text="ScreenCapture_Configure_Response"}
*Defined in [fuchsia.ui.composition/screen_capture.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/screen_capture.fidl;l=100)*
&lt;EMPTY&gt;
### ScreenCapture_ReleaseFrame_Response {#ScreenCapture_ReleaseFrame_Response data-text="ScreenCapture_ReleaseFrame_Response"}
*Defined in [fuchsia.ui.composition/screen_capture.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/screen_capture.fidl;l=128)*
&lt;EMPTY&gt;
### TransformId {#TransformId data-text="TransformId"}
*Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=251)*
<p>A user-defined identifier for a particular transform. See <a class='link' href='#CreateTransform'>CreateTransform</a> and
<a class='link' href='#ReleaseTransform'>ReleaseTransform</a> for more information.</p>
<table>
<tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
<tr id="TransformId.value">
<td><code>value</code></td>
<td>
<code>uint64</code>
</td>
<td></td>
<td>No default</td>
</tr>
</table>
## **ENUMS**
### BlendMode [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#BlendMode data-text="BlendMode"}
Type: <code>uint32</code>
*Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=38)*
<p>The set of possible blending functions to choose from when determining how an image should
be composited on top of other images.</p>
<table>
<tr><th>Name</th><th>Value</th><th>Description</th></tr>
<tr id="BlendMode.SRC">
<td><h3 id="BlendMode.SRC" class="add-link hide-from-toc">SRC</h3></td>
<td><code>1</code></td>
<td><p>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.</p>
</td>
</tr>
<tr id="BlendMode.SRC_OVER">
<td><h3 id="BlendMode.SRC_OVER" class="add-link hide-from-toc">SRC_OVER</h3></td>
<td><code>2</code></td>
<td><p>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).</p>
</td>
</tr>
</table>
### ChildViewStatus [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#ChildViewStatus data-text="ChildViewStatus"}
Type: <code>uint32</code>
*Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=170)*
<table>
<tr><th>Name</th><th>Value</th><th>Description</th></tr>
<tr id="ChildViewStatus.CONTENT_HAS_PRESENTED">
<td><h3 id="ChildViewStatus.CONTENT_HAS_PRESENTED" class="add-link hide-from-toc">CONTENT_HAS_PRESENTED</h3></td>
<td><code>1</code></td>
<td><p>The underlying Flatland instance has connected its View, called <a class='link' href='#Present'>Present</a>, and the
acquisition fences of the <a class='link' href='#Present'>Present</a> 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).</p>
</td>
</tr>
</table>
### FlatlandError [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#FlatlandError data-text="FlatlandError"}
Type: <code>uint32</code>
*Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=14)*
<p>The set of error codes returned in <a class='link' href='#OnError'>OnError</a>. Everything except NO_ERROR, causes Flatland
channel to be closed.</p>
<table>
<tr><th>Name</th><th>Value</th><th>Description</th></tr>
<tr id="FlatlandError.BAD_OPERATION">
<td><h3 id="FlatlandError.BAD_OPERATION" class="add-link hide-from-toc">BAD_OPERATION</h3></td>
<td><code>1</code></td>
<td><p>Indicates that the parameters used the function calls are invalid.</p>
</td>
</tr>
<tr id="FlatlandError.NO_PRESENTS_REMAINING">
<td><h3 id="FlatlandError.NO_PRESENTS_REMAINING" class="add-link hide-from-toc">NO_PRESENTS_REMAINING</h3></td>
<td><code>2</code></td>
<td><p>Indicates that <code>additional_present_credits</code> field was not properly processed and the client
queued more <a class='link' href='#Present'>Present</a>s than allowed.</p>
</td>
</tr>
<tr id="FlatlandError.BAD_HANGING_GET">
<td><h3 id="FlatlandError.BAD_HANGING_GET" class="add-link hide-from-toc">BAD_HANGING_GET</h3></td>
<td><code>3</code></td>
<td><p>Indicates that the client has overwritten hanging gets in the protocols returned.</p>
</td>
</tr>
</table>
### HitTestInteraction [flexible](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#HitTestInteraction data-text="HitTestInteraction"}
Type: <code>uint8</code>
*Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=396)*
<p>The kind of hit test interaction expected for a hit region.</p>
<table>
<tr><th>Name</th><th>Value</th><th>Description</th></tr>
<tr id="HitTestInteraction.DEFAULT">
<td><h3 id="HitTestInteraction.DEFAULT" class="add-link hide-from-toc">DEFAULT</h3></td>
<td><code>0</code></td>
<td><p>The natural default behavior is for a hit region to interact with both regular hit testing
and accessibility hit testing.</p>
</td>
</tr>
<tr id="HitTestInteraction.SEMANTICALLY_INVISIBLE">
<td><h3 id="HitTestInteraction.SEMANTICALLY_INVISIBLE" class="add-link hide-from-toc">SEMANTICALLY_INVISIBLE</h3></td>
<td><code>1</code></td>
<td><p>Some use cases require that a hit region to interact with regular hit testing, but not
interact with accessibility hit testing. Here, &quot;semantics&quot; refers to accessibility's
semantic tree data, which describes UI elements in a View.</p>
</td>
</tr>
</table>
### ImageFlip [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#ImageFlip data-text="ImageFlip"}
Type: <code>uint32</code>
*Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=60)*
<p>The set of possible image flip functions to choose from when determining how the image texture
should be displayed.</p>
<div class="fidl-version-div"><span class="fidl-attribute fidl-version">Added: 10</span></div>
<table>
<tr><th>Name</th><th>Value</th><th>Description</th></tr>
<tr id="ImageFlip.NONE">
<td><h3 id="ImageFlip.NONE" class="add-link hide-from-toc">NONE</h3></td>
<td><code>0</code></td>
<td></td>
</tr>
<tr id="ImageFlip.LEFT_RIGHT">
<td><h3 id="ImageFlip.LEFT_RIGHT" class="add-link hide-from-toc">LEFT_RIGHT</h3></td>
<td><code>1</code></td>
<td><p>Let V be the vertical axis of reflection, positioned at width/2. Then each pixel's x
coordinate is reflected across V. The y coordinates remain constant. For instance:
|1234| |4321|
|abcd| would become |dcba|</p>
</td>
</tr>
<tr id="ImageFlip.UP_DOWN">
<td><h3 id="ImageFlip.UP_DOWN" class="add-link hide-from-toc">UP_DOWN</h3></td>
<td><code>2</code></td>
<td><p>Let H be the horizontal axis of reflection, positioned at height/2. Then each pixel's y
coordinate is reflected across H. The x coordinates remain constant. For instance:
|1234| |abcd|
|abcd| would become |1234|</p>
</td>
</tr>
</table>
### Orientation [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#Orientation data-text="Orientation"}
Type: <code>uint32</code>
*Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=29)*
<p>In Flatland, the +X axis is to the right and +Y axis is down. There is no notion of a Z axis.
Due to the lack of a Z axis, there is no mathematical notion of &quot;handedness&quot; (either right or
left) with respect to rotation. Thus, we define a counter-clockwise rotation in the same way
as if a skeuomorphic clock were to be displayed on the screen, with the hands of said clock
moving in a CCW motion from the POV of the observer.</p>
<table>
<tr><th>Name</th><th>Value</th><th>Description</th></tr>
<tr id="Orientation.CCW_0_DEGREES">
<td><h3 id="Orientation.CCW_0_DEGREES" class="add-link hide-from-toc">CCW_0_DEGREES</h3></td>
<td><code>1</code></td>
<td></td>
</tr>
<tr id="Orientation.CCW_90_DEGREES">
<td><h3 id="Orientation.CCW_90_DEGREES" class="add-link hide-from-toc">CCW_90_DEGREES</h3></td>
<td><code>2</code></td>
<td></td>
</tr>
<tr id="Orientation.CCW_180_DEGREES">
<td><h3 id="Orientation.CCW_180_DEGREES" class="add-link hide-from-toc">CCW_180_DEGREES</h3></td>
<td><code>3</code></td>
<td></td>
</tr>
<tr id="Orientation.CCW_270_DEGREES">
<td><h3 id="Orientation.CCW_270_DEGREES" class="add-link hide-from-toc">CCW_270_DEGREES</h3></td>
<td><code>4</code></td>
<td></td>
</tr>
</table>
### ParentViewportStatus [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#ParentViewportStatus data-text="ParentViewportStatus"}
Type: <code>uint32</code>
*Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=124)*
<p>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.</p>
<table>
<tr><th>Name</th><th>Value</th><th>Description</th></tr>
<tr id="ParentViewportStatus.CONNECTED_TO_DISPLAY">
<td><h3 id="ParentViewportStatus.CONNECTED_TO_DISPLAY" class="add-link hide-from-toc">CONNECTED_TO_DISPLAY</h3></td>
<td><code>1</code></td>
<td></td>
</tr>
<tr id="ParentViewportStatus.DISCONNECTED_FROM_DISPLAY">
<td><h3 id="ParentViewportStatus.DISCONNECTED_FROM_DISPLAY" class="add-link hide-from-toc">DISCONNECTED_FROM_DISPLAY</h3></td>
<td><code>2</code></td>
<td></td>
</tr>
</table>
### RegisterBufferCollectionError [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#RegisterBufferCollectionError data-text="RegisterBufferCollectionError"}
Type: <code>uint32</code>
*Defined in [fuchsia.ui.composition/allocator.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/allocator.fidl;l=10)*
<p>The set of error codes returned by Allocator::RegisterBufferCollection().</p>
<table>
<tr><th>Name</th><th>Value</th><th>Description</th></tr>
<tr id="RegisterBufferCollectionError.BAD_OPERATION">
<td><h3 id="RegisterBufferCollectionError.BAD_OPERATION" class="add-link hide-from-toc">BAD_OPERATION</h3></td>
<td><code>1</code></td>
<td></td>
</tr>
</table>
### RegisterBufferCollectionUsage [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#RegisterBufferCollectionUsage data-text="RegisterBufferCollectionUsage"}
Type: <code>uint32</code>
*Defined in [fuchsia.ui.composition/allocator.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/allocator.fidl;l=26)*
<p>The possible usages for registered buffer collection.</p>
<table>
<tr><th>Name</th><th>Value</th><th>Description</th></tr>
<tr id="RegisterBufferCollectionUsage.DEFAULT">
<td><h3 id="RegisterBufferCollectionUsage.DEFAULT" class="add-link hide-from-toc">DEFAULT</h3></td>
<td><code>0</code></td>
<td><p>DEFAULT means that the specified buffer collection will be used for
Flatland and gfx image creation.</p>
<p>See <a class='link' href='../fuchsia.ui.composition/'>fuchsia.ui.composition</a>/<a class='link' href='../fuchsia.ui.composition/#Flatland.CreateImage'>Flatland.CreateImage</a> for more.</p>
</td>
</tr>
<tr id="RegisterBufferCollectionUsage.SCREENSHOT">
<td><h3 id="RegisterBufferCollectionUsage.SCREENSHOT" class="add-link hide-from-toc">SCREENSHOT</h3></td>
<td><code>1</code></td>
<td><p>SCREENSHOT means that the specified buffer collection will be used for
screenshotting purposes.</p>
</td>
</tr>
</table>
### Rotation [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#Rotation data-text="Rotation"}
Type: <code>uint32</code>
*Defined in [fuchsia.ui.composition/screen_capture.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/screen_capture.fidl;l=33)*
<p>The rotation to be applied to the image.</p>
<p>If a given display is rotated, say, 270 degrees according to its
<code>display_info</code> config file, then applying the equal and opposite rotation,
<a class='link' href='#CW_270_DEGREES'>CW_270_DEGREES</a>, should cancel the display rotation leading to a
correctly rendered screenshot.</p>
<p>Clients should allocate an image according to the final dimensions they
ultimately want to use, i.e. after rotation. These would be identical
to the <code>width</code> and <code>height</code> values found in the <code>display_info</code> config file.</p>
<table>
<tr><th>Name</th><th>Value</th><th>Description</th></tr>
<tr id="Rotation.CW_0_DEGREES">
<td><h3 id="Rotation.CW_0_DEGREES" class="add-link hide-from-toc">CW_0_DEGREES</h3></td>
<td><code>0</code></td>
<td></td>
</tr>
<tr id="Rotation.CW_90_DEGREES">
<td><h3 id="Rotation.CW_90_DEGREES" class="add-link hide-from-toc">CW_90_DEGREES</h3></td>
<td><code>1</code></td>
<td></td>
</tr>
<tr id="Rotation.CW_180_DEGREES">
<td><h3 id="Rotation.CW_180_DEGREES" class="add-link hide-from-toc">CW_180_DEGREES</h3></td>
<td><code>2</code></td>
<td></td>
</tr>
<tr id="Rotation.CW_270_DEGREES">
<td><h3 id="Rotation.CW_270_DEGREES" class="add-link hide-from-toc">CW_270_DEGREES</h3></td>
<td><code>3</code></td>
<td></td>
</tr>
</table>
### ScreenCaptureError [flexible](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#ScreenCaptureError data-text="ScreenCaptureError"}
Type: <code>uint32</code>
*Defined in [fuchsia.ui.composition/screen_capture.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/screen_capture.fidl;l=10)*
<p>The possible errors from the ScreenCapture protocol.</p>
<table>
<tr><th>Name</th><th>Value</th><th>Description</th></tr>
<tr id="ScreenCaptureError.MISSING_ARGS">
<td><h3 id="ScreenCaptureError.MISSING_ARGS" class="add-link hide-from-toc">MISSING_ARGS</h3></td>
<td><code>1</code></td>
<td><p>One or more required arguments are missing in the table argument.</p>
</td>
</tr>
<tr id="ScreenCaptureError.INVALID_ARGS">
<td><h3 id="ScreenCaptureError.INVALID_ARGS" class="add-link hide-from-toc">INVALID_ARGS</h3></td>
<td><code>2</code></td>
<td><p>One or more of the arguments was not valid.</p>
</td>
</tr>
<tr id="ScreenCaptureError.BAD_OPERATION">
<td><h3 id="ScreenCaptureError.BAD_OPERATION" class="add-link hide-from-toc">BAD_OPERATION</h3></td>
<td><code>3</code></td>
<td><p>A general error occurred during the method call.</p>
</td>
</tr>
<tr id="ScreenCaptureError.BUFFER_FULL">
<td><h3 id="ScreenCaptureError.BUFFER_FULL" class="add-link hide-from-toc">BUFFER_FULL</h3></td>
<td><code>4</code></td>
<td><p>Error that is returned if <a class='link' href='#GetNextFrame'>GetNextFrame</a> is called when all of the VMOs in the
BufferCollection have been rendered to. <a class='link' href='#ReleaseFrame'>ReleaseFrame</a> must be called before a
successful call to GetNextFrame can be made.</p>
</td>
</tr>
</table>
### ScreenshotFormat [flexible](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#ScreenshotFormat data-text="ScreenshotFormat"}
Type: <code>uint8</code>
*Defined in [fuchsia.ui.composition/screenshot.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/screenshot.fidl;l=11)*
<p>The different formats of Screenshot that can be requested.</p>
<div class="fidl-version-div"><span class="fidl-attribute fidl-version">Added: HEAD</span></div>
<table>
<tr><th>Name</th><th>Value</th><th>Description</th></tr>
<tr id="ScreenshotFormat.BGRA_RAW">
<td><h3 id="ScreenshotFormat.BGRA_RAW" class="add-link hide-from-toc">BGRA_RAW</h3></td>
<td><code>0</code></td>
<td><p>The default format, requesting a tightly packed pixel data with 32 bit BGRA pixels.</p>
</td>
</tr>
</table>
## **TABLES**
### FrameInfo [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#FrameInfo data-text="FrameInfo"}
*Defined in [fuchsia.ui.composition/screen_capture.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/screen_capture.fidl;l=63)*
<p>Metadata about the frame rendered by <a class='link' href='#GetNextFrame'>GetNextFrame</a>.</p>
<table>
<tr><th>Ordinal</th><th>Field</th><th>Type</th><th>Description</th></tr>
<tr id="FrameInfo.buffer_id">
<td><h3 id="FrameInfo.buffer_id" class="add-link hide-from-toc">1</h3></td>
<td><code>buffer_id</code></td>
<td>
<code>uint32</code>
</td>
<td><p>The index of the VMO where the requested frame has been rendered. Required.</p>
</td>
</tr>
</table>
### GetNextFrameArgs [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#GetNextFrameArgs data-text="GetNextFrameArgs"}
*Defined in [fuchsia.ui.composition/screen_capture.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/screen_capture.fidl;l=57)*
<p>The arguments passed into the <a class='link' href='#GetNextFrame'>GetNextFrame</a> call. All fields are necessary.</p>
<table>
<tr><th>Ordinal</th><th>Field</th><th>Type</th><th>Description</th></tr>
<tr id="GetNextFrameArgs.event">
<td><h3 id="GetNextFrameArgs.event" class="add-link hide-from-toc">1</h3></td>
<td><code>event</code></td>
<td>
<code>handle&lt;event&gt;</code>
</td>
<td><p>The event that will signal when the requested frame has been rendered. Required.</p>
</td>
</tr>
</table>
### ImageProperties {#ImageProperties data-text="ImageProperties"}
*Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=244)*
<p>The properties of an Image as defined by the client. These properties determine how an Image
uses the backing BufferCollection. See <a class='link' href='#CreateImage'>CreateImage</a> for more information.</p>
<table>
<tr><th>Ordinal</th><th>Field</th><th>Type</th><th>Description</th></tr>
<tr id="ImageProperties.size">
<td><h3 id="ImageProperties.size" class="add-link hide-from-toc">1</h3></td>
<td><code>size</code></td>
<td>
<code><a class='link' href='../fuchsia.math/'>fuchsia.math</a>/<a class='link' href='../fuchsia.math/#SizeU'>SizeU</a></code>
</td>
<td><p>The size of the Image in pixels.</p>
</td>
</tr>
</table>
### LayoutInfo {#LayoutInfo data-text="LayoutInfo"}
*Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=78)*
<p>The return type of <a class='link' href='#GetLayout'>GetLayout</a>. 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 <a class='link' href='#Present'>Present</a>.</p>
<table>
<tr><th>Ordinal</th><th>Field</th><th>Type</th><th>Description</th></tr>
<tr id="LayoutInfo.logical_size">
<td><h3 id="LayoutInfo.logical_size" class="add-link hide-from-toc">1</h3></td>
<td><code>logical_size</code></td>
<td>
<code><a class='link' href='../fuchsia.math/'>fuchsia.math</a>/<a class='link' href='../fuchsia.math/#SizeU'>SizeU</a></code>
</td>
<td><p>The layout size of a View in logical pixels, defined by the parent's call to
<a class='link' href='#SetViewportProperties'>SetViewportProperties</a>.</p>
<p>The logical size also serves as the clip boundary of the View. Anything outside the clip
boundary will not be rendered. Hence, the View's Root Transform has a useful coordinate
space of (0, 0) to (logical_size.width, logical_size.height).</p>
<p>Clients should re-layout their content when this value changes.</p>
</td>
</tr>
<tr id="LayoutInfo.">
<td><h3 id="LayoutInfo." class="add-link hide-from-toc">2</h3></td>
<td><code>RESERVED</code></td>
<td>
<code></code>
</td>
<td><div class="fidl-version-div"><span class="fidl-attribute fidl-version">Added: 11</span></div>
</td>
</tr>
<tr id="LayoutInfo.device_pixel_ratio">
<td><h3 id="LayoutInfo.device_pixel_ratio" class="add-link hide-from-toc">3</h3></td>
<td><code>device_pixel_ratio</code></td>
<td>
<code><a class='link' href='../fuchsia.math/'>fuchsia.math</a>/<a class='link' href='../fuchsia.math/#VecF'>VecF</a></code>
</td>
<td><p>The ratio of display's physical pixels to device independent pixels. Each logical pixel of a
View 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, but
accommodate by reallocating their Image buffers to avoid sampling artifacts. The HiDPI-aware
client should allocate buffers that are sized (<code>logical_size</code>*<code>device_pixel_ratio</code>).</p>
<div class="fidl-version-div"><span class="fidl-attribute fidl-version">Added: 9</span></div>
</td>
</tr>
<tr id="LayoutInfo.inset">
<td><h3 id="LayoutInfo.inset" class="add-link hide-from-toc">4</h3></td>
<td><code>inset</code></td>
<td>
<code><a class='link' href='../fuchsia.math/'>fuchsia.math</a>/<a class='link' href='../fuchsia.math/#Inset'>Inset</a></code>
</td>
<td><p>The offsets between the edges and the visible rectangle of the View. The clients can assume
that the boundary region between the inset and the View edge is occluded, and should adjust
content layout to avoid this region. This inset is described in the view's logical
coordinate system. The HiDPI-aware clients should scale this by <code>device_pixel_ratio</code>.</p>
<div class="fidl-version-div"><span class="fidl-attribute fidl-version">Added: 9</span></div>
</td>
</tr>
</table>
### OnNextFrameBeginValues {#OnNextFrameBeginValues data-text="OnNextFrameBeginValues"}
*Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=358)*
<p>Fields that a client needs in order to produce its next frame, returned in
<a class='link' href='#OnNextFrameBegin'>OnNextFrameBegin</a>. Each field is guaranteed to be set and contain valid information.</p>
<table>
<tr><th>Ordinal</th><th>Field</th><th>Type</th><th>Description</th></tr>
<tr id="OnNextFrameBeginValues.additional_present_credits">
<td><h3 id="OnNextFrameBeginValues.additional_present_credits" class="add-link hide-from-toc">1</h3></td>
<td><code>additional_present_credits</code></td>
<td>
<code>uint32</code>
</td>
<td><p>The number of <em>additional</em> <a class='link' href='#Present'>Present</a> calls allowed to the client so that they
can call <a class='link' href='#Present'>Present</a> further times. This is a delta in the present
credit budget, not the absolute number of present credits.</p>
</td>
</tr>
<tr id="OnNextFrameBeginValues.future_presentation_infos">
<td><h3 id="OnNextFrameBeginValues.future_presentation_infos" class="add-link hide-from-toc">2</h3></td>
<td><code>future_presentation_infos</code></td>
<td>
<code><a class='link' href='#FuturePresentationInfos'>FuturePresentationInfos</a></code>
</td>
<td><p>Information about future presentation and latch times that a client may aim for
precise scheduling behavior.</p>
</td>
</tr>
</table>
### PresentArgs [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#PresentArgs data-text="PresentArgs"}
*Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=268)*
<p>Arguments passed into <a class='link' href='#Present'>Present</a>. All arguments are optional, and if an
argument is omitted Flatland will use a reasonable default, specified below.</p>
<table>
<tr><th>Ordinal</th><th>Field</th><th>Type</th><th>Description</th></tr>
<tr id="PresentArgs.requested_presentation_time">
<td><h3 id="PresentArgs.requested_presentation_time" class="add-link hide-from-toc">1</h3></td>
<td><code>requested_presentation_time</code></td>
<td>
<code><a class='link' href='../zx/'>zx</a>/<a class='link' href='../zx/#time'>time</a></code>
</td>
<td><p><code>requested_presentation_time</code> 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 <code>CLOCK_MONOTONIC</code> timebase.</p>
<p>The default <code>requested_presentation_time</code> is 0.</p>
<p>Using a <code>requested_presentation_time</code> 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.</p>
<p>Using a <code>requested_presentation_time</code> in the future schedules the enqueued operations to
take visible effect on or as closely as possible after the stated time, but no earlier.</p>
<p>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 <a class='link' href='#Present'>Present</a> whose
<code>requested_presentation_time</code> is on or before the frame's target presentation time.</p>
</td>
</tr>
<tr id="PresentArgs.acquire_fences">
<td><h3 id="PresentArgs.acquire_fences" class="add-link hide-from-toc">2</h3></td>
<td><code>acquire_fences</code></td>
<td>
<code>vector&lt;event&gt;[16]</code>
</td>
<td><p>Flatland will wait until all of a Flatland instance's <code>acquire_fences</code> are ready before it
will execute the presented commands. Not signaling <code>acquire_fences</code> will block the current
<a class='link' href='#Present'>Present</a> as well as the following ones even if their <code>acquire_fences</code> are signaled.</p>
<p>The default <code>acquire_fences</code> value is the empty vector.</p>
</td>
</tr>
<tr id="PresentArgs.release_fences">
<td><h3 id="PresentArgs.release_fences" class="add-link hide-from-toc">3</h3></td>
<td><code>release_fences</code></td>
<td>
<code>vector&lt;event&gt;[16]</code>
</td>
<td><p>Flatland will signal all <code>release_fences</code> when the resources and shared buffers from this
<a class='link' href='#Present'>Present</a> are no longer in use. Callers should not modify shared resources, such as
BufferCollections, until after these fences are signaled.</p>
<p>If an error occurs, release fences are not necessarily fired as Flatland can close the
client's instance at any point.</p>
<p>The default <code>release_fences</code> value is the empty vector.</p>
</td>
</tr>
<tr id="PresentArgs.unsquashable">
<td><h3 id="PresentArgs.unsquashable" class="add-link hide-from-toc">4</h3></td>
<td><code>unsquashable</code></td>
<td>
<code>bool</code>
</td>
<td><p>If <code>unsquashable</code> is true, then the update is guaranteed to be uniquely shown for at
least one vsync interval.</p>
<p>If <code>unsquashable</code> is false, then the update can be combined with those that come after
it.</p>
<p>If absent, <code>unsquashable</code> is false.</p>
</td>
</tr>
<tr id="PresentArgs.server_wait_fences">
<td><h3 id="PresentArgs.server_wait_fences" class="add-link hide-from-toc">5</h3></td>
<td><code>server_wait_fences</code></td>
<td>
<code>vector&lt;event&gt;[16]</code>
</td>
<td><p>Flatland will wait until all of a Flatland instance's <code>server_wait_fences</code> are ready before
it will execute the presented commands. Not signaling <code>server_wait_fences</code> will block the
current <a class='link' href='#Present'>Present</a> as well as the following ones even if their <code>server_wait_fences</code> are
signaled.</p>
<p>The default <code>server_wait_fences</code> value is the empty vector.</p>
</td>
</tr>
<tr id="PresentArgs.server_signal_fences">
<td><h3 id="PresentArgs.server_signal_fences" class="add-link hide-from-toc">6</h3></td>
<td><code>server_signal_fences</code></td>
<td>
<code>vector&lt;event&gt;[16]</code>
</td>
<td><p>(read this one carefully, it may be counter-intuitive)</p>
<p>Flatland will signal all <code>server_signal_fences</code> when the resources and shared buffers from
<em>the previous</em> <a class='link' href='#Present'>Present</a> 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.</p>
<p>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.</p>
<p>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.</p>
<p>The default <code>server_signal_fences</code> value is the empty vector.</p>
</td>
</tr>
</table>
### RegisterBufferCollectionArgs [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#RegisterBufferCollectionArgs data-text="RegisterBufferCollectionArgs"}
*Defined in [fuchsia.ui.composition/allocator.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/allocator.fidl;l=52)*
<p>The table of arguments for <a class='link' href='#RegisterBufferCollection'>RegisterBufferCollection</a>. Note that some
fields below are REQUIRED.</p>
<table>
<tr><th>Ordinal</th><th>Field</th><th>Type</th><th>Description</th></tr>
<tr id="RegisterBufferCollectionArgs.export_token">
<td><h3 id="RegisterBufferCollectionArgs.export_token" class="add-link hide-from-toc">1</h3></td>
<td><code>export_token</code></td>
<td>
<code><a class='link' href='#BufferCollectionExportToken'>BufferCollectionExportToken</a></code>
</td>
<td><p>Clients can send <a class='link' href='#export_token'>export_token</a> to register buffer collections with Allocator to be used
later in <a class='link' href='../fuchsia.ui.composition/'>fuchsia.ui.composition</a>/<a class='link' href='../fuchsia.ui.composition/#Flatland'>Flatland</a> instances or other Scenic APIs, such as
Screenshot.</p>
<p>For example, by passing a <a class='link' href='#BufferCollectionImportToken'>BufferCollectionImportToken</a> containing the matching peer of
<a class='link' href='#BufferCollectionExportToken'>BufferCollectionExportToken</a>, they can create image resources via
<a class='link' href='../fuchsia.ui.composition/'>fuchsia.ui.composition</a>/<a class='link' href='../fuchsia.ui.composition/#Flatland.CreateImage'>Flatland.CreateImage</a>.</p>
<p>Clients should wait for the response before using <code>import_token</code>.</p>
<p>This field is REQUIRED.</p>
</td>
</tr>
<tr id="RegisterBufferCollectionArgs.buffer_collection_token">
<td><h3 id="RegisterBufferCollectionArgs.buffer_collection_token" class="add-link hide-from-toc">2</h3></td>
<td><code>buffer_collection_token</code></td>
<td>
<code><a class='link' href='../fuchsia.sysmem/'>fuchsia.sysmem</a>/<a class='link' href='../fuchsia.sysmem/#BufferCollectionToken'>BufferCollectionToken</a></code>
</td>
<td><p>Flatland participates in the allocation of buffers by setting constraints on the
BufferCollection referenced by <code>buffer_collection_token</code>. It will not block on buffers
being allocated until the client creates content using the BufferCollection.</p>
<p>The buffer collection registered with <code>export_token</code> is available and kept alive as long
as the client holds a valid <a class='link' href='#BufferCollectionImportToken'>BufferCollectionImportToken</a>. They will be garbage collected
when all <a class='link' href='#BufferCollectionImportToken'>BufferCollectionImportToken</a>s are closed and all the associated Image resources
are released.</p>
<p>This field is REQUIRED.</p>
</td>
</tr>
<tr id="RegisterBufferCollectionArgs.usage">
<td><h3 id="RegisterBufferCollectionArgs.usage" class="add-link hide-from-toc">3</h3></td>
<td><code>usage</code></td>
<td>
<code><a class='link' href='#RegisterBufferCollectionUsage'>RegisterBufferCollectionUsage</a></code>
</td>
<td><p>The client can register a buffer collection for various uses, each
coming with their own unique constraints.</p>
<p>This field is OPTIONAL. If <code>usage</code> is omitted it will be treated as if
it has the DEFAULT option.</p>
<h1>Deprecation</h1>
<p>This arg is deprecated at API version 9 with addition of |usages|.</p>
<div class="fidl-version-div"><span class="fidl-attribute fidl-version">Deprecated: 9</span></div>
</td>
</tr>
<tr id="RegisterBufferCollectionArgs.usages">
<td><h3 id="RegisterBufferCollectionArgs.usages" class="add-link hide-from-toc">4</h3></td>
<td><code>usages</code></td>
<td>
<code><a class='link' href='#RegisterBufferCollectionUsages'>RegisterBufferCollectionUsages</a></code>
</td>
<td><p>The client can register a buffer collection for various uses and has the ability to
combine usages if multiple are needed.</p>
<p>This field is OPTIONAL. If <code>usages</code> is omitted it will be treated as if
it has only the DEFAULT option.</p>
<div class="fidl-version-div"><span class="fidl-attribute fidl-version">Added: 9</span></div>
</td>
</tr>
</table>
### ScreenCaptureConfig [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#ScreenCaptureConfig data-text="ScreenCaptureConfig"}
*Defined in [fuchsia.ui.composition/screen_capture.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/screen_capture.fidl;l=41)*
<p>The arguments passed into the <a class='link' href='#Configure'>Configure</a> call. Note that not all fields are necessary.</p>
<table>
<tr><th>Ordinal</th><th>Field</th><th>Type</th><th>Description</th></tr>
<tr id="ScreenCaptureConfig.import_token">
<td><h3 id="ScreenCaptureConfig.import_token" class="add-link hide-from-toc">1</h3></td>
<td><code>import_token</code></td>
<td>
<code><a class='link' href='#BufferCollectionImportToken'>BufferCollectionImportToken</a></code>
</td>
<td><p>The import token referencing a BufferCollection registered with
Allocator. Required.</p>
</td>
</tr>
<tr id="ScreenCaptureConfig.size">
<td><h3 id="ScreenCaptureConfig.size" class="add-link hide-from-toc">2</h3></td>
<td><code>size</code></td>
<td>
<code><a class='link' href='../fuchsia.math/'>fuchsia.math</a>/<a class='link' href='../fuchsia.math/#SizeU'>SizeU</a></code>
</td>
<td><p>The size of the image in pixels. Required.</p>
</td>
</tr>
<tr id="ScreenCaptureConfig.buffer_count">
<td><h3 id="ScreenCaptureConfig.buffer_count" class="add-link hide-from-toc">3</h3></td>
<td><code>buffer_count</code></td>
<td>
<code>uint32</code>
</td>
<td><p>The number of buffers in the BufferCollection. Required.</p>
</td>
</tr>
<tr id="ScreenCaptureConfig.rotation">
<td><h3 id="ScreenCaptureConfig.rotation" class="add-link hide-from-toc">4</h3></td>
<td><code>rotation</code></td>
<td>
<code><a class='link' href='#Rotation'>Rotation</a></code>
</td>
<td><p>The rotation to be applied to the stream of images. Optional; if absent no rotation is
applied.</p>
</td>
</tr>
</table>
### ScreenshotTakeRequest [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#ScreenshotTakeRequest data-text="ScreenshotTakeRequest"}
*Defined in [fuchsia.ui.composition/screenshot.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/screenshot.fidl;l=36)*
<table>
<tr><th>Ordinal</th><th>Field</th><th>Type</th><th>Description</th></tr>
<tr id="ScreenshotTakeRequest.format">
<td><h3 id="ScreenshotTakeRequest.format" class="add-link hide-from-toc">1</h3></td>
<td><code>format</code></td>
<td>
<code><a class='link' href='#ScreenshotFormat'>ScreenshotFormat</a></code>
</td>
<td><p>Format of the requested screenshot.</p>
</td>
</tr>
</table>
### ScreenshotTakeResponse [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#ScreenshotTakeResponse data-text="ScreenshotTakeResponse"}
*Defined in [fuchsia.ui.composition/screenshot.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/screenshot.fidl;l=39)*
<table>
<tr><th>Ordinal</th><th>Field</th><th>Type</th><th>Description</th></tr>
<tr id="ScreenshotTakeResponse.vmo">
<td><h3 id="ScreenshotTakeResponse.vmo" class="add-link hide-from-toc">1</h3></td>
<td><code>vmo</code></td>
<td>
<code>handle&lt;vmo&gt;</code>
</td>
<td><p>CPU mappable read-only VMO that contains screenshot data. The server owns the VMO and
may reuse for the next <a class='link' href='#Take'>Take</a>. The VMO is guaranteed to be accessible after mapping.
In some allocations, VMO::read() might not be available, i.e. on emulator.</p>
<p>Basic usage: After the client receives a VMO handle, to ensure data stability, it should
finish reading the VMO before calling <a class='link' href='#Take'>Take</a> again. When finished reading, the client
should drop the VMO handle.</p>
<p>Advanced usage: To edit the data, or to persist it beyond the next <a class='link' href='#Take'>Take</a> call, the
client should copy the data to a private VMO.</p>
</td>
</tr>
<tr id="ScreenshotTakeResponse.size">
<td><h3 id="ScreenshotTakeResponse.size" class="add-link hide-from-toc">2</h3></td>
<td><code>size</code></td>
<td>
<code><a class='link' href='../fuchsia.math/'>fuchsia.math</a>/<a class='link' href='../fuchsia.math/#SizeU'>SizeU</a></code>
</td>
<td><p>Size of the screenshot in pixels.</p>
</td>
</tr>
</table>
### ViewBoundProtocols [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#ViewBoundProtocols data-text="ViewBoundProtocols"}
*Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=370)*
<p>The protocol endpoints bound to a Flatland ViewCreationToken. These protocols operate on the
View that ViewCreationToken created in the Flatland session.</p>
<table>
<tr><th>Ordinal</th><th>Field</th><th>Type</th><th>Description</th></tr>
<tr id="ViewBoundProtocols.view_ref_focused">
<td><h3 id="ViewBoundProtocols.view_ref_focused" class="add-link hide-from-toc">1</h3></td>
<td><code>view_ref_focused</code></td>
<td>
<code>server_end&lt;<a class='link' href='../fuchsia.ui.views/'>fuchsia.ui.views</a>/<a class='link' href='../fuchsia.ui.views/#ViewRefFocused'>ViewRefFocused</a>&gt;</code>
</td>
<td><p>Learn when a View gains focus.</p>
<p>Server-bound ViewRef. The <a class='link' href='#view_ref_focused'>view_ref_focused</a> 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.</p>
</td>
</tr>
<tr id="ViewBoundProtocols.view_focuser">
<td><h3 id="ViewBoundProtocols.view_focuser" class="add-link hide-from-toc">2</h3></td>
<td><code>view_focuser</code></td>
<td>
<code>server_end&lt;<a class='link' href='../fuchsia.ui.views/'>fuchsia.ui.views</a>/<a class='link' href='../fuchsia.ui.views/#Focuser'>Focuser</a>&gt;</code>
</td>
<td><p>Enable a View to request focus transfer to a child (target) View.</p>
<p>Server-bound ViewRef. The <a class='link' href='#view_focuser'>view_focuser</a> client does not specify the &quot;requestor&quot; ViewRef
explicitly, only the &quot;target&quot; ViewRef. Instead, the server implementation uses the ViewRef
used in View creation as the &quot;requestor&quot; ViewRef.</p>
</td>
</tr>
<tr id="ViewBoundProtocols.touch_source">
<td><h3 id="ViewBoundProtocols.touch_source" class="add-link hide-from-toc">3</h3></td>
<td><code>touch_source</code></td>
<td>
<code>server_end&lt;<a class='link' href='../fuchsia.ui.pointer/'>fuchsia.ui.pointer</a>/<a class='link' href='../fuchsia.ui.pointer/#TouchSource'>TouchSource</a>&gt;</code>
</td>
<td><p>Receive touch events that are associated with a View.</p>
</td>
</tr>
<tr id="ViewBoundProtocols.mouse_source">
<td><h3 id="ViewBoundProtocols.mouse_source" class="add-link hide-from-toc">4</h3></td>
<td><code>mouse_source</code></td>
<td>
<code>server_end&lt;<a class='link' href='../fuchsia.ui.pointer/'>fuchsia.ui.pointer</a>/<a class='link' href='../fuchsia.ui.pointer/#MouseSource'>MouseSource</a>&gt;</code>
</td>
<td><p>Receive mouse events that are associated with a View.</p>
</td>
</tr>
</table>
### ViewportProperties {#ViewportProperties data-text="ViewportProperties"}
*Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=231)*
<p>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.
<code>ViewportProperties</code> must have <code>logical_size</code> set at least once. This is the initial size that
will drive the layout of the child.</p>
<table>
<tr><th>Ordinal</th><th>Field</th><th>Type</th><th>Description</th></tr>
<tr id="ViewportProperties.logical_size">
<td><h3 id="ViewportProperties.logical_size" class="add-link hide-from-toc">1</h3></td>
<td><code>logical_size</code></td>
<td>
<code><a class='link' href='../fuchsia.math/'>fuchsia.math</a>/<a class='link' href='../fuchsia.math/#SizeU'>SizeU</a></code>
</td>
<td><p>The size of the Viewport in logical pixels. This maps directly to the logical_size field in
LayoutInfo. The valid logical_size must have positive X and Y components.</p>
</td>
</tr>
<tr id="ViewportProperties.inset">
<td><h3 id="ViewportProperties.inset" class="add-link hide-from-toc">2</h3></td>
<td><code>inset</code></td>
<td>
<code><a class='link' href='../fuchsia.math/'>fuchsia.math</a>/<a class='link' href='../fuchsia.math/#Inset'>Inset</a></code>
</td>
<td><p>The offsets between the edges and the visible rectangle of the Viewport. This maps directly
to the <code>inset</code> field in LayoutInfo. The valid inset must have all components greater than or
equal to 0.</p>
<div class="fidl-version-div"><span class="fidl-attribute fidl-version">Added: 9</span></div>
</td>
</tr>
</table>
## **UNIONS**
### Allocator_RegisterBufferCollection_Result [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#Allocator_RegisterBufferCollection_Result data-text="Allocator_RegisterBufferCollection_Result"}
*Defined in [fuchsia.ui.composition/allocator.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/allocator.fidl;l=108)*
<table>
<tr><th>Ordinal</th><th>Variant</th><th>Type</th><th>Description</th></tr>
<tr id="Allocator_RegisterBufferCollection_Result.response">
<td><h3 id="Allocator_RegisterBufferCollection_Result.response" class="add-link hide-from-toc">1</h3></td>
<td><code>response</code></td>
<td>
<code><a class='link' href='#Allocator_RegisterBufferCollection_Response'>Allocator_RegisterBufferCollection_Response</a></code>
</td>
<td></td>
</tr>
<tr id="Allocator_RegisterBufferCollection_Result.err">
<td><h3 id="Allocator_RegisterBufferCollection_Result.err" class="add-link hide-from-toc">2</h3></td>
<td><code>err</code></td>
<td>
<code><a class='link' href='#RegisterBufferCollectionError'>RegisterBufferCollectionError</a></code>
</td>
<td></td>
</tr>
</table>
### ScreenCapture_Configure_Result [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#ScreenCapture_Configure_Result data-text="ScreenCapture_Configure_Result"}
*Defined in [fuchsia.ui.composition/screen_capture.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/screen_capture.fidl;l=100)*
<table>
<tr><th>Ordinal</th><th>Variant</th><th>Type</th><th>Description</th></tr>
<tr id="ScreenCapture_Configure_Result.response">
<td><h3 id="ScreenCapture_Configure_Result.response" class="add-link hide-from-toc">1</h3></td>
<td><code>response</code></td>
<td>
<code><a class='link' href='#ScreenCapture_Configure_Response'>ScreenCapture_Configure_Response</a></code>
</td>
<td></td>
</tr>
<tr id="ScreenCapture_Configure_Result.err">
<td><h3 id="ScreenCapture_Configure_Result.err" class="add-link hide-from-toc">2</h3></td>
<td><code>err</code></td>
<td>
<code><a class='link' href='#ScreenCaptureError'>ScreenCaptureError</a></code>
</td>
<td></td>
</tr>
</table>
### ScreenCapture_GetNextFrame_Result [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#ScreenCapture_GetNextFrame_Result data-text="ScreenCapture_GetNextFrame_Result"}
*Defined in [fuchsia.ui.composition/screen_capture.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/screen_capture.fidl;l=122)*
<table>
<tr><th>Ordinal</th><th>Variant</th><th>Type</th><th>Description</th></tr>
<tr id="ScreenCapture_GetNextFrame_Result.response">
<td><h3 id="ScreenCapture_GetNextFrame_Result.response" class="add-link hide-from-toc">1</h3></td>
<td><code>response</code></td>
<td>
<code><a class='link' href='#FrameInfo'>FrameInfo</a></code>
</td>
<td></td>
</tr>
<tr id="ScreenCapture_GetNextFrame_Result.err">
<td><h3 id="ScreenCapture_GetNextFrame_Result.err" class="add-link hide-from-toc">2</h3></td>
<td><code>err</code></td>
<td>
<code><a class='link' href='#ScreenCaptureError'>ScreenCaptureError</a></code>
</td>
<td></td>
</tr>
</table>
### ScreenCapture_ReleaseFrame_Result [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#ScreenCapture_ReleaseFrame_Result data-text="ScreenCapture_ReleaseFrame_Result"}
*Defined in [fuchsia.ui.composition/screen_capture.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/screen_capture.fidl;l=128)*
<table>
<tr><th>Ordinal</th><th>Variant</th><th>Type</th><th>Description</th></tr>
<tr id="ScreenCapture_ReleaseFrame_Result.response">
<td><h3 id="ScreenCapture_ReleaseFrame_Result.response" class="add-link hide-from-toc">1</h3></td>
<td><code>response</code></td>
<td>
<code><a class='link' href='#ScreenCapture_ReleaseFrame_Response'>ScreenCapture_ReleaseFrame_Response</a></code>
</td>
<td></td>
</tr>
<tr id="ScreenCapture_ReleaseFrame_Result.err">
<td><h3 id="ScreenCapture_ReleaseFrame_Result.err" class="add-link hide-from-toc">2</h3></td>
<td><code>err</code></td>
<td>
<code><a class='link' href='#ScreenCaptureError'>ScreenCaptureError</a></code>
</td>
<td></td>
</tr>
</table>
## **BITS**
### RegisterBufferCollectionUsages [flexible](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#RegisterBufferCollectionUsages}
Type: <code>uint16</code>
*Defined in [fuchsia.ui.composition/allocator.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/allocator.fidl;l=40)*
<p>The possible usages for a registered buffer collection. Can be a combination of options.</p>
<div class="fidl-version-div"><span class="fidl-attribute fidl-version">Added: 9</span></div>
<table>
<tr><th>Name</th><th>Value</th><th>Description</th></tr>
<tr id="RegisterBufferCollectionUsages.DEFAULT">
<td><h3 id="RegisterBufferCollectionUsages.DEFAULT" class="add-link hide-from-toc">DEFAULT</h3></td>
<td>1</td>
<td><p>The specified buffer collection can be used for Flatland and GFX image creation.</p>
<p>See <a class='link' href='../fuchsia.ui.composition/'>fuchsia.ui.composition</a>/<a class='link' href='../fuchsia.ui.composition/#Flatland.CreateImage'>Flatland.CreateImage</a> for more.</p>
</td>
</tr>
<tr id="RegisterBufferCollectionUsages.SCREENSHOT">
<td><h3 id="RegisterBufferCollectionUsages.SCREENSHOT" class="add-link hide-from-toc">SCREENSHOT</h3></td>
<td>2</td>
<td><p>The specified buffer collection can be used for screenshotting purposes.</p>
</td>
</tr>
</table>
## **CONSTANTS**
<table>
<tr><th>Name</th><th>Value</th><th>Type</th><th>Description</th></tr>
<tr id="MAX_ACQUIRE_RELEASE_FENCE_COUNT">
<td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=264">MAX_ACQUIRE_RELEASE_FENCE_COUNT</a></td>
<td>
<code>16</code>
</td>
<td><code>int32</code></td>
<td></td>
</tr>
<tr id="MAX_HIT_REGION_COUNT">
<td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=393">MAX_HIT_REGION_COUNT</a></td>
<td>
<code>64</code>
</td>
<td><code>int32</code></td>
<td><p>A maximum of 64 hit regions is enough for the expected usage of these APIs.</p>
</td>
</tr>
<tr id="MAX_PRESENT_ARGS_FENCE_COUNT">
<td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=262">MAX_PRESENT_ARGS_FENCE_COUNT</a></td>
<td>
<code>16</code>
</td>
<td><code>int32</code></td>
<td></td>
</tr>
</table>
## **ALIASES**
<table>
<tr><th>Name</th><th>Value</th><th>Description</th></tr>
<tr id="FuturePresentationInfos">
<td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=354">FuturePresentationInfos</a></td>
<td>
<code>vector</code>[<code>8</code>]</td>
<td><p>A user-defined identifier for future presentation info. A maximum of 8
future presentation counts is enough for the current usage of these APIs.</p>
</td>
</tr>
</table>