Struct FlatlandProxy

pub struct FlatlandProxy { /* private fields */ }

Implementations

impl FlatlandProxy

pub fn new(channel: Channel) -> FlatlandProxy

Create a new Proxy for fuchsia.ui.composition/Flatland.

pub fn take_event_stream(&self) -> FlatlandEventStream

Get a Stream of events from the remote end of the protocol.

Panics

Panics if the event stream was already taken.

pub fn present(&self, args: PresentArgs) -> Result<(), Error>

Complete execution of all feed-forward operations.

If executing an operation produces an error (e.g., CreateTransform(0)), an [OnError] event is emitted. Operations that produce errors are ignored and the channel is closed.

If the execution is completed successfully, [OnNextFrameBegin] emits NO_ERROR along with other valid fields.

The client may only call [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] event, which informs the client when it receives additional present credits. Each [Present] call uses one present credit and decrements the server count by one. If the client calls [Present] with no present credits, the server will return a NO_PRESENTS_REMAINING error.

The client should assume that prior to receiving any [OnNextFrameBegin] events, they have one present credit.

Every [Present] call results in one [OnNextFrameBegin] event, and one [OnFramePresented] event, typically in that order.

When the commands flushed by [Present] make it to display, an [OnFramePresented] event is fired. This event includes information pertaining to all [Present]s that had content that were part of that frame.

See [fuchsia.ui.composition/PresentArgs] documentation above for more detailed information on what arguments are passed in and their role.

pub fn create_view( &self, token: ViewCreationToken, parent_viewport_watcher: ServerEnd<ParentViewportWatcherMarker>, ) -> Result<(), Error>

Two Flatland instances may be connected in a parent-child relationship. The parent endpoint is held in a Viewport, and the child endpoint is held in a View. The parent Flatland instance that creates a Viewport has control over how the child’s View is integrated into its own View.

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], and the ViewCreationToken to the child, which calls [CreateView].

Only nodes connected to the Root Transform in this Flatland instance will be rendered into the parent’s Viewport.

Calling [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] 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] or [SetRootTransform]. This allows clients to wait for layout information from their parent before calling [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.

pub fn create_view2( &self, token: ViewCreationToken, view_identity: ViewIdentityOnCreation, protocols: ViewBoundProtocols, parent_viewport_watcher: ServerEnd<ParentViewportWatcherMarker>, ) -> Result<(), Error>

Identical to [CreateView], except it allows association of View identity (ViewRef) and view-bound protocols.

pub fn create_transform(&self, transform_id: &TransformId) -> Result<(), Error>

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 instances.

Transforms have attributes. Child Transforms inherit the combined attributes of their parents. Content attached to a Transform is also affected by that Transform’s attributes.

When a sub-graph of Transforms is rendered, Content will be rendered back-to-front, starting with the Content on the root transform, and continuing recursively through all of its child Transforms in the order the children were added. See [AddChild] for more information.

Zero is not a valid transform id. All other values are valid, assuming they are not already in use (see [ReleaseTransform] for more details).

pub fn set_translation( &self, transform_id: &TransformId, translation: &Vec_, ) -> Result<(), Error>

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.

pub fn set_orientation( &self, transform_id: &TransformId, orientation: Orientation, ) -> Result<(), Error>

Sets the orientation on a Transform. The order of geometric attribute application is addressed in the documentation for [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.

pub fn set_scale( &self, transform_id: &TransformId, scale: &VecF, ) -> Result<(), Error>

Sets the scale on a transform. The order of geometric attribute application is addressed above. The (x,y) values in the VecF |scale| refer to the scale factor in the x-axis (width) and y-axis (height) respectively. Scale values must be normal 32-bit floating point values: https://en.wikipedia.org/wiki/Normal_number_%28computing%29

pub fn set_opacity( &self, transform_id: &TransformId, value: f32, ) -> Result<(), Error>

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.

pub fn set_clip_boundary( &self, transform_id: &TransformId, rect: Option<&Rect>, ) -> Result<(), Error>

Sets the bounds, expressed in the local coordinate space of the transform, that constrains the region that content attached to this transform can be rendered to. If the content’s area exceeds the clip bounds, the area outside the bounds will not be rendered. These bounds are valid for all children of this transform node as well, which includes nested Flatland instances and their node hierarchies. If a child transform attempts to set clip bounds larger than that of its parent, it will be clipped to the parent’s clip bounds. The default state is for a transform to be unclipped, meaning it will not have any bounds placed on its render region. The clip width/height must be positive. Negative values will result in an error. Passing in an empty box to the |rect| parameter will remove the clip bounds.

pub fn add_child( &self, parent_transform_id: &TransformId, child_transform_id: &TransformId, ) -> Result<(), Error>

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.

pub fn remove_child( &self, parent_transform_id: &TransformId, child_transform_id: &TransformId, ) -> Result<(), Error>

Removes a child Transform from a parent Transform.

pub fn replace_children( &self, parent_transform_id: &TransformId, new_child_transform_ids: &[TransformId], ) -> Result<(), Error>

Removes all child Transforms from a parent Transform and replaces them with the new child transforms in new_child_transform_ids.

pub fn set_root_transform( &self, transform_id: &TransformId, ) -> Result<(), Error>

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]). Any parents of the Root Transform in this Graph will be ignored.

The Root Transform, and all children of the Root Transform, are kept alive if they are released (see [ReleaseTransform] for more details).

There is only ever one Root. Since 0 is not a valid transform id (see [CreateTransform]), calling SetRootTransform(0) clears the current Root, destroying any previously released objects that are not referenced by the new root.

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] documentation.

Default hit region rules

A default hit region follows these rules:

• When SetRootTransform is called, T receives a maximal hit region, covering the entire view.
• If [SetHitRegions] is called on T, either before or after SetRootTransform, 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 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] with the appropriate vector.

pub fn set_hit_regions( &self, transform_id: &TransformId, regions: &[HitRegion], ) -> Result<(), Error>

Sets the interactive areas for a Transform. By default, Content is not interactive; hit regions must be placed for a user to interact with the Content in a View. Because hit regions are described in the Flatland protocol, a Flatland instance can synchronize Content and hit regions.

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 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].

Note that root transforms get a default hit region installed by Flatland. For more details, see the [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]) and S ([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]), where a user expects to interact with Content that is visible, or front-most.

Across Flatland instances, for a given hit test, the front-most instance’s front-most Transform’s hit regions take precedence over those behind. This follows the expected reverse “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.

pub fn set_infinite_hit_region( &self, transform_id: &TransformId, hit_test: HitTestInteraction, ) -> Result<(), Error>

Identical to [SetHitRegions], except the hit region associated with [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].

pub fn create_viewport( &self, viewport_id: &ContentId, token: ViewportCreationToken, properties: &ViewportProperties, child_view_watcher: ServerEnd<ChildViewWatcherMarker>, ) -> Result<(), Error>

The Viewport and View pair, together, represent the connection between two Flatland instances. The Viewport is created in the parent, and the View is created in the child. The parent has control over how the child’s View is integrated into its own View.

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.

Zero is not a valid ContentId. All other values are valid, assuming they are not already in use for another piece of Content (see [ReleaseViewport] for more details).

Lifecycle note. The lifetime of the ChildViewWatcher channel is bound by the peer ViewCreationToken. When the ViewCreationToken dies, this ChildViewWatcher channel is destroyed.

pub fn create_image( &self, image_id: &ContentId, import_token: BufferCollectionImportToken, vmo_index: u32, properties: &ImageProperties, ) -> Result<(), Error>

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.)

Zero is not a valid Image id. All other values are valid, assuming they are not already in use for another piece of Content (see [ReleaseImage] for more details).

pub fn set_image_sample_region( &self, image_id: &ContentId, rect: &RectF, ) -> Result<(), Error>

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] and the sample region is specified by [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] 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].

pub fn set_image_destination_size( &self, image_id: &ContentId, size: &SizeU, ) -> Result<(), Error>

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]. The destination size will be affected by scaling if [SetScale] is used on the attached Transform or its parents.

pub fn set_image_blending_function( &self, image_id: &ContentId, blend_mode: BlendMode, ) -> Result<(), Error>

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.

pub fn set_image_opacity( &self, image_id: &ContentId, val: f32, ) -> Result<(), Error>

Sets an opacity in linear space to be applied to a flatland image. Opacity values must be in the range [0.0, 1.0].

pub fn set_image_flip( &self, image_id: &ContentId, flip: ImageFlip, ) -> Result<(), Error>

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.

pub fn create_filled_rect(&self, rect_id: &ContentId) -> Result<(), Error>

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

pub fn set_solid_fill( &self, rect_id: &ContentId, color: &ColorRgba, size: &SizeU, ) -> Result<(), Error>

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).

pub fn release_filled_rect(&self, rect_id: &ContentId) -> Result<(), Error>

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.

pub fn set_content( &self, transform_id: &TransformId, content_id: &ContentId, ) -> Result<(), Error>

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.

pub fn set_viewport_properties( &self, viewport_id: &ContentId, properties: &ViewportProperties, ) -> Result<(), Error>

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.

pub fn release_transform(&self, transform_id: &TransformId) -> Result<(), Error>

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).

pub fn release_view(&self) -> Result<(), Error>

pub fn release_viewport( &self, viewport_id: &ContentId, ) -> QueryResponseFut<ViewportCreationToken>

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] 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] and requires a call to [Present] to be executed. The ViewportCreationToken will be returned after the presented operations have been executed.

pub fn release_image(&self, image_id: &ContentId) -> Result<(), Error>

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).

pub fn clear(&self) -> Result<(), Error>

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.

pub fn set_debug_name(&self, name: &str) -> Result<(), Error>

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] can be an arbitrary string, but the current process name (see fsl::GetCurrentProcessName()) is a good default.

Trait Implementations

impl Clone for FlatlandProxy

fn clone(&self) -> FlatlandProxy

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for FlatlandProxy

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

Formats the value using the given formatter.

impl FlatlandProxyInterface for FlatlandProxy

type ReleaseViewportResponseFut = QueryResponseFut<ViewportCreationToken>

fn present(&self, args: PresentArgs) -> Result<(), Error>

fn create_view( &self, token: ViewCreationToken, parent_viewport_watcher: ServerEnd<ParentViewportWatcherMarker>, ) -> Result<(), Error>

fn create_view2( &self, token: ViewCreationToken, view_identity: ViewIdentityOnCreation, protocols: ViewBoundProtocols, parent_viewport_watcher: ServerEnd<ParentViewportWatcherMarker>, ) -> Result<(), Error>

fn create_transform(&self, transform_id: &TransformId) -> Result<(), Error>

fn set_translation( &self, transform_id: &TransformId, translation: &Vec_, ) -> Result<(), Error>

fn set_orientation( &self, transform_id: &TransformId, orientation: Orientation, ) -> Result<(), Error>

fn set_scale( &self, transform_id: &TransformId, scale: &VecF, ) -> Result<(), Error>

fn set_opacity( &self, transform_id: &TransformId, value: f32, ) -> Result<(), Error>

fn set_clip_boundary( &self, transform_id: &TransformId, rect: Option<&Rect>, ) -> Result<(), Error>

fn add_child( &self, parent_transform_id: &TransformId, child_transform_id: &TransformId, ) -> Result<(), Error>

fn remove_child( &self, parent_transform_id: &TransformId, child_transform_id: &TransformId, ) -> Result<(), Error>

fn replace_children( &self, parent_transform_id: &TransformId, new_child_transform_ids: &[TransformId], ) -> Result<(), Error>

fn set_root_transform(&self, transform_id: &TransformId) -> Result<(), Error>

fn set_hit_regions( &self, transform_id: &TransformId, regions: &[HitRegion], ) -> Result<(), Error>

fn set_infinite_hit_region( &self, transform_id: &TransformId, hit_test: HitTestInteraction, ) -> Result<(), Error>

fn create_viewport( &self, viewport_id: &ContentId, token: ViewportCreationToken, properties: &ViewportProperties, child_view_watcher: ServerEnd<ChildViewWatcherMarker>, ) -> Result<(), Error>

fn create_image( &self, image_id: &ContentId, import_token: BufferCollectionImportToken, vmo_index: u32, properties: &ImageProperties, ) -> Result<(), Error>

fn set_image_sample_region( &self, image_id: &ContentId, rect: &RectF, ) -> Result<(), Error>

fn set_image_destination_size( &self, image_id: &ContentId, size: &SizeU, ) -> Result<(), Error>

fn set_image_blending_function( &self, image_id: &ContentId, blend_mode: BlendMode, ) -> Result<(), Error>

fn set_image_opacity(&self, image_id: &ContentId, val: f32) -> Result<(), Error>

fn set_image_flip( &self, image_id: &ContentId, flip: ImageFlip, ) -> Result<(), Error>

fn create_filled_rect(&self, rect_id: &ContentId) -> Result<(), Error>

fn set_solid_fill( &self, rect_id: &ContentId, color: &ColorRgba, size: &SizeU, ) -> Result<(), Error>

fn release_filled_rect(&self, rect_id: &ContentId) -> Result<(), Error>

fn set_content( &self, transform_id: &TransformId, content_id: &ContentId, ) -> Result<(), Error>

fn set_viewport_properties( &self, viewport_id: &ContentId, properties: &ViewportProperties, ) -> Result<(), Error>

fn release_transform(&self, transform_id: &TransformId) -> Result<(), Error>

fn release_view(&self) -> Result<(), Error>

fn release_viewport( &self, viewport_id: &ContentId, ) -> <FlatlandProxy as FlatlandProxyInterface>::ReleaseViewportResponseFut

fn release_image(&self, image_id: &ContentId) -> Result<(), Error>

fn clear(&self) -> Result<(), Error>

fn set_debug_name(&self, name: &str) -> Result<(), Error>

impl Proxy for FlatlandProxy

type Protocol = FlatlandMarker

The protocol which this Proxy controls.

fn from_channel(inner: Channel) -> FlatlandProxy

Create a proxy over the given channel.

fn into_channel(self) -> Result<Channel, FlatlandProxy>

Attempt to convert the proxy back into a channel.

fn as_channel(&self) -> &Channel

Get a reference to the proxy’s underlying channel.

fn into_client_end(self) -> Result<ClientEnd<Self::Protocol>, Self>

Attempt to convert the proxy back into a client end.

fn is_closed(&self) -> bool

Returns true if the proxy has received the PEER_CLOSED signal.

fn on_closed(&self) -> OnSignals<'_, Unowned<'_, Handle>>

Returns a future that completes when the proxy receives the PEER_CLOSED signal.