b3dSetEntityPadding

Sets frustum culling padding for entity (extends culling bounds beyond collision box). Takes entity (entity handle), width (X-axis padding in world units), height (Y-axis padding in world units), depth (Z-axis padding in world units). Returns nothing. Extends entity axis-aligned bounding box (AABB) used for frustum culling by specified amounts on each axis, prevents premature culling when entity parts extend beyond base collision box. Particularly useful for animated meshes where limbs extend beyond bind pose.

Frustum culling: GPU-driven culling tests each entity AABB against camera frustum (view volume, pyramid shape from camera), entities outside frustum skipped (no draw call, performance optimization), AABB calculated from collision box + padding (world space bounds after transform). Padding extends bounds: width extends X-axis (left/right), height extends Y-axis (up/down), depth extends Z-axis (forward/back), prevents culling when extremities reach screen edges. Common use cases: (1) Animated characters (bind pose compact but animations extend limbs, arms/legs swing beyond collision box, padding prevents disappearing at screen edges), (2) Billboard effects (sprite rotation can extend beyond base bounds), (3) Particle systems (particles spawn beyond emitter position), (4) Dynamic objects (objects that change size or extend parts).

Animated mesh problem: collision boxes calculated from bind pose vertices (arms down, legs together, compact bounds), animations extend limbs (arm swing, leg kick, dance moves extend far beyond bind pose), without padding character culled aggressively (limbs reach edge but center still visible, frustum cull removes entire entity). Solution: add padding matching maximum limb extension (analyze animation extremes, measure furthest reach, add padding to cover maximum extent), typical animated character needs 50-100% of collision box size as padding (e.g., 2-unit tall character might need 1-1.5 units padding on X/Z axes).

Padding defaults to 0 (no extension, tight culling based on collision box only), must explicitly call b3dSetEntityPadding to extend bounds. Padding applied in local space (scaled with entity scale, rotated with entity rotation), final AABB in world space (includes position, rotation, scale, and padding). GPU frustum culling: AABB test on GPU (compute shader, per-entity parallel test), results written to visibility buffer (1 = visible, 0 = culled), only visible entities rendered (indirect draw calls, GPU-driven rendering). Performance: padding increases AABB size (slightly more entities pass culling, minimal performance cost), too much padding wastes rendering (entities off-screen still rendered), too little padding causes pop-in (entity disappears prematurely at edges). Recommended approach: analyze your animations (watch character at screen edges, note when inappropriate culling occurs), measure minimum padding needed (start conservative, reduce until pop-in observed, add back small margin), different animations may need different padding (consider maximum across all animations).

Example values: static mesh (0, 0, 0 - no padding needed, collision box accurate), animated humanoid character (1.5, 0.5, 1.5 - arms/legs extend on X/Z, less vertical extension), billboard sprite (0.5, 0.5, 0.5 - rotation can extend all directions), particle emitter (2.0, 2.0, 2.0 - particles spawn in radius). Setting per-entity: each entity has independent padding (character A can have different padding than character B, even if same mesh), padding stored in entity (cullPaddingWidth, cullPaddingHeight, cullPaddingDepth fields), modifiable at runtime (can change padding dynamically, e.g., increase when special animation plays). Validation: silently accepts any entity handle (invalid handle does nothing), padding can be negative (shrinks bounds, causes aggressive culling, rarely useful), typical values 0-5 world units (depends on entity scale and animation extent).

Technical implementation: padding added to local space OBB (Oriented Bounding Box, collision box min/max extended by padding), OBB transformed to world space (rotation and scale applied), AABB calculated from rotated OBB (Arvo's method, axis-aligned envelope of rotated box), AABB uploaded to GPU (used in frustum culling shader). Interaction with scale: padding values in local space (b3dScaleEntity does NOT automatically scale padding, padding remains constant in local coordinates), world space padding increases with scale (2x scale = 2x world space padding from same local values). Call order: set padding AFTER scaling entity (if b3dScaleEntity called after b3dSetEntityPadding, padding values unchanged in local space but world space extent grows with scale), typical workflow: load mesh, scale to desired size, set padding for scaled size, animate. Updates: padding change marks AABBs dirty (recalculated next frame), new bounds used immediately for culling, no need to manually refresh.

Related: b3dLoadAnimMesh loads animated mesh (sets collision box from bind pose, padding defaults to 0), b3dEntityBox gets collision box dimensions (base bounds before padding), b3dScaleEntity scales entity (padding in local space scales with entity), b3dEntityInView tests visibility (returns true if entity passed frustum culling, accounts for padding).