Blitz3D+ Command Reference

LoadShader ( file$ )

Parameters

file$ - path to a .b3shader asset, or a builtin: name such as "builtin:toon"

Description

Loads a shader from a file or the built-in library and returns a new shader instance.

This is the entry point to the whole shader system. A .b3shader descriptor tells Blitz3D whether the asset is a material or a post-processing shader, where its compiled code lives, and which named parameters it exposes. Once loaded, apply the instance to a model with EntityShader, store it in a brush with BrushShader, or attach it to a camera with CameraEffect.

The compiled GPU program is cached, but every call returns a fresh instance with independent parameter values - load the same water shader twice for a calm pool and a stormy sea. Source-backed assets are compiled by the IDE when required; a standalone game ships only packaged bytecode.

Names beginning with builtin: (matched case-insensitively) load from the packaged library of 28 effects - from materials such as builtin:unlit, builtin:toon, builtin:foliage and builtin:water to camera effects such as builtin:bloom, builtin:vignette, builtin:ssao and builtin:motion-blur. They need no shader files beside your program, even as a standalone executable.

A failed load raises a descriptive runtime error rather than returning 0, and ShaderError reads any diagnostic retained by a valid instance.

For every alias, its parameters and its cost, see the built-in shader catalogue.

Requires Extended mode.

See also: CopyShader, FreeShader, ShaderError, EntityShader, BrushShader, CameraEffect.

Example

; LoadShader Example
; ------------------
; Requires Extended mode.

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

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

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

cube=CreateCube()

; Load one of the packaged built-in shaders by its alias
shader=LoadShader("builtin:toon")
If shader=0 Then RuntimeError "Could not load shader"
EntityShader cube,shader

bands=4

While Not KeyDown(1)

    ; Press [ / ] to change the toon shader's band count
    If KeyHit(26) And bands>1 Then bands=bands-1
    If KeyHit(27) And bands<8 Then bands=bands+1
    ShaderFloat shader,"Bands",bands

    TurnEntity cube,0.25,0.5,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,"[ / ] : toon bands   Arrow keys: move camera   Esc: exit"
    Text 0,20,"shader=LoadShader("+Chr$(34)+"builtin:toon"+Chr$(34)+")   Bands "+bands

    Flip

Wend

FreeShader shader
End

Index