Skip to content

Improve voxel memory usage via Texture3D #13084

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jjhembd wants to merge 16 commits into
base: main
Choose a base branch
from
+675 −597
Open

Improve voxel memory usage via Texture3D #13084

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
b470f85
Update ContextLimits for webgl2, fix Texture3D size limit
Nov 7, 2025
9ecb55a
WIP: Add 3d texture size calculations in Megatexture
Nov 11, 2025
0b63a41
Add spec, clean up unused WebGL1 voxel code
Nov 12, 2025
034dee1
Add Texture3D.prototype.copyFrom
Nov 19, 2025
c576dce
Use 3D textures for voxel rendering
Nov 19, 2025
99a6be5
Fix ContextLimits.maximum3DTextureSize
Nov 26, 2025
5717661
Fix voxel rendering with nearest sampling
Dec 2, 2025
918b52c
Use VoxelProvider.availableLevels to estimate number of tiles
Dec 2, 2025
51aa022
Clean up Voxels sandcastle
Dec 3, 2025
3523120
Fix MegatextureSpec
Dec 4, 2025
d9d394e
Clean up dimension handling in VoxelTraversal
Dec 4, 2025
b626d96
Fix failing specs
Dec 5, 2025
a326430
Merge branch 'main' into voxel-texture3d
Dec 5, 2025
b61e6c6
Add MAX_3D_TEXTURE_SIZE to WebGL stub for specs
Dec 5, 2025
becb359
Stub more 3D3D texture methods for specs
Dec 5, 2025
c576e21
Update CHANGES.md
Dec 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 0 additions & 3 deletions Apps/Sandcastle/gallery/VolumeCloud.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -327,9 +327,6 @@ <h1>Loading...</h1>
}`;

const fragmentShader = /* glsl */ `
precision highp float;
precision highp sampler3D;

in vec3 vOrigin;
in vec3 vDirection;

Expand Down
10 changes: 9 additions & 1 deletion CHANGES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,14 @@
# Change Log

## 1.137 - 2026-01-02

### @cesium/engine

#### Fixes :wrench:

- Fix texture coordinates in large billboard collections. [#13042](https://github.com/CesiumGS/cesium/pull/13042)
- Improved voxel memory usage by reworking `Megatexture` to use `Texture3D`. [#12570](https://github.com/CesiumGS/cesium/issues/12570)

## 1.136 - 2025-12-01

### @cesium/engine
Expand All @@ -10,7 +19,6 @@
- Billboards using `imageSubRegion` now render as expected. [#12585](https://github.com/CesiumGS/cesium/issues/12585)
- Fixed depth testing bug with billboards and labels clipping through models [#13012](https://github.com/CesiumGS/cesium/issues/13012)
- Fixed unexpected outline artifacts around billboards [#4525](https://github.com/CesiumGS/cesium/issues/4525)
- Fix texture coordinates in large billboard collections [#13042](https://github.com/CesiumGS/cesium/pull/13042)

#### Additions :tada:

Expand Down
4 changes: 4 additions & 0 deletions Specs/getWebGLStub.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -112,6 +112,9 @@ function getWebGLStub(canvas, options) {
stub.texParameteri = noop;
stub.texImage2D = noop;
stub.texSubImage2D = noop;
stub.texStorage3D = noop;
stub.texImage3D = noop;
stub.texSubImage3D = noop;
stub.uniform1f = noop;
stub.uniform1fv = noop;
stub.uniform1i = noop;
Expand Down Expand Up @@ -232,6 +235,7 @@ function getParameterStub(options) {
parameterStubValues[WebGLConstants.MAX_TEXTURE_IMAGE_UNITS] = 16;
parameterStubValues[WebGLConstants.MAX_RENDERBUFFER_SIZE] = 16384;
parameterStubValues[WebGLConstants.MAX_TEXTURE_SIZE] = 16384;
parameterStubValues[WebGLConstants.MAX_3D_TEXTURE_SIZE] = 2048;
parameterStubValues[WebGLConstants.MAX_VARYING_VECTORS] = 30;
parameterStubValues[WebGLConstants.MAX_VERTEX_ATTRIBS] = 16;
parameterStubValues[WebGLConstants.MAX_VERTEX_TEXTURE_IMAGE_UNITS] = 16;
Expand Down
21 changes: 11 additions & 10 deletions packages/engine/Source/Renderer/Context.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,32 +86,33 @@ function Context(canvas, options) {

ContextLimits._maximumCombinedTextureImageUnits = gl.getParameter(
gl.MAX_COMBINED_TEXTURE_IMAGE_UNITS,
); // min: 8
);
ContextLimits._maximumCubeMapSize = gl.getParameter(
gl.MAX_CUBE_MAP_TEXTURE_SIZE,
); // min: 16
);
ContextLimits._maximumFragmentUniformVectors = gl.getParameter(
gl.MAX_FRAGMENT_UNIFORM_VECTORS,
); // min: 16
);
ContextLimits._maximumTextureImageUnits = gl.getParameter(
gl.MAX_TEXTURE_IMAGE_UNITS,
); // min: 8
);
ContextLimits._maximumRenderbufferSize = gl.getParameter(
gl.MAX_RENDERBUFFER_SIZE,
); // min: 1
ContextLimits._maximumTextureSize = gl.getParameter(gl.MAX_TEXTURE_SIZE); // min: 64
);
ContextLimits._maximumTextureSize = gl.getParameter(gl.MAX_TEXTURE_SIZE);
ContextLimits._maximum3DTextureSize = gl.getParameter(gl.MAX_3D_TEXTURE_SIZE);
ContextLimits._maximumVaryingVectors = gl.getParameter(
gl.MAX_VARYING_VECTORS,
); // min: 8
);
ContextLimits._maximumVertexAttributes = gl.getParameter(
gl.MAX_VERTEX_ATTRIBS,
); // min: 8
);
ContextLimits._maximumVertexTextureImageUnits = gl.getParameter(
gl.MAX_VERTEX_TEXTURE_IMAGE_UNITS,
); // min: 0
);
ContextLimits._maximumVertexUniformVectors = gl.getParameter(
gl.MAX_VERTEX_UNIFORM_VECTORS,
); // min: 128
);

ContextLimits._maximumSamples = this._webgl2
? gl.getParameter(gl.MAX_SAMPLES)
Expand Down
66 changes: 40 additions & 26 deletions packages/engine/Source/Renderer/ContextLimits.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ const ContextLimits = {
_maximumTextureImageUnits: 0,
_maximumRenderbufferSize: 0,
_maximumTextureSize: 0,
_maximum3DTextureSize: 0,
_maximumVaryingVectors: 0,
_maximumVertexAttributes: 0,
_maximumVertexTextureImageUnits: 0,
Expand All @@ -31,11 +32,11 @@ const ContextLimits = {
Object.defineProperties(ContextLimits, {
/**
* The maximum number of texture units that can be used from the vertex and fragment
* shader with this WebGL implementation. The minimum is eight. If both shaders access the
* shader with this WebGL implementation. The minimum is 32. If both shaders access the
Copy link
Contributor Author

@jjhembd jjhembd Dec 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All these comments have been updated to the WebGL2 minimums, since we now default to a WebGL2 context.

Copy link
Member

@donmccurdy donmccurdy Dec 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When defaulting to a WebGL2 context, is there still a fallback path for devices that only support WebGL 1? I understand voxel rendering will require WebGL 2, but other CesiumJS APIs can run with just WebGL 1?

If not, just wondering if the comments should reflect the minimums for browsers and hardware that CesiumJS supports, rather than the minimums for the preferred/default WebGL 2.

(or if deprecating WebGL 1 support more broadly is on the roadmap, maybe that changes things!)

* same texture unit, this counts as two texture units.
* @memberof ContextLimits
* @type {number}
* @see {@link https://www.khronos.org/opengles/sdk/docs/man/xhtml/glGet.xml|glGet} with <code>MAX_COMBINED_TEXTURE_IMAGE_UNITS</code>.
* @see {@link https://registry.khronos.org/OpenGL-Refpages/es3.0/html/glGet.xhtml|glGet} with <code>MAX_COMBINED_TEXTURE_IMAGE_UNITS</code>.
*/
maximumCombinedTextureImageUnits: {
get: function () {
Expand All @@ -45,10 +46,10 @@ Object.defineProperties(ContextLimits, {

/**
* The approximate maximum cube map width and height supported by this WebGL implementation.
* The minimum is 16, but most desktop and laptop implementations will support much larger sizes like 8,192.
* The minimum is 2048, but most desktop and laptop implementations will support much larger sizes like 8,192.
* @memberof ContextLimits
* @type {number}
* @see {@link https://www.khronos.org/opengles/sdk/docs/man/xhtml/glGet.xml|glGet} with <code>MAX_CUBE_MAP_TEXTURE_SIZE</code>.
* @see {@link https://registry.khronos.org/OpenGL-Refpages/es3.0/html/glGet.xhtml|glGet} with <code>MAX_CUBE_MAP_TEXTURE_SIZE</code>.
*/
maximumCubeMapSize: {
get: function () {
Expand All @@ -58,10 +59,10 @@ Object.defineProperties(ContextLimits, {

/**
* The maximum number of <code>vec4</code>, <code>ivec4</code>, and <code>bvec4</code>
* uniforms that can be used by a fragment shader with this WebGL implementation. The minimum is 16.
* uniforms that can be used by a fragment shader with this WebGL implementation. The minimum is 224.
* @memberof ContextLimits
* @type {number}
* @see {@link https://www.khronos.org/opengles/sdk/docs/man/xhtml/glGet.xml|glGet} with <code>MAX_FRAGMENT_UNIFORM_VECTORS</code>.
* @see {@link https://registry.khronos.org/OpenGL-Refpages/es3.0/html/glGet.xhtml|glGet} with <code>MAX_FRAGMENT_UNIFORM_VECTORS</code>.
*/
maximumFragmentUniformVectors: {
get: function () {
Expand All @@ -70,10 +71,10 @@ Object.defineProperties(ContextLimits, {
},

/**
* The maximum number of texture units that can be used from the fragment shader with this WebGL implementation. The minimum is eight.
* The maximum number of texture units that can be used from the fragment shader with this WebGL implementation. The minimum is 16.
* @memberof ContextLimits
* @type {number}
* @see {@link https://www.khronos.org/opengles/sdk/docs/man/xhtml/glGet.xml|glGet} with <code>MAX_TEXTURE_IMAGE_UNITS</code>.
* @see {@link https://registry.khronos.org/OpenGL-Refpages/es3.0/html/glGet.xhtml|glGet} with <code>MAX_TEXTURE_IMAGE_UNITS</code>.
*/
maximumTextureImageUnits: {
get: function () {
Expand All @@ -83,10 +84,10 @@ Object.defineProperties(ContextLimits, {

/**
* The maximum renderbuffer width and height supported by this WebGL implementation.
* The minimum is 16, but most desktop and laptop implementations will support much larger sizes like 8,192.
* The minimum is 2048, but most desktop and laptop implementations will support much larger sizes like 8,192.
* @memberof ContextLimits
* @type {number}
* @see {@link https://www.khronos.org/opengles/sdk/docs/man/xhtml/glGet.xml|glGet} with <code>MAX_RENDERBUFFER_SIZE</code>.
* @see {@link https://registry.khronos.org/OpenGL-Refpages/es3.0/html/glGet.xhtml|glGet} with <code>MAX_RENDERBUFFER_SIZE</code>.
*/
maximumRenderbufferSize: {
get: function () {
Expand All @@ -96,23 +97,36 @@ Object.defineProperties(ContextLimits, {

/**
* The approximate maximum texture width and height supported by this WebGL implementation.
* The minimum is 64, but most desktop and laptop implementations will support much larger sizes like 8,192.
* The minimum is 2048, but most desktop and laptop implementations will support much larger sizes like 8,192.
* @memberof ContextLimits
* @type {number}
* @see {@link https://www.khronos.org/opengles/sdk/docs/man/xhtml/glGet.xml|glGet} with <code>MAX_TEXTURE_SIZE</code>.
* @see {@link https://registry.khronos.org/OpenGL-Refpages/es3.0/html/glGet.xhtml|glGet} with <code>MAX_TEXTURE_SIZE</code>.
*/
maximumTextureSize: {
get: function () {
return ContextLimits._maximumTextureSize;
},
},

/**
* The approximate maximum texture width, height, and depth supported by this WebGL implementation.
* The minimum is 256, but most desktop and laptop implementations will support much larger sizes like 2048.
* @memberof ContextLimits
* @type {number}
* @see {@link https://registry.khronos.org/OpenGL-Refpages/es3.0/html/glGet.xhtml|glGet} with <code>MAX_3D_TEXTURE_SIZE</code>.
*/
maximum3DTextureSize: {
get: function () {
return ContextLimits._maximum3DTextureSize;
},
},

/**
* The maximum number of <code>vec4</code> varying variables supported by this WebGL implementation.
* The minimum is eight. Matrices and arrays count as multiple <code>vec4</code>s.
* The minimum is 15. Matrices and arrays count as multiple <code>vec4</code>s.
* @memberof ContextLimits
* @type {number}
* @see {@link https://www.khronos.org/opengles/sdk/docs/man/xhtml/glGet.xml|glGet} with <code>MAX_VARYING_VECTORS</code>.
* @see {@link https://registry.khronos.org/OpenGL-Refpages/es3.0/html/glGet.xhtml|glGet} with <code>MAX_VARYING_VECTORS</code>.
*/
maximumVaryingVectors: {
get: function () {
Expand All @@ -121,10 +135,10 @@ Object.defineProperties(ContextLimits, {
},

/**
* The maximum number of <code>vec4</code> vertex attributes supported by this WebGL implementation. The minimum is eight.
* The maximum number of <code>vec4</code> vertex attributes supported by this WebGL implementation. The minimum is 16.
* @memberof ContextLimits
* @type {number}
* @see {@link https://www.khronos.org/opengles/sdk/docs/man/xhtml/glGet.xml|glGet} with <code>MAX_VERTEX_ATTRIBS</code>.
* @see {@link https://registry.khronos.org/OpenGL-Refpages/es3.0/html/glGet.xhtml|glGet} with <code>MAX_VERTEX_ATTRIBS</code>.
*/
maximumVertexAttributes: {
get: function () {
Expand All @@ -134,10 +148,10 @@ Object.defineProperties(ContextLimits, {

/**
* The maximum number of texture units that can be used from the vertex shader with this WebGL implementation.
* The minimum is zero, which means the GL does not support vertex texture fetch.
* The minimum is 16.
* @memberof ContextLimits
* @type {number}
* @see {@link https://www.khronos.org/opengles/sdk/docs/man/xhtml/glGet.xml|glGet} with <code>MAX_VERTEX_TEXTURE_IMAGE_UNITS</code>.
* @see {@link https://registry.khronos.org/OpenGL-Refpages/es3.0/html/glGet.xhtml|glGet} with <code>MAX_VERTEX_TEXTURE_IMAGE_UNITS</code>.
*/
maximumVertexTextureImageUnits: {
get: function () {
Expand All @@ -147,10 +161,10 @@ Object.defineProperties(ContextLimits, {

/**
* The maximum number of <code>vec4</code>, <code>ivec4</code>, and <code>bvec4</code>
* uniforms that can be used by a vertex shader with this WebGL implementation. The minimum is 16.
* uniforms that can be used by a vertex shader with this WebGL implementation. The minimum is 256.
* @memberof ContextLimits
* @type {number}
* @see {@link https://www.khronos.org/opengles/sdk/docs/man/xhtml/glGet.xml|glGet} with <code>MAX_VERTEX_UNIFORM_VECTORS</code>.
* @see {@link https://registry.khronos.org/OpenGL-Refpages/es3.0/html/glGet.xhtml|glGet} with <code>MAX_VERTEX_UNIFORM_VECTORS</code>.
*/
maximumVertexUniformVectors: {
get: function () {
Expand All @@ -162,7 +176,7 @@ Object.defineProperties(ContextLimits, {
* The minimum aliased line width, in pixels, supported by this WebGL implementation. It will be at most one.
* @memberof ContextLimits
* @type {number}
* @see {@link https://www.khronos.org/opengles/sdk/docs/man/xhtml/glGet.xml|glGet} with <code>ALIASED_LINE_WIDTH_RANGE</code>.
* @see {@link https://registry.khronos.org/OpenGL-Refpages/es3.0/html/glGet.xhtml|glGet} with <code>ALIASED_LINE_WIDTH_RANGE</code>.
*/
minimumAliasedLineWidth: {
get: function () {
Expand All @@ -174,7 +188,7 @@ Object.defineProperties(ContextLimits, {
* The maximum aliased line width, in pixels, supported by this WebGL implementation. It will be at least one.
* @memberof ContextLimits
* @type {number}
* @see {@link https://www.khronos.org/opengles/sdk/docs/man/xhtml/glGet.xml|glGet} with <code>ALIASED_LINE_WIDTH_RANGE</code>.
* @see {@link https://registry.khronos.org/OpenGL-Refpages/es3.0/html/glGet.xhtml|glGet} with <code>ALIASED_LINE_WIDTH_RANGE</code>.
*/
maximumAliasedLineWidth: {
get: function () {
Expand All @@ -186,7 +200,7 @@ Object.defineProperties(ContextLimits, {
* The minimum aliased point size, in pixels, supported by this WebGL implementation. It will be at most one.
* @memberof ContextLimits
* @type {number}
* @see {@link https://www.khronos.org/opengles/sdk/docs/man/xhtml/glGet.xml|glGet} with <code>ALIASED_POINT_SIZE_RANGE</code>.
* @see {@link https://registry.khronos.org/OpenGL-Refpages/es3.0/html/glGet.xhtml|glGet} with <code>ALIASED_POINT_SIZE_RANGE</code>.
*/
minimumAliasedPointSize: {
get: function () {
Expand All @@ -198,7 +212,7 @@ Object.defineProperties(ContextLimits, {
* The maximum aliased point size, in pixels, supported by this WebGL implementation. It will be at least one.
* @memberof ContextLimits
* @type {number}
* @see {@link https://www.khronos.org/opengles/sdk/docs/man/xhtml/glGet.xml|glGet} with <code>ALIASED_POINT_SIZE_RANGE</code>.
* @see {@link https://registry.khronos.org/OpenGL-Refpages/es3.0/html/glGet.xhtml|glGet} with <code>ALIASED_POINT_SIZE_RANGE</code>.
*/
maximumAliasedPointSize: {
get: function () {
Expand All @@ -210,7 +224,7 @@ Object.defineProperties(ContextLimits, {
* The maximum supported width of the viewport. It will be at least as large as the visible width of the associated canvas.
* @memberof ContextLimits
* @type {number}
* @see {@link https://www.khronos.org/opengles/sdk/docs/man/xhtml/glGet.xml|glGet} with <code>MAX_VIEWPORT_DIMS</code>.
* @see {@link https://registry.khronos.org/OpenGL-Refpages/es3.0/html/glGet.xhtml|glGet} with <code>MAX_VIEWPORT_DIMS</code>.
*/
maximumViewportWidth: {
get: function () {
Expand All @@ -222,7 +236,7 @@ Object.defineProperties(ContextLimits, {
* The maximum supported height of the viewport. It will be at least as large as the visible height of the associated canvas.
* @memberof ContextLimits
* @type {number}
* @see {@link https://www.khronos.org/opengles/sdk/docs/man/xhtml/glGet.xml|glGet} with <code>MAX_VIEWPORT_DIMS</code>.
* @see {@link https://registry.khronos.org/OpenGL-Refpages/es3.0/html/glGet.xhtml|glGet} with <code>MAX_VIEWPORT_DIMS</code>.
*/
maximumViewportHeight: {
get: function () {
Expand Down
37 changes: 19 additions & 18 deletions packages/engine/Source/Renderer/ShaderSource.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -153,14 +153,11 @@ function getBuiltinsAndAutomaticUniforms(shaderSource) {
}

function combineShader(shaderSource, isFragmentShader, context) {
let i;
let length;

// Combine shader sources, generally for pseudo-polymorphism, e.g., czm_getMaterial.
let combinedSources = "";
const sources = shaderSource.sources;
if (defined(sources)) {
for (i = 0, length = sources.length; i < length; ++i) {
for (let i = 0; i < sources.length; ++i) {
Copy link
Member

@donmccurdy donmccurdy Dec 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the cleanup here! Fond memories of being bitten by function-scoped 'var i' loop iterators in the bad old days. :)

// #line needs to be on its own line.
combinedSources += `\n#line 0\n${sources[i]}`;
}
Expand Down Expand Up @@ -225,30 +222,34 @@ function combineShader(shaderSource, isFragmentShader, context) {
let result = "";

const extensionsLength = extensions.length;
for (i = 0; i < extensionsLength; i++) {
for (let i = 0; i < extensionsLength; i++) {
result += extensions[i];
}

if (isFragmentShader) {
// If high precision isn't support replace occurrences of highp with mediump
// The highp keyword is not always available on older mobile devices
// If high precision isn't supported, replace occurrences of highp with mediump.
// The highp keyword is not always available on older mobile devices.
// See https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API/WebGL_best_practices#In_WebGL_1_highp_float_support_is_optional_in_fragment_shaders
result +=
"\
#ifdef GL_FRAGMENT_PRECISION_HIGH\n\
precision highp float;\n\
precision highp int;\n\
#else\n\
precision mediump float;\n\
precision mediump int;\n\
#define highp mediump\n\
#endif\n\n";
result += `
#ifdef GL_FRAGMENT_PRECISION_HIGH
precision highp float;
precision highp int;
#else
precision mediump float;
precision mediump int;
#define highp mediump
#endif
`;
}

if (context.webgl2) {
result += `precision highp sampler3D;\n\n`;
}

// Prepend #defines for uber-shaders
const defines = shaderSource.defines;
if (defined(defines)) {
for (i = 0, length = defines.length; i < length; ++i) {
for (let i = 0, length = defines.length; i < length; ++i) {
const define = defines[i];
if (define.length !== 0) {
result += `#define ${define}\n`;
Expand Down
2 changes: 1 addition & 1 deletion packages/engine/Source/Renderer/Texture.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -398,7 +398,7 @@ function loadBufferSource(texture, source) {
* @param {number} xOffset The texel x coordinate of the lower left corner of the subregion of the texture to be updated.
* @param {number} yOffset The texel y coordinate of the lower left corner of the subregion of the texture to be updated.
* @param {number} width The width of the source data, in pixels.
* @param {number} width The height of the source data, in pixels.
* @param {number} height The height of the source data, in pixels.
*
* @private
*/
Expand Down
Loading