b3dPhysicsCameraPick

Physics-based camera raycast through screen point (mouse picking, unprojects screen to world ray). Takes camera (camera entity handle), screenX/Y (screen pixel coordinates), layerMask (0=all layers, reserved for future). Returns entity handle if hit (0 if no hit). Unprojects screen coordinates to world-space ray, calls b3dPhysicsLinePick with calculated ray, stores hit details in g_lastPickResult. Use for mouse picking, click-to-select, targeting systems, or UI interaction with 3D physics objects.

This function performs camera-based physics raycast. Camera picking: converts screen coordinates to world-space ray (unprojection, inverse view-projection transform), raycasts from camera through screen point (origin = camera near plane, direction = toward far plane), only detects physics bodies (entities with b3dCreatePhysicsBody, ignores non-physics meshes), returns closest hit along ray (nearest intersection, same as b3dPhysicsLinePick). Screen coordinates: screenX/Y in pixels (0,0 = top-left corner, widthxheight = bottom-right), converted to NDC (Normalized Device Coordinates, -1 to +1 range), unprojected to world space (inverse view-projection matrix, transforms screen to world). Camera parameters: uses camera position and rotation (eyePos, pitch, yaw, roll define view matrix), uses camera projection (perspective FOV or orthographic, projection matrix), uses camera near/far planes (ray from near to far, max distance = far plane), validates camera entity (must be ENTITY_CAMERA type, camera object exists). Use cases: (1) Mouse picking (click to select physics objects), (2) Targeting (crosshair on physics entities), (3) UI interaction (click 3D physics buttons, interactive objects), (4) Drag-and-drop (physics object manipulation), (5) Context menus (right-click physics objects). Common patterns: mouse click hit = b3dPhysicsCameraPick(mainCamera, mouseX, mouseY, 0) select object under cursor, targeting reticle target = b3dPhysicsCameraPick(playerCamera, screenWidth/2, screenHeight/2, 0) center crosshair, hover detection hover = b3dPhysicsCameraPick(cam, mouseX, mouseY, 0) continuous hover check. Typical usage: call on mouse click (select or interact with clicked object), call every frame for hover (continuous detection, highlight hovered objects), combine with b3dPickedX/Y/Z for world position.

Unprojection algorithm: screen to NDC (ndcX = (screenX / width) * 2 - 1, ndcY = (screenY / height) * 2 - 1), NDC to clip space (nearPoint = (ndcX, ndcY, 0, 1), farPoint = (ndcX, ndcY, 1, 1) homogeneous coordinates), inverse view-projection (invViewProj = inverse(view * projection), world = invViewProj * clip), world-space ray (direction = normalize(farWorld - nearWorld), origin = nearWorld). View matrix calculation: camera position (eyePos from entity.position), camera forward direction (calculated from pitch/yaw, forward = (sin(yaw)*cos(pitch), -sin(pitch), cos(yaw)*cos(pitch))), camera up vector (calculated from roll, up = (sin(roll), cos(roll), 0) rotated by forward), LookAtLH matrix (standard DirectX left-handed view matrix). Projection matrix: perspective projection (if projMode != 2, FOV and aspect ratio), orthographic projection (if projMode = 2, width and height), near and far planes (from camera.nearPlane, camera.farPlane), viewport dimensions (camera.viewportWidth/Height or global resolution). Ray parameters: ray origin nearWorld (world position of screen point at near plane), ray direction normalized (from nearWorld toward farWorld, unit vector), ray length = far plane distance (max distance = camera.farPlane, full depth range), delegates to b3dPhysicsLinePick (calls with calculated ray parameters).

Mouse picking example: player clicks object (mouse click event, get mouse coordinates), raycast from camera (hit = b3dPhysicsCameraPick(mainCamera, mouseX, mouseY, 0)), check hit (If hit > 0 Then selectedObject = hit, highlight selected), object selection (select physics object under cursor). Targeting crosshair example: crosshair at screen center (fixed reticle UI element), raycast through center (target = b3dPhysicsCameraPick(playerCamera, screenWidth/2, screenHeight/2, 0)), display target info (If target > 0 Then show target name, distance), continuous targeting (call every frame, update target). Hover detection example: mouse moves over 3D scene (continuous mouse position tracking), raycast at mouse (hover = b3dPhysicsCameraPick(cam, mouseX, mouseY, 0)), highlight hovered object (If hover > 0 Then highlight hover, show tooltip), interactive feedback (visual feedback for hoverable objects). Context menu example: right-click on object (context menu trigger, mouse position), raycast to find object (clicked = b3dPhysicsCameraPick(cam, mouseX, mouseY, 0)), show context menu (If clicked > 0 Then showMenu(clicked), display actions), object-specific menu (menu options based on clicked entity type). Drag-and-drop example: click and drag object (mouse down, raycast to select, mouse move to drag), select object (dragging = b3dPhysicsCameraPick(cam, mouseX, mouseY, 0) on mouse down), update position (If dragging > 0 Then reposition object based on mouse), release object (mouse up, stop dragging), physics manipulation.

Screen coordinate systems: top-left origin (screenX=0, screenY=0 at top-left corner), right = increasing X (screenX increases toward right edge), down = increasing Y (screenY increases toward bottom edge), typical range (0 to screenWidth-1 for X, 0 to screenHeight-1 for Y). NDC coordinate system: center origin (ndcX=0, ndcY=0 at screen center), left = -1, right = +1 (ndcX range -1 to +1 horizontal), bottom = -1, top = +1 (ndcY range -1 to +1 vertical), Z depth (ndcZ 0=near plane, 1=far plane). Viewport dimensions: uses camera viewport (camera.viewportWidth/Height if set, custom viewport size), falls back to global resolution (g_3D_resolutionWidth/Height if camera viewport 0, full screen), affects aspect ratio (aspect = width / height, used in projection matrix). Perspective vs orthographic: perspective projection (FOV-based, objects smaller with distance, typical for 3D games), orthographic projection (parallel projection, no perspective, typical for 2D or isometric), unprojection differs (perspective uses FOV, orthographic uses width/height). Camera validation: checks camera entity exists (g_entities.find(cameraHandle), returns 0 if not found), checks entity type (entity.type == ENTITY_CAMERA, returns 0 if not camera), checks camera object (camera.camera != nullptr, returns 0 if null), graceful failure (invalid camera returns 0, no hit).

Ray length: ray extends to far plane (maxDistance = camera.farPlane, full depth range), typical far plane (100-10000 units, depends on scene scale), direction scaled by far plane (directionX/Y/Z * farPlane, endpoint at far plane), tests entire depth range (from near to far, all physics bodies along ray). Hit details: same as b3dPhysicsLinePick (g_lastPickResult stores position, normal, distance), b3dPickedX/Y/Z world position (intersection point, world space), b3dPickedTime distance (units from camera, depth), access immediately (read after raycast, before next pick call). Shared result structure: g_lastPickResult shared (b3dPhysicsLinePick, b3dPhysicsCameraPick, b3dPhysicsEntityPick all use same), overwritten by next pick (any pick function resets result, not persistent), read immediately (If hit Then x = b3dPickedX(), y = b3dPickedY(), don't delay). Performance: unprojection cost (matrix inverse, moderate cost ~0.1ms), raycast cost (b3dPhysicsLinePick, fast ~0.01ms), total cost (acceptable for per-frame or per-click, not thousands per frame), typical use (once per click, or once per frame for hover).

Camera-based vs line-based: camera-based (screen coordinates, automatic unprojection, user-friendly), line-based (manual ray calculation, explicit origin and direction, lower-level), camera-based for UI (mouse picking, targeting, click interaction), line-based for custom rays (arbitrary rays, non-camera raycasts, advanced use cases). Physics vs mesh picking: physics (b3dPhysicsCameraPick) tests physics bodies only (fast, Jolt acceleration), mesh (b3dCameraPick) tests mesh triangles (slower, more accurate, all meshes), physics for gameplay (interactive objects, physics entities), mesh for precise picking (decorative objects, exact triangle selection). Mouse coordinates: get from input system (BBR_GetMouseX/Y or platform-specific input), screen space (pixel coordinates, matches viewport), requires camera (must have valid camera entity, camera defines projection). Layer mask: layerMask 0 = all layers (default, tests all physics bodies), layer filtering future feature (currently unused, reserved), all bodies tested (regardless of mask, filtering not implemented). No hit behavior: returns 0 if no hit (ray doesn't intersect any physics body, no physics objects under cursor), g_lastPickResult reset (empty result, default values), check return value (If hit = 0 Then nothing under cursor).

Click-to-select pattern: mouse click event (get mouse coordinates at click time), raycast from camera (selected = b3dPhysicsCameraPick(cam, clickX, clickY, 0)), store selected object (If selected > 0 Then currentSelection = selected), highlight selected (visual feedback, outline or color change). Continuous hover pattern: call every frame (continuous raycast at mouse position, real-time hover), raycast at mouse (hover = b3dPhysicsCameraPick(cam, mouseX, mouseY, 0)), update hover state (If hover <> lastHover Then unhighlight last, highlight hover), smooth hover transitions. Targeting reticle pattern: fixed screen position (center of screen, crosshair UI), raycast through reticle (target = b3dPhysicsCameraPick(cam, screenWidth/2, screenHeight/2, 0)), display target info (If target > 0 Then show name, health, distance), aim assist (optional, snap to target). Multi-camera scenarios: specify camera handle (multiple cameras in scene, pick which one), viewport cameras (different viewports, correct camera for each), mini-map cameras (separate camera for mini-map, different projection). Invalid camera handling: returns 0 if camera not found (invalid handle, camera doesn't exist), returns 0 if not camera type (entity is not camera, wrong entity type), returns 0 if camera object null (camera not initialized, missing camera data), silent failure (graceful, no error messages).

Delegation to line pick: calls b3dPhysicsLinePick internally (calculates ray, delegates to line raycast), inherits line pick behavior (same hit detection, same result structure), inherits limitations (physics bodies only, approximate normals), convenience wrapper (automates unprojection, simpler interface). Coordinate validation: no validation on screen coordinates (any screenX/Y accepted, may be off-screen), off-screen coordinates (negative or > viewport return ray, may miss all objects), user responsible (ensure coordinates within viewport, typical 0 to width/height). Projection mode: projMode 2 = orthographic (parallel projection, no perspective), projMode != 2 = perspective (FOV-based, perspective division), affects unprojection (different projection matrix, different ray calculation), both supported (automatic, based on camera settings). Viewport offset: assumes viewport at (0,0) (top-left corner, no offset), custom viewports not supported (offset viewports may require adjustment), full-screen assumption (viewport covers entire screen).

Related: b3dPhysicsLinePick performs line raycast (lower-level, manual ray, this function calls it), b3dPhysicsEntityPick raycasts forward from entity (entity-based, forward direction), b3dCameraPick mesh-based camera raycast (triangle intersection, slower, all meshes), b3dPickedX/Y/Z/NX/NY/NZ/Time access hit details (result queries, shared across pick functions), BBR_GetMouseX/Y get mouse coordinates (input functions, provide screenX/Y for picking).