class Flatland2

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

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.

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.

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.

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.

Creates a new layer stack with the specified `stack_id`.

`stack_id` must satisfy the identifier rules documented on [`LayerId`].

Releases the layer stack with the specified `stack_id`.

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.

Creates an Image resource.

`image_id` must satisfy the identifier rules documented on [`LayerId`].

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.

Creates a Viewport resource.

`viewport_id` must satisfy the identifier rules documented on [`LayerId`].

Releases a Viewport from the scene.

Sets the properties of a Viewport.

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.