b3dUVMapSpherical

Applies spherical UV mapping using longitude/latitude projection with seam fixing. Takes mesh (surface-based mesh entity). Returns nothing. Validates mesh exists, type is ENTITY_MESH, surface-based, and locked. First pass: for each vertex, normalizes position to unit direction (nx, ny, nz = position/length). Calculates longitude U = (atan2(nz, nx)/PI + 1) * 0.5 (wraps around equator, 0-1 range). Calculates latitude V = 0.5 - asin(ny)/PI (pole-to-pole, 0-1 range). For degenerate vertices (length near zero), sets UV to (0.5, 0.5). Second pass: fixes seam-crossing triangles using same logic as cylindrical (detects U difference > 0.5, adjusts to prevent wrap). Silently returns on errors.

This function wraps textures around spherical geometry using geographic coordinates. Spherical mapping treats mesh as globe: longitude (U) wraps horizontally around equator, latitude (V) spans from north pole (0) to south pole (1). Perfect for: (1) Planets/moons (space games), (2) Balls/spheres (sports equipment), (3) Domes/arches (architecture), (4) Character heads (approximated as spheres), (5) Bubbles/particles (effects). Normalization critical: divides position by length to get direction vector - actual vertex distance from origin doesn't matter, only direction. This means spherical mapping works for any radius sphere (small or large, same UV result). Longitude formula: atan2(nz, nx) gives angle around Y axis (-PI to PI), normalized to 0-1. Latitude formula: asin(ny) gives elevation angle (-PI/2 to PI/2), transformed to 0-1 with 0.5 - angle/PI. Seam handling: same as cylindrical, prevents texture wrap at 0 degrees/360 degrees longitude boundary. Pole artifacts: vertices at north/south poles converge to single point (V=0 or V=1), all longitudes valid - causes triangle pinching. Degenerate vertex handling: vertices at exact origin (0,0,0) have undefined direction - assigned center UV (0.5, 0.5) to avoid NaN/Inf. Common use: earth texture on sphere, skybox on inside of inverted sphere. Workflow: mesh=b3dCreateSphere(...), b3dLockMesh(mesh), b3dUVMapSpherical(mesh), b3dUnlockMesh(mesh). Use equirectangular textures for best results (standard Earth map projections work). Alternative: b3dUVMapCylindrical for tube-like geometry, cube mapping for skyboxes (via b3dUVMapBox with special cube texture), manual UV for non-uniform geometry.