b3dLoadQuadRayMesh

Loads mesh and marks as quad ray source (creates volumetric light rays, renders WHITE in occlusion pass). Takes filename (mesh path, .glb/.gltf/.obj/.fbx formats). Returns entity handle (quad ray source entity, 0 if failed). Calls b3dLoadMesh internally (BBR_ONE_SLOT slot, BBR_NO_TEXTURE_UV no UV mapping, shared mesh buffer), marks entity.isQuadRaySource = true (invisible in main scene, renders WHITE in occlusion pass), initializes radiance fields (quadRayRadianceStart/End = 0.0 disabled, quadRayRadianceLevel = 1.0). Use for volumetric light effects (god rays, sunlight beams, flashlight cones), atmospheric lighting (fog rays, dust particles illuminated), or dramatic lighting (searchlights, stage lights). Quad ray source mesh defines light shape (sphere = omnidirectional rays, cone = spotlight rays, plane = directional sun rays), rendered WHITE in occlusion pass (creates white silhouette, post-processing traces rays from white pixels), invisible in main scene (doesn't render normally, only affects quad ray effect). Radiance effect: screen brightening when camera near source (startRadiance distance begins effect, endRadiance distance full effect, riseLevel brightness multiplier 1.0-3.0). Typical workflow: load quad ray mesh (this function), position/rotate source (b3dPositionEntity/b3dRotateEntity), configure fade distance (b3dSetQuadRayFadeDistance), configure radiance (b3dSetQuadRayRadianceDistance), configure direction/spread (b3dSetQuadRayDirection/b3dSetQuadRaySpreadFactor), enable quad rays system (b3dEnableQuadRays true), configure global settings (intensity/decay/samples/length via b3dSetQuadRays functions).

Quad ray source mesh: mesh shape defines ray casting geometry (sphere for sun/moon omnidirectional, cone for spotlights/flashlights, plane/rectangle for windows/doors directional), mesh scale affects ray volume (larger mesh = wider ray cone, smaller mesh = narrow focused rays), mesh position is ray origin (rays cast from mesh pixels in occlusion pass). Occlusion pass rendering: quad ray sources rendered WHITE to R8_UNORM occlusion texture (1024x576 or screen resolution), all other geometry rendered BLACK (blocks rays, creates shadows), post-processing shader traces rays from white pixels (reads occlusion texture, samples along ray path, accumulates light). Radiance fields initialization: quadRayRadianceStart = 0.0 (distance where screen brightening begins, 0 = disabled), quadRayRadianceEnd = 0.0 (distance where full brightness reached, 0 = disabled), quadRayRadianceLevel = 1.0 (brightness multiplier, 1.0 = no brightening). Use b3dSetQuadRayRadianceDistance to configure (startRadiance distance, endRadiance distance, riseLevel multiplier 1.0-3.0 typical).

Mesh loading parameters: BBR_ONE_SLOT = one material slot (minimal materials, quad ray source doesn't need textures), BBR_NO_TEXTURE_UV = no UV mapping (UV coordinates ignored, not needed for occlusion silhouette), shared mesh buffer (mesh geometry cached, reused by all instances). Mesh file formats: .glb/.gltf (preferred, standard PBR format), .obj (supported, simple geometry), .fbx (supported, complex rigging). Entity handle returned (valid entity, use with all entity functions like b3dPositionEntity/b3dRotateEntity/b3dScaleEntity), handle 0 on failure (invalid filename, file not found, mesh loading failed). Use cases: (1) Sunlight god rays (load sphere mesh, position as sun, configure radiance distance for screen brightening near horizon), (2) Flashlight cone (load cone mesh, attach to player entity, configure direction and spread factor), (3) Window light beams (load plane mesh, position at window, configure direction for sunlight streaming through), (4) Searchlight beam (load cone mesh, animate rotation, configure fade distance for atmospheric effect), (5) Cave exit glow (load plane mesh at cave exit, configure radiance for glowing exit effect).

Common patterns: sunlight rays = b3dLoadQuadRayMesh("sphere.glb") sphere mesh, position high and far, radiance distance for horizon glow; spotlight cone = b3dLoadQuadRayMesh("cone.glb") cone mesh, attach to light entity, direction follows light rotation; window beam = b3dLoadQuadRayMesh("plane.glb") plane mesh, position at window, rotate to match window orientation. Typical usage: load quad ray mesh (this function), position in scene (b3dPositionEntity places source, b3dRotateEntity orients rays), scale mesh (b3dScaleEntity adjusts ray volume, larger scale = wider rays), configure quad ray properties (fade distance, radiance distance, spread factor, direction), enable quad rays (b3dEnableQuadRays true to activate system). Mesh vs billboard quad rays: mesh sources use loaded geometry (custom shapes, complex volumes, accurate occlusion), billboard quad rays NOT IMPLEMENTED YET (point-source quad rays from billboards, simpler but less flexible).

Performance: mesh rendered once in occlusion pass (1024x576 texture, minimal cost <0.1ms), post-processing shader traces rays (numSamples iterations per pixel, 64 samples typical ~2ms), multiple quad ray sources (each adds to occlusion pass, share same post-processing, minimal additional cost). Quad ray baking: lock/unlock system (b3dLockQuadRay locks for editing, b3dUnlockQuadRay bakes and freezes occlusion texture), baked quad rays no longer update (frozen occlusion map, performance optimization for static scenes), locked quad rays allow property changes (modify without baking, useful during setup). Entity properties initialized: isQuadRaySource = true (marked as quad ray source, affects rendering pipeline), quadRayFadeStart = 0.0 (default no fade, set via b3dSetQuadRayFadeDistance), quadRayFadeFalloff = 1.0 (default linear falloff), quadRaySpreadFactor = 1.0 (default parallel rays, set via b3dSetQuadRaySpreadFactor), quadRayDirection = (0,0,0) (default no direction override, set via b3dSetQuadRayDirection), quadRayLocked = false (default unlocked, baking enabled), quadRayBaked = false (default unbaked, occlusion texture updates each frame).

Visibility: quad ray sources invisible by default (entity.visible = false in main scene, only rendered in occlusion pass), toggle visibility with b3dShowQuadRayEmitters (shows/hides quad ray source meshes in main scene for debugging), useful for debugging (visualize ray source positions and shapes). Coordinate system: mesh local space origin is ray casting origin (mesh center in local space), world space position via entity.position (b3dPositionEntity places source in world), rotation via entity.rotation (b3dRotateEntity orients source, affects ray direction), scale via entity.scale (b3dScaleEntity adjusts ray volume and spread). Integration with entity system: full entity support (position/rotation/scale/visibility/parenting all work), parenting supported (attach quad ray source to moving entities like player flashlight), hierarchy system (child quad ray sources follow parent transforms).

Validation: returns 0 if filename invalid (null pointer, empty string), returns 0 if file not found (mesh file doesn't exist at path), returns 0 if mesh loading fails (corrupted file, unsupported format, out of memory), check return value (If quadray = 0 Then error, handle failure). Silent failure (no error messages, check return value 0), entity created even on partial failure (handle valid, isQuadRaySource = true, but mesh may be missing). Related: b3dLoadMesh loads mesh (called internally, provides base mesh loading), b3dEnableQuadRays enables quad rays system (activates post-processing effect, required for visible rays), b3dSetQuadRaySource marks existing entity as source (alternative to loading new mesh, converts existing entities), b3dSetQuadRayFadeDistance configures fade (ray intensity fades with distance from source), b3dSetQuadRayRadianceDistance configures screen brightening (camera-distance-based glow effect), b3dSetQuadRayDirection overrides ray direction (forces rays in specific direction regardless of mesh orientation), b3dSetQuadRaySpreadFactor configures ray spread (parallel/spreading/converging rays), b3dShowQuadRayEmitters toggles source visibility (show/hide source meshes in main scene for debugging).