Blitz3D+ Command Reference

UpdateAsyncLoads [milliseconds#]

Parameters

milliseconds# (optional) - main-thread time to grant this call:
-1: use the configured AsyncLoadBudget value (default)
0: drain worker notifications only, no finalization work
positive: a one-call best-effort budget in milliseconds

Description

Gives background world loads main-thread time to finalize, right now.

Normally you never need this: Flip, FlipCanvas, Delay, and WaitTimer service loading automatically under the SetAsyncLoadBudget budget. Call UpdateAsyncLoads yourself in the two situations they cannot cover: a loop that never reaches any of those commands (a headless tool, a converter, an unusual inner loop), and a frame where you want to grant extra finalization time beyond the automatic budget - for example pushing a nearly finished load over the line while a loading screen is up.

The time is spent on WORLD_LOAD_FINALIZING work, plus streaming and manually requested assets of ready worlds. It is independent of GUI event processing and works in a windowless program. Negative values other than -1, and non-finite values, are a runtime error.

The budget is best effort: one indivisible resource creation can overshoot it, and the call returns early when there is nothing left to do.

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

Requires Extended mode.

See also: SetAsyncLoadBudget, AsyncLoadBudget, LoadWorldAsync, WorldLoadState.

Example

; UpdateAsyncLoads Example
; ------------------------
; Requires Extended mode.

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

; A simple loading screen lives in the default world
camera=CreateCamera()
PositionEntity camera,0,0,-5
light=CreateLight()
RotateEntity light,45,45,0
spinner=CreateCube()
EntityColor spinner,80,170,255

; Start loading the castle world in the background
castle_world=LoadWorldAsync("../../../samples/worlds/castle/castle.world")

While Not WorldReady(castle_world)
    If WorldLoadState(castle_world)=WORLD_LOAD_FAILED Then RuntimeError WorldLoadError(castle_world)

    ; Service async loading with up to 4 ms of main-thread finalization
    ; this frame. Flip also pumps automatically, so this call matters
    ; most in loops without Flip, FlipCanvas, Delay or WaitTimer
    ; (-1 uses the AsyncLoadBudget value, 0 only drains notifications)
    UpdateAsyncLoads 4

    TurnEntity spinner,0.5,1,0.25
    RenderWorld
    Text 0,0,"Loading the castle world..."
    Text 0,20,"UpdateAsyncLoads 4 grants extra finalization time each frame"
    Text 0,40,"Progress: "+(WorldLoadProgress(castle_world)/10.0)+"%"
    Flip
Wend

; The world is ready: select it and use its authored camera
SetWorld castle_world
castle_cam=FindWorldEntity(castle_world,"camera-main")
PointEntity castle_cam,FindWorldEntity(castle_world,"castle")

; A spinning beacon shows the loaded world animating
beacon=CreateCube()
ScaleEntity beacon,4,4,4
PositionEntity beacon,0,45,0
EntityColor beacon,255,200,80

While Not KeyDown(1)

    TurnEntity beacon,0,1,0

    ; Arrow keys move the camera (bigger steps suit the castle's scale)
    If KeyDown(200) Then MoveEntity castle_cam,0,0,1
    If KeyDown(208) Then MoveEntity castle_cam,0,0,-1
    If KeyDown(203) Then TurnEntity castle_cam,0,1,0
    If KeyDown(205) Then TurnEntity castle_cam,0,-1,0

    RenderWorld

    Text 0,0,"Arrow keys: move camera   Esc: exit"
    Text 0,20,"The castle finished loading with help from UpdateAsyncLoads"

    Flip

Wend

FreeWorld castle_world
End

Index