b3dPaintSurface

Applies brush to surface (creates material from brush properties, assigns to surface, sets blend mode). Takes meshEntityHandle (mesh entity), surfaceHandle (0-based surface index), brushHandle (brush handle). Returns nothing. Validates all handles and mesh is surface-based, creates new Material3D from brush properties (baseColorFactor, metallicFactor, roughnessFactor, textureIndex), determines blend mode (0=solid if alpha=1.0, 1=alpha blend if alpha<1.0), adds material to global g_materials, assigns material index to surface, sets mesh.needsGPUUpload flag for buffer recreation.

This function instantiates brush template as concrete material on surface. Painting process: (1) Validates mesh is surface-based (isSurfaceBased=true), loaded meshes rejected. (2) Validates surface exists (surfaceHandle 0-based, < surfaces.size()). (3) Creates new material copying brush properties. (4) Auto-determines blend mode from alpha. (5) Adds material to global list, gets material index. (6) Assigns material index to surface. (7) Flags mesh for GPU upload. Material creation: new Material3D instance created per paint operation (brush is template, each paint creates unique material), allows different surfaces to have independent materials even from same brush. Blend mode logic: if brush alpha < 1.0 sets blendMode=1 (alpha blend, transparency), if brush alpha=1.0 sets blendMode=0 (solid, opaque). Automatic determination simplifies API. Surface handle: 0-based index (not handle from b3dGetSurface which is 1-based), directly indexes into mesh->surfaces array. Use cases: (1) Multi-material meshes (different brush per surface), (2) Procedural texturing (paint surfaces at runtime), (3) Material swapping (repaint surfaces dynamically), (4) Level-of-detail materials (different materials for distance), (5) Dynamic appearance (weather, damage effects). Common pattern: mesh=b3dCreateMesh(...), surf0=b3dCreateSurface(mesh), brush=b3dCreateBrush(), b3dBrushColor(brush, 255, 0, 0), b3dPaintSurface(mesh, surf0, brush), paints first surface red. Requirements: mesh must be surface-based (created with b3dCreateMesh or procedural primitives), loaded meshes (b3dLoadMesh) not supported for painting. Surface must exist (created with b3dCreateSurface). Brush must be valid. Material lifetime: materials persist in g_materials (no automatic cleanup), repainting creates new material (old material orphaned if not referenced elsewhere). GPU upload: needsGPUUpload flag triggers RebuildGPUBuffersFromSurfaces at safe point (deferred GPU resource update). Brush reuse: same brush can paint multiple surfaces, each gets independent material copy. Property independence: after painting, changing brush properties doesn't affect already-painted surfaces (material is snapshot). Related: b3dCreateBrush creates brush template, b3dBrushColor/Texture/Shininess/Metallic/Alpha configure brush, b3dCreateSurface creates paintable surface, b3dCreateMesh creates surface-based mesh.