b3dCameraPick

Ray-casts from screen coordinates into 3D world (stores result, retrieve with b3dPickedEntity/X/Y/Z/NX/NY/NZ). Takes camera (camera entity handle), screenX/screenY (screen pixel coordinates). Returns nothing. Validates camera entity, resets g_lastPickResult, builds view/projection matrices, unprojects screen coords to world-space ray, tests ray against all mesh entities respecting pickMode (0=sphere, 1=box, 2=polygon), stores closest hit in g_lastPickResult. Mouse picking for click selection.

This function performs screen picking. Unprojection pipeline: (1) Convert screen coords (0,0=top-left) to NDC (-1 to 1, origin center), (2) Create near/far points in NDC space (z=0 for near plane, z=1 for far plane), (3) Invert view-projection matrix, (4) Transform NDC points to world space, (5) Build ray from near to far (origin=nearWorld, direction=normalized(farWorld-nearWorld)). Pick modes: pickMode=0 (PICK_SPHERE) uses ray-sphere intersection with entity collisionRadius (fast, approximate bounds), pickMode=1 (PICK_BOX) uses ray-OBB intersection with entity collisionBoxMin/Max (medium speed, tighter bounds), pickMode=2 (PICK_POLYGON) uses ray-triangle intersection for exact mesh picking (CPU for < 1000 tris, GPU for complex meshes). Closest hit: iterates all mesh entities (only ENTITY_MESH tested), finds closest intersection (smallest t value along ray), stores result in g_lastPickResult (entity handle, hit position, normal, triangle index, surface index, time). Result retrieval: call b3dPickedEntity() to get entity handle (0 if no hit), b3dPickedX/Y/Z() for hit position, b3dPickedNX/NY/NZ() for surface normal, b3dPickedTriangle() for triangle index, b3dPickedSurface() for surface index, b3dPickedTime() for distance along ray. Use cases: (1) Mouse clicking (click screen position, get 3D object), (2) Object selection (editor tools, click to select), (3) Interaction (click doors, buttons, items), (4) Context menus (right-click object for menu), (5) Targeting (click enemy for attack). Common pattern: if mouse button pressed then b3dCameraPick(cam, mouseX, mouseY), entity=b3dPickedEntity(), if entity > 0 then handle click. Typical usage: call every mouse click with screen coordinates, check if entity picked, perform action on picked object. Projection modes: supports both perspective (projMode=1) and orthographic (projMode=2), builds appropriate projection matrix. Viewport handling: uses camera viewport dimensions if set (viewportWidth/Height > 0), else uses g_3D_resolutionWidth/Height. GPU acceleration: meshes with > 1000 triangles use GPU compute shader for picking (fast for complex meshes), smaller meshes use CPU ray-triangle tests. Performance: O(N*T) where N=entity count, T=triangles per entity (CPU), O(N) for GPU picking (parallel triangle tests), typically fast enough for real-time mouse picking. Pick mode filtering: only tests entities with non-zero pickMode (set by b3dEntityPickMode), allows disabling picking for scenery/background. Related: b3dPickedEntity/X/Y/Z/NX/NY/NZ/Triangle/Surface retrieve pick results, b3dEntityPickMode sets entity pickability, b3dEntityPick picks from entity forward direction, b3dLinePick picks from arbitrary ray.