b3dCreateBillboard

Creates billboard entity with texture (camera-facing quad, three modes: spherical/cylindrical/static). Takes textureHandle (texture from b3dLoadTexture3D, displayed on billboard), mode (0=SPHERICAL, 1=CYLINDRICAL, 2=STATIC). Returns entity handle (ENTITY_BILLBOARD, 0 if failed). Creates quad geometry (shared vertex buffer, 1x1 unit quad), scales to texture aspect ratio (width=textureWidth/textureHeight, height=1.0), initializes billboard properties (alpha, color, emissive, blend mode). Use for particles, sprites, trees, grass, decals, or UI elements in 3D space.

This function creates billboard entity. Billboard modes: SPHERICAL (0) = fully faces camera (rotates on all axes, always perpendicular to view, typical for particles or icons), CYLINDRICAL (1) = Y-axis rotation only (rotates around vertical axis, stays upright, typical for trees or posts), STATIC (2) = no rotation (fixed orientation, visible from all angles, double-sided rendering, typical for decals or 2D sprites in 3D). Texture handle: textureHandle from b3dLoadTexture3D (assigns 3D texture to billboard quad, same texture system as meshes and materials), aspect ratio preserved (billboard width scaled to match texture width/height ratio, prevents distortion), invalid texture (0 or out of range) creates 1x1 square billboard (default aspect ratio 1.0). Geometry: shared vertex buffers (all billboards use same base geometry, instanced rendering), single-sided for SPHERICAL/CYLINDRICAL (6 vertices, front face only, culls back face), double-sided for STATIC (12 vertices, front and back faces, no culling), unit quad (1.0x1.0 base size, scaled via entity.scale). Entity integration: ENTITY_BILLBOARD type (integrates with entity system, supports position/rotation/scale), visible by default (entity.visible = true, rendered in scene), supports parenting (attach to other entities, hierarchy system), supports PBR materials (assign additional textures, normal maps, roughness via material system).

Billboard modes detailed: SPHERICAL (0) faces camera completely (billboard normal = -cameraForward, perpendicular to view direction), rotates pitch and yaw (follows camera on all axes, maintains facing), typical use (particles, explosions, icons, muzzle flashes, UI markers). CYLINDRICAL (1) rotates around Y axis only (billboard forward rotates toward camera horizontally, up vector stays +Y), keeps upright (no pitch rotation, prevents tilting), typical use (trees, grass, posts, cylindrical objects, vegetation). STATIC (2) no rotation (billboard orientation fixed, uses entity.rotation), double-sided rendering (visible from both front and back, no face culling), typical use (decals, 2D sprites, planes, ground markings, wall decals). Aspect ratio scaling: texture dimensions queried (width and height from g_textures[textureHandle]), aspect ratio calculated (width / height, e.g., 512x256 = 2.0), billboard scaled (width = aspectRatio, height = 1.0, preserves proportions), entity.scale set (entity.scale = (width, height, 1.0) maintains aspect). Default size: billboard base 1.0x1.0 (before entity.scale, unit quad), entity.scale adjusts final size (scale = (2, 1, 1) for 2:1 aspect ratio), world space size = entity.scale x entity.position offset (final size in scene).

Use cases: (1) Particles (fire, smoke, sparks, explosions use SPHERICAL mode, always face camera), (2) Vegetation (trees, grass, bushes use CYLINDRICAL mode, stay upright), (3) Sprites (2D game sprites in 3D world use STATIC mode, fixed orientation), (4) UI elements (health bars, name tags use SPHERICAL mode, readable from any angle), (5) Decals (bullet holes, scorch marks use STATIC mode, applied to surfaces), (6) Effects (lens flares, halos use SPHERICAL mode, face camera), (7) Icons (waypoint markers, objective indicators use SPHERICAL mode). Common patterns: particle billboard = b3dCreateBillboard(particleTex, 0) spherical, tree billboard = b3dCreateBillboard(treeTex, 1) cylindrical, decal billboard = b3dCreateBillboard(decalTex, 2) static. Typical usage: create billboard, position b3dPositionEntity (place in world), scale b3dScaleEntity (adjust size, multiplies aspect ratio scale), optional configure alpha/color/emissive (transparency, tinting, glow effects).

Shared geometry optimization: all billboards share vertex buffers (single-sided buffer for SPHERICAL/CYLINDRICAL, double-sided buffer for STATIC), instanced rendering (GPU renders many billboards efficiently, low CPU overhead), memory efficient (one vertex buffer for all billboards, minimal memory per billboard), reduces draw calls (batched billboard rendering, all billboards drawn together). Vertex buffer initialization: InitializeBillboardResources called (creates shared buffers on first billboard creation), persistent buffers (exist for lifetime of 3D system, reused by all billboards), automatic (user doesn't manage buffers, handled internally). Billboard properties: textureHandle (texture displayed on quad, assigned at creation), width/height (world space size, calculated from aspect ratio), mode (SPHERICAL/CYLINDRICAL/STATIC, billboard rotation behavior), alpha (transparency 0.0-1.0, default 1.0 opaque), color (RGB tint 0.0-1.0, default white 1,1,1), emissiveColor/Intensity (glow effect, default 0,0,0 no glow), blendMode (0=solid, 1=alpha, 2=multiply, 3=additive, default 0). Entity operations: b3dPositionEntity moves billboard (world space position), b3dRotateEntity rotates billboard (affects STATIC mode, ignored for SPHERICAL/CYLINDRICAL), b3dScaleEntity scales billboard (multiplies width/height, final size = scale x aspect ratio), b3dHideEntity/ShowEntity toggles visibility.

Rendering: billboards rendered in main pass (integrated with PBR pipeline, standard entity rendering), camera facing calculated per frame (SPHERICAL/CYLINDRICAL modes compute rotation matrix, STATIC uses entity.rotation), depth sorting optional (transparent billboards can be sorted back-to-front, render order configurable), lighting (PBR materials apply, or unlit for additive particles). Texture coordinates: UV 0-1 mapped to quad (standard texture mapping, (0,0) bottom-left, (1,1) top-right), supports texture atlases (assign sub-texture via UV offset/scale, sprite sheets possible), mipmaps and filtering (standard texture sampling, GPU filtering applies). Alpha transparency: alpha property (billboard.alpha controls transparency, 0.0 = invisible, 1.0 = opaque), blend mode (blendMode 1 = alpha blending, typical for particles), premultiplied alpha (alpha * color applied in shader, correct transparency). Color tinting: color property (billboard.color RGB tint, white (1,1,1) = no tint, red (1,0,0) = red tint), multiplicative (texture RGB multiplied by color, tints texture while preserving detail), typical use (colored particles, team colors, damage indicators). Emissive glow: emissiveColor/Intensity (adds glow independent of lighting, self-illumination), additive (added to final color, creates bloom effect), typical use (glowing particles, magic effects, lens flares, lights).

Multiple billboards: create many billboards (each billboard separate entity, independent position/scale/properties), efficient rendering (shared geometry and instancing, thousands of billboards possible), batch by texture (billboards with same texture batched, reduces state changes), sort by distance (transparent billboards sorted back-to-front for correct alpha blending). Billboard orientation: SPHERICAL rotation (billboard right = cameraRight, billboard up = cameraUp, billboard forward = -cameraForward), CYLINDRICAL rotation (billboard right = horizontal toward camera, billboard up = +Y world up, billboard forward calculated), STATIC orientation (billboard uses entity.rotation directly, no camera-relative rotation). Camera-relative rendering: view matrix used (camera position and rotation determine facing), updated per frame (billboards reorient each frame automatically, no user code needed), smooth rotation (billboards smoothly follow camera movement). Coordinate system: billboard faces -Z in local space (default forward, camera-relative transform applied), world space position (entity.position in world coordinates, billboard origin), scale affects size (entity.scale x aspect ratio = final billboard size in world units).

Texture aspect ratio examples: 1:1 square (512x512, aspect 1.0, billboard width=1.0 height=1.0), 2:1 wide (1024x512, aspect 2.0, billboard width=2.0 height=1.0), 1:2 tall (512x1024, aspect 0.5, billboard width=0.5 height=1.0), 4:1 very wide (2048x512, aspect 4.0, billboard width=4.0 height=1.0). Scale interaction: entity.scale = (2, 3, 1) multiplies aspect ratio (final size = aspect width x scaleX, aspect height x scaleY), uniform scale (entity.scale = (5, 5, 1) scales both dimensions equally), non-uniform scale (entity.scale = (1, 2, 1) stretches vertically). Performance: shared geometry efficient (minimal memory per billboard, ~100 bytes each), instanced rendering (GPU-friendly, thousands per frame), texture batching (group billboards by texture, reduces draw calls), typical (5000+ billboards at 60 FPS, performance depends on texture count and blending).

Failure cases: returns 0 if 3D device not initialized (3D system not ready, no GPU), returns 0 if mode invalid (mode not 0/1/2, only SPHERICAL/CYLINDRICAL/STATIC valid), returns 0 if buffer initialization fails (out of memory, GPU resource allocation failed), check return value (If billboard = 0 Then error, handle failure). Validation: mode clamped to 0-2 (invalid modes fail creation, user must provide valid mode), textureHandle validated (invalid texture creates square billboard, doesn't fail creation), silent for texture errors (billboard created with default size, no error message for missing texture). Related: b3dLoadImage loads texture (provides textureHandle for billboard), b3dPositionEntity positions billboard (places in world space), b3dScaleEntity scales billboard (adjusts final size, multiplies aspect ratio), b3dRotateEntity rotates STATIC billboards (affects orientation for STATIC mode only), b3dEntityAlpha sets transparency (controls billboard alpha blending), b3dEntityColor sets tint (RGB color tint for billboard).