Blitz3D+ Command Reference

WorldAssetTexture ( asset )

Parameters

asset - a ready texture asset handle returned by FindWorldAsset

Description

Returns an ordinary texture handle from a ready texture asset.

The result behaves exactly like a LoadTexture handle: apply it with EntityTexture or a brush, scale it, whatever your game needs. The asset's options in the .world file play the role of LoadTexture's flags. Preloading textures this way through an asset-only manifest means the decode happened on the background worker instead of hitching your game.

The returned handle is yours: it stays valid after the source world is freed - so you can pull everything you need out of a preload manifest, FreeWorld it, and keep using the textures - and you must release it with FreeTexture when you are done. The asset handle itself, by contrast, dies with its world.

The asset must be a texture and must be ready, or the call is a runtime error - check WorldAssetReady first for streaming or manual assets. Several worlds requesting compatible copies of the same texture share the ready data rather than loading it twice.

For the full story, see the Async World Loading guide.

Requires Extended mode.

See also: FindWorldAsset, WorldAssetReady, WorldAssetSound, WorldAssetShader, LoadTexture, FreeTexture.

Example

; WorldAssetTexture Example
; -------------------------
; Requires Extended mode.

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

camera=CreateCamera()
PositionEntity camera,0,1,-6
light=CreateLight()
RotateEntity light,45,45,0

; Load the asset manifest world in the background
manifest=LoadWorldAsync("../../../samples/worlds/asset-preload.world")
While Not WorldReady(manifest)
    If WorldLoadState(manifest)=WORLD_LOAD_FAILED Then RuntimeError WorldLoadError(manifest)
    Cls
    Text 0,0,"Loading the asset manifest..."
    Flip
Wend

; WorldAssetTexture turns the ready texture asset into an ordinary
; texture reference
texture_asset=FindWorldAsset(manifest,"display-texture")
tex=WorldAssetTexture(texture_asset)

; The reference survives freeing the source manifest world
FreeWorld manifest

; Two spinning crates: plain on the left, asset-textured on the right
plain=CreateCube()
PositionEntity plain,-1.5,1,0
textured=CreateCube()
PositionEntity textured,1.5,1,0
EntityTexture textured,tex

While Not KeyDown(1)

    TurnEntity plain,0,1,0
    TurnEntity textured,0,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   Esc: exit"
    Text 0,20,"The right crate wears texture "+tex+" from the 'display-texture' asset"
    Text 0,40,"The reference remains valid after FreeWorld freed the manifest"

    Flip

Wend

FreeTexture tex
End

Index