ConversionSystems

How does conversion work?

When you build your UI in your a subscene, Unity automatically converts all GameObjects to their entity format. This is done through all Authoring components (MonoBehaviours which implement the interface, IConvertGameObjectToEntity and any GameObjectToConversionSystem).

Conversion Systems

All elements are initially converted through their own respective systems. For example, images are converted through the PerImageConversionSystem, text through the PerTextConversionSystem and so on.

Below is a list of the conversion systems.

System	What does it do?
PerImageConversionSystem	Adds the LinkedMaterialEntity, LinkedTextureEntity, AppliedColor, and ImageFillAmount if the option is enabled.
PerTextConversionSystem	Adds the LinkedMaterialEntity, AppliedColor, TextOptions, LinkedTextFontEntity, and a DynamicBuffer of CharElements.
PerCanvasConversionSystem	Adds the CanvasScaler, ReferenceResolution, Dimensions, and ScreenSpace.
RectTransformConversionSystem	Removes all Unity Transform components. Adds the LocalSpace and ScreenSpace components in place of the Unity Transform components. Adds the Parent component if a parent exists for the transform. Adds the Anchor or Stretch components based on their Anchor presets.
DeclareRenderDataConversionSystem	Declares all font assets as entities. Conversion is done by the PerFontAssetConversionSystem.
PerFontAssetConversionSystem	Adds a DynamicBuffer of GlyphElements and FontFaceInfo.
PerButtonConversionSystem	Adds the ColorStates and ButtonVisualState. If the button is not interactable by default, it adds the NonInteractableTag.
BakedEntityNameConvesionSystem	Adds the BakedEntityName to store the GameObject's name, useful for debugging entities' names.
HierarchyConversionSystem	The HierarchyConversionSystem is complex and needs its own section to outline everything it does. See below.

HierarchyConversonSystem

The bulk of the conversion pipeline is done by the HierarchyConversionSystem and it is the last step in the conversion pipeline for UGUIDOTS. All the conversion systems mentioned above effectively add metadata which describes how the UI element appears on the screen.

What does the HierarchyConversonSystem do?

First it analyzes the hierarchy and creates submeshes of all children in the Canvas. Batches are built if the texture and the material amongst different GameObjects are the same.

• SubmeshKeyElement
  • Contains a reference to the linked Texture and Material entities.
• RenderElement
  • Stores the first entity in each submesh level. This entity is representative of the entire submesh's properties.
• Vertex
  • Stores the mesh vertex information (position, color, uv coordinates, normals, etc)
• Index
  • Stores the mesh indices to generate a triangle
• Reference Resolution
  • Stores the resolution the canvas was authored with.
• Dimension
  • Stores the current dimension from the RectTransform.
• StaticDataCount
  • Stores the total number of vertices and indices which are considered static (their representation does not change).
• SubmeshSliceElement
  • Stores the total number of vertices and indices and its position in the DynamicBuffer and DynamicBuffer that describes each submesh.
• Enabled
  • Stores whether or not the Entity is enabled in the hierarchy.

Children Entities

Children entities will get a component called SubmeshIndex, which defines which submesh the element belongs to. For example, if a mesh has 5 sublevels and an Image entity is part of submesh index 0, that means the Image is part of the first submesh.

Dynamic Text is generally added to the last level of the submesh because they need to be rebuilt and we want to avoid rebatching static elements everytime the text updates.

How are batches built?

Batches are determined by the UI element's texture if available and its material. If UI elements share the same textures and materials, then they should be batched together to reduce the draw call.

Why would you want to rebatch UI?

Well, in the event you need to replace an image, it would make sense to detect if that image is used elsewhere in the canvas. If it is, then we can determine whether or not it would make sense to rebatch the UI and redetermine how many submeshes should exist in the UI.

Missing Features

Currently, the ability to rebatch is not supported yet and will be worked on. This requires that elements are reanalyzed and their SubmeshIndex is updated to accomodate its new Submesh that the UI element belongs to.