b3dSetEntityRenderFlags

Sets entity render flags bitfield controlling rendering behavior (fullbright, culling, fog, vertex colors, flat shading). Takes entity (entity handle from b3dCreate* functions, positive integer), flags (bitwise render flags integer). Returns nothing. Validates entity exists and is mesh or terrain type, sets material.entityRenderFlags for main material and all submesh materials, modifies rendering pipeline behavior via shader and PSO selection.

This function controls special rendering modes via bitwise flags. Flag bits: Bit 0 (value 1) = fullbright (ignores lighting, uses base color only), Bit 1 (value 2) = vertex colors (multiplies base color by vertex colors), Bit 2 (value 4) = flat shading (uses face normals instead of vertex normals - future feature), Bit 3 (value 8) = disable fog (entity not affected by scene fog), Bit 4 (value 16) = disable backface culling (renders both front and back faces), Bit 5 (value 32) = invert lighting normals (flips normal direction for lighting calculations). Flags are bitwise combined (use addition or bitwise OR to combine multiple flags).

Fullbright mode (bit 0, value 1): skips all lighting calculations in pixel shader, renders entity with base color x base texture only (no shadows, no lights, no ambient), useful for: (1) UI elements in 3D space (health bars, floating text), (2) Emissive objects (glowing signs, self-illuminated panels), (3) Skyboxes (no lighting needed, always visible), (4) Debug visualization (show geometry without lighting interference), (5) Lightmaps baked into texture (lighting pre-computed, don't apply dynamic lights). Example: skybox = b3dCreateCube(), b3dSetEntityRenderFlags(skybox, 1) for fullbright skybox.

Vertex colors mode (bit 1, value 2): multiplies material base color by vertex color attribute, allows per-vertex tinting or blending, useful for: (1) Terrain blending (vertex colors blend between textures), (2) Team colors (tint geometry per vertex), (3) Ambient occlusion (darken vertices in crevices), (4) Damage effects (darken damaged areas), (5) Procedural coloring (paint vertices programmatically). Requires mesh with vertex colors (set via b3dVertexColor or loaded from file). Example: mesh with red vertices (1,0,0) and white base color (1,1,1) renders red, mesh with half-bright vertices (0.5,0.5,0.5) renders half brightness.

Flat shading mode (bit 2, value 4): uses face normals instead of interpolated vertex normals (future feature, not yet fully implemented), creates faceted appearance (hard edges between triangles), useful for: (1) Low-poly aesthetics (emphasize geometric structure), (2) Architectural visualization (sharp edges on buildings), (3) Crystal/gem rendering (distinct facets), (4) Technical drawings (clear polygon boundaries). Note: currently may not be fully functional, check implementation status.

Disable fog mode (bit 3, value 8): entity not affected by scene fog settings, renders at full visibility regardless of distance, useful for: (1) Skyboxes (always at infinity, fog doesn't apply), (2) UI elements (always fully visible), (3) Special effects (particles that should remain visible), (4) Far landmarks (mountains always visible on horizon), (5) Debug objects (always see debug markers). Scene fog configured via b3dCameraFogMode and b3dCameraFogRange. Example: skybox always visible, ground fades with distance.

Disable culling mode (bit 4, value 16): renders both front-facing and back-facing triangles, doubles rendered triangle count (performance cost), useful for: (1) Skyboxes (viewed from inside, need back faces), (2) Planes/sheets (visible from both sides like paper), (3) Foliage (leaves visible from both sides), (4) Glass/transparent surfaces (see through to interior), (5) Inverted geometry (inside-out meshes). Standard backface culling: GPU discards triangles facing away from camera (clockwise winding in screen space), disabling culling renders all triangles. PSO selection: changes pipeline state object to D3D12_CULL_MODE_NONE. Example: b3dSetEntityRenderFlags(skybox, 17) = 1+16 = fullbright + no culling for skybox (common pattern).

Invert lighting normals (bit 5, value 32): flips normal direction for lighting calculations (multiplies normal by -1), makes inside surfaces light correctly when viewed from inside, useful for: (1) Inverted geometry (caves, tunnels viewed from inside), (2) Interior spaces (rooms with inverted normals), (3) Mirror worlds (flipped coordinate systems), (4) Special effects (unusual lighting). Lighting calculations use flipped normal: light from opposite direction appears to illuminate surface. Doesn't affect normal mapping (only lighting direction).

Combining flags: use addition or bitwise OR to combine multiple flags, fullbright + no culling = 1 + 16 = 17 (common for skyboxes), fullbright + no fog = 1 + 8 = 9, vertex colors + no culling = 2 + 16 = 18, fullbright + no fog + no culling = 1 + 8 + 16 = 25. Example patterns: skybox = b3dSetEntityRenderFlags(skybox, 17) renders inside-out cube fully bright, foliage = b3dSetEntityRenderFlags(leaves, 16) renders double-sided leaves, glowing sign = b3dSetEntityRenderFlags(sign, 9) fullbright ignoring fog.

Material targeting: sets flags on entity's main material (entity.mesh->materialIndex or entity.materialOverrideIndex if present), also sets flags on all submesh materials (for multi-material meshes loaded from GLB), ensures consistent rendering across entire entity. Mesh and terrain only: function validates entity type is ENTITY_MESH or ENTITY_TERRAIN, billboards not supported (prints error if attempted), cameras/lights/pivots not applicable.

Shader behavior: pixel shader checks entityRenderFlags at runtime, branches based on bit tests (if (entityRenderFlags & 1) skip lighting), affects final pixel color calculation, shader code in DX12_Graphics3D.cpp PixelShader function. PSO selection: disable culling flag changes rasterizer state, switches from cull-back PSO to cull-none PSO during rendering, affects b3dRenderWorld batch rendering logic.

Performance: fullbright faster than lit (skips lighting calculations, fewer texture samples), vertex colors add multiply operation (minimal cost), disable culling doubles triangle processing (significant cost, use sparingly), flat shading similar cost to smooth (same triangle count, different normal interpolation), fog disable saves fog calculation (minimal savings). Typical cost: flag checks in shader add few instructions (negligible on modern GPUs), PSO switching adds CPU overhead (minimized by batching), culling disable most expensive (doubles fragment processing).

Use cases summary: (1) Skyboxes (flags 17 = fullbright + no culling, viewed from inside, always bright), (2) Emissive panels (flags 1 = fullbright, self-illuminated signs/displays), (3) Double-sided foliage (flags 16 = no culling, leaves visible both sides), (4) Vertex-painted terrain (flags 2 = vertex colors, blend textures via vertex colors), (5) Fog-immune landmarks (flags 8 = no fog, distant mountains always visible), (6) Interior lighting (flags 32 = invert normals, light inside-out geometry correctly).

Validation: returns silently if invalid entity handle (prints error to std::cerr), returns silently if entity type not mesh or terrain, prints error if mesh/terrain has no data, flags value not validated (any integer accepted, non-flag bits ignored by shader). Material cloning: if entity shares material with other entities, flags affect all instances (use b3dCloneEntityMaterial first for per-instance flags).

Related: b3dGetEntityRenderFlags returns current flags (query bitfield), b3dEntityBlend sets alpha blending mode (complementary rendering control), b3dEntityOrder sets render order (draw order for transparency), b3dCloneEntityMaterial clones material for per-instance flags (prevents shared material side effects), b3dCameraFogMode/Range configure scene fog (disabled by bit 3).