Class WideLineRenderer

Renders a collection of WideLine objects using a single instanced draw call per camera/layer pass. Lines can use different widths, colors, caps, joins and dash patterns while remaining in the same batch, as these properties are stored in per-segment instance data.

Each WideLine describes a connected polyline in world space. Its width can vary per point and is interpreted as screen pixels or world units according to WideLineRenderer#widthUnits. A line can belong to only one WideLineRenderer at a time. Use WideLineRenderer#add and WideLineRenderer#remove to transfer ownership without changing the line data.

Basic usage

The following example creates a three-point line with a color gradient, variable width and rounded ends and joins:

const renderer = new WideLineRenderer(app);
const line = new WideLine();

line.set(
    new Float32Array([
        -2, 0, 0,
         0, 1, 0,
         2, 0, 0
    ]),
    new Float32Array([
        1, 0, 0,
        1, 1, 0,
        0, 1, 1
    ]),
    new Float32Array([4, 12, 4])
);
line.cap = LINECAP_ROUND;
line.join = LINEJOIN_ROUND;
renderer.add(line);

// Release GPU resources and detach all lines when no longer needed.
app.on('destroy', () => renderer.destroy());
Copy

Point data can be updated using WideLine#setPositions, WideLine#setColors and WideLine#setWidths. These methods preserve the point count and reuse the line's existing storage. Use WideLine#set when the point count needs to change.

Performance

Each line segment is rendered as one GPU instance. All segments owned by this renderer are submitted together, so adding more WideLine objects does not add draw calls. A renderer with visible segments issues one draw call for each camera that renders its layer. Multiple renderers therefore provide useful update isolation, but each adds another draw call per camera/layer pass.

Changing any owned line marks the renderer dirty. Before the next render, instance data for all of its lines is rebuilt and uploaded. For mixed workloads, place lines that rarely change in one renderer and frequently updated lines in another. There is no static or dynamic mode; the separation is achieved using two renderer instances. This prevents dynamic updates from repeatedly rebuilding the static segment data:

const staticLines = new WideLineRenderer(app);
const dynamicLines = new WideLineRenderer(app);

staticLines.add(roadNetwork); // Built and uploaded once.
dynamicLines.add(projectilePath); // Updated frequently.
Copy

Buffer WideLineRenderer#capacity is measured in segments and grows automatically as needed. Setting it in advance can avoid GPU buffer reallocations when the expected maximum segment count is known. WideLineRenderer#clear removes the lines but retains this capacity for reuse.

Rendering behavior and limitations

• Rendering is opaque. Packed colors contain rgb values, the alpha component of a Color is ignored and transparent lines are not supported.
• Widths use screen pixels by default. Set WideLineRenderer#widthUnits to LINEWIDTH_WORLD for camera-facing ribbons measured in world units.
• WideLineRenderer#depthTest and WideLineRenderer#depthWrite control interaction with the depth buffer. Both default to true.
• The renderer is added to the Immediate layer by default. Assign WideLineRenderer#layer to render it in another layer.
• The batch is not frustum culled. Disable the renderer using WideLineRenderer#enabled when none of its lines need to be rendered.
• Call WideLineRenderer#destroy to release the internal mesh, material and instance buffer. Detached lines remain usable and can be added to another renderer.

See the following examples for interactive styling and update demonstrations:

• https://playcanvas.github.io/#/graphics/wide-line
• https://playcanvas.github.io/#/graphics/wide-lines-styles
• https://playcanvas.github.io/#/graphics/wide-lines-dynamic