V12 Documentation - Primary Canvas Objects V2

[Feu-Secret]

Primary Canvas Object V2

Reminder on the Purpose of Primary Canvas Objects

The PrimaryCanvasGroup serves as the container where all scene objects, excluding light and vision, are drawn. In this group, we handle object elevation and various occlusion effects when objects overlap. These functionalities are managed by specific objects known as Primary Canvas Objects (PCOs), which typically inherit from a PIXI.DisplayObject (e.g., SpriteMesh, PIXI.Graphics, etc.).

Additionally, we need to draw what we refer to as depth (encoding elevation), to determine whether certain parts of light sources or vision should be drawn and to perform some occlusion features. The depth is drawn into its own separate texture into CanvasDepthMask (using a different render path, even if the PCO is bound to the PrimaryCanvasGroup container). It is the role of the PCO to provide our framework with the necessary API to handle these specific cases.

Initial Behavior

An intermediate data layer was stored in the Primary Canvas Object (PCO) as the data property. The purpose of this data property was to keep track of input data, transform it into data understood by the PCO, and handle some of the processing that should have been the owner's responsibility.

Several classes are derived from PCOs, such as TokenMesh and TileMesh. Each of these classes carried out specific treatments associated with certain kinds of Placeable. While this operational mode had some advantages, it also had drawbacks; it was notably less reusable, and each class had different internal functioning.

Addressed Issues

It was deemed that this approach was too complex and deviated too much from the PIXI schema associated with PIXI.DisplayObject. Moreover, the intermediate layer was not very efficient as it required calling the initialize method, which was quite resource-intensive in terms of value and object copying. This intermediate layer and the classes specific to certain Placeable were removed.

New Behavior

The use of PCOs has been streamlined to align more closely with PIXI standards. All properties now behave like any inherited PIXI.DisplayObject. It is the responsibility of the caller to initialize the object's properties, as they would with any PIXI object. PCOs no longer perform intermediate processing regarding the positioning and dimensions of the object.

For the moment, PCO can only be direct children of the PrimaryCanvasGroup container.

Currently, there are two main categories of PCOs:

• PrimarySpriteMesh
  This class incorporates the necessary elements to manage Sprites, including the following specifics:

  • Elevation management
  • Depth rendering
  • Occlusion and hover fade management

• PrimaryGraphics
  This class is the counterpart to PIXI.Graphics, adapted for use in the PrimaryCanvasGroup. It enables elevation management, with new features planned for prototype 2.

In V11, if you needed to add occlusion behavior to a Sprite, you would have used either a TokenMesh or a TileMesh depending on the type of the Sprite. In V12, you can use a single class, PrimarySpriteMesh to configure any behavior you want, may it be a Token, a Tile, or anything which is drawn into the PrimaryCanvasGroup.

Priority

Each frame, after the placeable objects are refreshed (ticker priority OBJECTS) and before perception is refreshed (ticker priority PERCEPTION), we update, if necessary, the canvas bounds/transforms of all objects inside the primary group as well as their quadtree entries (ticker priority PRIMARY) . We also determine which objects should render to the depth mask and update the elevation-to-depth mapping, if necessary. Therefore, after the primary group has been updated, you must not ...

• add/remove objects to/from the primary group, and
• change any of the following object properties.
  • anchor
  • transform (that includes position, rotation, scale, width, height, ...)
  • elevation
  • texture
  • textureAlphaThreshold
  • roof
  • hidden

Changes to these properties and adding/removing object from primary group need to be done before the primary group is updated.
In general, you must not change any property that would change the bounds of the object or change whether the object is depth rendered.

Compatibility

The design of new V12 Primary Canvas Objects (PCOs) and the PrimarySpriteMesh class differs significantly from its predecessors; TileMesh and TokenMesh are no longer present.

Providing a compatibility API for these removed classes would be costly and would require us to sacrifice other V12 features to work on that. As such, we have not prioritized compatibility for these removals yet and we are requesting community feedback on whether this work is necessary. We want to understand the use cases where TileMesh or TokenMesh were used previously, particularly cases where a migration to the new PrimarySpriteMesh class is not feasible for the developer.

Feedback and insights from our dev community will guide our prioritization; we will invest in more backwards compatibility tools for TileMesh and TokenMesh if we receive clear feedback that it is necessary. Otherwise we will channel our development efforts into new APIs and VTT features.