Blitz3D+ Command Reference

CreateGPUParticleEmitter ( [maximum][,parent] )

Parameters

maximum (optional) - particle capacity, from 1 to 1048576; 65536 (default)

parent (optional) - parent entity of the emitter

Description

Creates an emitter whose particles are simulated and drawn on the GPU.

Returns an entity handle, or 0 with a reason in ParticleError if capability or allocation fails. It never substitutes a CPU emitter. GPU particles need the DX12 renderer; call GPUParticlesSupported after Graphics3D.

Use the existing Particle commands for presets, motion, appearance, bursts, pause and capacity. The backend is fixed for the entity lifetime. CopyEntity copies settings and material but starts empty with zero counters and the default random seed. FreeEntity releases the emitter; queued draws retain the state they need.

The capacity is an allocation safety limit, not a guaranteed practical particle count. Many views, sorting, mesh complexity and overlapping transparent particles add cost. No expanded CPU vertex buffer limits the GPU particle population.

Modes 1 (billboard), 2 (stretched) and 3 (copied mesh), plus per-emitter sorting, are available. The default material and builtin:soft-particle are supported with full-bright or emissive FX. Physics collision, standard lighting, shadows, highlight and other custom shaders are unsupported. Soft particles also reject colour overlay and dither coverage. Unsupported setters raise a runtime error and set ParticleError before changing state.

With full-bright (1) or emissive (32768), supported FX include vertex colours (2), flat shading (4), no fog (8), double-sided (16), vertex alpha (32) and explicit alpha testing (8192). Vertex alpha preserves positive fractional coverage for blending; without it, alpha testing clips at the material cutoff. Masked texture holes keep their separate test. Conditional lighting (16384) does not add lighting to these unlit materials.

Particle parameters and entity/brush colour, alpha and shininess must be finite. Invalid appearance setters or painted brushes leave the prior material intact. EntityShader overrides BrushShader; removing an override is rejected if it would activate an unsupported brush shader.

UpdateWorld controls automatic simulation, independently of rendering. CountParticles and ParticleTotalEmitted are exact and may wait for GPU work; use CountParticlesAsync for a display count.

For the full story, see the Particles guide.

Requires Extended mode.

See also: CreateParticleEmitter, GPUParticlesSupported, ParticleError, ParticleBackend, CountParticlesAsync.

Example

; CreateGPUParticleEmitter - Extended mode, DX12.

Graphics3D 800,600,0,2
SetBuffer BackBuffer()
If GPUParticlesSupported()=0 Then RuntimeError "GPU particles are unavailable."
VSync 0
FrameLimit 60
camera=CreateCamera()
PositionEntity camera,0,1,-5
CameraClsColor camera,10,15,30
emitter=CreateGPUParticleEmitter(10000)
If emitter=0 Then RuntimeError ParticleError$()
ParticlePreset emitter,1
timer=CreateTimer(60)
paused=False
While Not KeyHit(1)
    If KeyHit(25)
        paused=Not paused
        PauseParticles emitter,paused
    EndIf
    If KeyHit(57) Then EmitParticles emitter,100
    If KeyHit(19) Then ClearParticles emitter

    ticks=WaitTimer(timer)
    If ticks>15 Then ticks=15
    For tick=1 To ticks
        UpdateWorld
    Next
    RenderWorld
    live=CountParticlesAsync(emitter)
    live_text$="pending"
    If live>=0 Then live_text$=Str$(live)
    Color 255,255,255
    Text 16,16,"CreateGPUParticleEmitter | P Pause | Space Burst | R Clear | Esc Exit"
    Text 16,38,"Latest GPU count: "+live_text$+"   Paused: "+paused
    Text 16,60,"Capacity 10000, backend: "+ParticleBackend(emitter)
    Flip
Wend
FreeTimer timer
FreeEntity emitter

End

Index