Blitz3D+ Command Reference

ParticleError$ ( )

Parameters

None.

Description

Returns the last GPU particle failure reason, or an empty string when clear.

The string describes the last GPU particle creation or configuration failure. Reading it, ParticleBackend, GPUParticlesSupported and the count queries does not clear the error. A GPU creation or configuration attempt clears it before work and records a useful reason if the operation fails.

CreateGPUParticleEmitter returns 0 on unavailable capability, invalid capacity or allocation failure; read this string immediately to explain that recoverable result. Existing void setters cannot return a failure handle: unsupported GPU use raises a runtime error and records the same explanation. Invalid entity handles follow the normal runtime-error convention.

The example deliberately requests capacity 0, saves the reason, then creates a valid emitter and shows that successful creation clears the stored error. Save the string yourself if it must survive later configuration calls.

Requires Extended mode.

See also: CreateGPUParticleEmitter, GPUParticlesSupported, CountParticlesAsync.

Example

; ParticleError Example
; ---------------------
; Requires Extended mode.

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

; Creation failure is recoverable: capacity 0 returns 0 and records why
invalid=CreateGPUParticleEmitter(0)
failure$=ParticleError$()

; A successful GPU creation clears the stored error again
emitter=CreateGPUParticleEmitter(10000)
If emitter=0 Then RuntimeError ParticleError$()
recovery$=ParticleError$()

; 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

    Color 255,255,255
    Text 0,0,"Arrow keys: move camera   P: pause   Space: burst   R: clear   Esc: exit"
    Text 0,20,"Invalid capacity returned "+invalid+"; saved ParticleError: "+failure$
    Text 0,40,"ParticleError after the valid creation: ["+recovery$+"]"

    Flip

Wend

FreeTimer timer
FreeEntity emitter

End

Index