Added: 7 ## **PROTOCOLS** ## Allocator *Defined in [fuchsia.ui.composition/allocator.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/allocator.fidl;l=109)* ### RegisterBufferCollection 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. See [RegisterBufferCollectionArgs](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#RegisterBufferCollectionArgs) for information on each argument. #### Request | Name | Type | |---|---| | `args` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#RegisterBufferCollectionArgs` | #### Response | Name | Type | |---|---| | `payload` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Allocator_RegisterBufferCollection_Result` | ## ChildViewWatcher *Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=197)* A protocol that provides information about a particular child View which is attached to the Viewport owned by the parent client; connections to this protocol are estabished in [CreateViewport](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#CreateViewport). Since a Flatland session may contain any number of Viewports, each of which may or may not be attached to a transform, the client can maintain connections to an equal number of ChildViewWatcher instances. Each ChildViewWatcher instance will remain connected as long as the corresponding child View exists; the connection will also be closed if the child's ViewCreationToken is dropped without using it to create a View.
### GetStatus A hanging get for receiving the status of a View. This provides information to the parent, such as whether or not the child has successfully presented content through this View. This hanging get will only fire when the ChildViewStatus is different than the previously returned ChildViewStatus. This can happen immediately, and even if the creator of the Viewport hasn't yet called Present() after calling CreateViewport(). This allows the parent to know that the child has content ready to display before the parent modifies their own local scene graph to incorporate the child content. It is invalid to call `GetStatus` while a previous call is still pending. Doing so will cause both this channel and the Flatland channel that handed out ChildViewWatcher to be closed. #### Request \ #### Response | Name | Type | |---|---| | `status` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ChildViewStatus` | ### GetViewRef Hanging get to receive the ViewRef of the child View. This will only fire when the View ref is different from the previously-returned View ref. Note: currently the View ref will not change after it is first received, but this will change if/when the API changes to allow relinking of views. The ViewRef is not returned until the View is included in the View tree, in other words when there is a chain of ancestor transforms all the way back up to the root of the scene graph, i.e. the display. It is invalid to call `GetViewRef` while a previous call is still pending. Doing so will cause both this channel and the Flatland channel that handed out ChildViewWatcher to be closed. A `GetViewRef` call will hang if the View was created using `CreateView`, but returns the View if the View was created using CreateView2. This is because `CreateView` does not mint a ViewRef for that View. #### Request \ #### Response | Name | Type | |---|---| | `view_ref` | `https://fuchsia.dev/reference/fuchsia.ui.views//https://fuchsia.dev/reference/fuchsia.ui.views#ViewRef` | ## Flatland *Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=465)* Each Flatland session contains a Graph, which consists of a set of objects, and the relationships between those objects. The client can specify a subset of those objects (specifically, the directed acyclic graph starting at the root transform) to be presented as content to some kind of output -- usually, a display. Flatland Graphs are both hierarchical, and distributed. Graphs from different Flatland sessions may be connected together, allowing multiple processes to be involved in authoring content for a particular output. All functions in this protocol are feed-forward. The operations they represent are not fully executed until [Present](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Present) is called.
### AddChild Adds a child Transform to a parent Transform. The new child Transform, and any Content attached to it or its children, will be rendered on top of the parent's Content, as well as any previously added children. The caller must ensure that `child_transform_id` is valid and that there are no repetitions. Sending a repeated `child_transform_id` over multiple calls will result in session closure. #### Request | Name | Type | |---|---| | `parent_transform_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#TransformId` | | `child_transform_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#TransformId` | ### Clear 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. #### Request \ ### CreateFilledRect Creates a solid-color rectangle. By default a filled-rect does not have a defined color or size. It is necessary to call \|SetSolidFill\| to specify a color and size before a filled rect can be used for rendering. Not doing so will result the rectangle having a default size of (0,0) and so it will not show up when rendering. `rect_id` must satisfy standard [ContentId](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ContentId) creation constraints. Deprecated: 33 #### Request | Name | Type | |---|---| | `rect_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ContentId` | ### CreateImage An Image is a bitmap backed by a specific VMO in a BufferCollection. Image creation requires an allocated BufferCollection registered with Allocator. This function will fail unless all clients of the specified BufferCollection have set their constraints. The Image must reference a valid VMO index and must have ImageProperties that fall within the constraints specified by the backing BufferCollection (i.e. width and height within a valid range, etc.) `image_id` must satisfy standard [ContentId](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ContentId) creation constraints. Deprecated: 33 #### Request | Name | Type | |---|---| | `image_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ContentId` | | `import_token` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#BufferCollectionImportToken` | | `vmo_index` | `uint32` | | `properties` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ImageProperties` | ### CreateImage2 Creates an Image resource. `image_id` must satisfy the identifier rules documented on [LayerId](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerId). #### Request | Name | Type | |---|---| | `image_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ImageId` | | `import_token` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#BufferCollectionImportToken` | | `vmo_index` | `uint32` | | `properties` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ImageProperties` | ### CreateLayer A Layer is a type of `Content` that composites either a single `Image` or a solid color. It separates visual properties (such as size, flip, opacity, and blending) from the raw pixel data. Unlike typical `Content` items which represent a static visual resource, a Layer is designed to be a dynamic container for an image sequence. Typical usage involves setting the layer's visual properties and image metadata infrequently, and then rapidly swapping the active `Image` (e.g. on every frame) with another image of matching metadata. This separation allows a single `Image` resource to be reused across multiple layers with different visual configurations simultaneously. To use a Layer: 1. Create a `Layer` using [CreateLayer](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#CreateLayer). 2. Set properties on the `Layer` via [SetLayerProperties](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#SetLayerProperties), including the composition mode. 3. For an image layer, associate an `Image` with the `Layer` via [SetLayerImage](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#SetLayerImage). 4. Add the `Layer` to a `LayerStack` via [SetStackLayers](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#SetStackLayers). 5. Set the `LayerStack` as the content of a node via [SetTransformContent](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#SetTransformContent). `layer_id` must satisfy the identifier rules documented on [LayerId](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerId). #### Request | Name | Type | |---|---| | `layer_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerId` | ### CreateLayerStack Creates a new layer stack with the specified `stack_id`. `stack_id` must satisfy the identifier rules documented on [LayerId](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerId). #### Request | Name | Type | |---|---| | `stack_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerStackId` | ### CreateTransform Creates a new Transform node. Transforms are a hierarchical piece of a Flatland graph. They can have children, and can reference Content. A sub-graph represented by a Transform and its descendants can be rendered to a display. Transforms are kept alive, even when released, as long as they are children of either an unreleased Transform, or the Root Transform. Each Transform can have a single piece of attached Content. Common types of Content include bitmaps, asynchronous streams of images, and Viewports to Views hosted in other Flatland sessions. Transforms have attributes. Child Transforms inherit the combined attributes of their parents. Content attached to a Transform is also affected by that Transform's attributes. When a sub-graph of Transforms is rendered, Content will be rendered back-to-front, starting with the Content on the root transform, and continuing recursively through all of its child Transforms in the order the children were added. See [AddChild](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#AddChild) for more information. Zero is not a valid transform id. All other values are valid, assuming they are not already in use (see [ReleaseTransform](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ReleaseTransform) for more details). #### Request | Name | Type | |---|---| | `transform_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#TransformId` | ### CreateView Two Flatland sessions 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 session that creates a Viewport has control over how the child's View is integrated into its own View. The lifecycle of a parent-child connection starts with two endpoints of a channel object: a ViewportCreationToken and a ViewCreationToken. Out-of-band protocols pass the ViewportCreationToken to the parent, which calls [CreateViewport](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#CreateViewport), and the ViewCreationToken to the child, which calls [CreateView](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#CreateView). Only nodes connected to the Root Transform in this Flatland session will be rendered into the parent's Viewport. Calling [CreateView](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#CreateView) a second time will disconnect the Root Transform from the existing parent's Viewport, and attach it to a new parent's Viewport. In other words, each View can only have one parent. This function is queued, meaning that the Root Transform will not be attached to the parent Viewport until [Present](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Present) is called. However, clients will receive information through their ParentViewportWatcher (e.g., LayoutInfo) immediately after calling this function, even if they have not called [Present](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Present) or [SetRootTransform](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#SetRootTransform). This allows clients to wait for layout information from their parent before calling [Present](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Present). Any illegal operations on ParentViewportWatcher will cause both ParentViewportWatcher channel and this Flatland channel to be torn down. Lifecycle note. The lifetime of the ParentViewportWatcher channel is bound by the peer ViewportCreationToken. When the ViewportCreationToken dies, this ParentViewportWatcher channel is destroyed. Views and subgraphs of Views created using `CreateView` 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 `CreateView` to know that they are excluded from the ViewTree. #### Request | Name | Type | |---|---| | `token` | `https://fuchsia.dev/reference/fuchsia.ui.views//https://fuchsia.dev/reference/fuchsia.ui.views#ViewCreationToken` | | `parent_viewport_watcher` | `server_end:https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ParentViewportWatcher` | ### CreateView2 Identical to [CreateView](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#CreateView), except it allows association of View identity (ViewRef) and view-bound protocols. #### Request | Name | Type | |---|---| | `token` | `https://fuchsia.dev/reference/fuchsia.ui.views//https://fuchsia.dev/reference/fuchsia.ui.views#ViewCreationToken` | | `view_identity` | `https://fuchsia.dev/reference/fuchsia.ui.views//https://fuchsia.dev/reference/fuchsia.ui.views#ViewIdentityOnCreation` | | `protocols` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ViewBoundProtocols` | | `parent_viewport_watcher` | `server_end:https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ParentViewportWatcher` | ### CreateViewport The Viewport and View pair, together, represent the connection between two Flatland sessions. The Viewport is created in the parent, and the View is created in the child. The parent has control over how the child's View is integrated into its own View. Any illegal operations on ChildViewWatcher will cause both ChildViewWatcher channel and this Flatland channel to be torn down. `ViewportProperties` must have logical_size set. This is the initial size that will drive the layout of the child. The logical_size is also used as the default Content size, but subsequent changes to the logical_size will have no effect on the Content size. `ViewportProperties` may have inset field not set. In that case, the default value of (0, 0, 0, 0) is used. The logical_size must have positive X and Y components. Lifecycle note. The lifetime of the ChildViewWatcher channel is bound by the peer ViewCreationToken. When the ViewCreationToken dies, this ChildViewWatcher channel is destroyed. `viewport_id` must satisfy standard [ContentId](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ContentId) creation constraints. Deprecated: 33 #### Request | Name | Type | |---|---| | `viewport_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ContentId` | | `token` | `https://fuchsia.dev/reference/fuchsia.ui.views//https://fuchsia.dev/reference/fuchsia.ui.views#ViewportCreationToken` | | `properties` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ViewportProperties` | | `child_view_watcher` | `server_end:https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ChildViewWatcher` | ### CreateViewport2 Creates a Viewport resource. `viewport_id` must satisfy the identifier rules documented on [LayerId](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerId). #### Request | Name | Type | |---|---| | `viewport_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ViewportId` | | `token` | `https://fuchsia.dev/reference/fuchsia.ui.views//https://fuchsia.dev/reference/fuchsia.ui.views#ViewportCreationToken` | | `properties` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ViewportProperties` | | `child_view_watcher` | `server_end:https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ChildViewWatcher` | ### OnError If an error occurs after a [Present](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Present), an `OnError` event will fire with associated information. FlatlandErrors will close the connection with the client. - response `error` the error a client may receive after performing some invalid operations. #### Response | Name | Type | |---|---| | `error` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#FlatlandError` | ### OnFramePresented This event is fired whenever a set of one or more [Present](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Present)s are presented simultaneously, and are therefore no longer in flight. This event signifies that the commands enqueued before the [Present](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Present) have taken effect in the scene graph, and are globally visible. Clients do NOT have to implement a handler for this event for basic frame scheduling, unless they explicitly want feedback on prior frame presentation. All future frame information is given in the [OnNextFrameBegin](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#OnNextFrameBegin) event. TODO(https://fxbug.dev/42141795): remove `num_presents_allowed` from this event. #### Response | Name | Type | |---|---| | `frame_presented_info` | `https://fuchsia.dev/reference/fuchsia.scenic.scheduling//https://fuchsia.dev/reference/fuchsia.scenic.scheduling#FramePresentedInfo` | ### OnNextFrameBegin This event is fired when clients should expect minimal resource contention. Clients may use the timing of this event to begin their rendering work, using the information returned to inform their scheduling decisions. Importantly, OnNextFrameBegin is only fired when the client has one or more present credits, including what is returned in this event. It is therefore safe to present once every time this event fires. - response `values` the table of information a client needs to produce its next frame. See [OnNextFrameBeginValues](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#OnNextFrameBeginValues) for more information. #### Response | Name | Type | |---|---| | `values` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#OnNextFrameBeginValues` | ### Present Complete execution of all feed-forward operations. If executing an operation produces an error (e.g., CreateTransform(0)), an [OnError](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#OnError) event is emitted. Operations that produce errors are ignored and the channel is closed. If execution completes successfully, [OnNextFrameBegin](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#OnNextFrameBegin) is emitted with valid frame production information. The client may only call [Present](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Present) when they have a non-zero number of present credits, which are tracked by the server. The server may increment the number of credits when it fires the [OnNextFrameBegin](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#OnNextFrameBegin) event, which informs the client when it receives additional present credits. Each [Present](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Present) call uses one present credit and decrements the server count by one. If the client calls [Present](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Present) with no present credits, the server will return a `NO_PRESENTS_REMAINING` error. The client should assume that prior to receiving any [OnNextFrameBegin](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#OnNextFrameBegin) events, they have one present credit. Every [Present](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Present) call results in one [OnNextFrameBegin](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#OnNextFrameBegin) event, and one [OnFramePresented](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#OnFramePresented) event, typically in that order. When the commands flushed by [Present](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Present) make it to display, an [OnFramePresented](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#OnFramePresented) event is fired. This event includes information pertaining to all [Present](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Present)s that had content that were part of that frame. See [fuchsia.ui.composition](https://fuchsia.dev/reference/fuchsia.ui.composition/)/[PresentArgs](https://fuchsia.dev/reference/fuchsia.ui.composition/#PresentArgs) documentation above for more detailed information on what arguments are passed in and their role. #### Request | Name | Type | |---|---| | `args` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#PresentArgs` | ### ReleaseFilledRect 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. `rect_id` must refer to a valid, unreleased filled rectangle. Deprecated: 33 #### Request | Name | Type | |---|---| | `rect_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ContentId` | ### ReleaseImage Released Images will be garbage collected by the system once they are no longer necessary for rendering. For Images, this means the Image is no longer attached to any Transform and any pending rendering that references the Image is complete. Use SetContent(transform_id, 0) to clean up references to released Images. Once released, the id immediately goes out of scope for future function calls and can be reused when creating new Images. It is an error to call functions with a released id (unless that id has been reused to construct a new Image). Deprecated: 33 #### Request | Name | Type | |---|---| | `image_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ContentId` | ### ReleaseImage2 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 bound to any Layer, and - any pending rendering that references the Image is complete. The `image_id` value is freed for reuse immediately by the client (identifier uniqueness is instantaneous). Note: Per-binding release fences (passed to `SetLayerImage`) are unaffected by this call. They track the lifecycle of individual layer bindings, not the client's `image_id`. `image_id` must refer to a valid, unreleased Image. #### Request | Name | Type | |---|---| | `image_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ImageId` | ### ReleaseImageImmediately Releases an image immediately, without waiting for the next present. #### Request | Name | Type | |---|---| | `image_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ContentId` | ### ReleaseImageImmediately2 Releases an Image immediately, without waiting for the next present. This is a trusted memory-eviction path. The Image is forcibly unbound from any Layers that currently reference it. Those Layers behave as if their image was simply never set (they are invisible, but retain their image properties) until their next `SetLayerImage()`. Any pending release fences for the evicted Image's bindings will signal at the earliest safe point. This method is only available if Flatland2 is enabled and the session is trusted. #### Request | Name | Type | |---|---| | `image_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ImageId` | ### ReleaseLayer Released Layers will be garbage collected by the system once they are no longer necessary for rendering. For Layers, this means: - the Layer is no longer referenced by any LayerStack, and - any pending rendering that references the Layer is complete. `layer_id` must refer to a valid, unreleased Layer. #### Request | Name | Type | |---|---| | `layer_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerId` | ### ReleaseLayerStack Releases the layer stack with the specified `stack_id`. #### Request | Name | Type | |---|---| | `stack_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerStackId` | ### ReleaseTransform Released Transforms will be garbage collected by the system once they are no longer necessary for rendering. For Transforms, this means there is no path from any unreleased Transform to the newly-released Transform. Once released, the id immediately goes out of scope for future function calls and can be reused when creating new Transforms. It is an error to call functions with a released id (unless that id has been reused to construct a new Transform). #### Request | Name | Type | |---|---| | `transform_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#TransformId` | ### ReleaseView Releases the View, which disconnects this Flatland session from its parent Viewport in another Flatland session. To clear the existing content from the screen without releasing the current View, use SetRootTransform(0) instead. Despite having a return type, this function is still feed-forward Like [CreateView](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#CreateView) and requires a call to [Present](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Present) to be executed. The ViewCreationToken will be returned after the presented operations have been executed. #### Request \ ### ReleaseViewport Releases a Viewport from the scene, even if the Viewport is still connected to a Transform. Unlike other resources, Viewports are garbage collected by the system during the next [Present](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Present) because a removed Viewport is guaranteed to provide no renderable content. Use SetContent(transform_id, 0) to clean up references to released Viewports. Despite having a return type, this function is still feed-forward like [CreateView](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#CreateView) and requires a call to [Present](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Present) to be executed. The ViewportCreationToken will be returned after the presented operations have been executed. Deprecated: 33 #### Request | Name | Type | |---|---| | `viewport_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ContentId` | #### Response | Name | Type | |---|---| | `token` | `https://fuchsia.dev/reference/fuchsia.ui.views//https://fuchsia.dev/reference/fuchsia.ui.views#ViewportCreationToken` | ### ReleaseViewport2 Releases a Viewport from the scene. #### Request | Name | Type | |---|---| | `viewport_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ViewportId` | #### Response | Name | Type | |---|---| | `token` | `https://fuchsia.dev/reference/fuchsia.ui.views//https://fuchsia.dev/reference/fuchsia.ui.views#ViewportCreationToken` | ### RemoveChild Removes a child Transform from a parent Transform. #### Request | Name | Type | |---|---| | `parent_transform_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#TransformId` | | `child_transform_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#TransformId` | ### ReplaceChildren Removes all child Transforms from a parent Transform and replaces them with the new child transforms in `new_child_transform_ids`. The caller must ensure that all `TransformId` values in `new_child_transform_ids` are valid and that there are no repetitions. Sending a repeated `TransformId` in `new_child_transform_ids` will result in session closure. #### Request | Name | Type | |---|---| | `parent_transform_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#TransformId` | | `new_child_transform_ids` | `vector:64` | ### ResetLayer Unbinds any Image bound to the layer and clears every stored [LayerProperties](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerProperties) field, returning the layer to its freshly-created state (composition mode `INVISIBLE`, all properties at their documented defaults). This is the only operation which forgets stored layer properties. `layer_id` must refer to a valid, unreleased Layer. #### Request | Name | Type | |---|---| | `layer_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerId` | ### SetClipBoundary 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 sessions 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. #### Request | Name | Type | |---|---| | `transform_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#TransformId` | | `rect` | `https://fuchsia.dev/reference/fuchsia.math//https://fuchsia.dev/reference/fuchsia.math#Rect?` | ### SetContent Setting a piece of Content on a Transform makes that Content visible in the render tree as long as the Transform is visible from the root Transform. The Content will be rendered before, and therefore "behind", any Content attached to the descendants of the Transform. Because each Transform can have, at most, a single piece of Content on it, calling this function on a Transform that already has Content will replace that Content. A Content may be set on more than one Transform. Calling this function with a Content id of 0 will remove any Content currently on the Transform. `content_id` must refer to a valid, unreleased Content object, or 0 to clear. Deprecated: 33 #### Request | Name | Type | |---|---| | `transform_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#TransformId` | | `content_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ContentId` | ### SetDebugName Set debug name of the current client that can be used by Flatland to print as a prefix to logs to help client distinguish what is theirs. [name](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#name) can be an arbitrary string, but the current process name (see fsl::GetCurrentProcessName()) is a good default. #### Request | Name | Type | |---|---| | `name` | `string:64` | ### SetHitRegions 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 session can synchronize Content and hit regions. Each hit region is placed in the coordinate space of the owning Transform, and may or may not interact with different types of hit testing, depending on its [HitTestInteraction](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#HitTestInteraction) type. When there are multiple hit regions that intersect with a hit test, the precedence rules given below dictate which hit region has interacted with the hit test. Only Transforms that transitively connect to the root Transform have their hit regions interact with a hit test. Calling this function replaces any previous values set on this Transform. To reset a Transform to "no hit testing": send an empty vector with [SetHitRegions](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#SetHitRegions). Note that root transforms get a default hit region installed by Flatland. For more details, see the [SetRootTransform](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#SetRootTransform) documentation. Precedence rules Within a Transform, if multiple hit regions overlap, the hit test examines each intersecting hit region for a possible interaction. Thus, for a regular hit test R and an accessibility hit test A, where R and A both intersect two hit regions D ([DEFAULT](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#DEFAULT)) and S ([SEMANTICALLY_INVISIBLE](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#SEMANTICALLY_INVISIBLE)) on the same Transform, (1) R interacts with both D and S, and (2) A only interacts with D. Generally, hit regions that overlap in a single Transform can cause confusing behavior. Within a View, for a given hit test, the front-most Transform's hit regions take precedence over those behind. This follows the expected reverse "render order" of Transforms (described in [CreateTransform](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#CreateTransform)), where a user expects to interact with Content that is visible, or front-most. Across Flatland sessions, for a given hit test, the front-most session's front-most Transform's hit regions take precedence over those behind. This follows the expected reverse "render order" of views, where a user expects to interact with the View that is visible, or front-most. For example, if a child View owns Content that is rendered over the parent View, the user expects to interact with the child's Content. #### Request | Name | Type | |---|---| | `transform_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#TransformId` | | `regions` | `vector:64` | ### SetImageBlendMode Determines the blend function to use when rendering the content specified by \|image_id\|. \|image_id\| must be a valid ContentId associated to a transform through a call to \|CreateImage\| or \|CreateFilledRect\|. For details on the different blend functions that are available, please refer to the BlendMode2 enum. If this function is not called, the default blendmode is BlendMode2::REPLACE. Deprecated: 33 Added: 29 #### Request | Name | Type | |---|---| | `image_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ContentId` | | `blend_mode` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#BlendMode2` | ### SetImageBlendingFunction Determines the blend function to use when rendering the content specified by \|image_id\|. \|image_id\| must be a valid ContentId associated to a transform through a call to \|CreateImage\| or \|CreateFilledRect\|. 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. Deprecated: 33 #### Request | Name | Type | |---|---| | `image_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ContentId` | | `blend_mode` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#BlendMode` | ### SetImageDestinationSize 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. If this method is not called, the default image destination size is the width and height set at ImageProperties from [CreateImage](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#CreateImage). The destination size will be affected by scaling if [SetScale](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#SetScale) is used on the attached Transform or its parents. Deprecated: 33 #### Request | Name | Type | |---|---| | `image_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ContentId` | | `size` | `https://fuchsia.dev/reference/fuchsia.math//https://fuchsia.dev/reference/fuchsia.math#SizeU` | ### SetImageFlip 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. Deprecated: 33 #### Request | Name | Type | |---|---| | `image_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ContentId` | | `flip` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ImageFlip` | ### SetImageOpacity Sets an opacity in linear space to be applied to a flatland image. Opacity values must be in the range \[0.0, 1.0\]. Deprecated: 33 #### Request | Name | Type | |---|---| | `image_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ContentId` | | `val` | `float32` | ### SetImageSampleRegion This function is used to determine the region (in texel space) of an image that will be used by Flatland when rendering. The image to be sampled is referenced by [image_id](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#image_id) and the sample region is specified by [rect](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#rect) which itself is comprised of an origin point (x,y) as well as a width and height, in unnormalized coordinates. It is illegal to call this function on non-image content, or to sample a region outside of the texel space of the image. In other words, the region specifed by [rect](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#rect) must not exceed the ranges (0, image_width) and (0, image_height). If (rect.x + rect.width \> image_width) or (rect.y + rect.height \> image_height) or if any of the values are negative, this will result in an error. 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 [CreateImage](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#CreateImage). `image_id` must refer to a valid, unreleased Image. Deprecated: 33 #### Request | Name | Type | |---|---| | `image_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ContentId` | | `rect` | `https://fuchsia.dev/reference/fuchsia.math//https://fuchsia.dev/reference/fuchsia.math#RectF` | ### SetInfiniteHitRegion Identical to [SetHitRegions](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#SetHitRegions), except the hit region associated with [transform_id](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#transform_id) covers an infinite region. The hit region is invariant against translation, scaling, and orientation of the Transform. An infinite hit region is still limited in extent by the View's clip boundary, just like a finite hit region. Calling this function replaces any previous values set on this Transform. To reset a Transform to "no hit testing": send an empty vector with [SetHitRegions](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#SetHitRegions). #### Request | Name | Type | |---|---| | `transform_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#TransformId` | | `hit_test` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#HitTestInteraction` | ### SetLayerImage Associates an Image with the Layer. The binding is legal in any composition mode, and is sticky: it survives composition mode changes, and is replaced only by a later [SetLayerImage](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#SetLayerImage) call (or cleared by [ResetLayer](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ResetLayer)). The image is displayed only while the layer's composition mode is `IMAGE`. The bound image must be large enough for the layer's stored `sample_rect`; this is checked at [fuchsia.ui.composition](https://fuchsia.dev/reference/fuchsia.ui.composition/)/[Flatland.Present](https://fuchsia.dev/reference/fuchsia.ui.composition/#Flatland.Present), not here. See [LayerProperties.sample_rect](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerProperties.sample_rect). `layer_id` must refer to a valid, unreleased Layer. `image_id` must refer to a valid, unreleased Image. `acquire_fence` is an optional fence that must be signaled before the image is displayed. `release_fence` is an optional fence, signaled by Scenic when *this binding* no longer references the image. It is per-binding, not per-image: an image bound to several layers has one such fence per binding, and the image is safe to write only once every one of them has signaled. A binding is ended by: - being superseded by a later [SetLayerImage](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#SetLayerImage) on the same layer - [ResetLayer](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ResetLayer) - the layer ref-count reaching zero, either via [ReleaseLayer](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ReleaseLayer) or by being released by a layer stack - destruction of the session, which ends every binding it holds For a binding ended while the session is alive, Scenic signals at the first frame retire after that point. Bindings that never reached the screen (e.g. one superseded within a single batch, or one lost when several [fuchsia.ui.composition](https://fuchsia.dev/reference/fuchsia.ui.composition/)/[Flatland.Present](https://fuchsia.dev/reference/fuchsia.ui.composition/#Flatland.Present) calls are squashed into a single frame) signal at that same retire rather than immediately. The signal is therefore conservative by at most one frame; it is never early. #### Request | Name | Type | |---|---| | `layer_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerId` | | `image_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ImageId` | | `acquire_fence` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#WaitFence?` | | `release_fence` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#SignalFence?` | ### SetLayerProperties Sets properties of the Layer. The provided `properties` table is merged into the layer's stored properties: fields which are unset in `properties` retain their previously stored values. Stored properties are sticky; see [LayerProperties](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerProperties) for the full persistence semantics. Values are stored as given; validation which depends on other state (notably `sample_rect` against the bound image) happens at [fuchsia.ui.composition](https://fuchsia.dev/reference/fuchsia.ui.composition/)/[Flatland.Present](https://fuchsia.dev/reference/fuchsia.ui.composition/#Flatland.Present). See [LayerProperties.sample_rect](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerProperties.sample_rect). `layer_id` must refer to a valid, unreleased Layer. #### Request | Name | Type | |---|---| | `layer_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerId` | | `properties` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerProperties` | ### SetOpacity 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. #### Request | Name | Type | |---|---| | `transform_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#TransformId` | | `value` | `float32` | ### SetOrientation Sets the orientation on a Transform. The order of geometric attribute application is addressed in the documentation for [SetTranslation](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#SetTranslation). 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. #### Request | Name | Type | |---|---| | `transform_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#TransformId` | | `orientation` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Orientation` | ### SetRootTransform Sets the Root Transform for the graph. The sub-graph defined by the Root Transform and its children will be rendered as View in the connected parent's Viewport (see [CreateView](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#CreateView)). Any parents of the Root Transform in this Graph will be ignored. The Root Transform, and all children of the Root Transform, are kept alive if they are released (see [ReleaseTransform](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ReleaseTransform) for more details). There is only ever one Root. Since 0 is not a valid transform id (see [CreateTransform](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#CreateTransform)), calling SetRootTransform(0) clears the current Root, destroying any previously released objects that are not referenced by the new root. 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. Setting the root transform installs a full screen hit region on the root transform. Clients may remove this hit region if they don't want users to be able to interact with the root transform's content. For additional details on hit regions, see the [SetHitRegions](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#SetHitRegions) documentation. Default hit region rules A default hit region follows these rules: - When [SetRootTransform](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#SetRootTransform)(T) is called, T receives a maximal hit region, covering the entire view. - If [SetHitRegions](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#SetHitRegions) is called on T, either before or after [SetRootTransform](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#SetRootTransform)(T), then no default hit region is active and the client specified hit regions are used. - If a transform is no longer the root transform, i.e., [SetRootTransform](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#SetRootTransform)(U) is called, then the original transform no longer has its default hit region. - Clients can remove or modify the root transform's hit regions the same way they would reset any other transform's hit regions, by calling [SetHitRegions](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#SetHitRegions) with the appropriate vector. #### Request | Name | Type | |---|---| | `transform_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#TransformId` | ### SetScale 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 positive 32-bit floating point values: https://en.wikipedia.org/wiki/Normal_number_%28computing%29 #### Request | Name | Type | |---|---| | `transform_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#TransformId` | | `scale` | `https://fuchsia.dev/reference/fuchsia.math//https://fuchsia.dev/reference/fuchsia.math#VecF` | ### SetSolidFill 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). `rect_id` must refer to a valid, unreleased filled rectangle. Deprecated: 33 #### Request | Name | Type | |---|---| | `rect_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ContentId` | | `color` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ColorRgba` | | `size` | `https://fuchsia.dev/reference/fuchsia.math//https://fuchsia.dev/reference/fuchsia.math#SizeU` | ### SetStackLayers Sets the layers in the stack. The order of layers in the vector determines their Z-order, with the first element being the back-most and the last element being the front-most. `stack_id` must refer to a valid, unreleased LayerStack. Each element of `layers` must refer to a valid, unreleased Layer. Duplicate layers within `layers` are disallowed. #### Request | Name | Type | |---|---| | `stack_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerStackId` | | `layers` | `vector:32` | ### SetTransformContent Sets (or clears) the content of a Transform. The same content may be attached to more than one Transform; each attachment composites that content again under its own Transform's matrix, clip, and opacity, so a single LayerStack or Viewport can appear repeatedly in a scene without the client duplicating the underlying resources. A Transform's content can be cleared by not providing the optional `content`. If `content` is set, it must refer to a valid, unreleased LayerStack or Viewport. Unlike classic [Flatland.SetContent](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Flatland.SetContent), a zero id does not clear the content. #### Request | Name | Type | |---|---| | `transform_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#TransformId` | | `content` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#TransformContent?` | ### SetTranslation All Transform objects support all attributes. Geometric attributes are applied in the following order: 1. Scale (relative to the parent transform's coordinate space) 2. Orientation (relative to the parent transform's coordinate space) 3. Translation (relative to the parent transforms's coordinate space, unaffected by scale applied to the current transform). 4. Clipping (relative to the current transform's coordinate space) The effects of each of these attributes are cumulative. This means the transform's position in the view space, and its clip boundary, will be calculated based on that chain of geometric attributes going up to the root transform. For instance, in a nested hierarchy such as the following: \[Root-Transform -\> Transform1 -\> Transform2 -\> CurrentTransform\] If Transform1 is translated by \[2,0\] and Transform2 is translated by \[0,1\] then the view-space position of CurrentTransform will be \[2,1\]. Sets the translation on a Transform. The order of geometric attribute application is addressed above. #### Request | Name | Type | |---|---| | `transform_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#TransformId` | | `translation` | `https://fuchsia.dev/reference/fuchsia.math//https://fuchsia.dev/reference/fuchsia.math#Vec` | ### SetViewportProperties 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. Deprecated: 33 #### Request | Name | Type | |---|---| | `viewport_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ContentId` | | `properties` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ViewportProperties` | ### SetViewportProperties2 Sets the properties of a Viewport. #### Request | Name | Type | |---|---| | `viewport_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ViewportId` | | `properties` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ViewportProperties` | ## Flatland2 *Defined in [fuchsia.ui.composition/flatland2.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland2.fidl;l=289)* This protocol is composed into the "classic" [Flatland](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Flatland) protocol, and cleans up some "warts" in the original design. All methods defined in this protocol are ONLY available when Flatland2 is enabled (e.g. via [TrustedFlatlandConfig.use_flatland2_api](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#TrustedFlatlandConfig.use_flatland2_api)). Calling these methods when Flatland2 is not enabled will result in a channel closure. Broadly speaking, the "warts" involve properties that are set on images when they shouldn't be. For example, it should be possible to display two copies of the same image side by side, with one image flipped `LEFT_RIGHT` to reflect the other. This is impossible in the classic Flatland API, because the flip is a property of the image. In Flatland2, the flip is a property of the layer, and the client's goal is easily achieved with two layers with the same image and different flips. Certain "classic" Flatland methods are disabled/illegal when Flatland2 is enabled. Eventually these methods will be removed; Flatland2 will be the standard way to display images in Flatland. Until then, this "opt in" approach provides clients with a convenient way to migrate to this modernized API. The disabled methods are: - [fuchsia.ui.composition](https://fuchsia.dev/reference/fuchsia.ui.composition/)/[Flatland.CreateFilledRect](https://fuchsia.dev/reference/fuchsia.ui.composition/#Flatland.CreateFilledRect) - [fuchsia.ui.composition](https://fuchsia.dev/reference/fuchsia.ui.composition/)/[Flatland.CreateImage](https://fuchsia.dev/reference/fuchsia.ui.composition/#Flatland.CreateImage) - [fuchsia.ui.composition](https://fuchsia.dev/reference/fuchsia.ui.composition/)/[Flatland.CreateViewport](https://fuchsia.dev/reference/fuchsia.ui.composition/#Flatland.CreateViewport) - [fuchsia.ui.composition](https://fuchsia.dev/reference/fuchsia.ui.composition/)/[Flatland.ReleaseFilledRect](https://fuchsia.dev/reference/fuchsia.ui.composition/#Flatland.ReleaseFilledRect) - [fuchsia.ui.composition](https://fuchsia.dev/reference/fuchsia.ui.composition/)/[Flatland.ReleaseImage](https://fuchsia.dev/reference/fuchsia.ui.composition/#Flatland.ReleaseImage) - [fuchsia.ui.composition](https://fuchsia.dev/reference/fuchsia.ui.composition/)/[Flatland.ReleaseViewport](https://fuchsia.dev/reference/fuchsia.ui.composition/#Flatland.ReleaseViewport) - [fuchsia.ui.composition](https://fuchsia.dev/reference/fuchsia.ui.composition/)/[Flatland.SetContent](https://fuchsia.dev/reference/fuchsia.ui.composition/#Flatland.SetContent) - [fuchsia.ui.composition](https://fuchsia.dev/reference/fuchsia.ui.composition/)/[Flatland.SetImageBlendingFunction](https://fuchsia.dev/reference/fuchsia.ui.composition/#Flatland.SetImageBlendingFunction) - [fuchsia.ui.composition](https://fuchsia.dev/reference/fuchsia.ui.composition/)/[Flatland.SetImageBlendMode](https://fuchsia.dev/reference/fuchsia.ui.composition/#Flatland.SetImageBlendMode) - [fuchsia.ui.composition](https://fuchsia.dev/reference/fuchsia.ui.composition/)/[Flatland.SetImageDestinationSize](https://fuchsia.dev/reference/fuchsia.ui.composition/#Flatland.SetImageDestinationSize) - [fuchsia.ui.composition](https://fuchsia.dev/reference/fuchsia.ui.composition/)/[Flatland.SetImageFlip](https://fuchsia.dev/reference/fuchsia.ui.composition/#Flatland.SetImageFlip) - [fuchsia.ui.composition](https://fuchsia.dev/reference/fuchsia.ui.composition/)/[Flatland.SetImageOpacity](https://fuchsia.dev/reference/fuchsia.ui.composition/#Flatland.SetImageOpacity) - [fuchsia.ui.composition](https://fuchsia.dev/reference/fuchsia.ui.composition/)/[Flatland.SetSolidFill](https://fuchsia.dev/reference/fuchsia.ui.composition/#Flatland.SetSolidFill) - [fuchsia.ui.composition](https://fuchsia.dev/reference/fuchsia.ui.composition/)/[Flatland.SetImageSampleRegion](https://fuchsia.dev/reference/fuchsia.ui.composition/#Flatland.SetImageSampleRegion) - [fuchsia.ui.composition](https://fuchsia.dev/reference/fuchsia.ui.composition/)/[Flatland.SetViewportProperties](https://fuchsia.dev/reference/fuchsia.ui.composition/#Flatland.SetViewportProperties) - [fuchsia.ui.composition](https://fuchsia.dev/reference/fuchsia.ui.composition/)/[TrustedFlatland.ReleaseImageImmediately](https://fuchsia.dev/reference/fuchsia.ui.composition/#TrustedFlatland.ReleaseImageImmediately) Added: HEAD
### CreateImage2 Creates an Image resource. `image_id` must satisfy the identifier rules documented on [LayerId](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerId). #### Request | Name | Type | |---|---| | `image_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ImageId` | | `import_token` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#BufferCollectionImportToken` | | `vmo_index` | `uint32` | | `properties` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ImageProperties` | ### CreateLayer A Layer is a type of `Content` that composites either a single `Image` or a solid color. It separates visual properties (such as size, flip, opacity, and blending) from the raw pixel data. Unlike typical `Content` items which represent a static visual resource, a Layer is designed to be a dynamic container for an image sequence. Typical usage involves setting the layer's visual properties and image metadata infrequently, and then rapidly swapping the active `Image` (e.g. on every frame) with another image of matching metadata. This separation allows a single `Image` resource to be reused across multiple layers with different visual configurations simultaneously. To use a Layer: 1. Create a `Layer` using [CreateLayer](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#CreateLayer). 2. Set properties on the `Layer` via [SetLayerProperties](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#SetLayerProperties), including the composition mode. 3. For an image layer, associate an `Image` with the `Layer` via [SetLayerImage](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#SetLayerImage). 4. Add the `Layer` to a `LayerStack` via [SetStackLayers](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#SetStackLayers). 5. Set the `LayerStack` as the content of a node via [SetTransformContent](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#SetTransformContent). `layer_id` must satisfy the identifier rules documented on [LayerId](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerId). #### Request | Name | Type | |---|---| | `layer_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerId` | ### CreateLayerStack Creates a new layer stack with the specified `stack_id`. `stack_id` must satisfy the identifier rules documented on [LayerId](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerId). #### Request | Name | Type | |---|---| | `stack_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerStackId` | ### CreateViewport2 Creates a Viewport resource. `viewport_id` must satisfy the identifier rules documented on [LayerId](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerId). #### Request | Name | Type | |---|---| | `viewport_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ViewportId` | | `token` | `https://fuchsia.dev/reference/fuchsia.ui.views//https://fuchsia.dev/reference/fuchsia.ui.views#ViewportCreationToken` | | `properties` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ViewportProperties` | | `child_view_watcher` | `server_end:https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ChildViewWatcher` | ### ReleaseImage2 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 bound to any Layer, and - any pending rendering that references the Image is complete. The `image_id` value is freed for reuse immediately by the client (identifier uniqueness is instantaneous). Note: Per-binding release fences (passed to `SetLayerImage`) are unaffected by this call. They track the lifecycle of individual layer bindings, not the client's `image_id`. `image_id` must refer to a valid, unreleased Image. #### Request | Name | Type | |---|---| | `image_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ImageId` | ### ReleaseLayer Released Layers will be garbage collected by the system once they are no longer necessary for rendering. For Layers, this means: - the Layer is no longer referenced by any LayerStack, and - any pending rendering that references the Layer is complete. `layer_id` must refer to a valid, unreleased Layer. #### Request | Name | Type | |---|---| | `layer_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerId` | ### ReleaseLayerStack Releases the layer stack with the specified `stack_id`. #### Request | Name | Type | |---|---| | `stack_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerStackId` | ### ReleaseViewport2 Releases a Viewport from the scene. #### Request | Name | Type | |---|---| | `viewport_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ViewportId` | #### Response | Name | Type | |---|---| | `token` | `https://fuchsia.dev/reference/fuchsia.ui.views//https://fuchsia.dev/reference/fuchsia.ui.views#ViewportCreationToken` | ### ResetLayer Unbinds any Image bound to the layer and clears every stored [LayerProperties](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerProperties) field, returning the layer to its freshly-created state (composition mode `INVISIBLE`, all properties at their documented defaults). This is the only operation which forgets stored layer properties. `layer_id` must refer to a valid, unreleased Layer. #### Request | Name | Type | |---|---| | `layer_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerId` | ### SetLayerImage Associates an Image with the Layer. The binding is legal in any composition mode, and is sticky: it survives composition mode changes, and is replaced only by a later [SetLayerImage](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#SetLayerImage) call (or cleared by [ResetLayer](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ResetLayer)). The image is displayed only while the layer's composition mode is `IMAGE`. The bound image must be large enough for the layer's stored `sample_rect`; this is checked at [fuchsia.ui.composition](https://fuchsia.dev/reference/fuchsia.ui.composition/)/[Flatland.Present](https://fuchsia.dev/reference/fuchsia.ui.composition/#Flatland.Present), not here. See [LayerProperties.sample_rect](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerProperties.sample_rect). `layer_id` must refer to a valid, unreleased Layer. `image_id` must refer to a valid, unreleased Image. `acquire_fence` is an optional fence that must be signaled before the image is displayed. `release_fence` is an optional fence, signaled by Scenic when *this binding* no longer references the image. It is per-binding, not per-image: an image bound to several layers has one such fence per binding, and the image is safe to write only once every one of them has signaled. A binding is ended by: - being superseded by a later [SetLayerImage](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#SetLayerImage) on the same layer - [ResetLayer](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ResetLayer) - the layer ref-count reaching zero, either via [ReleaseLayer](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ReleaseLayer) or by being released by a layer stack - destruction of the session, which ends every binding it holds For a binding ended while the session is alive, Scenic signals at the first frame retire after that point. Bindings that never reached the screen (e.g. one superseded within a single batch, or one lost when several [fuchsia.ui.composition](https://fuchsia.dev/reference/fuchsia.ui.composition/)/[Flatland.Present](https://fuchsia.dev/reference/fuchsia.ui.composition/#Flatland.Present) calls are squashed into a single frame) signal at that same retire rather than immediately. The signal is therefore conservative by at most one frame; it is never early. #### Request | Name | Type | |---|---| | `layer_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerId` | | `image_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ImageId` | | `acquire_fence` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#WaitFence?` | | `release_fence` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#SignalFence?` | ### SetLayerProperties Sets properties of the Layer. The provided `properties` table is merged into the layer's stored properties: fields which are unset in `properties` retain their previously stored values. Stored properties are sticky; see [LayerProperties](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerProperties) for the full persistence semantics. Values are stored as given; validation which depends on other state (notably `sample_rect` against the bound image) happens at [fuchsia.ui.composition](https://fuchsia.dev/reference/fuchsia.ui.composition/)/[Flatland.Present](https://fuchsia.dev/reference/fuchsia.ui.composition/#Flatland.Present). See [LayerProperties.sample_rect](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerProperties.sample_rect). `layer_id` must refer to a valid, unreleased Layer. #### Request | Name | Type | |---|---| | `layer_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerId` | | `properties` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerProperties` | ### SetStackLayers Sets the layers in the stack. The order of layers in the vector determines their Z-order, with the first element being the back-most and the last element being the front-most. `stack_id` must refer to a valid, unreleased LayerStack. Each element of `layers` must refer to a valid, unreleased Layer. Duplicate layers within `layers` are disallowed. #### Request | Name | Type | |---|---| | `stack_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerStackId` | | `layers` | `vector:32` | ### SetTransformContent Sets (or clears) the content of a Transform. The same content may be attached to more than one Transform; each attachment composites that content again under its own Transform's matrix, clip, and opacity, so a single LayerStack or Viewport can appear repeatedly in a scene without the client duplicating the underlying resources. A Transform's content can be cleared by not providing the optional `content`. If `content` is set, it must refer to a valid, unreleased LayerStack or Viewport. Unlike classic [Flatland.SetContent](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Flatland.SetContent), a zero id does not clear the content. #### Request | Name | Type | |---|---| | `transform_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#TransformId` | | `content` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#TransformContent?` | ### SetViewportProperties2 Sets the properties of a Viewport. #### Request | Name | Type | |---|---| | `viewport_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ViewportId` | | `properties` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ViewportProperties` | ## FlatlandDisplay *Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=1131)* This API connects to the singleton "primary display", and allows a tree of Flatland content to be attached underneath. Only one FlatlandDisplay client connection is allowed at one time.
### SetContent #### Request | Name | Type | |---|---| | `token` | `https://fuchsia.dev/reference/fuchsia.ui.views//https://fuchsia.dev/reference/fuchsia.ui.views#ViewportCreationToken` | | `child_view_watcher` | `server_end:https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ChildViewWatcher` | ### SetDevicePixelRatio 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 [LayoutInfo.device_pixel_ratio](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayoutInfo.device_pixel_ratio) for details. The default value is (1.0, 1.0). The valid values are 1.0 and above. #### Request | Name | Type | |---|---| | `device_pixel_ratio` | `https://fuchsia.dev/reference/fuchsia.math//https://fuchsia.dev/reference/fuchsia.math#VecF` | ## FlatlandFactory *Defined in [fuchsia.ui.composition/flatland_factory.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland_factory.fidl;l=28)* Factory protocol for spawning regular (untrusted) Flatland sessions. Added: HEAD
### CreateFlatland Creates a new Flatland session with the specified configuration. Clients should optimistically assume connection success and immediately begin pipelining [fuchsia.ui.composition](https://fuchsia.dev/reference/fuchsia.ui.composition/)/[Flatland](https://fuchsia.dev/reference/fuchsia.ui.composition/#Flatland) requests without waiting for this method to return. If session creation fails, the [fuchsia.ui.composition](https://fuchsia.dev/reference/fuchsia.ui.composition/)/[FlatlandFactory](https://fuchsia.dev/reference/fuchsia.ui.composition/#FlatlandFactory) server closes the `Flatland` session channel and returns a [fuchsia.ui.composition](https://fuchsia.dev/reference/fuchsia.ui.composition/)/[FlatlandFactoryError](https://fuchsia.dev/reference/fuchsia.ui.composition/#FlatlandFactoryError). Clients should asynchronously handle this failure and discard their `Flatland` client endpoint. ## Error Returns a `FlatlandFactoryError` if the operation fails. #### Request | Name | Type | |---|---| | `server_end` | `server_end:https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Flatland` | | `config` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#FlatlandConfig` | #### Response | Name | Type | |---|---| | `payload` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#FlatlandFactory_CreateFlatland_Result` | ## ParentViewportWatcher *Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=145)* A protocol that provides information about the parent Viewport attached to a Flatland session's sole View. Although Flatland sessions can have at most one view, it is possible to have multiple ParentViewportWatchers during the brief transition period when replacing the session's View with another, e.g. via [CreateView](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#CreateView). During this period, certain updates may be duplicated and sent to each ParentViewportWatcher connection. A ParentViewportWatcher will remain connected as long as the corresponding parent Viewport exists; the connection will also be closed if the parents's ViewportCreationToken is dropped without using it to create a Viewport.
### GetLayout A hanging get for receiving layout information. Clients may receive layout information before the ParentViewportWatcher operation has been presented. This allows children to layout their content before their first call to [Present](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Present). In transition cases where two ParentViewportWatcher channels exist at the same time, both protocol sessions will be receiving different layout information. This hanging get will only fire when the LayoutInfo is different than the previously returned LayoutInfo. Note that, since LayoutInfo is a table, only some fields may have changed. It is invalid to call `GetLayout` while a previous call is still pending. Doing so will cause both this channel and the Flatland channel that handed out ParentViewportWatcher to be closed. #### Request \ #### Response | Name | Type | |---|---| | `info` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayoutInfo` | ### GetStatus A hanging get for receiving the status of the parent Viewport. This provides global connectivity information to the child. This hanging get will only fire when the ParentViewportStatus is different than the previously returned ParentViewportStatus. It is invalid to call `GetStatus` while a previous call is still pending. Doing so will cause both this channel and the Flatland channel that handed out ParentViewportWatcher to be closed. #### Request \ #### Response | Name | Type | |---|---| | `status` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ParentViewportStatus` | ## 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=75)* This protocol provides a low-level ScreenCapture API for clients to use. ScreenCapture clients should familiarize themselves with the [fuchsia.sysmem](https://fuchsia.dev/reference/fuchsia.sysmem/)/[BufferCollection](https://fuchsia.dev/reference/fuchsia.sysmem/#BufferCollection) and [fuchsia.ui.composition](https://fuchsia.dev/reference/fuchsia.ui.composition/)/[Allocator](https://fuchsia.dev/reference/fuchsia.ui.composition/#Allocator) protocols as those are necessary to create the BufferCollections and images ScreenCapture uses.
### Configure 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. 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. 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 "top" is on the right, when looking at the display), then the client should specify a 270 degree rotation to account for it. 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. Finally, clients request the server to render the current screen to the shared buffers using [GetNextFrame](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#GetNextFrame). [Configure](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Configure) 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 [Configure](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Configure) will be released. #### Request | Name | Type | |---|---| | `payload` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ScreenCaptureConfig` | #### Response | Name | Type | |---|---| | `payload` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ScreenCapture_Configure_Result` | ### GetNextFrame Following a successful call to [Configure](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Configure), clients can call GetNextFrame. This will populate a buffer with the most recent frame. 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. The requested image will be in the BufferCollection that the client set up in the VMO at the index specified by buffer_id. When ScreenCapture is used to provide a stream, the rate that the client calls GetNextFrame will drive the frame rate. 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. #### Request | Name | Type | |---|---| | `payload` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#GetNextFrameArgs` | #### Response | Name | Type | |---|---| | `payload` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ScreenCapture_GetNextFrame_Result` | ### ReleaseFrame 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. #### Request | Name | Type | |---|---| | `buffer_id` | `uint32` | #### Response | Name | Type | |---|---| | `payload` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ScreenCapture_ReleaseFrame_Result` | ## Screenshot *Defined in [fuchsia.ui.composition/screenshot.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/screenshot.fidl;l=24)* Collects the current graphical content of a display.
### Take Collects the current graphical content of a display in a specified buffer `format` 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. See https://fuchsia.dev/fuchsia-src/concepts/ui/scenic/color_spaces for more information. Screenshot is taken immediately, populated with the display's content from the most recent VSYNC. If the client calls [Take](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Take) a second time before a first [Take](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Take) call returns, the server will close the Screenshot connection with a ZX_ERR_SHOULD_WAIT epitaph. If capture fails due to an internal error, the server will close the Screenshot connection with a ZX_ERR_INTERNAL epitaph. #### Request | Name | Type | |---|---| | `payload` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ScreenshotTakeRequest` | #### Response | Name | Type | |---|---| | `payload` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ScreenshotTakeResponse` | ### TakeFile Collects the current graphical content of a display in a specified buffer `format` 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. TODO(https://fxbug.dev/42065844): Link to fuchsia.dev documentation when it's up. Screenshot is taken immediately, populated with the display's content from the most recent VSYNC. If the client calls [TakeFile](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#TakeFile) a second time before a first [TakeFile](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#TakeFile) call returns, the server will close the Screenshot connection with a ZX_ERR_SHOULD_WAIT epitaph. If capture fails due to an internal error, the server will close the Screenshot connection with a ZX_ERR_INTERNAL epitaph. This call should be used if the client is on the host and does not support VMOs, as is the case for ffx tools. #### Request | Name | Type | |---|---| | `payload` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ScreenshotTakeFileRequest` | #### Response | Name | Type | |---|---| | `payload` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ScreenshotTakeFileResponse` | ## TrustedFlatland *Defined in [fuchsia.ui.composition/trusted_flatland_factory.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/trusted_flatland_factory.fidl;l=83)* A privileged protocol for trusted Flatland sessions that require special capabilities. This protocol is composed into the \[Flatland\] protocol. Methods in this protocol are only available if the Flatland session was created via \[TrustedFlatlandFactory\]. Added: HEAD
### ReleaseImageImmediately Releases an image immediately, without waiting for the next present. #### Request | Name | Type | |---|---| | `image_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ContentId` | ### ReleaseImageImmediately2 Releases an Image immediately, without waiting for the next present. This is a trusted memory-eviction path. The Image is forcibly unbound from any Layers that currently reference it. Those Layers behave as if their image was simply never set (they are invisible, but retain their image properties) until their next `SetLayerImage()`. Any pending release fences for the evicted Image's bindings will signal at the earliest safe point. This method is only available if Flatland2 is enabled and the session is trusted. #### Request | Name | Type | |---|---| | `image_id` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ImageId` | ## TrustedFlatlandFactory *Defined in [fuchsia.ui.composition/trusted_flatland_factory.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/trusted_flatland_factory.fidl;l=63)* A privileged factory for creating Flatland sessions with special configurations. This protocol is intended for trusted clients that require fine-grained control over Flatland's behavior for performance-critical applications. It is not intended for general use. Misuse of this API can negatively impact system performance and stability. Added: HEAD
### CreateFlatland Creates a new Flatland session with the specified configuration. ## Error Returns a \[TrustedFlatlandFactoryError\] error if the operation fails. #### Request | Name | Type | |---|---| | `server_end` | `server_end:https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Flatland` | | `config` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#TrustedFlatlandConfig` | #### Response | Name | Type | |---|---| | `payload` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#TrustedFlatlandFactory_CreateFlatland_Result` | ## **STRUCTS** ### 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=117)* \ ### BufferCollectionExportToken [resource](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#value-vs-resource) *Defined in [fuchsia.ui.composition/allocator.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/allocator.fidl;l=17)* A typed wrapper for an eventpair, representing the registry endpoint of a buffer collection.
| Field | Type | Description | Default | |---|---|---|---| | `value` | `handle` | | No default | ### BufferCollectionImportToken [resource](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#value-vs-resource) *Defined in [fuchsia.ui.composition/allocator.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/allocator.fidl;l=23)* A typed wrapper for an eventpair, representing the Image import endpoint of a buffer collection.
| Field | Type | Description | Default | |---|---|---|---| | `value` | `handle` | | No default | ### ColorRgba *Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=73)* 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.
| Field | Type | Description | Default | |---|---|---|---| | `red` | `float32` | | No default | | `green` | `float32` | | No default | | `blue` | `float32` | | No default | | `alpha` | `float32` | | No default | ### ContentId *Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=268)* A user-defined identifier for a particular piece of Content. See Content creation functions (e.g. [CreateViewport](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#CreateViewport), [CreateImage](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#CreateImage)) for more information.
| Field | Type | Description | Default | |---|---|---|---| | `value` | `uint64` | | No default | ### FlatlandFactory_CreateFlatland_Response *Defined in [fuchsia.ui.composition/flatland_factory.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland_factory.fidl;l=46)* \ ### HitRegion *Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=443)* An interactive area of a View, placed in the coordinate space of a specific Transform.
| Field | Type | Description | Default | |---|---|---|---| | `region` | `https://fuchsia.dev/reference/fuchsia.math//https://fuchsia.dev/reference/fuchsia.math#RectF` | The position and size of this hit region, in the coordinate space of the Transform that owns this hit region. | No default | | `hit_test` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#HitTestInteraction` | The interaction behavior specified for this hit region. To specify "no interaction at all", remove this hit region from the owning Transform. | No default | ### ImageId *Defined in [fuchsia.ui.composition/flatland2.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland2.fidl;l=41)* A user-defined identifier for a particular image created with [Flatland.CreateImage2](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Flatland.CreateImage2). Zero is never a valid `ImageId`; the shared identifier rules documented on [LayerId](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerId) also apply. Added: HEAD
| Field | Type | Description | Default | |---|---|---|---| | `value` | `uint64` | | No default | ### LayerId *Defined in [fuchsia.ui.composition/flatland2.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland2.fidl;l=19)* **Zero identifiers** : zero is never a valid identifier, for any of these types; each `Create*` method rejects it. Unlike the classic API (where, e.g., [Flatland.SetContent](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Flatland.SetContent) accepts id 0 to clear a Transform's content), Flatland2 never uses a zero id to express clearing; where clearing is possible, it is expressed by omitting an optional field (see [Flatland.SetTransformContent](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Flatland.SetTransformContent)). A user-defined identifier for a particular layer. See [Flatland.CreateLayer](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Flatland.CreateLayer) and [Flatland.ReleaseLayer](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Flatland.ReleaseLayer) for more information. Added: HEAD
| Field | Type | Description | Default | |---|---|---|---| | `value` | `uint64` | | No default | ### LayerStackId *Defined in [fuchsia.ui.composition/flatland2.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland2.fidl;l=28)* A user-defined identifier for a particular layer stack created with [Flatland.CreateLayerStack](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Flatland.CreateLayerStack). Zero is never a valid `LayerStackId`; the shared identifier rules documented on [LayerId](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerId) also apply. Added: HEAD
| Field | Type | Description | Default | |---|---|---|---| | `value` | `uint64` | | No default | ### 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=101)* \ ### 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=129)* \ ### TransformId *Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=258)* A user-defined identifier for a particular transform. See [CreateTransform](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#CreateTransform) and [ReleaseTransform](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ReleaseTransform) for more information.
| Field | Type | Description | Default | |---|---|---|---| | `value` | `uint64` | | No default | ### TrustedFlatlandFactory_CreateFlatland_Response *Defined in [fuchsia.ui.composition/trusted_flatland_factory.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/trusted_flatland_factory.fidl;l=75)* \ ### ViewportId *Defined in [fuchsia.ui.composition/flatland2.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland2.fidl;l=50)* A user-defined identifier for a particular viewport created with [Flatland.CreateViewport2](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Flatland.CreateViewport2). Zero is never a valid `ViewportId`; the shared identifier rules documented on [LayerId](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerId) also apply. Added: HEAD
| Field | Type | Description | Default | |---|---|---|---| | `value` | `uint64` | | No default | ## **ENUMS** ### BlendMode [strict](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible) Type: `uint32` *Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=40)* The set of possible blending functions to choose from when determining how an image should be composited on top of other images. Deprecated: 33
| Name | Value | Description | |---|---|---| | ### SRC | `1` | Indicates that the source pixels replace the destination pixels. In other words, the source pixels are treated as opaque, regardless of what alpha values are set. | | ### SRC_OVER | `2` | 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). | ### BlendMode2 [flexible](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible) Type: `uint32` *Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=52)* The set of possible blending functions to choose from when determining how an image should be composited on top of other images. Added: 29
| Name | Value | Description | |---|---|---| | ### REPLACE | `1` | Indicates that the source pixels replace the destination pixels: source pixel values, including alpha, are written into the output as-is, without blending against the destination. A source pixel with partial or zero alpha is stamped into the output with that alpha intact; it is not treated as opaque. (This describes the blend function itself; a layer's `opacity` can demote this mode. See [LayerProperties.blend_mode](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerProperties.blend_mode).) | | ### PREMULTIPLIED_ALPHA | `2` | 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. | | ### STRAIGHT_ALPHA | `3` | The source pixels are drawn over the destination pixels. The final pixel color that is displayed is calculated as: alpha_src \* C_src + (1.0 - alpha_src) \* C_dst. | ### ChildViewStatus [strict](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible) Type: `uint32` *Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=178)* | Name | Value | Description | |---|---|---| | ### CONTENT_HAS_PRESENTED | `1` | The underlying Flatland session has connected its View, called [Present](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Present), and the acquisition fences of the [Present](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Present) call have all be reached, indicating that it has some content ready to be displayed, and NOT that the child content has actually been shown on the screen (a common use case is for the parent to wait for the child content to be ready before attaching the child to the global scene graph). | ### CompositionMode [strict](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible) Type: `uint32` *Defined in [fuchsia.ui.composition/flatland2.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland2.fidl;l=75)* Selects what a Layer composites: an image, a solid color, or nothing at all. `INVISIBLE` is the freshly-created state. An `INVISIBLE` layer keeps its place in any `LayerStack` which references it, but contributes nothing to the frame. Because layer properties are sticky (see [LayerProperties](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerProperties)), passing through `INVISIBLE` and back loses nothing. Added: HEAD
| Name | Value | Description | |---|---|---| | ### INVISIBLE | `1` | | | ### IMAGE | `2` | | | ### SOLID_COLOR | `3` | | ### FlatlandError [strict](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible) Type: `uint32` *Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=15)* The set of error codes returned in [OnError](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#OnError). Any error causes the Flatland channel to be closed.
| Name | Value | Description | |---|---|---| | ### BAD_OPERATION | `1` | Indicates that the parameters used in the function calls are invalid. | | ### NO_PRESENTS_REMAINING | `2` | Indicates that `additional_present_credits` field was not properly processed and the client queued more [Present](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Present)s than allowed. | | ### BAD_HANGING_GET | `3` | Indicates that the client has overwritten hanging gets in the protocols returned. | ### FlatlandFactoryError [flexible](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible) Type: `uint32` *Defined in [fuchsia.ui.composition/flatland_factory.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland_factory.fidl;l=16)* An error that can occur when using [fuchsia.ui.composition](https://fuchsia.dev/reference/fuchsia.ui.composition/)/[FlatlandFactory.CreateFlatland](https://fuchsia.dev/reference/fuchsia.ui.composition/#FlatlandFactory.CreateFlatland). Added: HEAD
| Name | Value | Description | |---|---|---| | ### INVALID_ARGS | `1` | Client provided an invalid configuration, so no Flatland session could be created. | | ### INTERNAL | `2` | The server was unable to establish the Flatland session for an unspecified reason that is not the client's fault. | ### HitTestInteraction [flexible](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible) Type: `uint8` *Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=431)* The kind of hit test interaction expected for a hit region.
| Name | Value | Description | |---|---|---| | ### DEFAULT | `0` | The natural default behavior is for a hit region to interact with both regular hit testing and accessibility hit testing. | | ### SEMANTICALLY_INVISIBLE | `1` | Some use cases require that a hit region to interact with regular hit testing, but not interact with accessibility hit testing. Here, "semantics" refers to accessibility's semantic tree data, which describes UI elements in a View. | ### ImageFlip [strict](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible) Type: `uint32` *Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=83)* The set of possible image flip functions to choose from when determining how the image texture should be displayed. Deprecated: 33
| Name | Value | Description | |---|---|---| | ### NONE | `0` | | | ### LEFT_RIGHT | `1` | 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\| | | ### UP_DOWN | `2` | 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\| | ### Orientation [strict](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible) Type: `uint32` *Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=30)* 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 "handedness" (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.
| Name | Value | Description | |---|---|---| | ### CCW_0_DEGREES | `1` | | | ### CCW_90_DEGREES | `2` | | | ### CCW_180_DEGREES | `3` | | | ### CCW_270_DEGREES | `4` | | ### ParentViewportStatus [strict](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible) Type: `uint32` *Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=131)* 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.
| Name | Value | Description | |---|---|---| | ### CONNECTED_TO_DISPLAY | `1` | | | ### DISCONNECTED_FROM_DISPLAY | `2` | | ### RegisterBufferCollectionError [strict](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible) Type: `uint32` *Defined in [fuchsia.ui.composition/allocator.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/allocator.fidl;l=12)* The set of error codes returned by Allocator::RegisterBufferCollection().
| Name | Value | Description | |---|---|---| | ### BAD_OPERATION | `1` | | ### RegisterBufferCollectionUsage [strict](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible) Type: `uint32` *Defined in [fuchsia.ui.composition/allocator.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/allocator.fidl;l=29)* The possible usages for registered buffer collection.
| Name | Value | Description | |---|---|---| | ### DEFAULT | `0` | DEFAULT means that the specified buffer collection will be used for Flatland and gfx image creation. See [fuchsia.ui.composition](https://fuchsia.dev/reference/fuchsia.ui.composition/)/[Flatland.CreateImage](https://fuchsia.dev/reference/fuchsia.ui.composition/#Flatland.CreateImage) for more. | | ### SCREENSHOT | `1` | SCREENSHOT means that the specified buffer collection will be used for screenshotting purposes. | ### Rotation [strict](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible) Type: `uint32` *Defined in [fuchsia.ui.composition/screen_capture.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/screen_capture.fidl;l=34)* The rotation to be applied to the image. If a given display is rotated, say, 270 degrees according to its `display_info` config file, then applying the equal and opposite rotation, [CW_270_DEGREES](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#CW_270_DEGREES), should cancel the display rotation leading to a correctly rendered screenshot. 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 `width` and `height` values found in the `display_info` config file.
| Name | Value | Description | |---|---|---| | ### CW_0_DEGREES | `0` | | | ### CW_90_DEGREES | `1` | | | ### CW_180_DEGREES | `2` | | | ### CW_270_DEGREES | `3` | | ### ScreenCaptureError [flexible](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible) Type: `uint32` *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)* The possible errors from the ScreenCapture protocol.
| Name | Value | Description | |---|---|---| | ### MISSING_ARGS | `1` | One or more required arguments are missing in the table argument. | | ### INVALID_ARGS | `2` | One or more of the arguments was not valid. | | ### BAD_OPERATION | `3` | A general error occurred during the method call. | | ### BUFFER_FULL | `4` | Error that is returned if [GetNextFrame](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#GetNextFrame) is called when all of the VMOs in the BufferCollection have been rendered to. [ReleaseFrame](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ReleaseFrame) must be called before a successful call to GetNextFrame can be made. | ### ScreenshotFormat [flexible](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible) Type: `uint8` *Defined in [fuchsia.ui.composition/screenshot.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/screenshot.fidl;l=11)* The different formats of Screenshot that can be requested.
| Name | Value | Description | |---|---|---| | ### BGRA_RAW | `0` | The default format, requesting a tightly packed pixel data with 32 bit BGRA pixels. | | ### RGBA_RAW | `2` | Requests tightly packed pixel data with 32 bit RGBA pixels. | | ### PNG | `1` | Requests tightly packed pixel data which is compressed into PNG format. | ### TrustedFlatlandFactoryError [flexible](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible) Type: `uint32` *Defined in [fuchsia.ui.composition/trusted_flatland_factory.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/trusted_flatland_factory.fidl;l=50)* An error that can occur when using the \[TrustedFlatlandFactory\]. Added: HEAD
| Name | Value | Description | |---|---|---| | ### BAD_OPERATION | `1` | A general error occurred during the method call. This may happen if the configuration is invalid or if the system is unable to create a new Flatland session. | ## **TABLES** ### FlatlandConfig *Defined in [fuchsia.ui.composition/flatland_factory.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland_factory.fidl;l=8)* Configuration parameters for instantiating a regular Flatland session. Added: HEAD
| Ordinal | Field | Type | Description | |---|---|---|---| | ### 1 | `use_flatland2` | `bool` | If true, opts the session into the Flatland2 API surface and layer data model. Defaults to false. | ### FrameInfo [resource](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#value-vs-resource) *Defined in [fuchsia.ui.composition/screen_capture.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/screen_capture.fidl;l=64)* Metadata about the frame rendered by [GetNextFrame](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#GetNextFrame).
| Ordinal | Field | Type | Description | |---|---|---|---| | ### 1 | `buffer_id` | `uint32` | The index of the VMO where the requested frame has been rendered. Required. | ### GetNextFrameArgs [resource](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#value-vs-resource) *Defined in [fuchsia.ui.composition/screen_capture.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/screen_capture.fidl;l=58)* The arguments passed into the [GetNextFrame](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#GetNextFrame) call. All fields are necessary.
| Ordinal | Field | Type | Description | |---|---|---|---| | ### 1 | `event` | `handle` | The event that will signal when the requested frame has been rendered. Required. | ### ImageProperties *Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=251)* The properties of an Image as defined by the client. These properties determine how an Image uses the backing BufferCollection. See [CreateImage](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#CreateImage) for more information.
| Ordinal | Field | Type | Description | |---|---|---|---| | ### 1 | `size` | `https://fuchsia.dev/reference/fuchsia.math//https://fuchsia.dev/reference/fuchsia.math#SizeU` | The size of the Image in pixels. | ### LayerProperties *Defined in [fuchsia.ui.composition/flatland2.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland2.fidl;l=100)* Stateful properties associated with a Layer. All fields are sticky: [SetLayerProperties](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#SetLayerProperties) merges the provided table into the layer's stored properties, and stored values persist across [SetLayerImage](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#SetLayerImage) calls and across composition mode changes. Fields not used by the current composition mode keep their values, and take effect again when a mode that uses them is re-entered. Nothing is cleared implicitly; [ResetLayer](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ResetLayer) is the only operation that forgets stored properties. \*\*Hints (Safety and Performance Semantics)\*\*: Hints (such as [hint_damage_rects](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#hint_damage_rects) and [hint_visible_rects](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#hint_visible_rects)) are optional optimization details provided by the client. - **Ignorable by Design**: The implementation is free to ignore these hints. If ignored, rendering remains fully correct, though possibly less optimal. - **Correct Hints**: Yield the identical visual result but may improve performance (e.g., by allowing composition shortcuts or partial updates). - **Incorrect Hints**: May result in rendering artifacts, stale regions, or incorrect pixels on the display, as the implementation might optimize based on false assumptions. Added: HEAD
| Ordinal | Field | Type | Description | |---|---|---|---| | ### 1 | `display_rect` | `https://fuchsia.dev/reference/fuchsia.math//https://fuchsia.dev/reference/fuchsia.math#RectU` | The rectangle where the layer content will be displayed in its local coordinate space. For image layers, visual properties are applied in the following order: 1. **Sample** : The region specified by `sample_rect` is extracted from the image. 2. **Transform** : The sampled region is flipped and rotated as specified by `transform`. 3. **Scale/Fit** : Transformed content is implicitly scaled to fit the `display_rect`. Hardware image scaling is requested implicitly when the dimensions of the transformed `sample_rect` differ from the extent of the `display_rect`. Not all display hardware supports scaling, or may have limitations. The dimensions of `display_rect` must account for image dimension changes caused by rotations to avoid implicit scaling or distortion. For example, rotating a 600x300 pixel region by 90 degrees would require specifying 300x600 dimensions here to maintain the aspect ratio. **Note**: This rectangle is specified in the local space of the LayerStack (or the Transform the LayerStack is attached to). Any scaling applied by parent transforms in the Flatland scene graph will further affect the final size on the physical display. Default: (0,0,0,0). The layer will not be visible until a rectangle with non-zero width and height is set. | | ### 2 | `opacity` | `float32` | The opacity of the layer, in the range \[0..1\]. Multiplies with opacity inherited from `Transform`s above the layer's `LayerStack` (see [fuchsia.ui.composition](https://fuchsia.dev/reference/fuchsia.ui.composition/)/[Flatland.SetOpacity](https://fuchsia.dev/reference/fuchsia.ui.composition/#Flatland.SetOpacity)) to give the layer's *effective opacity* . The layer renders as if its content's own alpha (image pixels' alpha, or `color.alpha` for a solid-color layer) were scaled by the effective opacity; since this requires blending, a `REPLACE` layer with effective opacity below 1.0 renders as `PREMULTIPLIED_ALPHA` (see [blend_mode](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#blend_mode)). A layer with effective opacity 0.0 is invisible. Default: 1.0 (the content's own alpha applies unmodified). | | ### 3 | `blend_mode` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#BlendMode2` | The blend mode used to composite the layer over the content beneath it. `REPLACE` is honored only while the layer's effective opacity is 1.0 (see [opacity](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#opacity)); at lower effective opacity the layer renders as `PREMULTIPLIED_ALPHA`, so that opacity always fades the layer. To write exact sub-unity alpha values into the output (e.g. punching a hole for an underlay), author them in the content itself (the image's own pixels, or `color.alpha` for a solid-color layer) and leave `opacity` at 1.0. `STRAIGHT_ALPHA` names a content *encoding* , and is meaningful for image content. A solid-color layer's encoding is fixed by the API (`color` is straight RGBA regardless of `blend_mode`), so for solid-color content `STRAIGHT_ALPHA` is accepted and composites identically to `PREMULTIPLIED_ALPHA`. Default: `BlendMode2.REPLACE`. | | ### 4 | `color` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ColorRgba` | The color to fill the layer with, as straight (non-premultiplied) RGBA regardless of `blend_mode`. The compositor performs any conversion needed for rendering. Default: opaque white (1.0, 1.0, 1.0, 1.0). | | ### 5 | `sample_rect` | `https://fuchsia.dev/reference/fuchsia.math//https://fuchsia.dev/reference/fuchsia.math#RectF` | Describes the region inside the image to sample from, in unnormalized coordinates (rect width/height match image width/height). Default: (0,0,0,0), which is interpreted as the entire image region. A client can reset to the full image by setting this field to (0,0,0,0). Must lie within the bounds of the bound image. This is checked during [fuchsia.ui.composition](https://fuchsia.dev/reference/fuchsia.ui.composition/)/[Flatland.Present](https://fuchsia.dev/reference/fuchsia.ui.composition/#Flatland.Present), and only for layers whose `composition_mode` is `IMAGE`, so the order of calls within a batch does not matter: a rect and an image of matching size may be set in either order, and a rect set while no image is bound (or while another mode is in effect) is stored without complaint. A violation at `Present` closes the connection with `BAD_OPERATION`. | | ### 6 | `transform` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#FlipThenRotate` | Specifies image transform. Default: No transformation (identity). | | ### 7 | `hint_damage_rects` | `vector` | A hint describing the region of the source image that has changed since the last frame. Specified in the coordinate space of the source image (buffer). Default: Empty vector (interpreted as the entire sample rect being damaged). Refer to [LayerProperties](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerProperties) for the general safety and performance semantics of hints. | | ### 8 | `hint_visible_rects` | `vector` | A hint describing the visible region of the layer on the screen. Specified in the local coordinate space of the Layer (matching `display_rect`). Default: Empty vector (interpreted as the entire `display_rect` being visible). Refer to [LayerProperties](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerProperties) for the general safety and performance semantics of hints. | | ### 9 | `composition_mode` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#CompositionMode` | Selects which of the property groups above is in effect; see [CompositionMode](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#CompositionMode). Default: `CompositionMode.INVISIBLE`. | ### LayoutInfo *Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=101)* The return type of [GetLayout](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#GetLayout). This table contains most of the information necessary for a client to decide how to layout their content in a Flatland session. This data may be provided to the client before the command that creates the View is presented, so that the client may lay out content properly before their first call to [Present](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Present).
| Ordinal | Field | Type | Description | |---|---|---|---| | ### 1 | `logical_size` | `https://fuchsia.dev/reference/fuchsia.math//https://fuchsia.dev/reference/fuchsia.math#SizeU` | The layout size of a View in logical pixels, defined by the parent's call to [SetViewportProperties](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#SetViewportProperties). 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). Clients should re-layout their content when this value changes. | | ### 3 | `device_pixel_ratio` | `https://fuchsia.dev/reference/fuchsia.math//https://fuchsia.dev/reference/fuchsia.math#VecF` | 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 (`logical_size`\*`device_pixel_ratio`). | | ### 4 | `inset` | `https://fuchsia.dev/reference/fuchsia.math//https://fuchsia.dev/reference/fuchsia.math#Inset` | 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 `device_pixel_ratio`. | ### OnNextFrameBeginValues *Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=377)* Fields that a client needs in order to produce its next frame, returned in [OnNextFrameBegin](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#OnNextFrameBegin). Each field is guaranteed to be set and contain valid information.
| Ordinal | Field | Type | Description | |---|---|---|---| | ### 1 | `additional_present_credits` | `uint32` | The number of *additional* [Present](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Present) calls allowed to the client so that they can call [Present](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Present) further times. This is a delta in the present credit budget, not the absolute number of present credits. | | ### 2 | `future_presentation_infos` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#FuturePresentationInfos` | Information about future presentation and latch times that a client may aim for precise scheduling behavior. | ### PresentArgs [resource](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#value-vs-resource) *Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=279)* Arguments passed into [Present](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Present). All arguments are optional, and if an argument is omitted Flatland will use a reasonable default, specified below.
| Ordinal | Field | Type | Description | |---|---|---|---| | ### 1 | `requested_presentation_time` | `https://fuchsia.dev/reference/zx//https://fuchsia.dev/reference/zx#Time` | `requested_presentation_time` specifies the time on or after which the client would like the enqueued operations to take visible effect (light up pixels on the screen), expressed in nanoseconds in the `CLOCK_MONOTONIC` timebase. The default `requested_presentation_time` is 0. Using a `requested_presentation_time` in the present or past (such as 0) schedules enqueued operations to take visible effect as soon as possible, during the next frame to be prepared. Using a `requested_presentation_time` in the future schedules the enqueued operations to take visible effect on or as closely as possible after the stated time, but no earlier. Each rendered frame has a target presentation time. This is when Flatland aims to have the frame presented to the user. Before rendering a frame, Flatland applies all enqueued operations associated with all squashable calls to [Present](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Present) whose `requested_presentation_time` is on or before the frame's target presentation time. | | ### 2 | `acquire_fences` | `vector>:16` | Flatland will wait until all of a Flatland session's `acquire_fences` are ready before it will execute the presented commands. Not signaling `acquire_fences` will block the current [Present](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Present) as well as the following ones even if their `acquire_fences` are signaled. The default `acquire_fences` value is the empty vector. | | ### 3 | `release_fences` | `vector>:16` | Flatland will signal all `release_fences` when it is safe to reuse resources which no longer appear in the local scene graph at the time of the current [Present](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Present). At the latest, this will happen when the local scene graph (checkpointed at this [Present](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Present)) has been integrated into the global scene graph, and the global scene has been displayed on screen. (Under some circumstances, the fences may be signaled earlier, but clients do not need to worry about this: the fences will only be signaled when it is safe to reuse the associated resources). These fences are intended to manage the reuse of shared memory resources such as sysmem buffers. For example, it is undesirable for the client to render into an image which is currently displayed on screen, because this may result in graphical artifacts such as tearing. It is up to the client to maintain the mapping between each fence and the resources which will become reusable when the fence is signaled. A common strategy is to keep track of resources which were used by the previous [Present](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Present) but are no longer used by the current [Present](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Present). For example, if an image is removed from the scene by the current [Present](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Present), the client would insert a fence here. When the fence is later signaled, the client knows that it is safe to render into the image and insert it into the local scene graph in a subsequent [Present](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Present). If an error occurs, Flatland may close the channel without signaling these fences. Clients may immediately release shared buffers, but they should not immediately modify such buffers, because they may still be displayed on screen. There is currently no good signal available to the client about when it is safe to reuse shared buffers. The default `release_fences` value is the empty vector. | | ### 4 | `unsquashable` | `bool` | If `unsquashable` is true, then the update is guaranteed to be uniquely shown for at least one vsync interval. If `unsquashable` is false, then the update can be combined with those that come after it. If absent, `unsquashable` is false. | | ### 7 | `present_fences` | `vector>:16` | Flatland will signal all `present_fences` when the frame corresponding to this `Present` is reported as displayed by the display hardware. Additionally, each fence will have the monotonic timestamp of the corresponding vsync written into it. The default `present_fences` value is the empty vector. Added: HEAD | | ### 8 | `release_counters` | `vector>:16` | Flatland will signal all `release_counters` when it is safe to reuse resources which no longer appear in the local scene graph at the time of the current `Present` (i.e. resources from the previous present). This is similar to `release_fences` but by using counters instead of events, counters hold the monotonic timestamp of when resources became safe for reuse. The event based `release_fences` can be used simultaneously with `release_counters` for resources that don't care about this timestamp. The default `release_counters` value is the empty vector. Added: HEAD | ### RegisterBufferCollectionArgs [resource](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#value-vs-resource) *Defined in [fuchsia.ui.composition/allocator.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/allocator.fidl;l=54)* The table of arguments for [RegisterBufferCollection](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#RegisterBufferCollection). Note that some fields below are REQUIRED.
| Ordinal | Field | Type | Description | |---|---|---|---| | ### 1 | `export_token` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#BufferCollectionExportToken` | Clients can send [export_token](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#export_token) to register buffer collections with Allocator to be used later in [fuchsia.ui.composition](https://fuchsia.dev/reference/fuchsia.ui.composition/)/[Flatland](https://fuchsia.dev/reference/fuchsia.ui.composition/#Flatland) instances or other Scenic APIs, such as Screenshot. For example, by passing a [BufferCollectionImportToken](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#BufferCollectionImportToken) containing the matching peer of [BufferCollectionExportToken](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#BufferCollectionExportToken), they can create image resources via [fuchsia.ui.composition](https://fuchsia.dev/reference/fuchsia.ui.composition/)/[Flatland.CreateImage](https://fuchsia.dev/reference/fuchsia.ui.composition/#Flatland.CreateImage). Clients should wait for the response before using `import_token`. This field is REQUIRED. | | ### 2 | `buffer_collection_token` | `client_end:https://fuchsia.dev/reference/fuchsia.sysmem//https://fuchsia.dev/reference/fuchsia.sysmem#BufferCollectionToken` | Removed: NEXT Deprecated: 25 Added: 7 | | ### 3 | `usage` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#RegisterBufferCollectionUsage` | The client can register a buffer collection for various uses, each coming with their own unique constraints. This field is OPTIONAL. If `usage` is omitted it will be treated as if it has the DEFAULT option. # Deprecation This arg is deprecated at API version 9 with addition of \|usages\|. If both the `usages` and `usage` fields are set, `usages` takes precedence and `usage` is ignored. Deprecated: 9 | | ### 4 | `usages` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#RegisterBufferCollectionUsages` | The client can register a buffer collection for various uses and has the ability to combine usages if multiple are needed. This field is OPTIONAL. If `usages` is omitted it will be treated as if it has only the DEFAULT option. | | ### 5 | `buffer_collection_token2` | `client_end:https://fuchsia.dev/reference/fuchsia.sysmem2//https://fuchsia.dev/reference/fuchsia.sysmem2#BufferCollectionToken` | Flatland participates in the allocation of buffers by setting constraints on the BufferCollection referenced by `buffer_collection_token2` (or `buffer_collection_token` prior to its removal). It will not block on buffers being allocated until the client creates content using the BufferCollection. The buffer collection registered with `export_token` is available and kept alive as long as the client holds a valid [BufferCollectionImportToken](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#BufferCollectionImportToken). They will be garbage collected when all [BufferCollectionImportToken](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#BufferCollectionImportToken)s are closed and all the associated Image resources are released. `buffer_collection_token2` must be set (or prior to `buffer_collection_token` removal, exactly one of `buffer_collection_token2` or `buffer_collection_token` must be set). Added: 25 | ### ScreenCaptureConfig [resource](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#value-vs-resource) *Defined in [fuchsia.ui.composition/screen_capture.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/screen_capture.fidl;l=42)* The arguments passed into the [Configure](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Configure) call. Note that not all fields are necessary.
| Ordinal | Field | Type | Description | |---|---|---|---| | ### 1 | `import_token` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#BufferCollectionImportToken` | The import token referencing a BufferCollection registered with Allocator. Required. | | ### 2 | `size` | `https://fuchsia.dev/reference/fuchsia.math//https://fuchsia.dev/reference/fuchsia.math#SizeU` | The size of the image in pixels. Required. | | ### 3 | `buffer_count` | `uint32` | The number of buffers in the BufferCollection. Required. | | ### 4 | `rotation` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Rotation` | The rotation to be applied to the stream of images. Optional; if absent no rotation is applied. | ### ScreenshotTakeFileRequest [resource](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#value-vs-resource) *Defined in [fuchsia.ui.composition/screenshot.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/screenshot.fidl;l=77)* | Ordinal | Field | Type | Description | |---|---|---|---| | ### 1 | `format` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ScreenshotFormat` | Format of the requested screenshot. | ### ScreenshotTakeFileResponse [resource](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#value-vs-resource) *Defined in [fuchsia.ui.composition/screenshot.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/screenshot.fidl;l=80)* | Ordinal | Field | Type | Description | |---|---|---|---| | ### 1 | `file` | `client_end:https://fuchsia.dev/reference/fuchsia.io//https://fuchsia.dev/reference/fuchsia.io#File` | \|fuchsia.io.File\| channel used to read the generated screenshot file data. The server side of the channel is stored on the device until ZX_CHANNEL_PEER_CLOSED is detected. Basic usage: After the client recieves the client end of the file channel, to avoid memory pile-ups, it should finish reading the data before calling [TakeFile](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#TakeFile) again. When finished reading, the client should call [Close](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Close) on the \|fuchsia.io.File\| channel, this will release the memory allocated on the server side. | | ### 2 | `size` | `https://fuchsia.dev/reference/fuchsia.math//https://fuchsia.dev/reference/fuchsia.math#SizeU` | Size of the screenshot in pixels. | ### ScreenshotTakeRequest [resource](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#value-vs-resource) *Defined in [fuchsia.ui.composition/screenshot.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/screenshot.fidl;l=40)* | Ordinal | Field | Type | Description | |---|---|---|---| | ### 1 | `format` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ScreenshotFormat` | Format of the requested screenshot. | ### ScreenshotTakeResponse [resource](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#value-vs-resource) *Defined in [fuchsia.ui.composition/screenshot.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/screenshot.fidl;l=43)* | Ordinal | Field | Type | Description | |---|---|---|---| | ### 1 | `vmo` | `handle` | CPU mappable read-only VMO that contains screenshot data. The server owns the VMO and may reuse for the next [Take](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Take). The VMO is guaranteed to be accessible after mapping. In some allocations, VMO::read() might not be available, i.e. on emulator. Basic usage: After the client receives a VMO handle, to ensure data stability, it should finish reading the VMO before calling [Take](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Take) again. When finished reading, the client should drop the VMO handle. Advanced usage: To edit the data, or to persist it beyond the next [Take](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Take) call, the client should copy the data to a private VMO. | | ### 2 | `size` | `https://fuchsia.dev/reference/fuchsia.math//https://fuchsia.dev/reference/fuchsia.math#SizeU` | Size of the screenshot in pixels. | ### TrustedFlatlandConfig [resource](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#value-vs-resource) *Defined in [fuchsia.ui.composition/trusted_flatland_factory.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/trusted_flatland_factory.fidl;l=10)* All arguments are optional; default values will be provided if they are absent. By default, the resulting Flatland will behave identically to connecting to the \[Flatland\] service instead of connecting via the factory. Added: HEAD
| Ordinal | Field | Type | Description | |---|---|---|---| | ### 1 | `schedule_asap` | `bool` | If true and the \[PresentArgs.requested_presentation_time\] passed to \[Flatland.Present\] is set to 0 or less than or equal to the nearest presentation time, a frame will be scheduled to be presented as soon as all acquire fences are signaled, instead of waiting for other clients to present within the same vsync. This allows the caller to decide when to wake up for preparing a frame. If \[requested_presentation_time\] is set to a value greater than the nearest presentation time, this flag will have no effect and the wakeup time decision will be made by the scheduler. If absent, `schedule_asap` is false. | | ### 2 | `pass_acquire_fences` | `bool` | If true, Scenic should pass acquire fences to the drivers for composition HW, instead of waiting for them on CPU. This can improve performance by reducing CPU overhead. If absent, `pass_acquire_fences` is false. | | ### 3 | `skips_present_credits` | `bool` | If true, the client will not utilize Flatland's built in frame-scheduling mechanism and will ignore present credits, instead relying on their own flow control system. If absent, `skips_present_credits` is false. | | ### 4 | `skips_on_frame_presented` | `bool` | If true, the client will not receive \[Flatland.OnFramePresented\] events. If absent, `skips_on_frame_presented` is false. | | ### 5 | `use_flatland2_api` | `bool` | If true, clients may use the [fuchsia.ui.composition](https://fuchsia.dev/reference/fuchsia.ui.composition/)/[Flatland2](https://fuchsia.dev/reference/fuchsia.ui.composition/#Flatland2) protocol, which is composed into the "classic" [fuchsia.ui.composition](https://fuchsia.dev/reference/fuchsia.ui.composition/)/[Flatland](https://fuchsia.dev/reference/fuchsia.ui.composition/#Flatland) protocol. Note: some "classic" Flatland methods are disabled when Flatland2 is enabled; see the [fuchsia.ui.composition](https://fuchsia.dev/reference/fuchsia.ui.composition/)/[Flatland2](https://fuchsia.dev/reference/fuchsia.ui.composition/#Flatland2) documentation for details. If absent, `use_flatland2_api` is false. | ### ViewBoundProtocols [resource](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#value-vs-resource) *Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=389)* The protocol endpoints bound to a Flatland ViewCreationToken. These protocols operate on the View that ViewCreationToken created in the Flatland session.
| Ordinal | Field | Type | Description | |---|---|---|---| | ### 1 | `view_ref_focused` | `server_end:https://fuchsia.dev/reference/fuchsia.ui.views//https://fuchsia.dev/reference/fuchsia.ui.views#ViewRefFocused` | Learn when a View gains focus. Server-bound ViewRef. The [view_ref_focused](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#view_ref_focused) client does not specify the ViewRef explicitly; instead, the server implementation uses the ViewRef used in View creation for reporting focus movement on/off this View. | | ### 2 | `view_focuser` | `server_end:https://fuchsia.dev/reference/fuchsia.ui.views//https://fuchsia.dev/reference/fuchsia.ui.views#Focuser` | Enable a View to request focus transfer to a child (target) View. Server-bound ViewRef. The [view_focuser](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#view_focuser) client does not specify the "requester" ViewRef explicitly, only the "target" ViewRef. Instead, the server implementation uses the ViewRef used in View creation as the "requester" ViewRef. | | ### 3 | `touch_source` | `server_end:https://fuchsia.dev/reference/fuchsia.ui.pointer//https://fuchsia.dev/reference/fuchsia.ui.pointer#TouchSource` | Receive touch events that are associated with a View. Mutually exclusive with `touch_source_v2`. Providing both will result in a `FlatlandError.BAD_OPERATION` error and channel closure. | | ### 4 | `mouse_source` | `server_end:https://fuchsia.dev/reference/fuchsia.ui.pointer//https://fuchsia.dev/reference/fuchsia.ui.pointer#MouseSource` | Receive mouse events that are associated with a View. Mutually exclusive with `mouse_source_v2`. Providing both will result in a `FlatlandError.BAD_OPERATION` error and channel closure. | | ### 5 | `touch_source_v2` | `server_end:https://fuchsia.dev/reference/fuchsia.ui.pointer//https://fuchsia.dev/reference/fuchsia.ui.pointer#TouchSourceV2` | Receive touch events that are associated with a View. Mutually exclusive with `touch_source`. Providing both will result in a `FlatlandError.BAD_OPERATION` error and channel closure. Added: 33 | | ### 6 | `mouse_source_v2` | `server_end:https://fuchsia.dev/reference/fuchsia.ui.pointer//https://fuchsia.dev/reference/fuchsia.ui.pointer#MouseSourceV2` | Receive mouse events that are associated with a View. Mutually exclusive with `mouse_source`. Providing both will result in a `FlatlandError.BAD_OPERATION` error and channel closure. Added: 33 | ### ViewportProperties *Defined in [fuchsia.ui.composition/flatland.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=239)* The properties of a Viewport as defined by the parent. This data, along with the set of attached Transforms, will be used to compute the LayoutInfo for the View of the Viewport. `ViewportProperties` must have `logical_size` set at least once. This is the initial size that will drive the layout of the child.
| Ordinal | Field | Type | Description | |---|---|---|---| | ### 1 | `logical_size` | `https://fuchsia.dev/reference/fuchsia.math//https://fuchsia.dev/reference/fuchsia.math#SizeU` | 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. | | ### 2 | `inset` | `https://fuchsia.dev/reference/fuchsia.math//https://fuchsia.dev/reference/fuchsia.math#Inset` | The offsets between the edges and the visible rectangle of the Viewport. This maps directly to the `inset` field in LayoutInfo. The valid inset must have all components greater than or equal to 0. | ## **UNIONS** ### Allocator_RegisterBufferCollection_Result [strict](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible) *Defined in [fuchsia.ui.composition/allocator.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/allocator.fidl;l=117)* | Ordinal | Variant | Type | Description | |---|---|---|---| | ### 1 | `response` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Allocator_RegisterBufferCollection_Response` | | | ### 2 | `err` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#RegisterBufferCollectionError` | |
### FlatlandFactory_CreateFlatland_Result [strict](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible) *Defined in [fuchsia.ui.composition/flatland_factory.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland_factory.fidl;l=46)* | Ordinal | Variant | Type | Description | |---|---|---|---| | ### 1 | `response` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#FlatlandFactory_CreateFlatland_Response` | | | ### 2 | `err` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#FlatlandFactoryError` | |
### ScreenCapture_Configure_Result [strict](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible) *Defined in [fuchsia.ui.composition/screen_capture.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/screen_capture.fidl;l=101)* | Ordinal | Variant | Type | Description | |---|---|---|---| | ### 1 | `response` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ScreenCapture_Configure_Response` | | | ### 2 | `err` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ScreenCaptureError` | |
### ScreenCapture_GetNextFrame_Result [strict](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible) [resource](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#value-vs-resource) *Defined in [fuchsia.ui.composition/screen_capture.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/screen_capture.fidl;l=123)* | Ordinal | Variant | Type | Description | |---|---|---|---| | ### 1 | `response` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#FrameInfo` | | | ### 2 | `err` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ScreenCaptureError` | |
### ScreenCapture_ReleaseFrame_Result [strict](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible) *Defined in [fuchsia.ui.composition/screen_capture.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/screen_capture.fidl;l=129)* | Ordinal | Variant | Type | Description | |---|---|---|---| | ### 1 | `response` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ScreenCapture_ReleaseFrame_Response` | | | ### 2 | `err` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ScreenCaptureError` | |
### SignalFence [strict](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible) [resource](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#value-vs-resource) *Defined in [fuchsia.ui.composition/flatland2.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland2.fidl;l=246)* A fence that will be signaled by Scenic when some condition becomes true. For more details, refer to the method the fence appears in. Added: HEAD | Ordinal | Variant | Type | Description | |---|---|---|---| | ### 1 | `basic` | `handle` | A basic handle (e.g., EVENT or EVENTPAIR). | | ### 2 | `timestamp` | `handle` | Before Scenic signals the fence, it will write the timestamp of the corresponding event into the counter. |
### TransformContent [strict](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible) *Defined in [fuchsia.ui.composition/flatland2.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland2.fidl;l=227)* Content that can be attached to a Transform when Flatland2 is enabled. This union defines the types of content that can be attached to a Transform using [Flatland.SetTransformContent](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#Flatland.SetTransformContent). Added: HEAD | Ordinal | Variant | Type | Description | |---|---|---|---| | ### 1 | `layer_stack` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#LayerStackId` | | | ### 2 | `viewport` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#ViewportId` | |
### TrustedFlatlandFactory_CreateFlatland_Result [strict](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible) *Defined in [fuchsia.ui.composition/trusted_flatland_factory.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/trusted_flatland_factory.fidl;l=75)* | Ordinal | Variant | Type | Description | |---|---|---|---| | ### 1 | `response` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#TrustedFlatlandFactory_CreateFlatland_Response` | | | ### 2 | `err` | `https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#TrustedFlatlandFactoryError` | |
### WaitFence [strict](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible) [resource](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#value-vs-resource) *Defined in [fuchsia.ui.composition/flatland2.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland2.fidl;l=235)* A fence that will be signaled when the associated resource is ready for Scenic to use. For context-specific usage info, refer to the method the fence appears in. Added: HEAD | Ordinal | Variant | Type | Description | |---|---|---|---| | ### 1 | `basic` | `handle` | A basic handle (e.g., EVENT or EVENTPAIR). | | ### 2 | `timestamp` | `handle` | At the time the fence is signalled, the timestamp of the corresponding event will have been written into the counter. |
## **BITS** ### FlipThenRotate [strict](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible) Type: `uint8` *Defined in [fuchsia.ui.composition/flatland2.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland2.fidl;l=57)* Bitset which supports all permutations of flips and rotations. Flips (if any) are performed first, followed by rotation (if any). Added: HEAD
| Name | Value | Description | |---|---|---| | ### FLIP_H | 1 | Flip the image horizontally (across the Y-axis). | | ### FLIP_V | 2 | Flip the image vertically (across the X-axis). | | ### ROTATE_90 | 4 | Rotate the image 90 degrees clockwise. | ### RegisterBufferCollectionUsages [flexible](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible) Type: `uint16` *Defined in [fuchsia.ui.composition/allocator.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/allocator.fidl;l=42)* The possible usages for a registered buffer collection. Can be a combination of options.
| Name | Value | Description | |---|---|---| | ### DEFAULT | 1 | The specified buffer collection can be used for Flatland and GFX image creation. See [fuchsia.ui.composition](https://fuchsia.dev/reference/fuchsia.ui.composition/)/[Flatland.CreateImage](https://fuchsia.dev/reference/fuchsia.ui.composition/#Flatland.CreateImage) for more. | | ### SCREENSHOT | 2 | The specified buffer collection can be used for screenshotting purposes. | ## **CONSTANTS** | Name | Value | Type | Description | |---|---|---|---| | [MAX_ACQUIRE_RELEASE_FENCE_COUNT](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=275) | `16` | `int32` | | | [MAX_CHILD_TRANSFORMS](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=264) | `64` | `int32` | A maximum of 64 child transforms is enough for the expected usage of these APIs. Callers may beyond this limit using [AddChild](https://fuchsia.dev/reference/fidl/fuchsia.ui.composition#AddChild). | | [MAX_HIT_REGION_COUNT](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=428) | `64` | `int32` | A maximum of 64 hit regions is enough for the expected usage of these APIs. | | [MAX_PRESENT_ARGS_FENCE_COUNT](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=273) | `16` | `int32` | | | [MAX_STACK_LAYERS](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland2.fidl;l=34) | `32` | `int32` | A maximum of 32 layers per stack is enough for the expected usage of these APIs. Added: HEAD | ## **ALIASES** | Name | Value | Description | |---|---|---| | [FuturePresentationInfos](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.composition/flatland.fidl;l=373) | `vector`\[`8`\] | A user-defined identifier for future presentation info. A maximum of 8 future presentation counts is enough for the current usage of these APIs. |