|
texture - texture created by LoadTexture or LoadAnimTexture enabled (optional) - True starts watching the texture's source file, False stops; True (default) |
|
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 as Flip or FlipCanvas finishes showing a frame (when you render to 3D canvases, once every view you rendered, in the window or a canvas, has been flipped), 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. Entities, brushes, shaders and TextureBuffer handles keep using the texture and show the new pixels, even at a new size; a file that switches between DDS and another format keeps its old pixels. 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. See also: ReloadTexture, TextureReloadError, LoadTexture, LoadAnimTexture. |
; WatchTexture Example
; --------------------
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