class Flatland

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.

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.

Identical to [`CreateView`], except it allows association of View identity (ViewRef) and

view-bound protocols.

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

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.

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.

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

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.

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.

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.

Removes a child Transform from a parent Transform.

Removes all child Transforms from a parent Transform and replaces them with the new child

transforms in `new_child_transform_ids`.

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`](T) is called, T receives a maximal hit region, covering the

entire view.

- If [`SetHitRegions`] is called on T, either before or after [`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`](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`] with the appropriate

vector.

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.

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

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.

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

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

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.

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.

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.

Sets an opacity in linear space to be applied to a flatland image. Opacity values must

be in the range [0.0, 1.0].

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.

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

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

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.

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.

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.

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

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.

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

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.

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.