Blitz3D+ Command Reference

EntityCullRange entity,distance#

Parameters

entity - mesh entity to limit

distance# - furthest distance at which the entity is still drawn, in world units; 0 disables the limit

Description

Stops drawing an entity once the camera is further away than the given distance.

Some things are simply not worth drawing at range: pebbles, grass tufts, fence posts, litter, the small props that make a scene feel lived in. Giving them a cull range means they stop costing anything once they are too far away to notice, which is often a bigger win than a lower-detail mesh because the entity is skipped entirely.

Distance is measured from the camera to the nearest point on the entity's transformed bounding box, the same measurement AddEntityLOD uses, so the two work naturally together: swap to cheaper meshes as things recede, then drop them completely at the far end. Entities removed this way are counted by RenderCulledEntities, which is the easy way to see how much a range is really saving.

Pass 0 to remove the limit and draw the entity at any distance. That is the default for every mesh.

Gotcha: this is a rendering setting only. The entity is still in the world - UpdateWorld still animates it, collision still stops the player walking into it, and picking still finds it - so it will pop back into view when you get close. Because objects appear and disappear at a hard boundary, pick a distance where the pop is genuinely hard to see, or fade the entity out with EntityAutoFade over the last stretch. The setting is per entity and CopyEntity copies it.

Requires Extended mode.

See also: AddEntityLOD, ClearEntityLODs, RenderCulledEntities, EntityAutoFade, CameraRange.

Example

; EntityCullRange 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 glowing marker crystal, copied into a long avenue ahead of the camera
crystal=CreateSphere(8)
ScaleMesh crystal,0.8,1.6,0.8
PositionMesh crystal,0,1.6,0
EntityColor crystal,80,200,255

Dim crystals(59)
For n=0 To 59
    crystals(n)=CopyEntity(crystal)
    PositionEntity crystals(n),(n Mod 4)*6-9,0,(n/4)*4
Next
HideEntity crystal

cull_range#=30

While Not KeyDown(1)

    ; Press [ / ] to change the cull distance (0 disables culling)
    If KeyDown(26) And cull_range>0 Then cull_range=cull_range-0.25
    If KeyDown(27) And cull_range<100 Then cull_range=cull_range+0.25

    ; Apply the rendering cull distance to every crystal
    For n=0 To 59
        EntityCullRange crystals(n),cull_range
    Next

    ; 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

    Text 0,0,"Arrow keys: move camera   [ / ] : cull distance   Esc: exit"
    If cull_range>0
        Text 0,20,"EntityCullRange crystal,"+cull_range
    Else
        Text 0,20,"EntityCullRange crystal,0  (culling disabled)"
    EndIf
    Text 0,40,"Crystals culled this frame: "+RenderCulledEntities()+" of 60"

    Flip

Wend

End

Index