Blitz3D+ Command Reference

BrushEnvironmentMap brush[,texture][,frame][,strength#]

Parameters

brush - brush handle

texture (optional) - 2:1 equirectangular environment image, or 0 to remove the map (default)

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

strength# (optional) - lighting and reflection intensity, 0 or higher; 1.0 (default)

Description

Lights a Standard material with an image of its surroundings.

This is image-based lighting: the environment image supplies soft ambient light and reflections at the same time. Rough surfaces pick up a believable overall tone from it, while smooth metals mirror it - it is what makes PBR materials, especially metals, come alive instead of looking black away from direct light.

Use an ordinary 2:1 equirectangular panorama, loaded with mipmaps (rougher surfaces sample blurrier mips). The image decoder is 8-bit, so HDR image files are not supported. Strength scales both the ambient light and the reflections.

This command only lights the material. To show the same panorama behind the scene, create a skybox from the same texture - the two are deliberately independent, so you can dim the visible sky without dulling reflections. Pass 0 as the texture to remove the map. Calling this command attaches the Standard material automatically.

For the full story, see environments and skyboxes in the shader guide.

Requires Extended mode.

See also: CreateSkyBox, SkyBoxIntensity, BrushPBR, LoadTexture.

Example

; BrushEnvironmentMap 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 a tiny 2:1 equirectangular environment: sky, horizon and sun
environment=CreateTexture(64,32,1+8+32)
SetBuffer TextureBuffer(environment)
ClsColor 30,80,180
Cls
Color 255,160,60
Rect 0,16,64,16,True
Color 255,240,180
Oval 44,4,8,8,True
SetBuffer BackBuffer()

; A smooth metal sphere reflects the environment strongly
brush=CreateStandardBrush(220,220,220)
BrushPBR brush,1,0.15
sphere=CreateSphere(32)

strength#=1.0

While Not KeyDown(1)

    ; Press [ / ] to change the environment lighting strength
    If KeyDown(26) And strength>0 Then strength=strength-0.02
    If KeyDown(27) And strength<3 Then strength=strength+0.02

    ; Light the sphere from the image and repaint it
    BrushEnvironmentMap brush,environment,0,strength
    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,"[ / ] : strength   Arrow keys: move camera   Esc: exit"
    Text 0,20,"BrushEnvironmentMap brush,environment,0,"+strength

    Flip

Wend

FreeBrush brush
End

Index