bgiGetCanvasMouseX

Returns the canvas-relative X coordinate of the mouse cursor. Searches g_canvasMap for canvasID. If not found, returns 0. Calls GetCursorPos to get screen cursor position. If GetCursorPos fails, returns last known position from g_canvasLastMousePos map (or 0 if no cached position). Calls ScreenToClient with canvas hWnd to convert screen coordinates to canvas client-area coordinates. If ScreenToClient fails, returns last known position. Checks if cursor is within canvas bounds (cursorPos.x >= 0 && cursorPos.x < width && cursorPos.y >= 0 && cursorPos.y < height). If mouse is inside canvas, updates g_canvasLastMousePos[canvasID] cache and returns cursorPos.x. If mouse is outside canvas, returns last valid cached position from g_canvasLastMousePos (or 0 if no cache).

This function provides canvas-relative mouse coordinates for multi-viewport applications. GetCursorPos returns global screen coordinates. ScreenToClient converts to window client-area coordinates (0,0 = top-left of canvas). Boundary check ensures coordinates are within canvas dimensions. Last position caching implements "freeze at edge" behavior - when mouse leaves canvas, reported position stays at last valid edge coordinate (prevents negative coords or coords beyond canvas size). Cache prevents jumps when mouse re-enters canvas. Useful for 3D camera controls, object manipulation, viewport navigation. Returns 0 for invalid canvas (ambiguous - could be left edge). Common pattern: check bgiIsMouseOverCanvas first, then get coordinates if true. Cache is per-canvas in g_canvasLastMousePos map (std::map<int, POINT>). Coordinates are in canvas space, not parent window space.