b3dCameraProject

Projects 3D world position to 2D screen coordinates (stores in camera for retrieval). Takes camera (camera entity handle), worldX/worldY/worldZ (3D world position). Returns nothing. Validates camera entity, allocates Camera3D if null, transforms world position through view/projection matrices to screen coordinates, stores results in camera->projectedX/Y/Z. Retrieve results with b3dProjectedX/Y/Z.

This function transforms 3D to 2D. Projection pipeline: (1) World space position (input worldX/Y/Z), (2) View space (multiply by inverse camera world matrix), (3) Clip space (multiply by projection matrix), (4) NDC space (perspective divide, range [-1,1]), (5) Screen space (scale/offset to viewport pixels). Screen coordinates: projectedX/Y in viewport pixel coordinates (0,0)=top-left, projectedZ in depth range [0,1] (0=near plane, 1=far plane). Projection modes: mode=0 (disabled) sets all projected values to 0.0 and returns early, mode=1 (perspective) uses FOV-based perspective projection with depth perspective divide, mode=2 (orthographic) uses parallel projection (FOV*0.1 as ortho size). Viewport handling: if viewport width/height=0 uses g_3D_resolutionWidth/Height (fullscreen), else uses camera viewport dimensions, screen coordinates offset by viewportX/Y, screen X/Y scaled to viewport size. Y-axis flip: NDC Y-axis inverted for screen coordinates (NDC +Y=up, screen +Y=down), screenY = (1.0 - ndcY) * 0.5 * viewportHeight. Use cases: (1) 3D name tags (project entity position, draw text at screen coords), (2) Cursor picking (project mouse to 3D for ray intersection), (3) Minimap (project world positions to 2D map), (4) HUD elements (anchor UI to 3D objects), (5) Debug visualization (show 3D positions as 2D overlay). Common pattern: b3dCameraProject(cam, entityX, entityY, entityZ), screenX=b3dProjectedX(cam), screenY=b3dProjectedY(cam), draw text at (screenX, screenY). Typical usage: project entity positions every frame for name tags, project world cursor for picking, project waypoints for HUD markers. Depth testing: projectedZ useful for depth sorting 2D elements (higher Z = further from camera, draw distant labels first for proper occlusion). Off-screen detection: if projectedX/Y outside viewport bounds, object is off-screen (check screenX < 0 or screenX > viewportWidth), if projectedZ < 0 or projectedZ > 1, object is outside depth range (behind camera or beyond far plane). Performance: O(1) matrix math (few vector transforms, no iteration), call once per object per frame for name tags. Camera allocation: if camera->camera==nullptr, allocates new Camera3D. Related: b3dProjectedX/Y/Z retrieve stored screen coordinates, b3dCameraViewport sets viewport region, b3dCameraProjMode sets projection mode.