b3dSetEntityBaseTexture

Sets entity base color texture (diffuse/albedo map, multiplied with baseColorFactor). Takes entityHandle (mesh/terrain entity handle), textureHandle (texture handle from b3dLoadTexture3D). Returns nothing. Updates material.baseColorTextureIndex to textureHandle, texture sampled in shader and multiplied with baseColorFactor (finalColor = texture * factor). Mesh and terrain entities only.

This function sets base texture. Texture application: base color texture is primary albedo/diffuse map (defines surface color pattern), sampled in pixel shader and multiplied with baseColorFactor (if factor is white 1,1,1 texture shown as-is, if factor is red 1,0,0 texture tinted red, allows color variation without multiple textures). Material handling: surface-based meshes (procedural shapes) update all surface materials directly (each surface gets same texture), loaded meshes (GLB models) update mesh.materialIndex material (single material for entire mesh, use b3dCloneEntityMaterial first if mesh is shared), terrain entities update terrain.materialIndex material. Use cases: (1) Model texturing (apply diffuse maps to characters, vehicles, buildings), (2) Terrain texturing (apply ground/rock/grass textures to terrain), (3) Dynamic texture swapping (change textures at runtime for variety), (4) Damage states (swap to damaged texture when hit), (5) Team colors (swap texture based on player team). Common patterns: apply texture b3dSetEntityBaseTexture(entity, texHandle), swap texture b3dSetEntityBaseTexture(entity, damagedTex), tint textured model b3dSetEntityBaseTexture(entity, tex) then b3dSetEntityColorFX(entity, 255, 128, 128) for red tint. Typical usage: set after creating entity to apply visual appearance, swap textures for dynamic variety (different skins on same model), combine with baseColorFactor for tinting (texture * tint color). PBR baseColorTexture: stores albedo color (diffuse reflection color, what color surface is), RGB channels used (alpha channel used for transparency if blendMode enabled), multiplied with baseColorFactor in shader (finalBaseColor = textureSample(baseColorTexture) * baseColorFactor). Shared mesh warning: if entity shares mesh with others (GLB instances) changing texture affects ALL instances, use b3dCloneEntityMaterial first to make texture change per-entity (clones mesh + material for independent modification), procedural shapes (b3dCreateCube, etc.) don't share materials (each has own material automatically). Texture handle: must be valid handle from b3dLoadTexture3D (0 is default white texture, negative or >= g_textures.size() causes error), handle is array index into g_textures (not SRV heap index). Default texture: if never called or textureHandle=0 uses default white 1x1 texture (baseColorFactor becomes dominant color source). Material index storage: baseColorTextureIndex stored as texture handle (g_textures array index), shader converts to SRV heap index via g_textures[handle].srvHeapIndex for sampling. Terrain support: works for terrain entities (entity.type == ENTITY_TERRAIN), applies texture to entire terrain (future: multi-texture terrain blending). Performance: O(1) for loaded mesh or terrain (single material update), O(N) for procedural mesh with N surfaces (all surfaces updated). Validation: prints error if invalid entity handle, invalid texture handle, entity is not mesh or terrain, mesh/terrain has no material. Related: b3dLoadTexture3D loads textures (provides textureHandle), b3dSetEntityColorFX sets baseColorFactor (multiplied with texture), b3dCloneEntityMaterial clones material for per-entity textures, b3dSetEntityDetailTexture adds detail layers on top of base.