b3dLoadTexture3D

Loads texture from file (PNG/JPG/BMP, returns handle, 0 on failure, creates GPU resource). Takes filename (path to image file string). Returns texture handle (index in g_textures array) or 0 if failed. Uses stb_image to decode file, creates GPU texture resource (D3D12 DEFAULT heap), uploads pixel data via intermediate UPLOAD heap, creates shader resource view (SRV) in persistent descriptor heap, stores in g_textures array. Supports common image formats.

This function loads textures. Image decoding: uses stb_image library (supports PNG, JPG, BMP, TGA, GIF, PSD, HDR formats), forces RGBA output (4 channels, 8-bit per channel = 32-bit per pixel). GPU resource creation: creates D3D12_RESOURCE_DIMENSION_TEXTURE2D in DEFAULT heap (GPU-only memory, not CPU accessible), format DXGI_FORMAT_R8G8B8A8_UNORM (standard 32-bit RGBA), single mip level (no mipmaps, always full resolution). Upload process: creates intermediate UPLOAD heap buffer (CPU-writable, GPU-readable), copies decoded pixels to intermediate buffer via UpdateSubresources helper, GPU copies from intermediate to final texture via command list, transitions texture from COPY_DEST to PIXEL_SHADER_RESOURCE state (ready for sampling), waits for GPU upload completion before returning (synchronous loading). SRV creation: allocates next available SRV slot in g_textureDescriptorHeap (persistent GPU-visible descriptor heap), creates SRV descriptor pointing to texture resource, stores CPU and GPU descriptor handles in Texture3D struct, increments g_nextTextureSRVIndex for next texture. Return value: texture handle is array index in g_textures (0-based, handle 0 is default white texture, handle 1 is default roughness texture, etc.), 0 on failure (invalid filename, decode error, GPU resource creation error). Use cases: (1) Material textures (load diffuse/albedo textures for models), (2) Detail textures (load overlay textures for multi-layered materials), (3) Terrain textures (load ground/rock/grass textures for terrain), (4) UI textures (load icons, buttons, HUD elements), (5) Effect textures (load particle sprites, decals). Common patterns: load texture tex = b3dLoadTexture3D("assets/wood.png") then b3dSetEntityBaseTexture(entity, tex), check failure if tex = 0 then print "Failed to load texture", preload textures at startup for tex in texFiles then texHandles[i] = b3dLoadTexture3D(tex). Typical usage: load at startup or level load (not per-frame, expensive operation), cache handles in variables/arrays for reuse, check return value for 0 before using handle, free when no longer needed with b3dFreeTexture. Texture storage: Texture3D struct stored in g_textures vector contains textureResource (ComPtr to ID3D12Resource), srvCpuHandle/srvGpuHandle (descriptor handles), srvHeapIndex (SRV slot index), width/height (texture dimensions), name (filename for debugging). No mipmaps: textures loaded without mip chains (single level, MipLevels=1), may cause aliasing at distance (future enhancement: generate mipmaps for quality). Memory management: GPU texture memory allocated on DEFAULT heap (stays in VRAM), freed when b3dFreeTexture called or program exits, intermediate upload buffer released after upload completes (no persistent CPU copy). Performance: synchronous loading (blocks until upload complete, may cause stutter), consider async loading for large textures (future enhancement), typical load time: small textures <10ms, large textures (2048x2048) 20-50ms. Supported formats: stb_image supports PNG (lossless, alpha), JPG (lossy, no alpha), BMP (uncompressed), TGA (with alpha), GIF (animated but only first frame), others (verify via stbi_load documentation). RGBA forcing: all textures converted to 4-channel RGBA regardless of source (RGB images get alpha=255, grayscale gets R=G=B=value), simplifies shader code (always sample RGBA). Validation: returns 0 if filename is NULL, file doesn't exist, decode fails (corrupted file, unsupported format), GPU resource creation fails (out of VRAM). Error messages: prints to stderr with stbi_failure_reason() for decode errors, "Failed to create texture resource" for GPU errors. Related: b3dFreeTexture frees loaded texture, b3dSetEntityBaseTexture applies texture to entity, b3dSetEntityDetailTexture adds detail layer.