CLab

Bringing Hardware Occlusion Culling (HOC) to Minecraft entity rendering optimization.

CLab is a client-side rendering optimization mod. It leverages GPU OpenGL occlusion queries to determine entity visibility directly, eliminating the approximation errors and side effects inherent to traditional CPU-side pathtracing.

Core Features

• Hardware Occlusion Culling (HOC)
  Uses GPU queries to test entity bounding boxes against the depth buffer, measuring real occlusion against actually rendered terrain rather than CPU-side approximations of the world model.

• Zero False-Positive Culling
  Based on ground-truth depth buffer testing. An entity is never hidden if even a single pixel is visible. No whitelist needed, no per-mod patches required.

• Render-Layer Only, Zero Intrusion
  Only decides whether to invoke the entity render method. Does not interfere with client-side ticks, animation states, position interpolation, or any logic. Trains, vehicles, and contraptions behave normally.

• Built-in Leaf Face Culling
  Automatically culls leaf faces occluded by adjacent leaves, reducing terrain rendering overhead.

• Zero-Config, Works Out of the Box
  No entity whitelist, no distance threshold, no tick-culling toggle. Install and play.

Technical Overview

CLab uses Hardware Occlusion Culling:

1. During entity rendering, submit the entity bounding box to the GPU as an occlusion query (OpenGL Query).
2. The GPU compares the bounding box against the already-rendered terrain depth buffer at the hardware level.
3. Read the previous frame's query result: if no pixels passed the depth test, skip rendering this entity.

This creates a fundamental difference:

| Aspect | CPU Pathtracing | CLab HOC |
|--------|---------------|----------|
| Occlusion basis | Simplified assumptions about world model | Actual GPU-rendered depth buffer |
| False positives (hiding visible entities) | Common (near non-solid blocks) | Extremely unlikely |
| Entity tick/animation | Often frozen or skipped | Completely unaffected |
| CPU overhead | Continuous background traversal | Render thread submits AABB only; GPU handles the rest asynchronously |
| Configuration required | Whitelists, distance limits, thresholds as compensatory mechanisms | None required |

⚠️ Important Compatibility Notes

• Hardware Requirement: CLab requires a dedicated graphics card with OpenGL 3.3 or higher. Most modern GPUs meet this requirement, but certain older integrated graphics or outdated drivers may not.
• Do NOT use with other entity culling mods: CLab should not be installed alongside EntityCulling or any other mod that modifies entity/block entity visibility. While these mods use different techniques, they all ultimately override the same visibility decisions. Running more than one will not improve performance — instead, they may conflict and cancel out each other's optimizations, resulting in wasted resources and potential visual inconsistencies. For the best results, keep only CLab active.

Compatibility & Future Optimizations

The current approach was chosen to maintain compatibility with older devices and macOS. A more advanced technique is available, but it would introduce compatibility problems on those systems. Development and testing are currently done on a Mac, which limits how far I can improve things today. I plan to transition to a machine with OpenGL 4.6 support soon, after which I’ll introduce a system that automatically selects the optimal method during loading.