Blitz3D+ Command Reference

FreeShader shader

Parameters

shader - shader handle to release; 0 is allowed and does nothing

Description

Releases a shader handle when your program no longer needs it.

Entities, brushes and cameras retain the instance attached to them, so freeing your handle does not break anything already using the shader - loading an effect, attaching it and freeing the handle straight away is a perfectly tidy pattern:

shader=LoadShader("builtin:toon")
EntityShader cube,shader
FreeShader shader

Keep the handle if you still want to change parameters, toggle the effect with CameraEffectEnabled, or detach it later - once freed, the handle must not be used again. Treat shader handles like textures and brushes: free the ones you keep when they are no longer needed.

For the full story, see copying and lifetime in the shader guide.

Requires Extended mode.

See also: LoadShader, CopyShader, EntityShader, CameraEffect.

Example

; FreeShader Example
; ------------------
; Requires Extended mode.

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

camera=CreateCamera()
PositionEntity camera,0,0,-5

light=CreateLight()
RotateEntity light,30,-30,0

cube=CreateCube()

; Load a shader and apply it to the cube
shader=LoadShader("assets/help_surface.b3shader")
EntityShader cube,shader

; Release the script's handle - the cube retains its own instance,
; so it keeps rendering with the shader. Never reuse the handle.
FreeShader shader

While Not KeyDown(1)

    TurnEntity cube,0.3,0.4,0

    ; 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

    RenderWorld

    Color 255,255,255
    Text 0,0,"Arrow keys: move camera   Esc: exit"
    Text 0,20,"FreeShader shader was called - the cube still renders with it"

    Flip

Wend

End

Index