b3dGetBaseTexture

Retrieves the base color texture handle from an entity's material. Takes entityHandle (mesh, terrain, or other entity with material). Returns texture handle (non-negative integer) or -1 on failure. Validates entity exists. Determines entity type (ENTITY_MESH, ENTITY_TERRAIN, etc.). For meshes: if surface-based, gets material from first surface (surfaces[0].materialIndex); otherwise gets material from mesh->materialIndex. For terrain: gets material from terrain data. Looks up material in g_materials array. Returns material.baseColorTextureIndex (index into g_textures). Returns -1 if: invalid entity handle, entity has no mesh/terrain, no material assigned, material has no base texture (solid color only). Texture handle can be used with b3dTextureToImage for pixel editing.

This function accesses material system for texture retrieval. Base color texture = diffuse map in traditional rendering, albedo in PBR. Material structure contains: baseColorTextureIndex (int), metallicTextureIndex, roughnessTextureIndex, normalTextureIndex, baseColorFactor (solid color tint). If material uses solid color only (no texture), baseColorTextureIndex = -1, this function returns -1. Multi-material meshes (surface-based with multiple surfaces): only returns first surface's texture - use material override functions for per-surface access. Use cases: (1) Read texture with b3dTextureToImage, (2) Modify pixels (recolor, add decals), (3) Upload with b3dImageToTexture, (4) Re-assign with b3dSetEntityBaseTexture. Common pattern: texHandle = b3dGetBaseTexture(entity), img = b3dTextureToImage(texHandle), b2dDrawToRenderTarget(img, ...), newTex = b3dImageToTexture(img), b3dSetEntityBaseTexture(entity, newTex). Texture handles persistent - safe to cache. Textures shared across entities (GPU instancing) - modifying texture affects all entities using it. For entity-specific texture changes, clone texture first or use unique mesh. Alternative: use material system directly for more control (access metallic/roughness/normal maps).