b3dSubdivideMesh

Subdivides mesh triangles by splitting edges and creating midpoint vertices, optionally applying smoothing. Takes mesh (surface-based mesh entity), iterations (number of subdivision passes, 1+), smooth (0=no smoothing, 1=apply smoothing), smoothFactor (0.0-1.0, smoothing strength when smooth=1, ignored when smooth=0). Returns nothing. Validates mesh exists, type is ENTITY_MESH, surface-based, and locked. Clamps iterations to minimum 1. Clamps smoothFactor to 0.0-1.0 range. For each iteration, processes each surface independently. Builds edge map (maps edge (v0,v1) to midpoint vertex index). Edge key normalized (smaller index first) so (0,1) and (1,0) map to same edge. For each edge encountered, creates midpoint vertex if not exists: position = average of endpoints, normal = normalized average, texCoord = average, color = average. For each original triangle (v0,v1,v2), creates 4 new triangles: (v0,m01,m02), (m01,v1,m12), (m02,m12,v2), (m01,m12,m02) where m01=midpoint of edge v0-v1. Replaces surface indices with subdivided triangles. Each iteration quadruples triangle count (1 tri -> 4 tris -> 16 tris -> 64 tris...). If smooth=1, applies Laplacian smoothing pass after all subdivision iterations: builds vertex adjacency map from triangles, calculates average position of each vertex's neighbors, blends original position with neighbor average using smoothFactor (smoothFactor=0.0 means 100% original position, smoothFactor=0.5 means 50% original/50% neighbors, smoothFactor=1.0 means 100% neighbor average). Silently returns on errors.

This function increases mesh resolution for smoother surfaces or LOD generation. Subdivision splits each triangle into 4 smaller triangles by adding vertices at edge midpoints. Iteration count controls refinement level: 1 iteration = 4x triangles, 2 iterations = 16x, 3 iterations = 64x, 4 iterations = 256x. Memory explodes quickly - use conservatively. The smooth parameter controls post-subdivision behavior: smooth=0 preserves original shape (linear subdivision, just adds detail while maintaining blocky appearance - good for hard-surface models or when original shape is already round), smooth=1 rounds out geometry via Laplacian smoothing (moves vertices toward neighbor averages to create softer, rounder shapes - turns low-poly sphere into smooth sphere, turns cube into rounded cube). The smoothFactor parameter (0.0-1.0) controls smoothing strength when smooth=1: smoothFactor=0.0 applies no smoothing (same as smooth=0), smoothFactor=0.3 applies subtle smoothing (slightly rounds edges), smoothFactor=0.5 applies medium smoothing (balanced between original and smooth), smoothFactor=1.0 applies maximum smoothing (fully rounds geometry). Use cases: (1) Smooth low-poly meshes (icosphere subdivision with smooth=1, smoothFactor=0.5 for round spheres), (2) Displacement mapping setup (need dense mesh for vertex displacement, use smooth=0 to preserve base shape), (3) Adaptive LOD (subdivide based on distance to camera, smooth=1 with varying smoothFactor for organic models), (4) Hard-surface modeling (mechanical parts with smooth=0 to keep crisp edges, or smooth=1 with low smoothFactor=0.2 for beveled edges), (5) Sculpting/deformation (need vertex density for detail, smooth=1 with smoothFactor=0.5 for organic forms). Edge midpoint calculation: simple linear interpolation for all attributes (position, normal, UV, color). Normal re-normalized after averaging (prevents shrinkage). UV interpolation enables texture continuity across subdivision. Triangle splitting pattern: original vertices at corners, midpoints on edges, center triangle connects three midpoints - creates regular subdivision. Must lock mesh before calling. After subdivision, unlock to upload. Triangle count growth: original x 4^iterations. Vertex count growth: slower than triangles (vertices shared between triangles). Performance impact: 1000 tris -> 4000 tris = 4x rendering cost, 1000 tris -> 64000 tris (3 iterations) = 64x cost. Smoothing adds minimal overhead (single pass after subdivision). Common workflow: Create low-poly sphere (20 tris), subdivide 2 times with smooth=1 and smoothFactor=0.5 (320 tris, rounder), apply vertex noise for organic planet. Alternative: use b3dCreateSphere with higher segment count instead of subdividing, procedurally generate detailed meshes directly, LOD via distance-based mesh swapping. Edge map prevents duplicate midpoints - each edge creates single shared vertex. Subdivision maintains topology (no holes created). Surface boundaries remain smooth. Typical smoothFactor values: 0.2-0.3 (subtle rounding), 0.5 (balanced smoothing), 0.7-1.0 (aggressive smoothing).