b3dCreateTerrain

Creates terrain entity from heightmap with 5 LOD levels (GPU tessellation, geometry-based LOD). Takes heightmapPath (path to heightmap image file, white=high black=low), gridResolution (base grid resolution 4-256, default 64). Returns entity handle (terrain entity, 0 if failed). Loads heightmap to CPU and GPU, creates 5 LOD meshes (full, 1/2, 1/4, 1/8, 1/16 resolution), uploads R32_FLOAT texture for GPU sampling. Use for large outdoor environments, realistic terrain rendering, physics-compatible height fields.

This function creates terrain entity. Heightmap loading: loads heightmap image (PNG, JPG, BMP supported, grayscale recommended), normalizes to 0.0-1.0 range (0=black=low, 1=white=high), stores CPU copy for physics and queries (heightSamples vector float array), uploads to GPU as R32_FLOAT texture (pixel shader samples for smooth interpolation). Grid resolution: base resolution 4-256 (clamped, default 64 if out of range), defines highest LOD geometry (LOD 0 full resolution, LOD 1 half, LOD 2 quarter, etc.), typical values (64 for small terrain, 128 for medium, 256 for large), higher resolution = more triangles but smoother. LOD system: creates 5 LOD levels automatically (LOD 0=gridResolution, LOD 1=gridRes/2, LOD 2=gridRes/4, LOD 3=gridRes/8, LOD 4=gridRes/16 or min 8x8), geometry-based LOD (different meshes per distance, not GPU tessellation), default distances (0-50, 50-100, 100-150, 150-200, 200+), configurable via b3dSetTerrainLOD. Entity-based terrain: returns entity handle (ENTITY_TERRAIN type, integrates with entity system), supports position/rotation/scale (entity.position/rotation/scale transform terrain), uses material system (assign textures via b3dEntityTexture, supports PBR materials), visible/parent hierarchy (entity.visible, parenting supported like meshes). Use cases: (1) Outdoor environments (large landscapes, mountains, valleys), (2) Game levels (terrain-based maps, natural environments), (3) Flight simulators (rolling terrain, varied elevation), (4) Racing games (tracks with elevation, off-road terrain), (5) Open world (exploration, dynamic terrain features). Common usage: create terrain terrain = b3dCreateTerrain("heightmap.png", 128), set LOD b3dSetTerrainLOD(terrain, 50, 100, 150, 200), add physics b3dCreateTerrainPhysics(terrain), texture b3dEntityTexture(terrain, grassTex).

Heightmap format: inverted internally (1.0 - height for GPU shader, white=high after inversion), R32_FLOAT GPU texture (single-channel float, high precision for smooth sampling), bilinear filtering (GPU samples between pixels, smooth interpolation), supports any image format (PNG, JPG, BMP, converted to grayscale 0-1 range). Grid mesh: base grid vertices (gridResolution x gridResolution vertices, XZ plane grid), height displacement (GPU samples heightmap texture, displaces Y in vertex shader), indexed triangles (triangle strip or indexed list, optimized for GPU). LOD creation: LOD 0 full resolution (gridResolution, highest detail near camera), LOD 1-4 progressively lower (half resolution each level, fewer triangles further away), automatic generation (all LODs created at load time, stored in lodLevels array), minimum 8x8 grid (stops halving when reaches 8, LOD 4 minimum size). Texture coordinates: UV 0-1 mapped to terrain (0,0 = corner, 1,1 = opposite corner), uvScale multiplier (configurable via b3dSetTerrainDetail, tiles texture), entity texture (use b3dEntityTexture to assign base texture, supports detail layers). Terrain scale: terrainScale internal (separate from entity scale, stored in Terrain3D struct), default (1, 1, 1) for 1:1 mapping, entity scale separate (entity.scale multiplies final size, scales both XZ and Y). Material system: materialIndex for PBR (same as meshes, supports albedo/normal/roughness/metallic), default material 0 (white, non-metallic, rough surface), assign via material system (or use entity texture for basic texturing).

Default LOD distances: LOD 0 0-50 units (highest detail, near camera), LOD 1 50-100 units (half resolution), LOD 2 100-150 units (quarter resolution), LOD 3 150-200 units (eighth resolution), LOD 4 200+ units (minimum resolution, far background), reconfigurable (call b3dSetTerrainLOD to change thresholds). Distance-based LOD selection: calculates camera distance (distance from camera to terrain center), selects LOD level (compare distance to lodDistances thresholds), renders appropriate mesh (different index/vertex buffers per LOD), smooth transitions (LODs change based on distance, no pop-in if thresholds reasonable). GPU rendering: heightmap texture sampled (pixel shader reads R32_FLOAT texture, interpolates height), vertex displacement (vertex shader applies height from texture sample), normal calculation (shader calculates normals from heightmap gradients), PBR shading (standard PBR material system, lighting and shadows). Coordinate system: XZ horizontal plane (X = east-west, Z = north-south), Y vertical (height from heightmap, upward positive), entity position (terrain positioned at entity.position, entity.position.Y = base height). Height range: 0-1 normalized (heightmap values 0.0 to 1.0 after load), scaled by entity scale Y (final height = heightValue * entity.scale.Y * terrainScale.Y), typical setup (entity scale Y = 100 for 0-100 unit height range).

Physics integration: create physics with b3dCreateTerrainPhysics (separate call after terrain creation), uses Jolt HeightFieldShape (optimized for terrain, much faster than mesh collision), static body (terrain doesn't move, efficient collision detection). Height queries: use b3dTerrainHeight (query height at world X/Z position, bilinear interpolation), useful for placing objects (spawn objects on terrain surface, character ground placement), AI pathfinding (query terrain height for navigation, obstacle avoidance). Texture tiling: use b3dSetTerrainDetail (sets uvScale, multiplies texture coordinates), higher scale = more tiling (uvScale 10 = texture repeats 10 times across terrain), prevents stretching (large terrain with small texture, tiling avoids blurry stretching). Entity operations: position b3dPositionEntity (move terrain anywhere in world, terrain.position offset), scale b3dScaleEntity (resize terrain, both horizontal and vertical), rotate b3dRotateEntity (rotate terrain, unusual but supported), visibility b3dHideEntity/ShowEntity (toggle terrain rendering). Memory usage: heightmap CPU storage (width * height * 4 bytes float array, e.g., 1024x1024 = 4MB), heightmap GPU texture (R32_FLOAT, same size as CPU, 4MB for 1024x1024), LOD meshes (5 levels, vertices+indices, depends on gridResolution), total memory (10-50MB typical for 1024x1024 heightmap with 128 grid resolution).

Grid resolution tradeoffs: low resolution (4-32, very blocky, fast rendering but poor quality), medium resolution (64-128, balanced, smooth enough for most games), high resolution (256, very smooth, more triangles but still efficient with LOD), typical choice (64-128 for games, 256 for high-quality or close-up terrain). Heightmap size: any size supported (128x128, 512x512, 1024x1024, 2048x2048, etc.), larger = more detail (finer height variations, smoother interpolation), performance (GPU samples texture, size doesn't significantly affect framerate), typical sizes (512x512 or 1024x1024 for games). Loading performance: one-time cost (load and process heightmap at creation, not per-frame), CPU processing (load image, normalize, convert to float array), GPU upload (copy to texture, create SRV, synchronous wait), typical load time (10-100ms for 1024x1024 heightmap, acceptable for level load). Rendering performance: LOD system efficient (only one LOD rendered per terrain, distance-based selection), far terrain low cost (LOD 4 only 8x8 grid = 128 triangles, very cheap), near terrain moderate cost (LOD 0 might be 128x128 = 32K triangles, manageable), typical framerate (60+ FPS with multiple terrains, LOD keeps cost low).

Multiple terrains: create multiple terrains (each terrain separate entity, independent heightmaps and LODs), tile terrains (position terrains adjacent, create large continuous world), different heights/scales (vary entity scale for mountains vs plains), independent textures (each terrain has own texture via b3dEntityTexture). Terrain transforms: position (entity.position moves terrain origin, heightmap relative to position), scale (entity.scale.X/Z stretches horizontal, entity.scale.Y stretches vertical height), rotation (entity.rotation rotates terrain, unusual but works, affects physics). Failure cases: returns 0 if heightmap load fails (invalid path, unsupported format, file not found), returns 0 if device not ready (3D system not initialized, no GPU device), returns 0 if LOD creation fails (out of memory, GPU resource allocation failed), check return value (If terrain = 0 Then error, handle failure). Validation: gridResolution clamped 4-256 (default 64 if out of range, user doesn't need to validate), heightmap path relative or absolute (supports both, searches asset paths), silent failure (returns 0 on error, no exceptions or crashes).

Related: b3dSetTerrainLOD sets LOD distance thresholds (configure when each LOD level activates, distances in world units), b3dSetTerrainDetail sets texture UV scale (controls texture tiling, prevents stretching), b3dCreateTerrainPhysics creates Jolt physics (HeightFieldShape for efficient collision, static body), b3dTerrainHeight queries height (gets height at world X/Z, bilinear interpolation), b3dEntityTexture assigns texture (base texture for terrain, supports detail layers), b3dPositionEntity/ScaleEntity/RotateEntity transform terrain (entity-based transforms, position/scale/rotation).