b3dLightShadowOrthoSize

Sets orthographic shadow map size for directional lights (controls shadow coverage area). Takes light (directional light handle), size (orthographic box half-size in world units). Returns nothing. Stores size in light->shadowOrthoSize field. Only works with directional lights (type 1).

This function configures shadow coverage. Orthographic shadows: directional lights use orthographic projection for shadow maps, orthographic box defines visible area for shadow rendering, size parameter = half-width of orthographic box (box is 2*size x 2*size), larger size = more area covered but lower shadow resolution per unit. Shadow map resolution: shadow map has fixed pixel resolution (e.g., 2048x2048), ortho size determines world units per pixel, small size = high detail shadows over small area, large size = low detail shadows over large area. Size tradeoff: too small = shadows cut off at edges (only small area visible), too large = pixelated shadows (stretched over large area), optimal = match scene size with acceptable resolution. Use cases: (1) Outdoor sunlight (large size 50-200 for terrain), (2) Indoor directional light (small size 10-30 for room), (3) Spotlight replacement (medium size 20-50 for stage), (4) Detail shadows (small size 5-10 for closeup objects), (5) Skylight (very large size 100-500 for open world). Common patterns: sun shadows = b3dLightShadowOrthoSize(sunLight, 100.0) for 200x200 unit area, room lighting = b3dLightShadowOrthoSize(dirLight, 20.0) for 40x40 unit room, dynamic size = adjust based on camera view (frustum-fitted shadows), LOD shadows = larger size for distant objects, smaller for near. Typical usage: call after b3dCreateLight(1) for directional light, set before enabling shadows with b3dLightCastShadow, adjust based on scene scale and desired quality, combine with shadow map resolution settings. Orthographic projection: shadow map renders from light's point of view, orthographic projection (no perspective, parallel rays), box centered on shadow camera position, size defines frustum extents (-size to +size on X and Z axes). Light type validation: function checks entity.type == ENTITY_LIGHT, prints error if not a light entity, no effect if invalid light handle, only affects directional lights (type 1), point/spot lights use different shadow projection. Shadow map frustum: orthoSize affects left/right/top/bottom frustum planes, near/far planes controlled separately (not by this function), frustum box moves with light position, rotates with light direction. Performance: larger ortho size = same shadow map resolution stretched over more area, no performance difference (same map size rendered), quality degrades with larger area (fewer pixels per world unit), smaller size = higher quality but limited coverage. Default value: if not set, uses default ortho size from light creation, typical default is 50.0 units (100x100 unit coverage), adjust based on scene requirements, no automatic adjustment (manual tuning required). Shadow clipping: objects outside ortho box don't cast shadows, shadows abruptly cut off at frustum edges, too small size causes visible clipping, too large size wastes resolution on empty space. Pixels per unit: shadow detail = shadow_map_resolution / (2 * orthoSize), example: 2048 map / (2 * 50) = 20.48 pixels per world unit, higher pixels/unit = sharper shadows, lower pixels/unit = softer/blurrier shadows. Common sizes: small room (10-20), medium area (30-60), large outdoor (80-150), massive terrain (200-500), match to gameplay area for best quality. Shadow cascades: BambooBasic doesn't use cascaded shadow maps, single ortho size for entire shadow map, advanced engines use multiple sizes for distance LOD, current implementation requires manual size tuning. Related shadow settings: b3dLightCastShadow enables shadow casting (on/off toggle), b3dLightShadowAlpha sets shadow darkness (0.0-1.0 opacity), b3dLightRange sets light influence distance (different from shadow range), b3dCreateLight(1) creates directional light (required for ortho shadows). Debugging tips: visualize shadow frustum in editor, check for shadow clipping at edges, increase size if shadows cut off, decrease size if pixelated, balance coverage vs quality, typical starting value = scene_bounding_box_size / 2. Light rotation: ortho box rotates with light direction, light rotation defines shadow projection direction, b3dRotateEntity(light, pitch, yaw, roll) aims shadows, ortho size remains constant regardless of rotation. Related: b3dCreateLight creates light entity (type 1 for directional), b3dLightCastShadow enables shadows (required for ortho size to matter), b3dLightShadowAlpha controls shadow opacity (darkness of shadows), b3dRotateEntity aims light direction (determines shadow angle).