Blitz3D+ Command Reference

RenderWorldToCanvas canvas,world[,tween#]

Parameters

canvas - a GUI canvas attached to 3D with Graphics3DCanvas

world - the ready world to render

tween# (optional) - interpolation between the last two CaptureWorld states, as in RenderWorld; 1 (default)

Description

Renders a world into a GUI canvas.

This is the RenderWorld of the GUI canvas system: it draws a 3D frame for one canvas gadget without presenting it and without changing the selected world (GetWorld is untouched). It powers windowed tools and games - an editor with several views, a model previewer in a panel - inside a GUI event loop that pumps WaitEvent and presents with FlipCanvas, which adds the canvas's 2D overlay on top of the 3D frame.

If a camera is bound with SetCanvasCamera, only that camera is rendered, temporarily using the whole canvas as its viewport; the camera must belong to the requested world or the call is a runtime error. With no binding, every camera in the world renders in its normal order with its stored viewport.

Rendering the same canvas again before FlipCanvas simply replaces its pending frame. Rendering the same world into several canvases is cheap: the world is prepared once per frame and re-drawn per view. When showing several views at once, render them all first, then call FlipCanvas with vwait False on all but the last view so you only wait for the display once.

The world must be ready - passing a still-loading LoadWorldAsync handle is a runtime error. The tween parameter matters only if you use the CaptureWorld render-tween pattern; leave it at 1 otherwise.

Requires Extended mode.

See also: SetCanvasCamera, CanvasCamera, FlipCanvas, CanvasBuffer, RenderWorld, CaptureWorld.

Example

; RenderWorldToCanvas Example
; ---------------------------
; Requires Extended mode.

Const EVENT_WINDOW_CLOSE=$803

; Build a GUI window with a 3D canvas
window=CreateWindow("RenderWorldToCanvas",100,100,640,480,0,15)
canvas=CreateCanvas(8,8,608,400,window)
label=CreateLabel("The 3D world renders into the GUI canvas above.   Esc: exit",8,416,608,32,window)
Graphics3DCanvas canvas

; The scene lives in the default world
world=GetWorld()
camera=CreateCamera()
PositionEntity camera,0,1,-5
SetCanvasCamera canvas,camera
light=CreateLight()
RotateEntity light,45,45,0
cube=CreateCube()
PositionEntity cube,0,1,0
EntityColor cube,80,165,240

frame=0
running=True
While running

    ; Pump GUI events so the window stays responsive
    event=WaitEvent(1)
    While event<>0
        If event=EVENT_WINDOW_CLOSE And EventSource()=window Then running=False
        event=PeekEvent()
    Wend
    If KeyHit(1) Then running=False

    TurnEntity cube,0,1,0
    frame=frame+1

    ; Build the pending 3D frame for the canvas; nothing is presented
    ; yet, and the selected world is not changed
    RenderWorldToCanvas canvas,world

    ; A 2D overlay drawn on the canvas buffer joins the pending frame
    SetBuffer CanvasBuffer(canvas)
    Color 235,242,255
    Text 8,8,"RenderWorldToCanvas frame "+frame
    SetBuffer BackBuffer()

    ; FlipCanvas presents the 3D frame plus the overlay
    FlipCanvas canvas,True

Wend

EndGraphics
FreeGadget window
End

Index