CLab

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

Загрузки: 1K
Подписчики: 12
Обновлён: 4 мая 2026 г.
Лицензия: LGPL-3.0-only

Опубликован 1 мая 2026 г.

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:

During entity rendering, submit the entity bounding box to the GPU as an occlusion query (OpenGL Query).
The GPU compares the bounding box against the already-rendered terrain depth buffer at the hardware level.
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.

Ченджлог

26.3.1Бета1.20, 1.20.1 · 4 мая 2026 г.

feat(renderer): add hardware occlusion culling for block entities

Implemented HardwareOcclusionBlockEntityCuller with OpenGL query-based visibility detection
Added BlockEntityCullingManager to handle registration and culling logic for block entities
Integrated block entity culling into rendering pipeline via MixinBlockEntityRenderDispatcher
Enhanced MixinLevelRenderer to process block entity queries after rendering phase
Added support for distance-based query frequency adjustment and result batching
Implemented proper resource management with query pool growth and cleanup routines
Updated ClientClass to initialize and manage block entity culling system alongside entity culling

26.3.1Бета1.20, 1.20.1 · 4 мая 2026 г.

feat(renderer): add hardware occlusion culling for block entities

Implemented HardwareOcclusionBlockEntityCuller with OpenGL query-based visibility detection
Added BlockEntityCullingManager to handle registration and culling logic for block entities
Integrated block entity culling into rendering pipeline via MixinBlockEntityRenderDispatcher
Enhanced MixinLevelRenderer to process block entity queries after rendering phase
Added support for distance-based query frequency adjustment and result batching
Implemented proper resource management with query pool growth and cleanup routines
Updated ClientClass to initialize and manage block entity culling system alongside entity culling

26.3.1Бета1.21, 1.21.1 · 4 мая 2026 г.

perf(culling): optimize hardware occlusion culling implementation

Increased initial query pool size from 512 to 1024 for better performance
Added shader caching mechanism to reduce redundant shader operations
Implemented matrix caching for projection and model-view transformations
Replaced direct shader drawing with optimized draw calls
Removed redundant imports and cleaned up code structure
Moved block entity culling logic to separate mixin class
Added proper shader matrix updates during query batches
Implemented resource cleanup in endQueryBatch methods

26.3.1Бета1.21, 1.21.1 · 4 мая 2026 г.

perf(culling): optimize hardware occlusion culling implementation

Increased initial query pool size from 512 to 1024 for better performance
Added shader caching mechanism to reduce redundant shader operations
Implemented matrix caching for projection and model-view transformations
Replaced direct shader drawing with optimized draw calls
Removed redundant imports and cleaned up code structure
Moved block entity culling logic to separate mixin class
Added proper shader matrix updates during query batches
Implemented resource cleanup in endQueryBatch methods

26.3Бета1.21, 1.21.1 · 3 мая 2026 г.

feat(rendering): add hardware occlusion culling for block entities

Implemented HardwareOcclusionBlockEntityCuller with OpenGL query-based visibility detection
Added BlockEntityCullingManager to handle registration and management of block entity cullers
Integrated block entity culling into LevelRenderer with proper mixin injections and redirects
Created IBlockEntityCuller interface for standardized culling implementation
Optimized rendering by caching camera position and using batched queries
Added proper resource cleanup and pool management for GPU queries