b3dGetSurface

Returns surface handle by 1-based index (Blitz3D compatibility). Takes mesh (surface-based mesh entity), index (surface number, 1-based). Returns surface handle (0-based index) or -1 on error. Validates mesh exists, type is ENTITY_MESH, and is surface-based. Converts index from 1-based to 0-based (index-1). Validates converted index in range [0, surfaces.size()). Returns surfaceIndex (0-based) for use with other surface functions. Returns -1 if: invalid mesh handle, not a mesh, not surface-based, index out of range (index < 1 or index > surface count).

This function provides Blitz3D-compatible iteration interface for surface access. Blitz3D uses 1-based indexing (first surface is 1, second is 2, etc.) while internal storage uses 0-based C++ arrays (first surface is 0). GetSurface bridges this gap - accepts 1-based user index, returns 0-based handle for API calls. Common usage: iterate surfaces with For loop (For i=1 To b3dCountSurfaces(mesh), surface=b3dGetSurface(mesh, i), process surface). Return value -1 indicates error - always validate before using surface handle. Surface handle is index into mesh->surfaces array - valid until surface deleted or mesh freed. Use cases: (1) Surface iteration (iterate all surfaces for material assignment), (2) Index conversion (convert user-friendly 1-based to API 0-based), (3) Validation (check surface exists before operations). Common pattern: count=b3dCountSurfaces(mesh), For i=1 To count, surf=b3dGetSurface(mesh, i), If surf >= 0 Then process. Indexing comparison: CreateSurface returns 0-based handle directly (first=0), GetSurface expects 1-based parameter (first=1), internal operations use 0-based (AddVertex, AddTriangle take 0-based surface handle). Why 1-based: Blitz3D legacy compatibility - original Blitz3D used 1-based arrays, BambooBasic maintains API compatibility while using 0-based internally. Alternative: track surface handles from CreateSurface return values, avoid iteration if handles stored. Fast operation - simple bounds check and subtraction. No GPU impact - pure CPU array index conversion.