b3dLoadMesh

Loads a 3D mesh from GLB file with GPU instancing support and multi-material handling. Takes filename (path to .glb file), textureSlots (BBR_ONE_SLOT to BBR_FOUR_SLOT for material texture count), uvMode (BBR_NO_TEXTURE_UV or BBR_TEXTURE_UV for UV coordinates), unique (0 = enable instancing/caching, non-zero = force unique copy). Returns entity handle or 0 on failure. Validates parameters (textureSlots in range, uvMode valid). Checks mesh cache using key "filename|textureSlots|uvMode" - if found and unique=0, reuses cached mesh for GPU instancing (multiple entities share same GPU buffers). If not cached or unique=1, parses GLB with cgltf library. Loads buffers (vertex/index data). Processes all nodes recursively applying transforms (position, rotation, scale). Merges all primitives from all meshes into unified vertex/index buffers. Handles multi-material meshes via submeshes. Extracts vertex attributes: POSITION (required), NORMAL (optional, generated if missing), TEXCOORD_0 to TEXCOORD_3 (based on textureSlots), COLOR_0 (optional vertex colors). Converts indices to uint32_t. Creates D3D12 vertex/index buffers (DEFAULT heap). Uploads via intermediate UPLOAD heap. Creates SRV descriptors for shader access. Stores materials (baseColor, metallic, roughness, textures). Creates Mesh3D structure, stores in entity. Adds to cache if unique=0. Returns entity handle.

This is the primary mesh loading function - supports full glTF 2.0 specification. GPU instancing optimization: when unique=0, multiple LoadMesh calls for same file+config share GPU memory, but each returns separate entity handle with independent position/rotation/material overrides. Massive memory savings for forests, crowds, particles. TextureSlots determines vertex buffer layout: BBR_ONE_SLOT = UV0 only (single texture), BBR_TWO_SLOT = UV0+UV1 (base+normal/lightmap), BBR_THREE_SLOT = UV0+UV1+UV2 (triple texture blending), BBR_FOUR_SLOT = all UVs (max material complexity). UVMode BBR_TEXTURE_UV includes UV coordinates, BBR_NO_TEXTURE_UV excludes (for solid color meshes, reduces vertex size). Multi-material support: exports from Blender with multiple materials create submeshes, each with separate material index, all rendered in single draw call via instancing. Transform baking: node transforms applied to vertices during load, enabling parent/child hierarchies in modeling software to export as single mesh. Normal generation: if GLB lacks normals, calculates from face orientation (cross product). Coordinate system: glTF uses +Y up, +Z forward (matches BambooBasic). File size: binary GLB format (smaller than .obj+.mtl). Supports embedded textures or external references. Use unique=1 for meshes that will be deformed/edited (b3dUpdateMeshVertices). Common errors: file not found (returns 0), invalid GLB format (parse error), missing position attribute (required), GPU resource allocation failure (out of VRAM).