Blitz3D+ Command Reference

ShaderTexture shader,parameter$,texture[,frame]

Parameters

shader - shader handle

parameter$ - name of a texture parameter declared by the shader asset

texture - texture handle

frame (optional) - frame of an animated texture; 0 (default)

Description

Binds a texture to a named parameter of a shader.

Any ordinary Blitz texture can feed a shader: the base texture of builtin:toon, the NoiseMap of builtin:dissolve, the LUT of builtin:lut-grade, normal maps for builtin:water. Load it with LoadTexture as usual and bind it by name.

The shader retains the underlying texture resource while it is bound, so the binding stays valid across copies and attachments. The binding is per-instance, like every other parameter.

Texture settings remain live after binding: you do not need to call ShaderTexture again after PositionTexture, ScaleTexture, RotateTexture or TextureCoords. The shader must use the shared UV helper (or equivalent code) to apply those settings. Its texture mapping still determines their meaning; a world-projected or screen-space map does not automatically follow mesh UV offsets. Standard's higher named maps now have independent transforms too. Custom layout-4 assets can declare texture-metadata 1 to use the shared helper for material slots 8-23.

Standard, foliage, wet-surface and parallax also keep normal-map lighting aligned with the map's rotation and chosen UV set. Parallax's base, normal and height textures can each have their own transform. Apply matching transforms when the maps were painted to line up together. Terrain retains its layer scales and applies the texture object's transform afterwards.

The asset must declare the name as a texture; a missing name or wrong-type setter raises a runtime error, and an out-of-range animation frame does too. Names are matched without regard to case.

For the full story, see named parameters in the shader guide.

Requires Extended mode.

See also: ShaderFloat, ShaderColor, ShaderVector, LoadShader, LoadTexture.

Example

; ShaderTexture 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

; Draw two textures to swap between: a checker and stripes
checker=CreateTexture(64,64)
SetBuffer TextureBuffer(checker)
Color 255,255,255
Rect 0,0,32,32,True
Rect 32,32,32,32,True
Color 30,80,180
Rect 32,0,32,32,True
Rect 0,32,32,32,True
SetBuffer BackBuffer()

stripes=CreateTexture(64,64)
SetBuffer TextureBuffer(stripes)
ClsColor 240,120,30
Cls
Color 120,30,120
For x=0 To 63 Step 16
    Rect x,0,8,64,True
Next
SetBuffer BackBuffer()

cube=CreateCube()

; Mode 2 makes the shader sample its Pattern texture
shader=LoadShader("assets/help_surface.b3shader")
ShaderInt shader,"Mode",2
EntityShader cube,shader

use_stripes=False

While Not KeyDown(1)

    ; Press Space to swap the bound texture
    If KeyHit(57) Then use_stripes=Not use_stripes

    ; Bind a texture to the shader's Pattern stage
    If use_stripes Then ShaderTexture shader,"Pattern",stripes Else ShaderTexture shader,"Pattern",checker

    TurnEntity cube,0.2,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,"Space: swap texture   Arrow keys: move camera   Esc: exit"
    If use_stripes Then Text 0,20,"ShaderTexture shader,"+Chr$(34)+"Pattern"+Chr$(34)+",stripes" Else Text 0,20,"ShaderTexture shader,"+Chr$(34)+"Pattern"+Chr$(34)+",checker"

    Flip

Wend

FreeShader shader
End

Index