Documentation / scene / Primitive

Class: Primitive

Defined in: libs/scene/src/render/primitive.ts:44

Holds vertex/index data and draw parameters for a mesh geometry.

Responsibilities:

• Owns one or more vertex buffers and an optional index buffer.
• Defines primitive topology, draw range (start/count), and vertex layout.
• Provides utilities to create/set/remove buffers and query vertex/face counts.
• Tracks changes via a change tag and notifies render-bundle caching.
• Optionally stores a bounding volume and supports ray intersection tests.

Ownership and lifecycle:

• When adding buffers (setVertexBuffer, setIndexBuffer), the primitive retains them.
• When removing/overwriting buffers, the primitive releases the previous buffers.
• Disposing the primitive also disposes the internal VertexLayout and releases retained buffers.

Extends

• object & Disposable<this>

Extended by

• Shape

Implements

• Clonable<Primitive>

Constructors

Constructor

new Primitive(): Primitive

Defined in: libs/scene/src/render/primitive.ts:81

Create an empty primitive.

Defaults:

• Primitive type: 'triangle-list'
• indexStart = 0, indexCount = null (auto-computed)
• No vertex/index buffers attached
• No bounding volume

Returns

Primitive

Overrides

makeObservable(Disposable)<{ bv_changed: []; }>().constructor

Accessors

disposed

Get Signature

get disposed(): boolean

Defined in: libs/base/dist/index.d.ts:6107

Returns

boolean

Inherited from

makeObservable(Disposable)<{ bv_changed: []; }>().disposed

---

id

Get Signature

get id(): number

Defined in: libs/scene/src/render/primitive.ts:100

Unique runtime identifier of this primitive.

Returns

number

The numeric instance id.

---

changeTag

Get Signature

get changeTag(): number

Defined in: libs/scene/src/render/primitive.ts:109

Change tag that increments whenever draw-affecting state changes. Useful for invalidating cached render bundles.

Returns

number

The current change tag value.

---

primitiveType

Get Signature

get primitiveType(): PrimitiveType

Defined in: libs/scene/src/render/primitive.ts:146

Primitive topology.

Returns

PrimitiveType

Set Signature

set primitiveType(type): void

Defined in: libs/scene/src/render/primitive.ts:149

Parameters

type

PrimitiveType

Returns

void

---

indexStart

Get Signature

get indexStart(): number

Defined in: libs/scene/src/render/primitive.ts:159

Starting index/vertex for drawing.

Returns

number

Set Signature

set indexStart(val): void

Defined in: libs/scene/src/render/primitive.ts:162

Parameters

val

number

Returns

void

---

indexCount

Get Signature

get indexCount(): number

Defined in: libs/scene/src/render/primitive.ts:172

Number of indices/vertices to draw.

Returns

number

Set Signature

set indexCount(val): void

Defined in: libs/scene/src/render/primitive.ts:176

Parameters

val

number

Returns

void

Methods

on()

Call Signature

on<K>(type, listener, context?): void

Defined in: libs/base/dist/index.d.ts:671

IEventTarget.on

Type Parameters

K

K extends "dispose" | "bv_changed"

Parameters

type

K

listener

EventListener<object & object, K>

context?

unknown

Returns

void

Inherited from

makeObservable(Disposable)<{ bv_changed: []; }>().on

Call Signature

on<K>(type, listener, context?): void

Defined in: libs/base/dist/index.d.ts:630

IEventTarget.on

Type Parameters

K

K extends "dispose"

Parameters

type

K

listener

EventListener<{ dispose: []; }, K>

context?

unknown

Returns

void

Inherited from

makeObservable(Disposable)<{ bv_changed: []; }>().on

---

once()

Call Signature

once<K>(type, listener, context?): void

Defined in: libs/base/dist/index.d.ts:675

IEventTarget.once

Type Parameters

K

K extends "dispose" | "bv_changed"

Parameters

type

K

listener

EventListener<object & object, K>

context?

unknown

Returns

void

Inherited from

makeObservable(Disposable)<{ bv_changed: []; }>().once

Call Signature

once<K>(type, listener, context?): void

Defined in: libs/base/dist/index.d.ts:634

IEventTarget.once

Type Parameters

K

K extends "dispose"

Parameters

type

K

listener

EventListener<{ dispose: []; }, K>

context?

unknown

Returns

void

Inherited from

makeObservable(Disposable)<{ bv_changed: []; }>().once

---

off()

Call Signature

off<K>(type, listener, context?): void

Defined in: libs/base/dist/index.d.ts:679

IEventTarget.off

Type Parameters

K

K extends "dispose" | "bv_changed"

Parameters

type

K

listener

EventListener<object & object, K>

context?

unknown

Returns

void

Inherited from

makeObservable(Disposable)<{ bv_changed: []; }>().off

Call Signature

off<K>(type, listener?, context?): void

Defined in: libs/base/dist/index.d.ts:638

IEventTarget.off

Type Parameters

K

K extends "dispose"

Parameters

type

K

listener?

EventListener<{ dispose: []; }>

context?

unknown

Returns

void

Inherited from

makeObservable(Disposable)<{ bv_changed: []; }>().off

---

dispatchEvent()

Call Signature

dispatchEvent<K>(type, ...args): void

Defined in: libs/base/dist/index.d.ts:683

IEventTarget.dispatchEvent

Type Parameters

K

K extends "dispose" | "bv_changed"

Parameters

type

K

args

...object & object[K]

Returns

void

Inherited from

makeObservable(Disposable)<{ bv_changed: []; }>().dispatchEvent

Call Signature

dispatchEvent<K>(type, ...args): void

Defined in: libs/base/dist/index.d.ts:642

IEventTarget.dispatchEvent

Type Parameters

K

K extends "dispose"

Parameters

type

K

args

...object[K]

Returns

void

Inherited from

makeObservable(Disposable)<{ bv_changed: []; }>().dispatchEvent

---

dispose()

dispose(): void

Defined in: libs/base/dist/index.d.ts:6108

Returns

void

Inherited from

makeObservable(Disposable)<{ bv_changed: []; }>().dispose

---

clone()

clone(): Primitive

Defined in: libs/scene/src/render/primitive.ts:119

Create a shallow clone: copies topology, draw range, and buffers.

Note: Buffers are re-retained on the new primitive.

Returns

Primitive

A cloned Primitive instance.

Implementation of

Clonable.clone

---

copyFrom()

copyFrom(other): void

Defined in: libs/scene/src/render/primitive.ts:134

Copy from another primitive.

Copies:

• All vertex buffers and the index buffer
• Primitive type, index start, index count

Parameters

other

this

The source primitive to copy from.

Returns

void

void

---

getNumVertices()

getNumVertices(): number

Defined in: libs/scene/src/render/primitive.ts:188

Query total vertex count from the position buffer, if present.

Returns

number

Total vertex count; 0 if no position buffer is set.

---

getNumFaces()

getNumFaces(): number

Defined in: libs/scene/src/render/primitive.ts:200

Query total face/segment count based on topology and buffer size.

• For indexed geometry: derived from index buffer.
• For non-indexed: derived from position vertex count.

Returns

number

Total primitive count for the current topology.

---

removeVertexBuffer()

removeVertexBuffer(semantic): void

Defined in: libs/scene/src/render/primitive.ts:230

Remove all vertex buffers that match a given semantic.

This releases retained buffers, marks the layout dirty, and invalidates bundles.

Parameters

semantic

VertexSemantic

The vertex semantic to remove (e.g., 'position', 'normal').

Returns

void

void

---

getVertexBuffer()

getVertexBuffer(semantic): StructuredBuffer<unknown>

Defined in: libs/scene/src/render/primitive.ts:250

Get the vertex buffer that matches a given semantic.

Parameters

semantic

VertexSemantic

The vertex semantic to look up.

Returns

StructuredBuffer<unknown>

The matching vertex buffer, or null if not found.

---

getVertexBufferInfo()

getVertexBufferInfo(semantic): VertexBufferInfo

Defined in: libs/scene/src/render/primitive.ts:264

Get vertex buffer information for a given semantic.

Parameters

semantic

VertexSemantic

The vertex semantic to look up.

Returns

VertexBufferInfo

The VertexBufferInfo, or null if not found.

---

createAndSetVertexBuffer()

createAndSetVertexBuffer(format, data, stepMode?): StructuredBuffer<unknown>

Defined in: libs/scene/src/render/primitive.ts:279

Create a vertex buffer from data and add it to the primitive.

• For interleaved layouts, pass an array of VertexAttribFormat.
• For a single attribute, pass a single VertexAttribFormat.

Parameters

format

VertexAttribFormat | VertexAttribFormat[]

Vertex attribute format(s).

data

TypedArray

Typed array with vertex data.

stepMode?

VertexStepMode

Optional step mode (e.g., 'vertex', 'instance').

Returns

StructuredBuffer<unknown>

The created StructuredBuffer.

---

setVertexBuffer()

setVertexBuffer(buffer, stepMode?): StructuredBuffer<unknown>

Defined in: libs/scene/src/render/primitive.ts:299

Add an existing vertex buffer to the primitive.

Ownership note: The primitive retains the buffer; it will be released or disposed when replaced or on dispose.

Parameters

buffer

StructuredBuffer

The vertex buffer to add.

stepMode?

VertexStepMode

Optional step mode for the buffer.

Returns

StructuredBuffer<unknown>

The same buffer.

---

createAndSetIndexBuffer()

createAndSetIndexBuffer(data, dynamic?): IndexBuffer<unknown>

Defined in: libs/scene/src/render/primitive.ts:317

Create an index buffer from data and set it on the primitive.

Parameters

data

Uint16Array<ArrayBuffer> | Uint32Array<ArrayBuffer>

Index data as Uint16Array or Uint32Array.

dynamic?

boolean

Whether the index buffer is dynamic (unmanaged).

Returns

IndexBuffer<unknown>

The created IndexBuffer.

---

setIndexBuffer()

setIndexBuffer(buffer): void

Defined in: libs/scene/src/render/primitive.ts:335

Set or replace the index buffer.

Ownership note: The primitive retains the buffer; previous buffer is released. Marks the vertex layout dirty and invalidates bundles.

Parameters

buffer

IndexBuffer<unknown>

The index buffer to set (non-null).

Returns

void

void

---

getIndexBuffer()

getIndexBuffer(): IndexBuffer<unknown>

Defined in: libs/scene/src/render/primitive.ts:350

Get the current index buffer.

Returns

IndexBuffer<unknown>

The index buffer, or undefined/null if none set.

---

draw()

draw(): void

Defined in: libs/scene/src/render/primitive.ts:358

Issue a non-instanced draw for the current topology and range.

Preconditions: A valid vertex layout and indexCount > 0.

Returns

void

---

drawInstanced()

drawInstanced(numInstances): void

Defined in: libs/scene/src/render/primitive.ts:371

Issue an instanced draw for the current topology and range.

Preconditions: A valid vertex layout and indexCount > 0.

Parameters

numInstances

number

Number of instances to draw.

Returns

void

---

onDispose()

protected onDispose(): void

Defined in: libs/scene/src/render/primitive.ts:380

Dispose this primitive and release associated GPU resources.

Returns

void

Overrides

makeObservable(Disposable)<{ bv_changed: []; }>().onDispose

---

getBoundingVolume()

getBoundingVolume(): BoundingVolume

Defined in: libs/scene/src/render/primitive.ts:405

Get the bounding volume associated with this primitive.

Returns

BoundingVolume

The current bounding volume, or null if not set.

---

setBoundingVolume()

setBoundingVolume(bv): void

Defined in: libs/scene/src/render/primitive.ts:416

Set or replace the bounding volume of this primitive.

Triggers registered bounding-volume change callbacks.

Parameters

bv

BoundingVolume

The bounding volume to set.

Returns

void

void

---

raycast()

raycast(ray): number

Defined in: libs/scene/src/render/primitive.ts:428

Test intersection against the current axis-aligned bounding box (AABB).

Parameters

ray

Ray

Ray to test against the primitive's AABB (derived from its bounding volume).

Returns

number

The distance from ray origin to the intersection, or null if no hit or no AABB.