InstancingRenderFeature

Remarks

The instance offset is a draw-call argument, not a binding. One storage buffer holds every instanced object's transforms back to back and is bound once for the frame; a draw reaches its own run through firstInstance, which Vulkan adds into gl_InstanceIndex before the shader ever sees it. So there is no descriptor per object, no dynamic offset, no alignment to round up to, and no fixed maximum instance count — three things the equivalent uniform-block design would all have needed.

The bounds must cover every instance. A forest drawn as one object with ten thousand transforms is culled as one object, so its Bounds has to enclose the whole forest — which also means it is all-or-nothing. Batching by locality rather than by mesh is what keeps that from being a regression, and it is the caller's decision because only the caller knows the scene's shape.

The instanced variant is a permutation rather than a branch, because the two read a vertex differently: the instanced one takes its world matrix from the buffer and the ordinary one from the push constant. A runtime branch would make every non-instanced draw carry the binding as well.

Fields and properties (12)

• public override string Name

  The sub-feature's name, for logging and profiling.

• public RenderDataKey<InstanceBatch> Batches

  Where each object's instance transforms start, and how many there are.

• public IGraphicsDevice? Device

  The device the buffers live on. Set before the first frame that prepares.

• public BufferHandle Buffer

  The buffer every batch lives in, for a host binding it once a frame.

• public BufferHandle ParameterBuffer

  The parallel buffer of InstanceParameters, bound the same way.

• public long ParameterBufferOffset

  The byte offset this frame's parameters start at.

• public int ParameterCount

  How many per-instance parameter records this frame holds.

• public ReadOnlySpan<Matrix4x4> Transforms

  This frame's instance transforms, in the order they were added.

• public ReadOnlySpan<InstanceParameters> Parameters

  This frame's per-instance parameters, at the same indices as Transforms.

• public long BufferOffset

  The byte offset this frame's transforms start at. Bind the buffer here, not at zero.

• public int TransformCount

  How many instance transforms this frame holds.

• public IReadOnlyList<PermutationKey<bool>> PermutationKeys

  The permutation keys this sub-feature decides.

Methods (10)

• public InstancingRenderFeature()

  Creates the feature, interning its permutation keys.

• public bool ValueOf(RenderSystem system, RenderObjectId id, int index)
• protected internal override void Initialize(RenderSystem system)

  Registers this sub-feature's per-object data. Called once.

• public void Begin()

  Starts a frame's batches. Call before the first SetInstances.

• public void SetInstances(RenderSystem system, RenderObjectId id, ReadOnlySpan<Matrix4x4> instances)

  Gives an object its instance transforms for this frame.

• public void SetInstances(RenderSystem system, RenderObjectId id, ReadOnlySpan<Matrix4x4> instances, ReadOnlySpan<InstanceParameters> instanceParameters)

  Gives an object its instance transforms and their per-instance parameters.

• protected internal override void Prepare(RenderSystem system)

  Fills this sub-feature's data for the visible objects.

• public int InstanceCountOf(RenderSystem system, RenderObjectId id)

  How many instances of an object to draw, or zero to leave the draw alone.

• public int FirstInstanceOf(RenderSystem system, RenderObjectId id)

  The first instance index, which is where this object's transforms start.

• public void Dispose()

  Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

Used by (2)

• HarnessVixen.Rendering.Tests
• SkinningAndInstancingTestsVixen.Rendering.Tests