Creates a new empty surface on a mesh with independent vertex/index arrays and material.
Takes mesh (surface-based mesh entity from b3dCreateMesh).
Returns surface handle (0-based index) or -1 on failure.
3D Graphics
Parameters & Returns
Parameters
meshInt
Returns
Int
Quick Summary
Creates a new empty surface on a mesh with independent vertex/index arrays and material.
Takes mesh (surface-based mesh entity from b3dCreateMesh).
Returns surface handle (0-based index) or -1 on failure.
Technical Exegesis...
Creates a new empty surface on a mesh with independent vertex/index arrays and material. Takes mesh (surface-based mesh entity from b3dCreateMesh). Returns surface handle (0-based index) or -1 on failure. Validates mesh exists, type is ENTITY_MESH, and is surface-based. Creates default Material3D (white base color 1,1,1,1, metallic=0, roughness=1, no emissive, no textures, name="Default_Procedural"). Adds material to g_materials array. Creates new Surface3D structure. Assigns material index to surface.
Creates a new empty surface on a mesh with independent vertex/index arrays and material. Takes mesh (surface-based mesh entity from b3dCreateMesh). Returns surface handle (0-based index) or -1 on failure. Validates mesh exists, type is ENTITY_MESH, and is surface-based. Creates default Material3D (white base color 1,1,1,1, metallic=0, roughness=1, no emissive, no textures, name="Default_Procedural"). Adds material to g_materials array. Creates new Surface3D structure. Assigns material index to surface. Sets needsGPUUpload=true (flags for upload on next unlock). Appends surface to mesh->surfaces array. Sets mesh->needsGPUUpload=true. Returns surface index (surfaces.size()-1). Returns -1 if validation fails.
This function creates independent geometry groups within single mesh for multi-material or organizational purposes. Surface = subdivision of mesh with own vertex array, index array, and material - enables different textures/colors per surface while maintaining single entity. Each surface gets fresh default material - modify with material functions or texture assignment. Surface handle is 0-based index into surfaces array - first surface is 0, second is 1, etc. Use handle for b3dAddVertex, b3dAddTriangle, material assignment. Empty surface after creation - contains no vertices or triangles until added. Surface independence: vertices not shared between surfaces (each surface is self-contained geometry). Use cases: (1) Multi-material objects (character with skin/clothing/hair as separate surfaces), (2) Texture atlas baking (each surface gets atlas region), (3) Selective rendering (show/hide surfaces individually), (4) LOD switching (different detail levels as surfaces). Common workflow: mesh=b3dCreateMesh(...), surface0=b3dCreateSurface(mesh), surface1=b3dCreateSurface(mesh), build geometry in each surface, assign different materials/textures. Material creation: always creates new material (not shared) - safe to modify without affecting other surfaces. Surface count limited only by memory - can create dozens/hundreds for complex objects. Alternative: single surface for simple objects, loaded meshes (b3dLoadMesh) have surfaces from GLB file. Surface ordering affects rendering order within mesh. After adding surfaces, use b3dCountSurfaces to verify count, b3dGetSurface for iteration (note: GetSurface uses 1-based indexing for Blitz3D compatibility).