b3dPositionDetailTexture

Offsets entity detail texture UV (offsetU/V, requires BBR_TEXTURE_UV flag, auto-clones shared materials). Takes entityHandle (mesh entity handle), textureHandle (texture handle identifying which detail layer), offsetU (horizontal UV offset double), offsetV (vertical UV offset double). Returns nothing. Finds detail layer containing textureHandle, updates detailTextureOffset[i] to {offsetU, offsetV}, controls detail texture position/shift. Requires mesh.allowsUVTransforms = true (set via BBR_TEXTURE_UV flag in b3dCreateMesh or b3dLoadMesh). Mesh entities only.

This function offsets entity-level detail texture coordinates. UV offsetting: offsetU/V add to texture coordinates (offsetU=0.5 shifts texture half-width right, offsetV=-0.5 shifts half-height down, wraps at boundaries with REPEAT mode). UV transform requirement: mesh must be created with BBR_TEXTURE_UV flag, prints helpful error if mesh.allowsUVTransforms = false. Layer identification: searches material detailTextureIndex[0-2] for matching textureHandle (compares both texture handle and SRV heap index), finds which layer contains this texture, updates corresponding detailTextureOffset[i]. Material handling: surface-based meshes (procedural shapes) update all surface materials directly (all surfaces get same detail offset), loaded meshes (GLB models) auto-clone material if shared (calls EnsureUniqueMaterial first), applies offset to entity's material. Use cases: (1) Detail alignment (offsetU=0.25 to align detail feature with mesh feature), (2) Scrolling details (animate offsetU for horizontal scrolling, offsetV for vertical), (3) Decal positioning (offset to place decal at specific location), (4) Pattern variation (different offset per instance for randomized appearance), (5) Multi-frame animation (offset to select different detail atlas frames). Common patterns: center detail b3dPositionDetailTexture(entity, detailTex, 0.5, 0.5), scroll horizontally offsetU = offsetU + 0.01 then b3dPositionDetailTexture(entity, detailTex, offsetU, 0.0), random offset b3dPositionDetailTexture(entity, detailTex, mathRnd(1.0), mathRnd(1.0)). Typical usage: offset to position detail textures on mesh, animate offset for scrolling effects (moving scratches, flowing patterns), set random offset per instance for variation, adjust offset to align detail features. Entity-level vs surface-level: b3dPositionDetailTexture applies to entire entity (all surfaces on surface-based mesh, single material on loaded mesh), b3dPositionSurfaceDetailTexture applies to specific surface (per-face control), use entity-level for uniform offsetting. Material auto-cloning: loaded meshes (GLB) automatically call EnsureUniqueMaterial if shared (prevents affecting other instances). Texture handle matching: searches for textureHandle or matching SRV heap index (flexible compatibility). Performance: O(1) for loaded mesh (finds layer, updates 2 floats after clone), O(N) for surface-based mesh with N surfaces, offset applied in shader. Texture not found: prints error if textureHandle not in any detail layer (must call b3dSetEntityDetailTexture first). Validation: prints error if invalid entity handle, entity not mesh, UV transforms not allowed, entity has no valid material, texture not found in detail layers. Related: b3dScaleDetailTexture scales entity detail texture UV, b3dRotateDetailTexture rotates entity detail texture UV, b3dSetEntityDetailTexture adds detail layer (required before offsetting), b3dPositionSurfaceDetailTexture offsets surface-specific detail (per-face control), b3dCreateMesh creates mesh with BBR_TEXTURE_UV flag.