b3dPositionSurfaceDetailTexture

Offsets surface detail texture UV (offsetU/V, requires BBR_TEXTURE_UV mesh flag, surface-based only). Takes meshHandle (mesh entity handle), surfaceHandle (surface index 0 to surfaceCount-1), textureHandle (texture handle identifying which layer), offsetU (horizontal UV offset double), offsetV (vertical UV offset double). Returns nothing. Finds detail layer containing textureHandle in specific surface's material, updates detailTextureOffset[i] to {offsetU, offsetV}, controls texture position/shift. Requires mesh.allowsUVTransforms = true (set via BBR_TEXTURE_UV flag in b3dCreateMesh).

This function offsets surface 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 (b3dCreateMesh(slots, BBR_TEXTURE_UV, unique) enables UV transforms), prints error if mesh.allowsUVTransforms = false. Layer identification: searches surface's material detailTextureIndex[0-2] for matching textureHandle (finds which layer contains this texture), updates corresponding detailTextureOffset[i] (offset stored per layer). Use cases: (1) Texture alignment (offsetU=0.25 to align detail feature with surface feature), (2) Scrolling textures (animate offsetU for horizontal scrolling, offsetV for vertical), (3) Decal positioning (offset to place decal at specific surface location), (4) Pattern variation (different offset per surface for randomized appearance), (5) Multi-frame animation (offset to select different texture atlas frames). Common patterns: center decal b3dPositionSurfaceDetailTexture(mesh, surf, detail, 0.5, 0.5), scroll horizontally offsetU = offsetU + 0.01 then b3dPositionSurfaceDetailTexture(mesh, surf, detail, offsetU, 0.0), random per surface b3dPositionSurfaceDetailTexture(mesh, i, detail, mathRnd(1.0), mathRnd(1.0)). Typical usage: offset to position decals/markings on surfaces, animate offset for scrolling effects (conveyor belts, waterfalls), set random offset per surface for pattern variation, adjust offset to align texture features. UV coordinate math: finalUV = baseUV + offset (offsetU=0.5 converts UV 0.0-1.0 to 0.5-1.5, texture wraps at 1.0 back to 0.0 with REPEAT mode). Offset wrapping: offsets > 1.0 or < 0.0 wrap around with REPEAT sampler (offsetU=1.5 same as offsetU=0.5 after wrapping, creates seamless tiling). Offset defaults: likely 0.0 if never set (verify during testing, 0.0 = no offset, texture aligned to UV origin). Surface targeting: affects single surface only (different offset per surface for variety, randomized positions). Scrolling animation: animate offsetU or offsetV per frame for moving textures (water flow, conveyor motion, scrolling clouds). Performance: O(1) operation (finds surface, searches 3 slots, updates 2 floats), offset applied in vertex/pixel shader. Surface-based restriction: only works for surface-based meshes (entity.mesh->isSurfaceBased = true), prints error if mesh not surface-based. UV transforms disabled error: prints helpful error if mesh.allowsUVTransforms = false, instructs to use BBR_TEXTURE_UV flag when creating mesh. Texture not found: prints error if textureHandle not in any layer for this surface (must call b3dSetSurfaceDetailTexture first). Validation: prints error if invalid mesh handle, mesh not surface-based, UV transforms not allowed, invalid surface handle, invalid texture handle, surface has no material, texture not assigned to surface. Related: b3dScaleSurfaceDetailTexture scales detail texture UV, b3dRotateSurfaceDetailTexture rotates detail texture UV, b3dSetSurfaceDetailTexture adds detail layer (required before positioning), b3dCreateMesh creates mesh with BBR_TEXTURE_UV flag (enables UV transforms).