b3dFreeTexture

Frees texture GPU memory (repoints SRV to default white, removes material references). Takes textureHandle (texture handle from b3dLoadTexture3D). Returns nothing. Removes all material references to texture (resets to defaults: baseColor to 0, metallicRoughness to 1, normal to 2, detail to -1), repoints SRV descriptor to default white texture (prevents GPU faults from stray references), releases GPU texture resource via ComPtr.Reset(), marks texture as freed. Safe cleanup.

This function frees textures. Material cleanup: iterates all materials in g_materials, checks each texture slot (baseColorTextureIndex, metallicRoughnessTextureIndex, normalTextureIndex, detailTextureIndex[0-2]), if slot matches freed texture's srvHeapIndex resets to safe defaults (baseColor=0 white, metallicRoughness=1 white, normal=2 default normal, detail=-1 empty). SRV repointing: critical safety measure (instead of leaving SRV pointing to freed GPU memory which causes crashes), updates SRV descriptor to point to g_textures[0] (default white texture), prevents GPU page faults if shader accidentally samples freed texture slot, uses same CPU descriptor handle (slot preserved in heap, only resource pointer changed). GPU resource release: calls texture.textureResource.Reset() (ComPtr decrements reference count, frees D3D12 resource when count reaches 0), frees VRAM occupied by texture (typically 4MB for 1024x1024 RGBA), does NOT free SRV descriptor slot (slot remains but points to white texture). Texture metadata: sets width=0, height=0, name="[FREED]" for debugging (helps identify use-after-free bugs in logs). Use cases: (1) Dynamic texture loading (free old textures when loading new level), (2) Memory management (free unused textures to reduce VRAM usage), (3) Cleanup on exit (free all textures before shutdown), (4) Texture swapping (free old, load new for dynamic content), (5) Error recovery (free partial textures after load failure). Common patterns: cleanup loop for tex in loadedTextures then b3dFreeTexture(tex), conditional free if textureHandle <> 0 then b3dFreeTexture(textureHandle), level unload freeAllTextures() calls b3dFreeTexture for all handles. Typical usage: free textures when changing levels/scenes, free when replacing with different texture, free during shutdown to prevent memory leaks, free after loading error to clean up partial resources. Already freed check: prints error if texture.textureResource == nullptr (double-free protection), safe to call multiple times (subsequent calls are no-ops with error message). Invalid handle: prints error if textureHandle < 0 or >= g_textures.size() (bounds check), safe to call with invalid handles (no crash, just error message). Material reference safety: ensures no material points to freed texture (all references reset to defaults before resource released), prevents rendering crashes from dangling texture references. SRV preservation: SRV heap slot NOT freed (g_nextTextureSRVIndex not decremented), slot reused for future textures would require complex compaction (not implemented), freed slots point to white texture (safe fallback). Default textures: g_textures[0] is white texture (1x1 pixel, RGB 255,255,255), g_textures[1] is default metallicRoughness (white, full roughness), g_textures[2] is default normal map (127,127,255 for flat surface). Performance: O(N) where N = material count (iterates all materials to clean references), typically fast (materials usually < 1000), GPU resource release is instant (ComPtr handles synchronization). Memory reclaim: GPU VRAM freed immediately (available for new allocations), CPU struct remains in g_textures (marked as freed but not removed from vector, no vector compaction). Validation: returns silently if invalid handle, prints error if already freed, does NOT crash on invalid input (safe to call in cleanup loops). Related: b3dLoadTexture3D loads textures (inverse operation), b3dSetEntityBaseTexture uses texture handles (should not use freed handles), b3dSetEntityDetailTexture adds detail textures (references cleaned by this function).