Blitz3D+ Command Reference

SetCanvasCamera canvas,camera

Parameters

canvas - a GUI canvas attached to 3D with Graphics3DCanvas

camera - a camera entity, or 0 to clear the binding

Description

Binds one camera to a 3D GUI canvas.

This is part of the GUI canvas system, for tools and games that render 3D views inside windows: a level editor with front and top views, a model previewer beside a property panel. Once a camera is bound, RenderWorldToCanvas draws only that camera into the canvas, temporarily using the full canvas as its viewport - the camera's stored CameraViewport is left untouched. With no binding, the canvas gets the world's normal all-camera rendering order instead.

The entity must actually be a camera (anything else is a runtime error), the canvas must be 3D-attached with Graphics3DCanvas, and one camera may happily be bound to several canvases at once. A binding is cleared automatically when its camera, world, canvas, parent window, or the graphics service is freed, so there is nothing to untidy on shutdown - pass 0 only when you want the all-camera behaviour back explicitly.

Canvas rendering lives inside the GUI event loop: pump events with WaitEvent or PeekEvent and present with FlipCanvas, rather than using the fullscreen Flip cycle.

Requires Extended mode.

See also: CanvasCamera, RenderWorldToCanvas, Graphics3DCanvas, CreateCanvas, FlipCanvas.

Example

; SetCanvasCamera Example
; -----------------------
; Requires Extended mode.

Const EVENT_WINDOW_CLOSE=$803

; A window with two 3D canvases, editor style
window=CreateWindow("SetCanvasCamera",100,100,640,480,0,15)
left_canvas=CreateCanvas(8,8,306,396,window)
right_canvas=CreateCanvas(322,8,306,396,window)
label=CreateLabel("Left: perspective camera   Right: top camera   Space: swap   Esc: exit",8,412,608,36,window)
Graphics3DCanvas left_canvas
Graphics3DCanvas right_canvas

world=GetWorld()

; A perspective camera and an orthographic top-down camera
perspective_camera=CreateCamera()
PositionEntity perspective_camera,0,1,-5
top_camera=CreateCamera()
CameraProjMode top_camera,2
PositionEntity top_camera,0,8,0
RotateEntity top_camera,90,0,0
light=CreateLight()
RotateEntity light,45,45,0
cube=CreateCube()
PositionEntity cube,0,1,0
EntityColor cube,80,165,240

; SetCanvasCamera binds one camera to each canvas, so
; RenderWorldToCanvas renders only that camera's view there
SetCanvasCamera left_canvas,perspective_camera
SetCanvasCamera right_canvas,top_camera
swapped=False

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

    ; Space swaps the two bindings
    If KeyHit(57)
        swapped=Not swapped
        If swapped
            SetCanvasCamera left_canvas,top_camera
            SetCanvasCamera right_canvas,perspective_camera
            SetGadgetText label,"Left: top camera   Right: perspective camera   Space: swap   Esc: exit"
        Else
            SetCanvasCamera left_canvas,perspective_camera
            SetCanvasCamera right_canvas,top_camera
            SetGadgetText label,"Left: perspective camera   Right: top camera   Space: swap   Esc: exit"
        EndIf
    EndIf

    TurnEntity cube,0,1,0

    ; Render both views, then present: vwait only on the final canvas
    RenderWorldToCanvas left_canvas,world
    RenderWorldToCanvas right_canvas,world
    FlipCanvas left_canvas,False
    FlipCanvas right_canvas,True

Wend

EndGraphics
FreeGadget window
End

Index