bgiSetActiveCanvas

Sets the active canvas for subsequent 3D rendering operations. If switching from one canvas to another (g_activeCanvasID > 0 and canvasID != g_activeCanvasID), calls DX12_WaitForGpu() to ensure GPU finishes previous canvas before switching (prevents instance buffer conflicts). If canvasID is -1, switches to main window: sets g_activeCanvasID=-1, calls b2dUpdateCanvasState with g_3D_resolutionWidth/Height to update 2D overlay for main window dimensions. If canvasID > 0, searches g_canvasMap for canvas. If not found, outputs debug message and returns. Sets g_activeCanvasID=canvasID. Calls b2dUpdateCanvasState with canvas width/height to update 2D overlay state for canvas dimensions. No return value.

This function redirects 3D rendering to a specific canvas render target. Active canvas ID determines which render target b3dCls3D binds. GPU wait prevents race condition where previous canvas's instance buffers are still being read while new data is written. Main window is ID -1 (default state). b2dUpdateCanvasState updates 2D overlay system to match render target dimensions - critical for correct draw command sizing. Does NOT flush rendering or bind render target immediately - binding happens on next b3dCls3D call. bgiFlipCanvas handles per-canvas flushing. Common pattern: bgiSetActiveCanvas(canvasID), b3dCls3D(), b3dRenderWorld(), bgiFlipCanvas(canvasID). Canvas must exist in g_canvasMap or function fails silently. Use bgiGetActiveCanvas to query current active canvas. Multiple canvases can exist but only one is active at a time. Switch between canvases each frame for multi-viewport rendering.