Blitz3D+ Command Reference

BrushVolume brush,thickness#,attenuation_distance#[,red#][,green#][,blue#]

Parameters

brush - brush handle

thickness# - authored optical travel distance in world units; 0 or higher. Zero disables bending and absorption.

attenuation_distance# - travel distance at which the transmitted colour is multiplied by the attenuation colour, in world units; 0 disables absorption

red#, green#, blue# (optional) - attenuation colour from 0 to 255; 255,255,255 (default)

Description

Gives a transmitting Standard material coloured thickness, like tinted glass.

Coloured glass absorbs light: a longer path through it produces a stronger tint. This command approximates that behaviour using an authored travel distance. It is useful for tinted windows, gemstones, murky ice and perspex. It does not measure the actual distance through a bottle or automatically detect thin mesh edges. Imported thickness textures can vary that authored distance across a surface.

Thickness controls how far the refracted ray is projected and how much absorption it receives. At one attenuation distance, the background is multiplied by the chosen colour; at twice that distance the multiplier is applied twice. Shorter attenuation distances therefore give stronger absorption. The default white absorbs nothing. Attenuation distance 0 disables absorption while preserving bending; thickness 0 disables both. Refraction still needs an IOR above 1.

The layer only shows on brushes with BrushTransmission above 0. Imported glTF models with the KHR_materials_volume extension arrive with this set. Calling this command attaches the Standard material to the brush automatically.

Requires Extended mode.

See also: BrushTransmission, BrushPBR, BrushStandard.

Example

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

; A bright backdrop shows the tinted absorption clearly
back=CreateCube()
PositionEntity back,0,0,3
ScaleEntity back,2,2,0.2
EntityColor back,255,80,30

; Volume needs a transmitting Standard material
brush=CreateStandardBrush(255,255,255)
BrushTransmission brush,0.9,1.45
sphere=CreateSphere(32)

thickness#=0.8
attenuation#=2.0

While Not KeyDown(1)

    ; Press [ / ] to change the wall thickness
    If KeyDown(26) And thickness>0 Then thickness=thickness-0.01
    If KeyDown(27) And thickness<2 Then thickness=thickness+0.01

    ; Press Z / X to change the attenuation distance
    If KeyDown(44) And attenuation>0.2 Then attenuation=attenuation-0.02
    If KeyDown(45) And attenuation<5 Then attenuation=attenuation+0.02

    ; Absorb light towards blue over distance and repaint
    BrushVolume brush,thickness,attenuation,120,210,255
    PaintEntity sphere,brush

    ; 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,"[ / ] : thickness   Z / X : attenuation   Arrow keys: move camera   Esc: exit"
    Text 0,20,"BrushVolume brush,"+thickness+","+attenuation+",120,210,255"

    Flip

Wend

FreeBrush brush
End

Index