# WireRenderer

Class · category: Graphics

Source: https://github.com/playcanvas/engine/blob/f059dc005842f76e052cdf44d8370c8c7ec475ac/src/extras/renderers/wire-renderer.js#L109

Renders wireframe shapes for a single frame, for debugging and visualization. Shapes are
submitted as line segments to the layer given by [WireRenderer#layer](https://api.playcanvas.com/engine/classes/WireRenderer.md#layer), which defaults to
the [LAYERID_IMMEDIATE](https://api.playcanvas.com/engine/variables/LAYERID_IMMEDIATE.md) layer, and are discarded once the frame has been rendered, so
they must be issued again on every frame they should be visible.

The renderer holds the state used by the shapes it draws - [WireRenderer#color](https://api.playcanvas.com/engine/classes/WireRenderer.md#color),
[WireRenderer#layer](https://api.playcanvas.com/engine/classes/WireRenderer.md#layer), [WireRenderer#depthTest](https://api.playcanvas.com/engine/classes/WireRenderer.md#depthtest), [WireRenderer#segments](https://api.playcanvas.com/engine/classes/WireRenderer.md#segments) and
[WireRenderer#transform](https://api.playcanvas.com/engine/classes/WireRenderer.md#transform). Fields can be assigned between calls, and drawing many shapes
with the same state allocates nothing:

```javascript
const wire = new WireRenderer(app);
wire.color = Color.RED;

app.on('update', () => {
    for (const item of items) {
        wire.sphere(item.position, item.radius);
    }
});
```

A second set of state is simply a second instance. Instances hold no GPU resources, and those
sharing a layer and depth test mode submit into the same batch, so using several has no
additional rendering cost:

```javascript
const xray = new WireRenderer(app);
xray.depthTest = false;
```

These are thin lines, one pixel wide. For thick lines with caps, joins and dashes, intended as
part of the rendered scene rather than as a debugging aid, see [WideLineRenderer](https://api.playcanvas.com/engine/classes/WideLineRenderer.md) instead.

## Constructors

### constructor

```ts
new WireRenderer(app: AppBase)
```

Creates a new WireRenderer instance.

**Parameters**

- `app` ([`AppBase`](https://api.playcanvas.com/engine/classes/AppBase.md)): The application.

**Example**

```ts
const wire = new WireRenderer(app);
```

## Properties

### color

```ts
color: Color
```

The color used by shapes, specified in sRGB color space. The alpha component is respected.
Defaults to white.

### depthTest

```ts
depthTest: boolean = true
```

Whether shapes are depth tested against the depth buffer. Defaults to true.

### layer

```ts
layer: Layer | null = null
```

The layer shapes are rendered into, or null to use the [LAYERID_IMMEDIATE](https://api.playcanvas.com/engine/variables/LAYERID_IMMEDIATE.md) layer.
Defaults to null.

### segments

```ts
segments: number = 20
```

The number of line segments used to approximate a full circle. Defaults to 20.

### transform

```ts
transform: Mat4 | null = null
```

A matrix applied to every point of every shape, or null for no transform. Assign this to
draw a group of shapes in the local space of a node. Defaults to null.

## Methods

### arrow

```ts
arrow(from: Vec3, to: Vec3): void
```

Renders an arrow, as a shaft with four barbs at its tip.

**Parameters**

- `from` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): The tail of the arrow.
- `to` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): The tip of the arrow.

**Example**

```ts
wire.arrow(position, position.clone().add(velocity));
```

### axes

```ts
axes(matrix: Mat4, size: number): void
```

Renders the three axes of a matrix, colored red, green and blue for x, y and z respectively.
This function ignores [WireRenderer#color](https://api.playcanvas.com/engine/classes/WireRenderer.md#color).

**Parameters**

- `matrix` ([`Mat4`](https://api.playcanvas.com/engine/classes/Mat4.md)): The transform whose axes are rendered.
- `size` (`number`): The length of each axis.

**Example**

```ts
wire.axes(entity.getWorldTransform(), 1);
```

### box

```ts
box(box: BoundingBox | OrientedBox): void
```

Renders the edges of a bounding box. An [OrientedBox](https://api.playcanvas.com/engine/classes/OrientedBox.md) is rendered in its own
orientation, composed with [WireRenderer#transform](https://api.playcanvas.com/engine/classes/WireRenderer.md#transform).

**Parameters**

- `box` ([`BoundingBox`](https://api.playcanvas.com/engine/classes/BoundingBox.md) `|` [`OrientedBox`](https://api.playcanvas.com/engine/classes/OrientedBox.md)): The box to render.

**Example**

```ts
wire.box(meshInstance.aabb);
```

### boxMinMax

```ts
boxMinMax(min: Vec3, max: Vec3): void
```

Renders the edges of a box specified by its min and max corners.

**Parameters**

- `min` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): The min corner of the box.
- `max` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): The max corner of the box.

**Example**

```ts
wire.boxMinMax(new Vec3(-1, -1, -1), new Vec3(1, 1, 1));
```

### capsule

```ts
capsule(start: Vec3, end: Vec3, radius: number): void
```

Renders a capsule as a ring and hemispherical cap at each end, joined by four side lines.

**Parameters**

- `start` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): The center of the start cap sphere.
- `end` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): The center of the end cap sphere.
- `radius` (`number`): The radius of the capsule.

**Example**

```ts
wire.capsule(feet, head, 0.4);
```

### circle

```ts
circle(center: Vec3, normal: Vec3, radius: number): void
```

Renders a circle lying in the plane described by a normal.

**Parameters**

- `center` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): The center of the circle.
- `normal` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): The normal of the plane containing the circle. Need not be
  normalized.
- `radius` (`number`): The radius of the circle.

**Example**

```ts
wire.circle(Vec3.ZERO, Vec3.UP, 5);
```

### cone

```ts
cone(apex: Vec3, direction: Vec3, angle: number, length: number): void
```

Renders a cone as a base ring joined to its apex by four side lines. The parameters match
those describing a spot light, so a light's cone can be visualized directly.

**Parameters**

- `apex` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): The tip of the cone.
- `direction` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): The direction the cone opens along. Need not be normalized.
- `angle` (`number`): The half-angle of the cone, in degrees, measured from `direction` to
  the cone edge.
- `length` (`number`): The distance from the apex to the base.

**Example**

```ts
wire.cone(position, direction, 30, 10);
```

### cylinder

```ts
cylinder(start: Vec3, end: Vec3, radius: number): void
```

Renders a cylinder as a ring at each end joined by four side lines.

**Parameters**

- `start` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): The center of the start cap.
- `end` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): The center of the end cap.
- `radius` (`number`): The radius of the cylinder.

**Example**

```ts
wire.cylinder(base, tip, 0.5);
```

### frustum

```ts
frustum(source: CameraComponent | Mat4): void
```

Renders the edges of a view frustum. The camera does not need to be enabled or rendering,
so the view volume of an inactive camera can be visualized.

**Parameters**

- `source` ([`CameraComponent`](https://api.playcanvas.com/engine/classes/CameraComponent.md) `|` [`Mat4`](https://api.playcanvas.com/engine/classes/Mat4.md)): A camera, or a view-projection matrix.

**Example**

```ts
wire.frustum(otherCamera.camera);
```

### light

```ts
light(light: LightComponent, size?: number): void
```

Renders the shape and extent of a light, using the light's own color. An omni light is drawn
as a sphere of its range, a spot light as its cone, and a directional light as an arrow
showing the direction it shines in. A light shines along the negative y-axis of its entity,
so the shape follows that axis rather than the entity's forward direction.

**Parameters**

- `light` ([`LightComponent`](https://api.playcanvas.com/engine/classes/LightComponent.md)): The light to render.
- `size` (`number`, optional, default `1`): The length of the arrow used for a directional light, which has no
  inherent extent. Defaults to 1.

**Example**

```ts
wire.light(entity.light);
```

### line

```ts
line(start: Vec3, end: Vec3): void
```

Renders a single line segment.

**Parameters**

- `start` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): The start of the line, in world space.
- `end` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): The end of the line, in world space.

**Example**

```ts
wire.line(new Vec3(0, 0, 0), new Vec3(0, 1, 0));
```

### lines

```ts
lines(positions: Vec3[], colors?: Color[]): void
```

Renders discrete line segments, formed by consecutive pairs of points.

**Parameters**

- `positions` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)`[]`): The points to draw lines between. The length must be a multiple
  of two.
- `colors` ([`Color`](https://api.playcanvas.com/engine/classes/Color.md)`[]`, optional): One color per point, or undefined to use
  [WireRenderer#color](https://api.playcanvas.com/engine/classes/WireRenderer.md#color). The color of each segment is interpolated between its ends.

**Example**

```ts
wire.lines([start, end], [Color.RED, Color.WHITE]);
```

### linesPacked

```ts
linesPacked(positions: number[] | Float32Array<ArrayBufferLike>, colors?: number[] | Float32Array<ArrayBufferLike>): void
```

Renders discrete line segments from packed arrays of numbers. This is the fastest of the
line functions, as it avoids reading individual [Vec3](https://api.playcanvas.com/engine/classes/Vec3.md) and [Color](https://api.playcanvas.com/engine/classes/Color.md) instances.

**Parameters**

- `positions` (`number[] | Float32Array<ArrayBufferLike>`): Packed xyz coordinates, forming pairs of points.
- `colors` (`number[] | Float32Array<ArrayBufferLike>`, optional): Packed rgba values, one color per point, or
  undefined to use [WireRenderer#color](https://api.playcanvas.com/engine/classes/WireRenderer.md#color).

**Example**

```ts
wire.linesPacked([0, 0, 0, 0, 1, 0]);
```

### loop

```ts
loop(positions: Vec3[], colors?: Color[]): void
```

Renders a closed strip of connected line segments, joining the last point back to the first.

**Parameters**

- `positions` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)`[]`): The points of the loop, in order.
- `colors` ([`Color`](https://api.playcanvas.com/engine/classes/Color.md)`[]`, optional): One color per point, or undefined to use
  [WireRenderer#color](https://api.playcanvas.com/engine/classes/WireRenderer.md#color).

**Example**

```ts
wire.loop(outline);
```

### plane

```ts
plane(center: Vec3, normal: Vec3, size: number): void
```

Renders a square section of a plane, with a short stub along its normal.

The rotation of the square within its plane is derived from the normal, and no such
derivation is continuous over all directions. An animated normal will therefore make the
square appear to jump as it passes the direction where the derivation switches. To rotate a
square smoothly, pass a fixed normal and drive [WireRenderer#transform](https://api.playcanvas.com/engine/classes/WireRenderer.md#transform) instead.

**Parameters**

- `center` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): The center of the square.
- `normal` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): The normal of the plane. Need not be normalized.
- `size` (`number`): The side length of the square.

**Example**

```ts
wire.plane(Vec3.ZERO, Vec3.UP, 10);
```

### point

```ts
point(position: Vec3, size: number): void
```

Renders a small axis-aligned cross marking a position.

**Parameters**

- `position` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): The position to mark.
- `size` (`number`): The overall length of each arm of the cross.

**Example**

```ts
wire.point(hit.point, 0.2);
```

### polyline

```ts
polyline(positions: Vec3[], colors?: Color[]): void
```

Renders an open strip of connected line segments.

**Parameters**

- `positions` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)`[]`): The points of the strip, in order.
- `colors` ([`Color`](https://api.playcanvas.com/engine/classes/Color.md)`[]`, optional): One color per point, or undefined to use
  [WireRenderer#color](https://api.playcanvas.com/engine/classes/WireRenderer.md#color).

**Example**

```ts
wire.polyline(trajectory);
```

### sphere

```ts
sphere(center: Vec3, radius: number): void
```

Renders a sphere as three great circles, one in each of the primary planes.

**Parameters**

- `center` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): The center of the sphere.
- `radius` (`number`): The radius of the sphere.

**Example**

```ts
wire.sphere(new Vec3(0, 1, 0), 0.5);
```