Enum Flatland2Request 

pub enum Flatland2Request {
    CreateLayer {
        layer_id: LayerId,
        control_handle: Flatland2ControlHandle,
    },
    ReleaseLayer {
        layer_id: LayerId,
        control_handle: Flatland2ControlHandle,
    },
    SetLayerImage {
        layer_id: LayerId,
        image_id: ImageId,
        acquire_fence: Option<Box<WaitFence>>,
        release_fence: Option<Box<SignalFence>>,
        control_handle: Flatland2ControlHandle,
    },
    SetLayerProperties {
        layer_id: LayerId,
        properties: LayerProperties,
        control_handle: Flatland2ControlHandle,
    },
    ResetLayer {
        layer_id: LayerId,
        control_handle: Flatland2ControlHandle,
    },
    CreateLayerStack {
        stack_id: LayerStackId,
        control_handle: Flatland2ControlHandle,
    },
    ReleaseLayerStack {
        stack_id: LayerStackId,
        control_handle: Flatland2ControlHandle,
    },
    SetStackLayers {
        stack_id: LayerStackId,
        layers: Vec<LayerId>,
        control_handle: Flatland2ControlHandle,
    },
    CreateImage2 {
        image_id: ImageId,
        import_token: BufferCollectionImportToken,
        vmo_index: u32,
        properties: ImageProperties,
        control_handle: Flatland2ControlHandle,
    },
    ReleaseImage2 {
        image_id: ImageId,
        control_handle: Flatland2ControlHandle,
    },
    CreateViewport2 {
        viewport_id: ViewportId,
        token: ViewportCreationToken,
        properties: ViewportProperties,
        child_view_watcher: ServerEnd<ChildViewWatcherMarker>,
        control_handle: Flatland2ControlHandle,
    },
    ReleaseViewport2 {
        viewport_id: ViewportId,
        responder: Flatland2ReleaseViewport2Responder,
    },
    SetViewportProperties2 {
        viewport_id: ViewportId,
        properties: ViewportProperties,
        control_handle: Flatland2ControlHandle,
    },
    SetTransformContent {
        transform_id: TransformId,
        content: Option<Box<TransformContent>>,
        control_handle: Flatland2ControlHandle,
    },
}

This protocol is composed into the “classic” [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]). 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/Flatland.CreateFilledRect]
• [fuchsia.ui.composition/Flatland.CreateImage]
• [fuchsia.ui.composition/Flatland.CreateViewport]
• [fuchsia.ui.composition/Flatland.ReleaseFilledRect]
• [fuchsia.ui.composition/Flatland.ReleaseImage]
• [fuchsia.ui.composition/Flatland.ReleaseViewport]
• [fuchsia.ui.composition/Flatland.SetContent]
• [fuchsia.ui.composition/Flatland.SetImageBlendingFunction]
• [fuchsia.ui.composition/Flatland.SetImageBlendMode]
• [fuchsia.ui.composition/Flatland.SetImageDestinationSize]
• [fuchsia.ui.composition/Flatland.SetImageFlip]
• [fuchsia.ui.composition/Flatland.SetImageOpacity]
• [fuchsia.ui.composition/Flatland.SetSolidFill]
• [fuchsia.ui.composition/Flatland.SetImageSampleRegion]
• [fuchsia.ui.composition/Flatland.SetViewportProperties]
• [fuchsia.ui.composition/TrustedFlatland.ReleaseImageImmediately]

Variants

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].
2. Set properties on the Layer via [SetLayerProperties], including the composition mode.
3. For an image layer, associate an Image with the Layer via [SetLayerImage].
4. Add the Layer to a LayerStack via [SetStackLayers].
5. Set the LayerStack as the content of a node via [SetTransformContent].

layer_id must satisfy the identifier rules documented on LayerId.

Fields

layer_id: LayerId

control_handle: Flatland2ControlHandle

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.

Fields

layer_id: LayerId

control_handle: Flatland2ControlHandle

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] call (or cleared by [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/Flatland.Present], not here. See [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] on the same layer
• [ResetLayer]
• the layer ref-count reaching zero, either via [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/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.

Fields

layer_id: LayerId

image_id: ImageId

acquire_fence: Option<Box<WaitFence>>

release_fence: Option<Box<SignalFence>>

control_handle: Flatland2ControlHandle

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 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/Flatland.Present]. See [LayerProperties.sample_rect].

layer_id must refer to a valid, unreleased Layer.

Fields

layer_id: LayerId

properties: LayerProperties

control_handle: Flatland2ControlHandle

ResetLayer

Unbinds any Image bound to the layer and clears every stored 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.

Fields

layer_id: LayerId

control_handle: Flatland2ControlHandle

CreateLayerStack

Creates a new layer stack with the specified stack_id.

stack_id must satisfy the identifier rules documented on LayerId.

Fields

stack_id: LayerStackId

control_handle: Flatland2ControlHandle

ReleaseLayerStack

Releases the layer stack with the specified stack_id.

Fields

stack_id: LayerStackId

control_handle: Flatland2ControlHandle

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.

Fields

stack_id: LayerStackId

layers: Vec<LayerId>

control_handle: Flatland2ControlHandle

CreateImage2

Creates an Image resource.

image_id must satisfy the identifier rules documented on LayerId.

Fields

image_id: ImageId

import_token: BufferCollectionImportToken

vmo_index: u32

properties: ImageProperties

control_handle: Flatland2ControlHandle

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.

Fields

image_id: ImageId

control_handle: Flatland2ControlHandle

CreateViewport2

Creates a Viewport resource.

viewport_id must satisfy the identifier rules documented on LayerId.

Fields

viewport_id: ViewportId

token: ViewportCreationToken

properties: ViewportProperties

child_view_watcher: ServerEnd<ChildViewWatcherMarker>

control_handle: Flatland2ControlHandle

ReleaseViewport2

Releases a Viewport from the scene.

Fields

viewport_id: ViewportId

responder: Flatland2ReleaseViewport2Responder

SetViewportProperties2

Sets the properties of a Viewport.

Fields

viewport_id: ViewportId

properties: ViewportProperties

control_handle: Flatland2ControlHandle

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], a zero id does not clear the content.

Fields

transform_id: TransformId

content: Option<Box<TransformContent>>

control_handle: Flatland2ControlHandle

Implementations

impl Flatland2Request

pub fn into_create_layer(self) -> Option<(LayerId, Flatland2ControlHandle)>

pub fn into_release_layer(self) -> Option<(LayerId, Flatland2ControlHandle)>

pub fn into_set_layer_image( self, ) -> Option<(LayerId, ImageId, Option<Box<WaitFence>>, Option<Box<SignalFence>>, Flatland2ControlHandle)>

pub fn into_set_layer_properties( self, ) -> Option<(LayerId, LayerProperties, Flatland2ControlHandle)>

pub fn into_reset_layer(self) -> Option<(LayerId, Flatland2ControlHandle)>

pub fn into_create_layer_stack( self, ) -> Option<(LayerStackId, Flatland2ControlHandle)>

pub fn into_release_layer_stack( self, ) -> Option<(LayerStackId, Flatland2ControlHandle)>

pub fn into_set_stack_layers( self, ) -> Option<(LayerStackId, Vec<LayerId>, Flatland2ControlHandle)>

pub fn into_create_image2( self, ) -> Option<(ImageId, BufferCollectionImportToken, u32, ImageProperties, Flatland2ControlHandle)>

pub fn into_release_image2(self) -> Option<(ImageId, Flatland2ControlHandle)>

pub fn into_create_viewport2( self, ) -> Option<(ViewportId, ViewportCreationToken, ViewportProperties, ServerEnd<ChildViewWatcherMarker>, Flatland2ControlHandle)>

pub fn into_release_viewport2( self, ) -> Option<(ViewportId, Flatland2ReleaseViewport2Responder)>

pub fn into_set_viewport_properties2( self, ) -> Option<(ViewportId, ViewportProperties, Flatland2ControlHandle)>

pub fn into_set_transform_content( self, ) -> Option<(TransformId, Option<Box<TransformContent>>, Flatland2ControlHandle)>

pub fn method_name(&self) -> &'static str

Name of the method defined in FIDL

Trait Implementations

impl Debug for Flatland2Request

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.