Blitz3D+ Command Reference

RenderInstancedDraws ( )

Parameters

None.

Description

Returns how many executed draw calls carried more than one instance, in the last completed frame.

GPU particle contributions are resolved asynchronously. Returns -1 while the relevant GPU counts are pending; display this as pending and query again after later frames. Reading this statistic never forces a GPU counter wait. CPU-only frames retain their existing immediate behaviour.

For ordinary meshes this indicates whether the renderer merged two or more surface instances into a draw. GPU particle draws also count when they contain more than one live particle; they use their own indirect instancing path rather than ordinary surface grouping.

The usual culprit is unique mesh data. Grouping matches on the mesh itself, so entities built with one template plus CopyEntity copies group, while entities that each ran their own LoadMesh, CreateCube or CopyMesh do not - identical vertex data is not enough, they have to be the same mesh. Alpha-blended surfaces are never grouped because their draw order matters, and raw custom shaders keep their own single draws because their vertex transform is entirely user-defined; surface shaders are the custom-shader route that still instances.

One ordinary grouped mesh draw holds at most 4,096 instances, so a very large group is split across several draws: 4,097 copies of one mesh execute as two draws, and only the full one counts as instanced. GPU particle draws have their own capacity and are not subject to this ordinary grouping limit.

This describes the most recently completed frame's main colour pass, so read it after Flip. Setting B3D_DISABLE_INSTANCING to 1 before starting disables ordinary mesh grouping; it does not disable GPU particle instancing.

Requires Extended mode.

See also: RenderInstanceGroups, RenderInstances, RenderDrawCalls, RenderSubmittedDraws, CopyEntity.

Example

; RenderInstancedDraws Example
; ----------------------------
; Requires Extended mode.

Graphics3D 640,480,0,2
SetBuffer BackBuffer()

camera=CreateCamera()
PositionEntity camera,0,6,-20
CameraClsColor camera,20,30,50

light=CreateLight()
RotateEntity light,45,45,0

ground=CreatePlane()
EntityColor ground,60,80,55

; Two mesh families: copies within each family share a mesh, so each
; family collapses into one draw call carrying many hardware instances
crate=CreateCube()
ScaleMesh crate,0.5,0.5,0.5
EntityColor crate,180,90,60

orb=CreateSphere(8)
ScaleMesh orb,0.6,0.6,0.6
EntityColor orb,80,200,255

Dim crates(59)
Dim orbs(59)
For n=0 To 59
    crates(n)=CopyEntity(crate)
    PositionEntity crates(n),(n Mod 10)*3-13,0.5,(n/10)*3+4
    orbs(n)=CopyEntity(orb)
    PositionEntity orbs(n),(n Mod 10)*3-12,2.5,(n/10)*3+4
Next
HideEntity crate
HideEntity orb

orbs_on=True

While Not KeyDown(1)

    ; Space hides or shows the orb family - one instanced draw appears/vanishes
    If KeyHit(57)
        orbs_on=Not orbs_on
        For n=0 To 59
            If orbs_on
                ShowEntity orbs(n)
            Else
                HideEntity orbs(n)
            EndIf
        Next
    EndIf

    ; Arrow keys move the camera
    If KeyDown(200) Then MoveEntity camera,0,0,0.1
    If KeyDown(208) Then MoveEntity camera,0,0,-0.1
    If KeyDown(203) Then TurnEntity camera,0,1,0
    If KeyDown(205) Then TurnEntity camera,0,-1,0

    RenderWorld

    ; Draw calls that carried more than one hardware instance
    Text 0,0,"Arrow keys: move camera   Space: toggle orbs   Esc: exit"
    Text 0,20,"RenderInstancedDraws() = "+RenderInstancedDraws()
    Text 0,40,"60 crates = 1 instanced draw, 60 orbs = 1 more"

    Flip

Wend

End

Index