b3dCreateBrush

Creates a new brush (material template) and returns brush handle for property configuration. Takes no parameters. Returns brush handle (0-based index into brush array). Checks if freed handles available in g_freeBrushHandles (reuses freed slot if available), otherwise creates new Brush3D structure with default properties, adds to global g_brushes array, returns array index as handle. Brushes are reusable material templates configured with color, texture, shininess, metallic properties, then applied to surfaces via b3dPaintSurface.

This function initializes a material template for painting procedural surfaces. Brush system: inspired by Blitz3D, brushes are material templates that store color/texture/PBR properties, created once, configured with property setters, applied to multiple surfaces via b3dPaintSurface. Workflow: (1) Create brush with b3dCreateBrush, (2) Configure properties (b3dBrushColor, b3dBrushTexture, b3dBrushShininess, b3dBrushMetallic, b3dBrushAlpha), (3) Apply to surfaces with b3dPaintSurface, (4) Optional: reuse same brush for multiple surfaces, (5) Free with b3dFreeBrush when done. Default properties: baseColorFactor = white (1,1,1,1), metallicFactor = 0.0 (non-metallic), roughnessFactor = 1.0 (rough), textureIndex = -1 (no texture). Brush handle: 0-based index into g_brushes array. Handle reuse: freed handles added to g_freeBrushHandles stack, b3dCreateBrush reuses freed slots before allocating new (prevents handle exhaustion, memory-efficient). Handle persistence: valid until freed with b3dFreeBrush or application exit. Use cases: (1) Procedural mesh texturing (apply materials to surface-based meshes), (2) Multi-material meshes (different brush per surface), (3) Dynamic material swapping (create brushes, paint surfaces at runtime), (4) Material reuse (one brush applied to many surfaces), (5) PBR material setup (metallic/roughness workflow). Common pattern: brush=b3dCreateBrush(), b3dBrushColor(brush, 200, 50, 50), b3dBrushTexture(brush, tex), b3dBrushMetallic(brush, 0.8), b3dPaintSurface(mesh, 0, brush), creates metallic red textured material. Brush vs material: brush is template (lightweight, reusable), material is concrete instance (created during b3dPaintSurface, assigned to surface). Multiple surfaces can share brush but each gets unique material. Property modification: change brush properties after creation, changes affect next b3dPaintSurface call only (not previously painted surfaces). Storage: brushes stored in global g_brushes vector, freed handles tracked in g_freeBrushHandles for reuse. No hard limit on brush count. Handle validity: invalid handles (negative or >= size) ignored by property setters. Freeing: b3dFreeBrush clears brush data, marks invalid, adds handle to free list for reuse (efficient memory management). Alternative: directly create materials and assign to surfaces (lower-level, no brush abstraction). Typical usage: create brushes as needed, configure, use, free when done (handles automatically reused).