Blitz3D+ Command Reference

SetAsyncLoadBudget milliseconds#

Parameters

milliseconds# - main-thread finalization time per frame, in milliseconds; must be finite and non-negative. The starting value is 2.

Description

Sets how much main-thread time per frame background world loads may spend finalizing.

Asynchronous world loading does its heavy reading and decoding on a background worker, but the final step - creating textures, meshes, terrains, and entities - must happen on the main thread. That work is sliced up and serviced automatically whenever your program reaches Flip, FlipCanvas, Delay, or WaitTimer, under this time budget. All those calls in one frame share a single deadline, so nested idle calls never multiply the cost.

The default 2 milliseconds keeps a 60 FPS game smooth. Raise the budget to finish loads faster at the price of bigger frame hitches (a dedicated loading screen can afford a lot more); lower it when every microsecond of the frame matters. A budget of 0 means the automatic pumps only drain notifications and do no finalization work - loads will then sit in WORLD_LOAD_FINALIZING until you grant time yourself with UpdateAsyncLoads.

The budget is best effort, not a hard real-time guarantee: one indivisible resource creation or driver call can occasionally overshoot it. Negative or non-finite values are a runtime error.

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

Requires Extended mode.

See also: AsyncLoadBudget, UpdateAsyncLoads, LoadWorldAsync.

Example

; SetAsyncLoadBudget 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

While Not KeyDown(1)

    ; Load (or reload) the castle world in the background
    SetWorld 0
    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)

        ; SetAsyncLoadBudget changes how many main-thread milliseconds the
        ; automatic async pumps (Flip, Delay...) may spend finalizing.
        ; A small budget keeps frames smooth; a large one loads faster
        If KeyDown(13) Then SetAsyncLoadBudget AsyncLoadBudget()+0.1
        If KeyDown(12) And AsyncLoadBudget()>0.1 Then SetAsyncLoadBudget AsyncLoadBudget()-0.1

        TurnEntity spinner,0.5,1,0.25
        RenderWorld
        Text 0,0,"Loading...   + / - : change budget   Esc: exit"
        Text 0,20,"SetAsyncLoadBudget "+AsyncLoadBudget()+" (default is 2 ms)"
        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")

    ; Explore the castle until R reloads it or Esc exits
    While Not KeyDown(1)
        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

        If KeyDown(13) Then SetAsyncLoadBudget AsyncLoadBudget()+0.1
        If KeyDown(12) And AsyncLoadBudget()>0.1 Then SetAsyncLoadBudget AsyncLoadBudget()-0.1

        RenderWorld
        Text 0,0,"Arrow keys: move camera   + / - : change budget   R: reload   Esc: exit"
        Text 0,20,"The configured budget is "+AsyncLoadBudget()+" ms (used while worlds load)"
        Flip

        If KeyHit(19) Then Exit
    Wend

    SetWorld 0
    FreeWorld castle_world

Wend

End

Index