Blitz3D+ Command Reference

ParticleTotalEmitted ( emitter )

Parameters

emitter - CPU or GPU particle emitter entity

Description

Returns how many particles this emitter has spawned in total.

On GPU emitters this exact query may wait for GPU work, including after explicit bursts without rendering. The GPU total uses a wide internal counter and saturates at 2147483647 in the Blitz integer return value.

The counter only goes up. It counts particles that were actually created, so it is the honest way to find out whether a burst really happened: ask for 500 sparks from a 256 particle emitter and the total will tell you how many the budget allowed. Sample it before and after a call to EmitParticles and the difference is the burst that was really produced.

It is a useful sanity check when an effect looks wrong. If the total is climbing but you cannot see anything, the particles exist and the problem is elsewhere - the texture, the blend mode, the size, or the camera. If the total is not climbing at all, emission is the problem: the rate may be 0, the emitter may be paused, the budget may be full, or your loop may not be calling UpdateWorld.

Gotcha: unlike the collision counter, this total is not reset by ClearParticles. It lives as long as the emitter does, so keep your own starting value if you want a per-event count. A fresh emitter made with CopyEntity starts its own total at 0.

Requires Extended mode.

See also: CountParticles, EmitParticles, ParticleEmissionRate, ParticleMax.

Example

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

; A campfire that has been burning since the program started
emitter=CreateParticleEmitter(800)
PositionEntity emitter,0,0.25,0
ParticlePreset emitter,1

While Not KeyDown(1)

    ; Space adds a burst, C clears live particles (the total keeps counting)
    If KeyHit(57) Then EmitParticles emitter,200
    If KeyHit(46) Then ClearParticles emitter

    ; 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

    ; UpdateWorld also advances the particle simulation
    UpdateWorld
    RenderWorld

    Text 0,0,"Arrow keys: move camera   Space: burst   C: clear live   Esc: exit"
    ; The lifetime total only ever climbs, unlike the live count
    Text 0,20,"ParticleTotalEmitted(emitter) = "+ParticleTotalEmitted(emitter)
    Text 0,40,"CountParticles(emitter) = "+CountParticles(emitter)

    Flip

Wend

End

Index