b3dSaveSceneGLB

Exports entire 3D scene to GLB file (binary GLTF format with hierarchy). Takes filename (output GLB file path). Returns 1 on success, 0 on failure. Collects all active visible mesh entities, builds node tree with parent-child hierarchy, exports geometry/materials/textures to GLB.

This function exports scenes. GLB format: binary GLTF (GL Transmission Format), industry standard for 3D model exchange, single file containing geometry + materials + textures, supports hierarchy (parent-child transforms), widely supported by Blender, Unity, Unreal, web viewers. Export process: (1) collects all active entities as scene nodes, (2) builds hierarchy tree with parent-child relationships, (3) extracts mesh geometry (vertices, indices, submeshes), (4) collects materials and textures, (5) reads textures from GPU memory, (6) encodes textures as PNG, (7) writes GLTF JSON + binary buffer to GLB file. Entity collection: iterates all active entities via g_activeHandlesList, includes all entity types (mesh, pivot, light, camera), only mesh entities contribute geometry, non-mesh entities included as empty nodes (for hierarchy), entity.visible flag filters geometry (invisible meshes excluded from export). Hierarchy preservation: exports parent-child relationships, each node stores position/rotation/scale, parent-child links maintained via parentHandle/childHandles, hierarchy structure preserved in GLTF node tree, root nodes (no parent) added to scene root. Mesh export: exports entity mesh geometry (vertices, indices), supports surface-based meshes (b3dCreateCube, b3dCreateSphere), supports loaded meshes (b3dLoadMesh from GLB/GLTF), handles submeshes with different materials, applies entity transforms (position/rotation/scale), negates Y and Z coordinates for GLTF right-handed system. Material export: collects unique materials from all meshes, exports base color, metallic, roughness, normal maps, material override per-entity supported (materialOverrideIndex), creates GLTF materials with PBR properties, references textures by index in GLTF material. Texture export: reads textures from GPU memory via ReadTextureFromGPU, converts RGBA8 pixel data to PNG format (stbi_write_png), embeds PNG data in GLB binary buffer, creates GLTF texture + image + sampler entries, deduplicates textures (same texture used by multiple materials only exported once). Use cases: (1) Level export (save constructed level for editing in Blender), (2) Asset pipeline (export from runtime to DCC tools), (3) Backup/versioning (save scene state to disk), (4) Collaboration (share scenes with artists/designers), (5) Web preview (export for web-based GLTF viewers). Common patterns: level save = b3dSaveSceneGLB("levels/level1.glb") after level construction, editor export = save button triggers b3dSaveSceneGLB(userPath), backup = if autosaveTimer > 300 then b3dSaveSceneGLB("autosave.glb"), asset extraction = load mesh, modify, export modified version. Typical usage: call after scene setup to save snapshot, use in level editor for asset export, combine with b3dLoadMesh to round-trip (export -> edit in Blender -> reimport), validate export by loading GLB in external viewer (Blender, online viewer). Error handling: returns 0 if no active entities in scene (empty scene), returns 0 if file creation fails (bad path, permissions), returns 1 on successful export, prints error to std::cerr with details, DEBUG_COUT shows export statistics (nodes, meshes, vertices, triangles). Coordinate system conversion: BambooBasic uses left-handed Y-up, GLTF uses right-handed Y-up, export negates Y and Z coordinates for vertices/normals/tangents, preserves hierarchy transforms (exported as-is), imported GLB files can be re-exported (round-trip compatible). Entity naming: exports entity.name if set (via b3dNameEntity), falls back to "Entity_<handle>" if unnamed, names help identify nodes in external editors, preserves naming conventions for collaboration. Geometry details: exports vertex positions (XMFLOAT3), normals (XMFLOAT3), texture coordinates (XMFLOAT2), tangents (XMFLOAT4), exports triangle indices (uint32_t), supports both 16-bit and 32-bit indices (converted to 32-bit for GLTF). Material properties: exports baseColorFactor (RGBA), metallicFactor (0.0-1.0), roughnessFactor (0.0-1.0), baseColorTexture, metallicRoughnessTexture, normalTexture, uses default values if not set (white base color, 0.0 metallic, 1.0 roughness). Texture format: reads RGBA8_UNORM or BGRA8_UNORM from GPU, converts BGRA to RGBA if needed, encodes as PNG (lossless compression), embeds PNG in GLB binary buffer, GLTF references buffer offsets for textures. Performance: O(n) where n = entity count + mesh vertices + textures, GPU readback is synchronous (waits for GPU to finish), texture encoding is CPU-bound (PNG compression), can be slow for large scenes (thousands of entities, large textures). Scene complexity: handles scenes with 100s-1000s of entities, exports millions of vertices if needed, texture count limited by memory (each texture read from GPU), materials deduplicated (shared materials exported once). Submesh support: exports meshes with multiple submeshes, each submesh becomes GLTF primitive with own material, submesh index ranges preserved, useful for multi-material models. Invisible entities: entities with visible=false excluded from geometry export, still included as nodes for hierarchy, allows exporting hierarchy without rendering all meshes, useful for LOD groups or hidden reference geometry. File size: GLB file size = JSON metadata + binary buffer, binary buffer = vertices + indices + textures (PNG compressed), texture compression significant (PNG reduces RGBA8 size), typical scene: 10MB for 100K verts + 2K textures. Validation: exported GLB should load in Blender without errors, hierarchy should match runtime scene structure, materials should preserve PBR properties, textures should appear correctly, round-trip test: export -> import -> export should produce identical results (within floating point precision). Limitations: only exports mesh entities (no lights, cameras, physics in GLTF), no animation export (static scene snapshot only), no vertex colors export (GLTF supports, not implemented), no morph targets (blend shapes), no skin/skeleton export (animated meshes exported as static). Comparison to b3dSaveMeshGLB: b3dSaveMeshGLB exports single mesh entity (no hierarchy), b3dSaveSceneGLB exports entire scene with hierarchy, scene export includes all entities and relationships, mesh export for individual asset extraction, use scene export for levels, mesh export for props. GLTF node structure: nodes contain transform (position/rotation/scale), nodes reference meshes (geometry), nodes reference children (hierarchy), root nodes listed in scene.nodes array, hierarchy traversed depth-first for rendering. Binary buffer layout: sequential binary data (vertices, indices, textures), GLTF JSON references buffer offsets (byteOffset + byteLength), accessors define data interpretation (type, component type, count), buffer views define memory slices. Related export: b3dSaveMeshGLB exports single mesh entity (individual asset), b3dSaveMeshOBJ exports mesh as OBJ (legacy format, no PBR), b3dLoadMesh loads GLB/GLTF (import counterpart), b3dSaveImage saves texture to file (individual texture export). Related: b3dLoadMesh loads GLB/GLTF files (import counterpart), b3dSaveMeshGLB exports single mesh (not entire scene), b3dNameEntity sets entity name (preserved in export), b3dSetEntityVisible controls geometry export (invisible excluded).