Blitz3D+ Command Reference

ParticleRenderMode emitter,mode,stretch#

Parameters

emitter - CPU or GPU particle emitter entity

mode - how each particle is drawn
1: billboard - a flat quad that always faces the camera
2: stretched - a quad aligned to the direction of travel
3: mesh - a copy of the mesh supplied by ParticleMesh

stretch# - extra length per unit of speed, used by mode 2 only. Negative values are treated as 0

Description

Chooses how each particle is drawn.

GPU emitters support all three modes. Mode 3 uses an immutable GPU copy supplied by ParticleMesh, with a billboard fallback when no mesh has been assigned. All modes use the supported GPU emitter materials; see CreateGPUParticleEmitter.

Billboard is the default and the right answer most of the time: a camera-facing quad showing the emitter's texture, which is what smoke, fire, dust, magic and splashes are made of.

Stretched mode turns each particle into a streak that lines up with its own velocity, and its length grows with speed. That is the difference between round dots and convincing rain, tracer fire, spark trails or a speed-line effect. The stretch value is how many extra units of length each unit of speed adds, so small numbers such as 0.025 for rain and 0.07 for sparks are usually enough; large numbers turn slow particles into long smears.

Mesh mode draws a real 3D shape per particle instead of a quad, for debris chunks, coins, leaves, rocks or shell casings. It needs a mesh registered with ParticleMesh first - selecting mode 3 with no mesh registered simply keeps drawing billboards.

Changing the mode rebuilds a CPU emitter's expanded vertex buffer; GPU emitters select their retained source geometry and vertex path. Stretched particles take their orientation from their velocity, which means ParticleRotation has no visible effect on them, and a particle with almost no speed falls back to a plain billboard.

Requires Extended mode.

See also: ParticleMesh, ParticleVelocity, ParticleSize, ParticleRotation, ParticlePreset.

Example

; ParticleRenderMode Example
; --------------------------
; Requires Extended mode.

Graphics3D 640,480,0,2
SetBuffer BackBuffer()

camera=CreateCamera()
PositionEntity camera,0,2,-6
CameraClsColor camera,8,12,24

; Mode 3 renders lit meshes, so give the scene a light
light=CreateLight()
RotateEntity light,45,-30,0

floor=CreatePlane()
EntityColor floor,30,34,44

; Mode names for the overlay
Dim mode_name$(3)
mode_name$(1)="1 billboard"
mode_name$(2)="2 stretched billboard"
mode_name$(3)="3 mesh"

; A spark fountain to view in each render mode
emitter=CreateParticleEmitter(800)
PositionEntity emitter,0,0.5,0
ParticleEmissionRate emitter,150
ParticleLifetime emitter,1.5,2.5
ParticleVelocity emitter,0,4,0,1,0.5,1
ParticleGravity emitter,0,-5,0
ParticleColor emitter,255,220,120,1,255,80,0,0
ParticleSize emitter,0.1,0.03,0.2

; Mode 3 needs a source mesh to batch
cone=CreateCone(6)
HideEntity cone
ParticleMesh emitter,cone

mode=1
stretch#=0.08
ParticleRenderMode emitter,1,stretch

While Not KeyDown(1)

    ; Keys 1-3 pick the render mode, [ / ] tune the mode-2 stretch factor
    If KeyHit(2) Then mode=1
    If KeyHit(3) Then mode=2
    If KeyHit(4) Then mode=3
    If KeyDown(26) And stretch>0 Then stretch=stretch-0.002
    If KeyDown(27) And stretch<0.3 Then stretch=stretch+0.002

    ; Apply the current mode and stretch
    ParticleRenderMode emitter,mode,stretch

    ; 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   1/2/3: render mode   [ / ] : stretch   Esc: exit"
    Text 0,20,"ParticleRenderMode emitter,"+mode+","+stretch+" ("+mode_name$(mode)+")"

    Flip

Wend

End

Index