b3dFreeBrush

Frees brush and reclaims handle for reuse (clears data, marks invalid, adds to free list). Takes brushHandle (brush handle to free). Returns nothing. Validates brush handle and checks not already freed (textureIndex=-2), resets brush to default state (Brush3D()), sets textureIndex=-2 (invalid marker), adds handle to g_freeBrushHandles for reuse by b3dCreateBrush. Properly frees brush resources and enables handle recycling.

This function frees brush and makes handle available for reuse. Freeing behavior: (1) Resets brush to default state (clears all properties), (2) Marks as freed (textureIndex=-2 sentinel), (3) Adds handle to free list (g_freeBrushHandles stack for reuse). Memory management: brush data cleared (releases any resources), handle slot remains in g_brushes but available for reuse, prevents memory waste from abandoned handles. Handle reuse: freed handles recycled by b3dCreateBrush (pops from g_freeBrushHandles, reuses slot), prevents handle exhaustion in dynamic brush creation/deletion scenarios. Double-free protection: checks if already freed (textureIndex=-2), silently returns if already freed (safe to call multiple times). Use cases: (1) Dynamic brush creation/deletion (temporary brushes for effects), (2) Brush pooling (create/use/free pattern in loops), (3) Memory management (cleanup after material generation), (4) Long-running applications (prevent handle exhaustion). Common pattern: brush=b3dCreateBrush(), configure and use brush, b3dFreeBrush(brush), handle becomes available for next b3dCreateBrush call. Painted surfaces: materials created from brush before freeing remain valid (materials are independent copies), freeing brush doesn't affect already-painted surfaces. Safe to free immediately after b3dPaintSurface. Validation: brush property setters (b3dBrushColor, etc.) should check handle validity, freed brushes rejected (textureIndex=-2 or out of range). Free list implementation: uses vector as stack (push_back on free, pop_back on create), LIFO order (last freed first reused), efficient O(1) operations. Handle lifecycle: create (gets new or reused handle) -> configure (set properties) -> paint (apply to surfaces) -> free (reclaim handle) -> reuse (next create). Memory efficiency: no memory leak from dynamic brush usage, handles recycled indefinitely, g_brushes size bounded by peak concurrent brush count (not total created count). Typical usage: free brushes when done, safe for dynamic creation/deletion patterns, handles automatically recycled for efficiency. Related: b3dCreateBrush creates brush and reuses freed handles, b3dPaintSurface uses brush before freeing (materials persist after free).