b3dSetSurfaceDetailAlpha

Sets surface detail layer opacity (0.0=invisible, 1.0=opaque, clamped 0.0-1.0, surface-based only). Takes meshHandle (mesh entity handle), surfaceHandle (surface index 0 to surfaceCount-1), textureHandle (texture handle identifying which layer), alpha (0.0-1.0 double). Returns nothing. Finds detail layer containing textureHandle in specific surface's material, updates detailBlendFactor[i] to clamped alpha, controls layer visibility/blending strength. Surface-based meshes only.

This function adjusts surface-specific detail opacity. Alpha clamping: input clamped to 0.0-1.0 range (negative values become 0.0, values > 1.0 become 1.0). Layer identification: searches surface's material detailTextureIndex[0-2] for matching textureHandle (finds which layer contains this texture in this specific surface), updates corresponding detailBlendFactor[i] (opacity control for that layer on that surface only). Surface targeting: affects single surface only (cube face 0 detail alpha independent of face 1 detail alpha), allows per-surface opacity control for fine-grained material variation. Use cases: (1) Selective weathering intensity (top surface moss at alpha 0.8, side surface moss at alpha 0.3), (2) Per-face detail strength (front logo at alpha 1.0 for prominence, side logo at alpha 0.5 for subtlety), (3) Gradual appearance (animate surface detail alpha for localized fade in/out), (4) Conditional visibility (hide detail on specific surfaces based on game state), (5) Surface damage levels (damaged surface at alpha 1.0 for heavy scratches, pristine surface at alpha 0.2 for light scratches). Common patterns: strong detail on top b3dSetSurfaceDetailAlpha(mesh, topSurf, detail, 1.0) weak on sides b3dSetSurfaceDetailAlpha(mesh, sideSurf, detail, 0.3), fade surface for i = 0 to surfCount then b3dSetSurfaceDetailAlpha(mesh, i, detail, alphas[i]), hide on specific surface b3dSetSurfaceDetailAlpha(mesh, bottomSurf, detail, 0.0). Typical usage: set different alpha per surface for weathering variation (top exposed to elements = high alpha, bottom protected = low alpha), adjust individual surface detail strength for artistic control, animate surface-specific detail alpha for effects. Surface-based restriction: only works for surface-based meshes (entity.mesh->isSurfaceBased = true), prints error if mesh not surface-based, does NOT work for loaded GLB models. Texture not found: prints error if textureHandle not in any layer for this surface (texture never added or already removed, must call b3dSetSurfaceDetailTexture first). Performance: O(1) operation (finds surface, searches 3 layer slots, updates single float). Validation: prints error if invalid mesh handle, mesh not surface-based, invalid surface handle, invalid texture handle, surface has no material, texture not assigned to surface. Related: b3dSetSurfaceDetailTexture adds surface detail layer (sets initial alpha 1.0), b3dRemoveSurfaceDetailTexture removes surface detail layer, b3dSetEntityDetailAlpha sets detail alpha for all surfaces (entire mesh).