Engine API Reference - v2.23.0-beta.23
    Preparing search index...

    Class OutlineRenderer

    The OutlineRenderer draws solid color outlines around the silhouettes of entities, for example to highlight objects that are selected or hovered in an editor. Each entity can be outlined in its own color.

    The outlines are generated in three steps:

    • An internal camera renders the mesh instances of the added entities into an offscreen texture matching the resolution of the scene camera, with each object drawn in its outline color.
    • The edges of the objects in the texture are detected and expanded to form the outlines.
    • The outlines are composited on top of the scene, just before the scene camera renders the layer passed to OutlineRenderer#frameUpdate.

    The outlines are drawn over everything the scene camera has rendered up to that layer, so they remain visible when the outlined objects are occluded by other objects. Anything rendered in that layer or after it, such as gizmos, is drawn on top of the outlines.

    OutlineRenderer#frameUpdate needs to be called every frame to keep the outlines in sync with the scene camera. Only render and model components are outlined, and the outline color is applied to mesh instances using a StandardMaterial.

    Relevant Engine API examples:

    // Create a layer used to render the outlined objects. It is added to the layer composition, but
    // not to the scene camera, so that the camera does not render the outlined objects a second time.
    const outlineLayer = new Layer({ name: 'OutlineLayer' });
    app.scene.layers.push(outlineLayer);

    // Create the outline renderer
    const outlineRenderer = new OutlineRenderer(app, outlineLayer);

    // Outline an entity and its descendants in red, and another entity in white
    outlineRenderer.addEntity(entity1, Color.RED);
    outlineRenderer.addEntity(entity2, Color.WHITE);

    // Each frame, composite the outlines into the scene before the scene camera renders the opaque
    // part of the 'Immediate' layer
    const immediateLayer = app.scene.layers.getLayerByName('Immediate');
    app.on('update', () => {
        outlineRenderer.frameUpdate(cameraEntity, immediateLayer, false);
    });

    // Later, stop outlining the first entity
    outlineRenderer.removeEntity(entity1);
    Index
    constructor
    addEntity destroy frameUpdate removeAllEntities removeEntity

    • Create a new OutlineRenderer.

      Parameters

      • app: AppBase

        The application.

      • OptionalrenderingLayer: Layer

        The layer the outlined mesh instances are added to, and which the internal outline camera renders. It must be part of the scene's layer composition. Defaults to the 'Immediate' layer. As the scene camera renders the 'Immediate' layer by default, the outlined objects are then rendered by the scene camera a second time - to avoid this, supply a dedicated layer which is not rendered by any other camera.

      • Optionalpriority: number = -1

        The priority of the internal outline camera. It needs to render before the scene camera, so it has to be smaller than the priority of the scene camera. Defaults to -1.

      Returns OutlineRenderer

    • Add an entity to the outline renderer, to draw an outline around it. The mesh instances of the entity's render and model components are outlined, including those of its descendants unless recursive is false. Adding an entity that is already outlined changes its outline color.

      Render and model components that are not currently rendered, because they or their entity are disabled, are skipped - this is evaluated when the entity is added.

      Note that this sets StandardMaterial#onUpdateShader on the materials of the outlined mesh instances, replacing any existing callback. OutlineRenderer#removeEntity clears it.

      Parameters

      • entity: Entity

        The entity to add.

      • color: Color

        The color of the outline. The alpha component is ignored.

      • Optionalrecursive: boolean = true

        Whether to also add the mesh instances of the entity's descendants. Defaults to true.

      Returns void

      // outline an entity and its descendants in orange
      outlineRenderer.addEntity(entity, new Color(1, 0.5, 0));

    • Update the outline renderer. This needs to be called once per frame, after the scene camera has been positioned, for example from the application's update event, which fires after scripts have been updated. It matches the internal outline camera to the scene camera's transform, projection, clip planes and resolution, and schedules the outlines to be composited into the scene for this frame.

      The outlines are composited just before the scene camera renders the opaque or transparent part of blendLayer, so that part of the layer, and everything rendered after it, is drawn on top of the outlines. The scene camera needs to render blendLayer, otherwise the outlines are not visible.

      Parameters

      • sceneCameraEntity: Entity

        The entity with the camera component used to render the scene.

      • blendLayer: Layer

        The layer before which the outlines are composited.

      • blendLayerTransparent: boolean

        True to composite the outlines before the transparent part of blendLayer, false to composite them before its opaque part.

      Returns void

      const immediateLayer = app.scene.layers.getLayerByName('Immediate');
      app.on('update', () => {
          outlineRenderer.frameUpdate(cameraEntity, immediateLayer, false);
      });

    • Remove all entities from the outline renderer, for example to clear the selection. Note that this removes all mesh instances from the rendering layer supplied to the constructor.

      Returns void

      // outline only the newly selected entity
      outlineRenderer.removeAllEntities();
      outlineRenderer.addEntity(selectedEntity, Color.WHITE);

    • Remove an entity from the outline renderer, to stop drawing its outline. This also works for an entity that has been disabled since it was added.

      Parameters

      • entity: Entity

        The entity to remove.

      • Optionalrecursive: boolean = true

        Whether to also remove the mesh instances of the entity's descendants. Defaults to true.

      Returns void

      outlineRenderer.removeEntity(entity);

    Settings
    Member Visibility

    On This Page
    Constructors
    Methods