b3dCreateQuadRay

Creates volumetric god ray effect from an entity (light shafts through geometry). Takes entityHandle (source entity to copy for occlusion detection). Returns new entity handle (quad ray source entity, or 0 on error). Copies source entity and marks as quad ray source for volumetric rendering.

This function creates god rays. Quad ray system: volumetric light shafts (god rays/crepuscular rays), light beams visible through atmospheric scattering, requires geometry to occlude rays (creates light/shadow patterns), uses occlusion buffer to determine visible areas, renders billboards/quads at occluded pixels. Creation process: (1) copies source entity via b3dCopyEntity (leaves original unchanged), (2) marks copy as quad ray source (sets isQuadRaySource = true), (3) initializes quad ray state fields (fade, billboard, direction, spread, texture), (4) initializes radiance fields (screen brightening effect), (5) sets global flag g_hasAnyQuadRaySources = true (enables quad ray rendering pass). Source entity: can be any mesh entity (typically simple geometry like sphere/cube), represents light source volume for occlusion detection, copy inherits mesh geometry (used for occlusion), copy rendered WHITE in occlusion pass (identifies light source areas), original entity unchanged (can be hidden or used normally). Quad ray state initialization: quadRayFadeStart = 0.0 (no fade by default), quadRayFadeFalloff = 1.0 (default falloff), quadRayBillboardHandle = -1 (no billboard assigned), quadRayLocked = false (not locked to baked state), quadRayBaked = false (not pre-baked), quadRayDirection = (0,0,0) (default direction), quadRaySpreadFactor = 1.0 (default spread), quadRayTextureHandle = -1 (no texture assigned). Radiance initialization: quadRayRadianceStart = 0.0 (disabled by default), quadRayRadianceEnd = 0.0 (no radiance effect), radiance creates screen-space brightening around light source, simulates bloom/glow effect on camera sensor. Use cases: (1) Sunlight through windows (volumetric shafts in dusty room), (2) Flashlight beams (cone of light with visible dust particles), (3) Underwater caustics (light rays through water surface), (4) Stage spotlights (theatrical light beams through fog), (5) Sci-fi energy effects (tractor beams, portals). Common patterns: sun rays = create from sphere at sun position + set radiance for glow, flashlight = create from cone mesh + b3dSetQuadRayDirection for beam, portal effect = create from torus/ring + animated texture, underwater = create from plane at surface + blue tint. Typical usage: (1) create light source geometry (sphere for sun, cone for spotlight), (2) call b3dCreateQuadRay to make ray source, (3) configure with b3dSetQuadRayFade/Direction/etc, (4) optionally assign billboard texture, (5) position/rotate ray source entity to aim beams. Rendering pipeline: occlusion pass renders ray sources WHITE against black background, main scene renders normally (creates depth buffer), quad ray pass compares occlusion buffer to depth buffer, generates billboard quads where occlusion visible but scene geometry blocks, quads rendered with additive blending for light shaft appearance. Performance: adds occlusion rendering pass (extra draw calls for ray sources), adds quad ray pass (billboard generation + rendering), cost proportional to screen coverage of ray sources, use sparingly (1-5 ray sources typical), more sources = more occlusion tests + billboard generation. Visibility control: ray source invisible in main scene (only in occlusion pass), use quadRayBillboardHandle to assign custom billboard appearance, billboards face camera (always perpendicular to view direction), additive blending creates bright light shafts. Error handling: returns 0 if b3dCopyEntity fails (invalid source entity), returns 0 if copied entity lookup fails (internal error), prints error to std::cerr with details, returns new entity handle on success. Entity management: returned entity is independent copy, freeing source entity doesn't affect ray source, freeing ray source entity disables effect, ray source has same parent/children as source (hierarchy copied). Occlusion geometry: ray source geometry defines occlusion shape, simple geometry (sphere/cone) works best, complex meshes increase occlusion pass cost, geometry rendered in occlusion pass only (not visible in main scene). Global state: sets g_hasAnyQuadRaySources flag (enables quad ray rendering), flag checked during rendering to skip passes if no sources, remains true until all ray sources freed. Related configuration: b3dSetQuadRayFade sets distance fade parameters (start/falloff), b3dSetQuadRayDirection aims light shafts (directional beams), b3dSetQuadRaySpread controls beam width (cone angle), b3dSetQuadRayTexture assigns billboard texture (custom ray appearance), b3dSetQuadRayRadiance configures screen glow (bloom effect). Billboard generation: quads generated at pixels where occlusion visible, quad size based on distance and spread factor, quads oriented to face camera, rendered with assigned texture (or default white). Typical setup sequence: (1) b3dCreateQuadRay(sunSphere) to create ray source, (2) b3dSetQuadRayFade(raySource, 10.0, 50.0) for distance fade, (3) b3dSetQuadRayRadiance(raySource, 0.8, 1.5) for glow, (4) b3dSetQuadRayDirection(raySource, 0, -1, 0) for downward beams. Atmospheric scattering simulation: god rays simulate light scattering through particles (dust, fog, water droplets), occlusion creates light/shadow patterns (Tyndall effect), additive blending mimics light accumulation, radiance simulates camera bloom. Limitations: not physically accurate (artistic approximation), requires visible geometry for occlusion (no rays in empty space unless configured), performance cost increases with screen coverage, limited to directional effects (not full volumetric simulation). Related: b3dLoadQuadRayMesh loads mesh for quad ray source (alternative to copying entity), b3dSetQuadRayFade configures distance attenuation (fade start/falloff), b3dSetQuadRayDirection sets beam direction (aims light shafts), b3dSetQuadRayRadiance configures screen glow (bloom/halo effect).