Flatland scene dump

This document describes how to dump information about the Flatland scene and reading the output. This guide is useful if you want to debug the state of the Flatland scene while developing for Fuchsia and using Flatland to create a graphical view. For more information about Flatland, see Flatland.

Inspect your Flatland scene

You can use Component Inspection to dump information about the Flatland scene:

ffx inspect show core/ui/scenic:root/scenic/FlatlandEngine:scene_dump

Understanding the scene dump output

The scene information can be categorized into three different sections:

Topology

Example output:


Topology:

2:0-| <-- (FlatlandDisplay)
 | 2:1-|
 |  | 4:1-|
 |  |  | 4:0-| <-- (SceneManager Display)
 |  |  |  | 4:2-|
 |  |  |  |  | 4:3-|
 |  |  |  |  |  | 4:4-|
 |  |  |  |  |  |  | 3:1-|
 |  |  | 4:5-|
 |  |  |  | 4:6-|
 |  |  |  |  | 5:1

The topology section creates an ASCII representation of the entire Flatland scene.

Each Flatland Transform node is represented by a pair of numbers. The first number in the pair is the *Flatland Instance Id*. It represents which Flatland Instance created that particular Transform. The second number in the pair is the Transform Id. This is a user-defined identifier for the Transform, unique among all Transforms created by an Instance. In the example above, (2:0), (2:1), (4:1) (and so on) represent Transform nodes. The Flatland Instance with the identifier 2 has created two Transforms (0 and 2).

Each line only contains one Transform node, and may include a debug name. The debug name may be specified using fuchsia.ui.composition.Flatland.SetDebugName. In the example above, node (2:0) has the debug name FlatlandDisplay.

The "-|" symbol represents a parent/child relationship between the nodes, creating a graph structure. For instance, node (2:1) is a child of node (2:0). Please see fuchsia.ui.composition.Flatland for further details on the implications. In short, this means that node (2:1) will be rendered on top of node (2:0). Similarly, the relationship between two Flatland instances is captured. node (2:1) and node (4:1) have a Viewport/View relationship, in which the content of the root Transform node (4:1) (and the resulting child node graph rendered) is displayed as content in node (2:1).

Note that, in the example above, node (4:1) has two child nodes -- (4:0) and (4:5). Direct children nodes are represented at the same indentation column. The lines between those two nodes represent the sub-graph of child node (4:0). The lines following node (4:1) represent the sub-graph of node (4:1).

The topology will always begin at the root node of the Display. This means that any Flatland Instances and Transforms that are not connected to the Display graph will not be shown in the ASCII representation.

All instances

Example output:


All Instances:

Instance 2 (FlatlandDisplay):
2:0-|
 | 2:1-|

Instance 4 (SceneManager Display):
4:1-|
 | 4:0-|
 |  | 4:2-|
 |  |  | 4:3-|
 |  |  |  | 4:4-|
   4:5-|
      4:6

Instance 3:
3:1-|

Instance 5:
5:1-|

Instance 6:
6:1-|
   6:2-|
      6-3-|

This section lists the topology of the Flatland Instances, without showing the Viewport/View connection between Instances. The ASCII representation is similar except that each Flatland Instance is listed separately.

Remember that the Topology section noted that only the Topology of Instances connected to the root display node are shown. In this output, all Instances are listed, regardless if they are connected to the root display topology or not. In the example above, Instance 6 is not connected to the root node topology which is why it is not shown in the example from the Topology section.

Image and image-rectangles

Example output:


Frame display-list contains 2 images and image-rectangles.
        image: size=1280x800  multiply_color=(1,1,1,1)  blend_mode=SRC
        transform: (4:3)
        rect: Rectangle2D[origin:(0, 0) extent:(1280, 800) clockwise_uvs:[(1, 0),(1, 1),(0, 1),(0, 0)]]
        image: size=64x64  multiply_color=(1,1,1,1)  blend_mode=SRC_OVER
        transform: (3:1)
        rect: Rectangle2D[origin:(128, 128) extent:(64, 64) clockwise_uvs:[(1, 0),(1, 1),(0, 1),(0, 0)]]

This section lists Flatland images created using fuchsia.ui.composition.Flatland.CreateImage. Information about each image is represented on three lines.

The first line shows the image properties. This includes:

The second line shows the Transform node which created the image.

The third line lists the properties of the Image Rectangle. This includes:

  • The origin, representing the top-left corner of the Rectangle.
  • The extent, representing the width and the height of the Rectangle.
  • The clockwise mapping UVs. Starting at the top-left corner and rotating clockwise, each corner's (x, y) sample point is represented with a value in the range [0.0, 1.0]. The clockwise UVs therefore contain information about the sample region, clipping region and rotation.