PixiJS

Class: RenderLayer

RenderLayer

The RenderLayer API provides a way to control the rendering order of objects independently of their logical parent-child relationships in the scene graph. This allows developers to decouple how objects are transformed (via their logical parent) from how they are rendered on the screen.

Key Concepts

RenderLayers Control Rendering Order:

  • RenderLayers define where in the render stack objects are drawn, but they do not affect an object's transformations (e.g., position, scale, rotation) or logical hierarchy.
  • RenderLayers can be added anywhere in the scene graph.

Logical Parenting Remains Unchanged:

  • Objects still have a logical parent for transformations via addChild.
  • Assigning an object to a layer does not reparent it.

Explicit Control:

  • Developers assign objects to layers using renderLayer.add and remove them using renderLayer.remove.

API Details

1. Creating a RenderLayer

A RenderLayer is a lightweight object responsible for controlling render order. It has no children or transformations of its own but can be inserted anywhere in the scene graph to define its render position.

const layer = new RenderLayer();
app.stage.addChild(layer); // Insert the layer into the scene graph

2. Adding Objects to a Layer

Use renderLayer.add to assign an object to a layer. This overrides the object's default render order defined by its logical parent.

const rect = new PIXI.Graphics();
container.addChild(rect);    // Add to logical parent
layer.attach(rect);      // Control render order via the layer

3. Removing Objects from a Layer

To stop an object from being rendered in the layer, use remove.

layer.remove(rect); // Stop rendering rect via the layer

When an object is removed from its logical parent (removeChild), it is automatically removed from the layer.

4. Re-Adding Objects to Layers

If an object is re-added to a logical parent, it does not automatically reassign itself to the layer. Developers must explicitly reassign it.

container.addChild(rect);    // Logical parent
layer.attach(rect);      // Explicitly reassign to the layer

5. Layer Position in Scene Graph

A layer's position in the scene graph determines its render priority relative to other layers and objects. Layers can be inserted anywhere in the scene graph.

const backgroundLayer = new RenderLayer();
const uiLayer = new RenderLayer();

app.stage.addChild(backgroundLayer);
app.stage.addChild(world);
app.stage.addChild(uiLayer);

This is a new API and therefore considered experimental at this stage. While the core is pretty robust, there are still a few tricky issues we need to tackle. However, even with the known issues below, we believe this API is incredibly useful!

Known issues:

  • Interaction may not work as expected since hit testing does not account for the visual render order created by layers. For example, if an object is visually moved to the front via a layer, hit testing will still use its original position.
  • RenderLayers and their children must all belong to the same renderGroup to work correctly

new RenderLayer (options)

ts:141

Creates a new RenderLayer instance

Name Type Attributes Default Description
options RenderLayerOptions

Configuration options for the RenderLayer
options.sortableChildren boolean <optional>
 false

If true, layer children will be automatically sorted each render
options.sortFunction Function <optional>

Custom function to sort layer children. Default sorts by zIndex

Extends

  • null

Members

defaultOptions RenderLayerOptions static

Default options for RenderLayer instances

Properties:
Name Type Description
sortableChildren boolean

If true, layer children will be automatically sorted each render. Default false.
sortFunction Function

Function used to sort layer children. Default sorts by zIndex.

renderLayerChildren Container[]

List of objects to be rendered by this layer

sortFunction (a: Container, b: Container) => number

Function used to sort layer children if sortableChildren is true

Methods

attach (…children) U[0]

ts:157

Add an Container to this render layer. The Container will be rendered as part of this layer while maintaining its original parent in the scene graph. If the Container already belongs to a layer, it will be removed from the old layer before being added to this one.

Name Type Description
children U

The Container(s) to add to this layer
Returns:
Type Description
U[0]

detach (…children) U[0]

ts:191

Remove an Container from this render layer. The Container will no longer be rendered as part of this layer but maintains its original parent.

Name Type Description
children U

The Container(s) to remove from this layer
Returns:
Type Description
U[0]

detachAll ()

ts:222

Remove all objects from this render layer.

sortRenderLayerChildren ()

ts:259

Sort the layer's children using the defined sort function. Will be called each render if sortableChildren is true. Otherwise can call this manually.