RenderDrawCalls ( )

Parameters

None.

Description

Returns how many draw calls were actually executed in the last completed frame.

This is the number that costs you time. Each draw call is a command the CPU hands to the GPU, and on a busy scene the CPU can easily spend more time issuing them than the GPU spends drawing. It is the first thing to check when the frame rate drops but the picture is not obviously complicated.

Read it together with RenderSubmittedDraws. Submitted is what your scene asked for; executed is what survived automatic instancing. In the maintained instancing benchmark, 1,000 three-surface trees made from CopyEntity copies submit 3,000 draws and execute 3. If your two numbers are identical, nothing is being grouped.

The usual reason nothing groups is that every entity owns unique mesh data. Grouping matches on the mesh itself, so 500 separate CreateCube or LoadMesh calls give 500 unrelated meshes and 500 draws, while one mesh plus 499 CopyEntity copies gives one. Alpha-blended surfaces are also never grouped, because their back-to-front order has to be preserved, and raw custom shaders keep their own single draws.

Gotcha: this describes the most recently completed frame's main colour pass, so read it after Flip; shadow passes are batched separately and 2D drawing is not counted. To measure what instancing is worth on your own scene, set the B3D_DISABLE_INSTANCING environment variable to 1 before starting the program and compare the two runs.

Requires Extended mode.

See also: RenderSubmittedDraws, RenderInstancedDraws, RenderInstances, RenderTriangles, DrawRenderStats.

Example

; RenderDrawCalls 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

; A spinning pickup that is always on screen
pickup=CreateCylinder()
ScaleEntity pickup,1,0.2,1
PositionEntity pickup,0,2,0
EntityColor pickup,255,220,60

; 150 UNIQUE meshes - separate CreateCube calls cannot be auto-instanced,
; so each visible crate costs one extra draw call
Dim crates(149)
For n=0 To 149
    crates(n)=CreateCube()
    ScaleEntity crates(n),0.5,0.5,0.5
    PositionEntity crates(n),(n Mod 15)*2-14,0.5,(n/15)*2+4
    EntityColor crates(n),100+(n Mod 8)*15,60,180
Next

crates_on=True

While Not KeyDown(1)

    ; Space hides or shows all 150 crates - watch the counter jump
    If KeyHit(57)
        crates_on=Not crates_on
        For n=0 To 149
            If crates_on
                ShowEntity crates(n)
            Else
                HideEntity crates(n)
            EndIf
        Next
    EndIf

    TurnEntity pickup,0,2,0

    ; 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

    ; Main-pass draw calls executed in the last completed frame
    Text 0,0,"Arrow keys: move camera   Space: toggle 150 crates   Esc: exit"
    Text 0,20,"RenderDrawCalls() = "+RenderDrawCalls()

    Flip

Wend

End

Index

Blitz3D+ Command Reference

RenderDrawCalls ( )

Parameters

Description

Example