Blitz3D+ Command Reference

RenderCulledEntities ( )

Parameters

None.

Description

Returns how many mesh entities were skipped by culling in the last RenderWorld.

An entity is counted when it is thrown away before drawing, either because it fell outside the camera frustum or because it was further away than its EntityCullRange. Those are the two cheapest wins in a 3D scene, and this counter tells you whether you are actually getting them.

The number is worth reading next to the total number of mesh entities in your world. If you have 2,000 props and this reports 40, almost everything is being drawn every frame and it is time to look at cull ranges, a tighter CameraRange, or splitting a huge single mesh into separate entities the frustum can reject individually.

Gotcha: this counter is reset at the start of every RenderWorld and filled in during it, so read it after RenderWorld and before the next one - unlike the draw-call counters, which describe the last completed frame. Only the main camera views count; mirror views and shadow passes are deliberately excluded so the number stays comparable.

Requires Extended mode.

See also: EntityCullRange, RenderLODSelections, RenderSubmittedDraws, DrawRenderStats, RenderWorld.

Example

; RenderCulledEntities Example
; ----------------------------
; Requires Extended mode.

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

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

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

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

; A ring of 80 pillars surrounds the camera, so some are always off screen
pillar=CreateCylinder(12)
ScaleMesh pillar,0.6,2,0.6
PositionMesh pillar,0,2,0
EntityColor pillar,80,200,255

For n=0 To 79
    copy=CopyEntity(pillar)
    PositionEntity copy,Cos(n*4.5)*(12+(n Mod 4)*8),0,Sin(n*4.5)*(12+(n Mod 4)*8)
    ; Distance culling: pillars stop rendering 40 units from the camera
    EntityCullRange copy,40
Next
HideEntity pillar

While Not KeyDown(1)

    ; Arrow keys move the camera - turn around to see frustum culling change
    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

    ; Counts pillars rejected by EntityCullRange or by frustum culling
    Text 0,0,"Arrow keys: move camera   Esc: exit"
    Text 0,20,"RenderCulledEntities() = "+RenderCulledEntities()+" of 80 pillars"
    Text 0,40,"Pillars beyond 40 units, or outside the view, are culled"

    Flip

Wend

End

Index