Query GPU Limits with Three.js WebGLCapabilities

When developing high-performance 3D graphics with Three.js, understanding the user’s hardware limitations is crucial for optimization and preventing crashes. This article explains how to use the Three.js WebGLCapabilities object to query critical GPU limits, such as maximum texture size and maximum varying vectors, allowing you to dynamically adjust your application’s graphics settings.

Accessing WebGLCapabilities

In Three.js, you do not instantiate the WebGLCapabilities class directly. Instead, it is automatically instantiated when you create a WebGLRenderer and is exposed via the .capabilities property.

To access these hardware details, you must first initialize your renderer:

import * as THREE from 'three';

// Create the renderer
const renderer = new THREE.WebGLRenderer();

// Access the capabilities object
const capabilities = renderer.capabilities;

Once you have reference to the capabilities object, you can query various read-only properties representing the host machine’s hardware limits.

Querying Maximum Texture Size

Loading a texture that exceeds the GPU’s maximum supported dimensions will result in a WebGL error and a failure to render. You can prevent this by querying maxTextureSize and scaling down your assets if they exceed the hardware limit:

const maxTextureSize = capabilities.maxTextureSize;
console.log(`Maximum supported texture size: ${maxTextureSize}x${maxTextureSize}`);

// Example fallback logic
const targetTextureSize = 8192; // Your preferred size
if (targetTextureSize > maxTextureSize) {
    console.warn(`Target texture size exceeds GPU limit. Downscaling to ${maxTextureSize}.`);
    // Load a lower-resolution asset instead
}

Querying Maximum Varying Vectors

Varying variables are passed from the vertex shader to the fragment shader. If your custom shaders use too many varying vectors, the shader will fail to compile. You can check the hardware limit using the maxVaryings property:

const maxVaryings = capabilities.maxVaryings;
console.log(`Maximum varying vectors: ${maxVaryings}`);

if (maxVaryings < 8) {
    // Enable a simplified shader fallback for low-end devices
}

Other Useful Hardware Queries

The WebGLCapabilities object provides several other properties useful for performance budgeting and feature detection:

• capabilities.maxPrecision: Returns the maximum precision supported by the GPU for shaders ('highp', 'mediump', or 'lowp').
• capabilities.maxVertexTextures: The maximum number of textures that can be accessed in a vertex shader.
• capabilities.maxFragmentUniforms: The maximum number of uniform vectors allowed in a fragment shader.
• capabilities.maxAttributes: The maximum number of vertex attributes that can be defined.

By querying these parameters at runtime, you can build adaptive rendering pipelines that offer rich visuals on high-end desktops while gracefully degrading performance-heavy features on mobile devices and older hardware.