b3dSetEntityDetailTexture

Adds detail texture layer (up to 3 layers, returns 1=success 0=failure, default alpha 1.0). Takes entityHandle (mesh/terrain entity handle), 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 (detailTextureIndex[0-2]), assigns textureHandle, sets detailBlendFactor to 1.0 (fully visible), allows multi-layered texturing. Mesh and terrain entities only.

This function adds detail layers. Detail textures: overlaid on top of base color texture (shader blends base + detail1 + detail2 + detail3), used for surface variation (dirt on metal, scratches on paint, moss on stone), up to 3 simultaneous detail layers per material. Slot assignment: checks if texture already assigned to any layer (if found updates existing layer instead of adding duplicate), finds first free slot (detailTextureIndex[i] == -1), assigns texture to slot with default blend factor 1.0 (fully opaque overlay). Blend factor: detailBlendFactor[i] controls layer opacity (0.0 = invisible, 1.0 = fully visible, blended additively or multiplicatively in shader), set to 1.0 by default (adjust with b3dSetEntityDetailAlpha later). Material handling: surface-based meshes (procedural shapes) update all surface materials directly (returns 1 if any surface succeeded), loaded meshes (GLB models) update mesh.materialIndex material (single material for entire mesh), terrain entities update terrain.materialIndex material. Use cases: (1) Surface weathering (add rust/dirt textures over base metal), (2) Detail enhancement (add scratches/cracks to smooth surfaces), (3) Decals (apply logos/markings to models), (4) Terrain blending (add grass/rock detail over base terrain texture), (5) Multi-material surfaces (combine wood grain + paint + scratches). Common patterns: add layer result = b3dSetEntityDetailTexture(entity, detailTex) if result = 0 then print "All detail slots full", multiple layers b3dSetEntityDetailTexture(entity, dirt) then b3dSetEntityDetailTexture(entity, scratches) then b3dSetEntityDetailTexture(entity, decal), adjust opacity b3dSetEntityDetailTexture(entity, detail) then b3dSetEntityDetailAlpha(entity, detail, 0.5) for 50% blend. Typical usage: add detail textures after base texture for enhanced surface appearance, layer multiple details for complex materials (base wood + grain detail + scratch detail), adjust individual layer alpha for blending control. Detail layer limit: maximum 3 layers per material (detailTextureIndex[0], [1], [2]), returns 0 if all slots occupied (remove layer first with b3dRemoveEntityDetailTexture), shader samples all 3 layers regardless of content (empty slots sample from index -1 which shader ignores). Duplicate handling: if texture already in any layer updates that layer (does NOT add duplicate), allows changing blend factor without removing/re-adding (call b3dSetEntityDetailAlpha directly instead). Free slot search: checks layers 0, 1, 2 in order (first free slot used, predictable ordering), layer order may affect blending (depends on shader implementation, typically additive or multiplicative). Shader blending: detail layers composited in shader (various blend modes possible: add, multiply, overlay, screen), blend factor controls layer strength (finalColor = baseColor + detail0 * factor0 + detail1 * factor1 + detail2 * factor2). Material storage: detailTextureIndex[i] stores texture handle (g_textures array index, same as baseColorTextureIndex), detailBlendFactor[i] stores opacity (0.0-1.0 float). Performance: O(1) for loaded mesh or terrain (single material update), O(N) for procedural mesh with N surfaces (all surfaces updated), shader cost increases with detail layers (3 extra texture samples + blending math). Return value semantics: 1 (TRUE) if texture added to any slot (new or existing), 0 (FALSE) if all 3 slots full (can't add more), 0 (FALSE) on error (invalid handle, no material). Validation: prints error if invalid entity handle, invalid texture handle, entity is not mesh or terrain, entity has no material, returns 0 for all errors. Related: b3dSetEntityDetailAlpha adjusts detail layer opacity (change blendFactor), b3dRemoveEntityDetailTexture removes detail layer (frees slot), b3dSetEntityBaseTexture sets base color texture (detail layers overlay this), b3dLoadTexture3D loads textures for detail layers.