Blitz3D+ Command Reference

ParticleSort emitter[,enabled]

Parameters

emitter - CPU or GPU particle emitter entity

enabled (optional) - True to sort particles back to front, False to leave them unsorted; True (default)

Description

Draws an emitter's particles back to front so alpha blending layers correctly.

GPU sorting uses per-view indices into frozen particle state, ordered by descending distance with stable birth identity for ties. It does not reorder simulation or download particle positions. Sorting adds GPU time and memory per retained view. Sorting is per emitter; intersecting emitters are not globally sorted.

Alpha-blended particles have to be drawn far to near or the ones behind punch holes in the ones in front. Without sorting, a thick alpha smoke column shows hard edges where puffs overlap, and those edges flicker as the camera moves because the drawing order keeps changing. Turning sorting on fixes that.

You do not need it for additive effects. Adding colours gives the same result whatever order you do it in, so fire, sparks and magic - anything using EntityBlend 3 - look correct unsorted and should stay unsorted. Sorting is for alpha-blended smoke, steam, dust, fog cards and anything with a soft texture that overlaps itself.

It is off by default because it is not free. The emitter measures every live particle's distance from the camera and sorts the list each time it is drawn, so the cost grows with the live particle count and is paid again for every pass the emitter appears in - a second camera, a mirror or a shadow pass each repeat it. If you need sorting on a busy emitter, it is usually cheaper to lower ParticleMax than to switch it off.

Gotcha: sorting only orders particles within one emitter. Two overlapping emitters still draw in entity order, so use EntityOrder if one cloud must sit behind another. Loading a ParticlePreset turns sorting back off.

Requires Extended mode.

See also: ParticleColor, ParticleMax, EntityBlend, EntityOrder, ParticlePreset.

Example

; ParticleSort Example
; --------------------
; Requires Extended mode.

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

camera=CreateCamera()
PositionEntity camera,0,2,-6
CameraClsColor camera,8,12,24

floor=CreatePlane()
EntityColor floor,30,34,44

; Thick alpha-blended smoke - overlapping puffs reveal draw-order errors
emitter=CreateParticleEmitter(600)
PositionEntity emitter,0,1,0
ParticleEmitterShape emitter,2,1.2,1.2,1.2
ParticleEmissionRate emitter,80
ParticleLifetime emitter,2.5,3.5
ParticleVelocity emitter,0,0.6,0,0.3,0.2,0.3
ParticleColor emitter,200,200,210,0.9,120,120,130,0
ParticleSize emitter,0.3,0.6,0.2
EntityBlend emitter,2

; Start with back-to-front sorting on
ParticleSort emitter,True
sorted=True

While Not KeyDown(1)

    ; Space toggles back-to-front sorting for the transparent puffs
    If KeyHit(57)
        sorted=Not sorted
        ParticleSort emitter,sorted
    EndIf

    ; Arrow keys move the camera - orbit through the smoke to compare
    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

    ; UpdateWorld also advances the particle simulation
    UpdateWorld
    RenderWorld

    Text 0,0,"Arrow keys: move camera   Space: toggle sorting   Esc: exit"
    If sorted Then state$="True (puffs layer correctly)" Else state$="False (watch for popping overlaps)"
    Text 0,20,"ParticleSort emitter,"+state$

    Flip

Wend

End

Index