|
maximum (optional) - particle capacity, from 1 to 1048576; 65536 (default) parent (optional) - parent entity of the emitter |
|
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. See also: CreateParticleEmitter, GPUParticlesSupported, ParticleError, ParticleBackend, CountParticlesAsync. |
; CreateGPUParticleEmitter Example
; --------------------------------
Graphics3D 640,480,0,2
SetBuffer BackBuffer()
; GPU particles need the DX12 device - check before creating
If GPUParticlesSupported()=0 Then RuntimeError "GPU particles are unavailable."
camera=CreateCamera()
PositionEntity camera,0,1,-5
CameraClsColor camera,10,15,30
; A GPU-simulated emitter with room for 10000 particles
emitter=CreateGPUParticleEmitter(10000)
If emitter=0 Then RuntimeError ParticleError$()
; The familiar particle commands drive it; preset 1 is a fire fountain
ParticlePreset emitter,1
; A fixed timer keeps the simulation stepping at 60 updates per second
timer=CreateTimer(60)
paused=False
While Not KeyDown(1)
; P pauses the simulation, Space adds a burst, R clears all particles
If KeyHit(25)
paused=Not paused
PauseParticles emitter,paused
EndIf
If KeyHit(57) Then EmitParticles emitter,100
If KeyHit(19) 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
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 0,0,"Arrow keys: move camera P: pause Space: burst R: clear Esc: exit"
Text 0,20,"CreateGPUParticleEmitter(10000) backend: "+ParticleBackend(emitter)
Text 0,40,"Latest GPU count: "+live_text$+" paused: "+paused
Flip
Wend
FreeTimer timer
FreeEntity emitter
End