Class BufferedEntityInstancing

Namespace

Stride.CommunityToolkit.Rendering.Instancing

Assembly

Stride.CommunityToolkit.dll

An EntityInstancing that owns its GPU buffers, so a scene where nothing moves costs no upload bandwidth at all.

public class BufferedEntityInstancing : InstancingUserBuffer, IInstancing, IDisposable

Inheritance

object

InstancingUserBuffer

BufferedEntityInstancing

Implements

IInstancing

IDisposable

Inherited Members

InstancingUserBuffer.InstanceWorldBuffer

InstancingUserBuffer.InstanceWorldInverseBuffer

InstancingUserBuffer.InstanceCount

InstancingUserBuffer.BoundingBox

Remarks

On the normal InstancingUserArray path the engine re-uploads every instance matrix each frame, even when they are identical to the last frame's - two matrices per instance, so 2.5 MB per frame at 20,000 instances. Deriving from InstancingUserBuffer instead puts the buffers under user control, and this class uploads only when the gather actually ran.

It requires an InstancingBufferUploadRenderer in the graphics compositor, which AddInstancingBufferUpload registers in the right place. Without it nothing is ever drawn, because the buffers are never created. Register it once and add every buffered instancing to it.

Pass the gather to the constructor to choose its behaviour - most usefully BepuEntityInstancing, which adds the sleep skip that makes the saving worthwhile. The buffers are released by Dispose(); the engine never releases user-owned buffers.

Constructors

BufferedEntityInstancing(EntityInstancing?)

Initializes a new instance backed by the given gather, or a plain EntityInstancing.

public BufferedEntityInstancing(EntityInstancing? gather = null)

Parameters

gather EntityInstancing

The instancing that collects the matrices. Use BepuEntityInstancing for physics bodies so settled scenes skip both the gather and the upload.

Properties

Gather

Gets the instancing that collects the matrices.

public EntityInstancing Gather { get; }

Property Value

EntityInstancing

LastUpdateMilliseconds

Gets how long the last Update() took. Intended for diagnostics and on-screen counters.

public double LastUpdateMilliseconds { get; }

Property Value

double

ModelTransformUsage

public override ModelTransformUsage ModelTransformUsage { get; }

Property Value

ModelTransformUsage

Remarks

Instance matrices are already in world space, so the master's own transform is ignored.

RegisteredInstanceCount

Gets the number of registered instances.

public int RegisteredInstanceCount { get; }

Property Value

int

UpdateSkippedLastFrame

Gets a value indicating whether the last update was skipped because nothing had moved.

public bool UpdateSkippedLastFrame { get; }

Property Value

bool

Remarks

Always false here; see BepuEntityInstancing.

UploadSkippedLastFrame

Gets a value indicating whether the last frame sent no data to the GPU.

public bool UploadSkippedLastFrame { get; }

Property Value

bool

Methods

AddInstance(Entity)

Registers an entity as an instance. Its TransformComponent is captured once, so the entity must not be reparented into a different transform component afterwards.

public bool AddInstance(Entity entity)

Parameters

entity Entity

The entity to draw as an instance. Must not carry a ModelComponent.

Returns

bool

true if it was added; false if it was already registered.

Clear()

Unregisters every instance.

public void Clear()

Dispose()

Releases the GPU buffers. The engine never releases user-owned buffers, so without this they live until the graphics device does.

public void Dispose()

Remarks

Call once the master entity is gone and no frame is in flight, such as after Game.Run returns. Registering the instancing with a compositor renderer after disposing it is not valid.

Dispose(bool)

Releases the GPU buffers.

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

true when called from Dispose().

RemoveInstance(Entity)

Unregisters an entity. Removing the entity from the scene does not unregister it, unlike the engine's InstanceComponent.

public bool RemoveInstance(Entity entity)

Parameters

entity Entity

The entity to stop drawing.

Returns

bool

true if it was registered.

Update()

Called by Stride's instancing processor once per frame, possibly on a worker thread. Does CPU work only; the GPU work happens in InstancingBufferUploadRenderer.

public void Update()

Remarks

Hides rather than overrides Update(), which is not virtual; the processor calls it through IInstancing, which this class re-implements.