b3dSetSurfaceDetailTexture

Adds detail texture to specific surface (surface-based meshes only, 1=success 0=failure). Takes meshHandle (mesh entity handle), surfaceHandle (surface index 0 to surfaceCount-1), textureHandle (texture handle from b3dLoadTexture3D). Returns 1 (TRUE) if layer added successfully, 0 (FALSE) if all 3 slots full or error. Finds free detail layer slot for specific surface's material, assigns textureHandle, sets detailBlendFactor to 1.0 (fully visible). Surface-based meshes only (b3dCreateCube, b3dCreateSphere, b3dCreateMesh).

This function adds surface-specific detail layers. Surface-based restriction: only works for surface-based meshes (entity.mesh->isSurfaceBased = true, created via b3dCreateCube, b3dCreateSphere, b3dCreateMesh), does NOT work for loaded GLB models (use b3dSetEntityDetailTexture for those), prints error if mesh not surface-based. Surface targeting: applies detail texture to single surface only (multi-surface meshes like cubes have 6 surfaces, can apply different detail textures to each face independently), surfaceHandle is index into mesh->surfaces array (0-based, get count via b3dCountSurfaces). Slot assignment: checks if texture already assigned to any layer in this surface's material (if found updates existing layer), finds first free slot (detailTextureIndex[i] == -1), assigns texture to slot with default blend factor 1.0 (fully opaque overlay). Use cases: (1) Per-face texturing (different details on each cube face, rust on one side, paint on another), (2) Selective weathering (add damage to specific surfaces, top surface gets moss, sides get scratches), (3) Decal placement (apply logo to front face only), (4) Material variation (different detail textures per surface for complex objects), (5) Terrain patches (different detail on different terrain sections). Common patterns: per-face details for i = 0 to 5 then b3dSetSurfaceDetailTexture(cube, i, faceTex[i]), selective detail b3dSetSurfaceDetailTexture(mesh, topSurface, moss) then b3dSetSurfaceDetailTexture(mesh, sideSurface, scratches), check result result = b3dSetSurfaceDetailTexture(mesh, surf, tex) if result = 0 then print "All slots full". Typical usage: apply different detail textures to different surfaces for variety, add surface-specific weathering (damage on exposed surfaces only), place decals on specific faces (logos, markings), create complex multi-material objects from single mesh. Detail layer limit: maximum 3 layers per surface material (detailTextureIndex[0-2]), each surface has own material with own 3 slots (cube has 6 surfaces * 3 slots = 18 possible detail layers total), returns 0 if surface's 3 slots all occupied. Surface vs entity functions: b3dSetSurfaceDetailTexture targets specific surface (fine-grained control per face), b3dSetEntityDetailTexture applies to all surfaces (entire mesh gets same detail), use surface functions for per-face variety. Surface material independence: each surface has separate materialIndex (surface[0].materialIndex != surface[1].materialIndex for procedural shapes), allows independent detail layers per surface. Multi-surface meshes: cubes have 6 surfaces (faces), spheres have 1 surface (entire sphere), cylinders have 3 surfaces (top cap, side, bottom cap), cones have 2 surfaces (base, side), meshes from b3dCreateMesh have user-defined surface count. Performance: O(1) operation (finds single surface, updates single material), each surface adds shader cost (3 detail texture samples * surfaceCount). Validation: prints error if invalid mesh handle, mesh not surface-based, invalid surface handle, invalid texture handle, surface has no material, returns 0 for all errors. Related: b3dSetSurfaceDetailAlpha adjusts surface detail opacity, b3dRemoveSurfaceDetailTexture removes surface detail layer, b3dSetEntityDetailTexture applies detail to all surfaces (entire mesh), b3dScaleSurfaceDetailTexture scales detail texture UV, b3dPositionSurfaceDetailTexture offsets detail texture UV, b3dRotateSurfaceDetailTexture rotates detail texture.