b3dSetRenderTargetCanvas

Sets 3D render target (canvasID for off-screen, -1 for main window). Takes canvasID (canvas handle from bgiCreateCanvas3D or -1 for main window). Returns nothing. Sets g_activeCanvasID to canvasID, subsequent b3dCls3D and b3dRenderWorld calls render to this target. Canvas must be created with bgiCreateCanvas3D.

This function selects render target. Render target types: main window (canvasID = -1, default, renders to main 3D window backbuffer), canvas (canvasID >= 0, renders to off-screen canvas texture, requires canvas.supports3D = true). Canvas 3D requirement: canvas must be created with bgiCreateCanvas3D (sets supports3D flag and allocates depth buffer). Active canvas persistence: g_activeCanvasID persists across frames (stays set until changed), affects all subsequent b3dCls3D and b3dRenderWorld calls, reset to -1 to return to main window rendering. Use cases: (1) Render to texture (render scene to canvas for mirrors, security cameras, picture-in-picture), (2) Multi-viewport rendering (split-screen, render different cameras to different canvases then composite), (3) Post-processing (render to canvas, apply shader effects, blit to main window), (4) UI integration (render 3D to small canvas, overlay on 2D UI), (5) Dynamic textures (render scene to canvas, use canvas as texture on mesh). Common patterns: render to texture b3dSetRenderTargetCanvas(mirrorCanvas) b3dCls3D() b3dRenderWorld() then b3dSetRenderTargetCanvas(-1) b3dCls3D() b3dRenderWorld(), split-screen for i = 0 to 1 then b3dSetRenderTargetCanvas(viewportCanvas[i]) b3dSetActiveCamera(cameras[i]) b3dCls3D() b3dRenderWorld(), reset to main b3dSetRenderTargetCanvas(-1). Typical usage: set before b3dCls3D/b3dRenderWorld to change render target, combine with b3dSetActiveCamera for multi-camera rendering, render to canvas then copy to main window for effects, use canvas as dynamic texture on meshes (security camera feed). Multi-camera interaction: each camera can render to different canvas (set canvas, set camera, clear, render), camera projection matrices updated per canvas (aspect ratio matches canvas dimensions, prevents distortion), allows different viewport sizes per camera. Canvas validation: checks if canvasID exists in g_canvasMap (prints error if not found), checks if canvas.supports3D = true (prints helpful error if false, all canvases created with bgiCreateCanvas3D have 3D support). Main window reset: canvasID = -1 special value (resets to main window rendering, g_activeCanvasID = -1), use when done with off-screen rendering. Canvas lifecycle: canvas must be created before setting as render target (bgiCreateCanvas3D creates canvas with 3D support), canvas can be freed while set as render target (undefined behavior, should reset to -1 first), canvas persists until explicitly freed. Performance: O(1) operation (simple global variable assignment), actual rendering cost depends on canvas resolution (larger canvas = more pixels to render). Depth buffer: canvases have depth buffer (Z-buffer for depth testing and occlusion), required for correct 3D rendering. Validation: prints error if canvas not found, prints error if canvas not created with bgiCreateCanvas3D (lacks 3D support). Related: bgiCreateCanvas3D creates canvas with 3D rendering support (required for this function), b3dCls3D clears active render target (uses g_activeCanvasID), b3dRenderWorld renders to active render target (uses g_activeCanvasID), b3dSetActiveCamera selects camera for rendering.