Blitz3D+ Command Reference

WatchTexture texture[,enabled]

Parameters

texture - texture created by LoadTexture or LoadAnimTexture

enabled (optional) - True starts watching the texture's source file, False stops; True (default)

Description

Watches a texture's source file and reloads it automatically when the file changes.

WatchTexture is live-editing for artists and tinkerers: leave your game running, save over grass.png in your paint program, and the new pixels appear in the running game moments later. No restart, no reload key - tweak, save, look.

The engine polls watched files about twice a second at the start of Flip, and it is deliberately careful: a change must look stable across two polls (same size and timestamp) before the reload happens, so a file still being written by your editor is never picked up half-saved. Expect roughly a second between saving and seeing the change.

Reloads are validated and atomic. The new image is decoded first and must match the original frame layout; only then are the pixels swapped. If decoding fails - or the file vanishes - the last-known-good pixels stay on screen, the failure is filed as an error in diagnostics, and TextureReloadError(texture) tells you why. A successful reload files an information record and clears the error.

Only file-backed textures can be watched: anything not created by LoadTexture or LoadAnimTexture stops the program with a runtime error. The watch follows the source file, so textures sharing that file update together. For a one-off manual reload under your control, use ReloadTexture instead. Source-backed shaders get the same treatment automatically, with no opt-in.

For the full story, see the Prototyping and Diagnostics guide.

Requires Extended mode.

See also: ReloadTexture, TextureReloadError, LoadTexture, LoadAnimTexture.

Example

; WatchTexture Example
; --------------------
; Requires Extended mode.

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

SeedRnd MilliSecs()

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

light=CreateLight()
RotateEntity light,45,45,0

; Write the texture file this example will watch, then load it
PaintFile 30,70,160
crate=CreateCube()
texture=LoadTexture("watch_demo.bmp")
EntityTexture crate,texture

; WatchTexture polls the file and applies any change once the file is stable
WatchTexture texture,True

While Not KeyDown(1)

    ; Space repaints the file on disk - the running texture updates by itself
    If KeyHit(57) Then PaintFile Rand(0,255),Rand(0,255),Rand(0,255)

    TurnEntity crate,0.5,1,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

    Text 0,0,"Arrow keys: move camera   Space: repaint the file on disk   Esc: exit"
    Text 0,20,"WatchTexture reloads watch_demo.bmp moments after it changes"
    If TextureReloadError(texture)<>"" Then Text 0,40,TextureReloadError(texture)

    Flip

Wend

; Stop watching and remove the file this example created
WatchTexture texture,False
FreeTexture texture
DeleteFile "watch_demo.bmp"

End

; Draw a coloured pattern and save it as the watched file on disk
Function PaintFile(red,green,blue)
    scratch=CreateTexture(64,64)
    SetBuffer TextureBuffer(scratch)
    ClsColor red,green,blue
    Cls
    Color 255-red,255-green,255-blue
    Oval 12,12,40,40,True
    SetBuffer BackBuffer()
    Color 255,255,255
    SaveBuffer TextureBuffer(scratch),"watch_demo.bmp"
    FreeTexture scratch
End Function

Index