Blitz3D+ Command Reference

ParticleMax emitter,maximum

Parameters

emitter - CPU or GPU particle emitter entity

maximum - most particles that may be alive at once; CPU: clamped to 1-16383; GPU: valid range 1-1048576

Description

Changes how many particles an emitter may keep alive at once.

GPU emitters accept 1-1048576; invalid values or allocation failures raise a runtime error and set ParticleError$ without replacing the working allocation. Growing preserves survivors; shrinking keeps the first survivors in GPU storage order. Retained views remain valid. GPU capacity is independent of the CPU expanded-mesh vertex ceiling described below; resizing can allocate substantial memory and should not be done each frame.

The maximum is a hard budget. While that many particles are alive, both continuous emission and EmitParticles bursts are silently ignored until something dies, so a too-small maximum shows up as an effect that looks thin rather than as an error.

A useful starting figure is your emission rate multiplied by your longest lifetime, plus room for the biggest burst you fire. A waterfall at 300 particles per second with a two second lifetime needs about 600; a one-shot explosion of 200 sparks needs 200.

This is a good runtime quality knob. If you offer a "particle detail" option in your game, calling ParticleMax on your emitters is the cheapest way to make it mean something, because its storage is resized to match the new limit.

Gotcha: shrinking the maximum immediately drops the surplus live particles rather than letting them fade out, and rebuilding the buffer is not free - set it while loading or when the player changes an option, not every frame.

On CPU emitters the value is clamped to 1-16383. In mesh render mode the effective ceiling is lower still, because the emitter buffer holds 65535 vertices in total and one particle costs a whole copy of the mesh - a 100 vertex mesh therefore caps out at 655 particles.

Requires Extended mode.

See also: CreateParticleEmitter, CountParticles, ParticleEmissionRate, ParticleMesh.

Example

; ParticleMax 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 dense bonfire that constantly wants more particles than allowed
emitter=CreateParticleEmitter(400)
PositionEntity emitter,0,0.5,0
ParticleEmissionRate emitter,400
ParticleLifetime emitter,1.5,2.5
ParticleVelocity emitter,0,2.5,0,0.6,0.4,0.6
ParticleColor emitter,255,220,120,1,255,80,0,0
ParticleSize emitter,0.12,0.03,0.2
EntityBlend emitter,3

maximum=400

While Not KeyDown(1)

    ; [ / ] resize the emitter's live-particle cap
    changed=False
    If KeyHit(26) And maximum>100
        maximum=maximum-100
        changed=True
    EndIf
    If KeyHit(27) And maximum<2000
        maximum=maximum+100
        changed=True
    EndIf
    If changed Then ParticleMax emitter,maximum

    ; 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   [ / ] : maximum particles   Esc: exit"
    Text 0,20,"ParticleMax emitter,"+maximum
    Text 0,40,"Live particles: "+CountParticles(emitter)+" (count saturates at the maximum)"

    Flip

Wend

End

Index