File: WebGLRenderer.md | Updated: 11/15/2025
This renderer uses WebGL 2 to display scenes.
WebGL 1 is not supported since r163.
Constructs a new WebGL renderer.
parameters | The configuration parameter.
---|---
Whether the renderer should automatically clear its output before rendering a frame or not.
Default is true.
If WebGLRenderer#autoClear set to true, whether the renderer should clear the color buffer or not.
Default is true.
If WebGLRenderer#autoClear set to true, whether the renderer should clear the depth buffer or not.
Default is true.
If WebGLRenderer#autoClear set to true, whether the renderer should clear the stencil buffer or not.
Default is true.
Holds details about the capabilities of the current rendering context.
User-defined clipping planes specified in world space. These planes apply globally. Points in space whose dot product with the plane is negative are cut away.
Defines the coordinate system of the renderer.
In WebGLRenderer, the value is always WebGLCoordinateSystem.
Default is WebGLCoordinateSystem.
A object with debug configuration settings.
checkShaderErrors: If it is true, defines whether material shader programs are checked for errors during compilation and linkage process. It may be useful to disable this check in production for performance gain. It is strongly recommended to keep these checks enabled during development. If the shader does not compile and link - it will not work and associated material will not render.onShaderError(gl, program, glVertexShader,glFragmentShader): A callback function that can be used for custom error reporting. The callback receives the WebGL context, an instance of WebGLProgram as well two instances of WebGLShader representing the vertex and fragment shader. Assigning a custom function disables the default error reporting.A canvas where the renderer draws its output.This is automatically created by the renderer in the constructor (if not provided already); you just need to add it to your page like so:
document.body.appendChild( renderer.domElement );
Provides methods for retrieving and testing WebGL extensions.
get(extensionName:string): Used to check whether a WebGL extension is supported and return the extension object if available.has(extensionName:string): returns true if the extension is supported.Holds a series of statistical information about the GPU memory and the rendering process. Useful for debugging and monitoring.
By default these data are reset at each render call but when having multiple render passes per frame (e.g. when using post processing) it can be preferred to reset with a custom pattern. First, set autoReset to false.
renderer.info.autoReset = false;
Call reset() whenever you have finished to render a single frame.
renderer.info.reset();
This flag can be used for type testing.
Default is true.
Whether the renderer respects object-level clipping planes or not.
Default is false.
Defines the output color space of the renderer.
Default is SRGBColorSpace.
Used to track properties of other objects like native WebGL objects.
Manages the render lists of the renderer.
Interface for managing shadows.
Whether the renderer should sort objects or not.
Note: Sorting is used to attempt to properly render objects that have some degree of transparency. By definition, sorting objects may not work in all cases. Depending on the needs of application, it may be necessary to turn off sorting and use other methods to deal with transparency rendering e.g. manually determining each object's rendering order.
Default is true.
Interface for managing the WebGL state.
The tone mapping technique of the renderer.
Default is NoToneMapping.
Exposure level of tone mapping.
Default is 1.
The normalized resolution scale for the transmission render target, measured in percentage of viewport dimensions. Lowering this value can result in significant performance improvements when using MeshPhysicalMaterial#transmission.
Default is 1.
A reference to the XR manager.
Tells the renderer to clear its color, depth or stencil drawing buffer(s). This method initializes the buffers to the current clear color values.
color | Whether the color buffer should be cleared or not. Default is true.
---|---
depth | Whether the depth buffer should be cleared or not. Default is true.
stencil | Whether the stencil buffer should be cleared or not. Default is true.
Clears the color buffer. Equivalent to calling renderer.clear( true, false, false ).
Clears the depth buffer. Equivalent to calling renderer.clear( false, true, false ).
Clears the stencil buffer. Equivalent to calling renderer.clear( false, false, true ).
Compiles all materials in the scene with the camera. This is useful to precompile shaders before the first rendering. If you want to add a 3D object to an existing scene, use the third optional parameter for applying the target scene.
Note that the (target) scene's lighting and environment must be configured before calling this method.
scene | The scene or another type of 3D object to precompile.
---|---
camera | The camera.
targetScene | The target scene. Default is null.
Returns: The precompiled materials.
Asynchronous version of WebGLRenderer#compile.
This method makes use of the KHR_parallel_shader_compile WebGL extension. Hence, it is recommended to use this version of compile() whenever possible.
scene | The scene or another type of 3D object to precompile.
---|---
camera | The camera.
targetScene | The target scene. Default is null.
Returns: A Promise that resolves when the given scene can be rendered without unnecessary stalling due to shader compilation.
Copies pixels from the current bound framebuffer into the given texture.
texture | The texture.
---|---
position | The start position of the copy operation. Default is null.
level | The mip level. The default represents the base mip. Default is 0.
Copies data of the given source texture into a destination texture.
When using render target textures as srcTexture and dstTexture, you must make sure both render targets are initialized WebGLRenderer#initRenderTarget.
srcTexture | The source texture.
---|---
dstTexture | The destination texture.
srcRegion | A bounding box which describes the source region. Can be two or three-dimensional. Default is null.
dstPosition | A vector that represents the origin of the destination region. Can be two or three-dimensional. Default is null.
srcLevel | The source mipmap level to copy. Default is 0.
dstLevel | The destination mipmap level. Default is null.
Frees the GPU-related resources allocated by this instance. Call this method whenever this instance is no longer used in your app.
Simulates a loss of the WebGL context. This requires support for the WEBGL_lose_context extension.
Simulates a restore of the WebGL context. This requires support for the WEBGL_lose_context extension.
Returns the active cube face.
Returns: The active cube face.
Returns the active mipmap level.
Returns: The active mipmap level.
Returns the clear alpha. Ranges within [0,1].
Returns: The clear alpha.
Returns the clear color.
target | The method writes the result in this target object.
---|---
Returns: The clear color.
Returns the rendering context.
Returns: The rendering context.
Returns the rendering context attributes.
Returns: The rendering context attributes.
Returns the current viewport definition.
target | The method writes the result in this target object.
---|---
Returns: The current viewport definition.
Returns the drawing buffer size in physical pixels. This method honors the pixel ratio.
target | The method writes the result in this target object.
---|---
Returns: The drawing buffer size.
Returns the pixel ratio.
Returns: The pixel ratio.
Returns the active render target.
Returns: The active render target. Returns null if no render target is currently set.
Returns the scissor region.
target | The method writes the result in this target object.
---|---
Returns: The scissor region.
Returns true if the scissor test is enabled.
Returns: Whether the scissor test is enabled or not.
Returns the renderer's size in logical pixels. This method does not honor the pixel ratio.
target | The method writes the result in this target object.
---|---
Returns: The renderer's size in logical pixels.
Returns the viewport definition.
target | The method writes the result in this target object.
---|---
Returns: The viewport definition.
Initializes the given WebGLRenderTarget memory. Useful for initializing a render target so data can be copied into it using WebGLRenderer#copyTextureToTexture before it has been rendered to.
target | The render target.
---|---
Initializes the given texture. Useful for preloading a texture rather than waiting until first render (which can cause noticeable lags due to decode and GPU upload overhead).
texture | The texture.
---|---
Reads the pixel data from the given render target into the given buffer.
renderTarget | The render target to read from.
---|---
x | The x coordinate of the copy region's origin.
y | The y coordinate of the copy region's origin.
width | The width of the copy region.
height | The height of the copy region.
buffer | The result buffer.
activeCubeFaceIndex | The active cube face index.
textureIndex | The texture index of an MRT render target. Default is 0.
Asynchronous, non-blocking version of WebGLRenderer#readRenderTargetPixels.
It is recommended to use this version of readRenderTargetPixels() whenever possible.
renderTarget | The render target to read from.
---|---
x | The x coordinate of the copy region's origin.
y | The y coordinate of the copy region's origin.
width | The width of the copy region.
height | The height of the copy region.
buffer | The result buffer.
activeCubeFaceIndex | The active cube face index.
textureIndex | The texture index of an MRT render target. Default is 0.
Returns: A Promise that resolves when the read has been finished. The resolve provides the read data as a typed array.
Renders the given scene (or other type of 3D object) using the given camera.
The render is done to a previously specified render target set by calling WebGLRenderer#setRenderTarget or to the canvas as usual.
By default render buffers are cleared before rendering but you can prevent this by setting the property autoClear to false. If you want to prevent only certain buffers being cleared you can autoClearColor, autoClearDepth or autoClearStencil to false. To force a clear, use WebGLRenderer#clear.
scene | The scene to render.
---|---
camera | The camera.
Can be used to reset the internal WebGL state. This method is mostly relevant for applications which share a single WebGL context across multiple WebGL libraries.
Applications are advised to always define the animation loop with this method and not manually with requestAnimationFrame() for best compatibility.
callback | The application's animation loop.
---|---
Sets the clear alpha.
alpha | The clear alpha.
---|---
Sets the clear color and alpha.
color | The clear color.
---|---
alpha | The clear alpha. Default is 1.
This method allows to define the drawing buffer size by specifying width, height and pixel ratio all at once. The size of the drawing buffer is computed with this formula:
size.x = width * pixelRatio;
size.y = height * pixelRatio;
width | The width in logical pixels.
---|---
height | The height in logical pixels.
pixelRatio | The pixel ratio.
Sets a custom opaque sort function for the render lists. Pass null to use the default painterSortStable function.
method | The opaque sort function.
---|---
Sets the given pixel ratio and resizes the canvas if necessary.
value | The pixel ratio.
---|---
Sets the active rendertarget.
renderTarget | The render target to set. When null is given, the canvas is set as the active render target instead.
---|---
activeCubeFace | The active cube face when using a cube render target. Indicates the z layer to render in to when using 3D or array render targets. Default is 0.
activeMipmapLevel | The active mipmap level. Default is 0.
Sets the scissor region to render from (x, y) to (x + width, y + height).
x | The horizontal coordinate for the lower left corner of the scissor region origin in logical pixel unit. Or alternatively a four-component vector specifying all the parameters of the scissor region.
---|---
y | The vertical coordinate for the lower left corner of the scissor region origin in logical pixel unit.
width | The width of the scissor region in logical pixel unit.
height | The height of the scissor region in logical pixel unit.
Enable or disable the scissor test. When this is enabled, only the pixels within the defined scissor area will be affected by further renderer actions.
boolean | Whether the scissor test is enabled or not.
---|---
Resizes the output canvas to (width, height) with device pixel ratio taken into account, and also sets the viewport to fit that size, starting in (0, 0). Setting updateStyle to false prevents any style changes to the output canvas.
width | The width in logical pixels.
---|---
height | The height in logical pixels.
updateStyle | Whether to update the style attribute of the canvas or not. Default is true.
Sets a custom transparent sort function for the render lists. Pass null to use the default reversePainterSortStable function.
method | The opaque sort function.
---|---
Sets the viewport to render from (x, y) to (x + width, y + height).
x | The horizontal coordinate for the lower left corner of the viewport origin in logical pixel unit. Or alternatively a four-component vector specifying all the parameters of the viewport.
---|---
y | The vertical coordinate for the lower left corner of the viewport origin in logical pixel unit.
width | The width of the viewport in logical pixel unit.
height | The height of the viewport in logical pixel unit.
WebGLRenderer Capabilities.
getMaxAnisotropy
function | Returns the maximum available anisotropy.
---|---
getMaxPrecision
function | Returns the maximum available precision for vertex and fragment shaders.
logarithmicDepthBuffer
boolean | true if logarithmicDepthBuffer was set to true in the constructor.
maxAttributes
number | The number of shader attributes that can be used by the vertex shader.
maxCubemapSize
number | Maximum height * width of cube map textures that a shader can use.
maxFragmentUniforms
number | The number of uniforms that can be used by a fragment shader.
maxSamples
number | Maximum number of samples in context of Multisample anti-aliasing (MSAA).
maxTextures
number | The maximum number of textures that can be used by a shader.
maxTextureSize
number | Maximum height * width of a texture that a shader use.
maxVaryings
number | The number of varying vectors that can used by shaders.
maxVertexTextures
number | The number of textures that can be used in a vertex shader.
maxVertexUniforms
number | The maximum number of uniforms that can be used in a vertex shader.
precision
string | The shader precision currently being used by the renderer.
reversedDepthBuffer
boolean | true if reversedDepthBuffer was set to true in the constructor and the rendering context supports EXT_clip_control.
vertexTextures
boolean | true if vertex textures can be used.
WebGLRenderer Info
autoReset
boolean | Whether to automatically reset the info by the renderer or not. Default is true.
---|---
memory
WebGLRenderer~InfoMemory | Information about allocated objects.
render
WebGLRenderer~InfoRender | Information about rendered objects.
programs
Array.<WebGLProgram> | An array WebGLPrograms used for rendering.
reset
function | Resets the info object for the next frame.
WebGLRenderer Info Memory
geometries
number | The number of active geometries.
---|---
textures
number | The number of active textures.
WebGLRenderer Info Render
frame
number | The frame ID.
---|---
calls
number | The number of draw calls per frame.
triangles
number | The number of rendered triangles primitives per frame.
points
number | The number of rendered points primitives per frame.
lines
number | The number of rendered lines primitives per frame.
WebGLRenderer options.
canvas
HTMLCanvasElement | OffscreenCanvas | A canvas element where the renderer draws its output. If not passed in here, a new canvas element will be created by the renderer. Default is null.
---|---
context
WebGL2RenderingContext | Can be used to attach an existing rendering context to this renderer. Default is null.
precision
'highp' | 'mediump' | 'lowp' | The default shader precision. Uses highp if supported by the device. Default is 'highp'.
alpha
boolean | Controls the default clear alpha value. When set totrue, the value is 0. Otherwise it's 1. Default is false.
premultipliedAlpha
boolean | Whether the renderer will assume colors have premultiplied alpha or not. Default is true.
antialias
boolean | Whether to use the default MSAA or not. Default is false.
stencil
boolean | Whether the drawing buffer has a stencil buffer of at least 8 bits or not. Default is false.
preserveDrawingBuffer
boolean | Whether to preserve the buffer until manually cleared or overwritten. Default is false.
powerPreference
'default' | 'low-power' | 'high-performance' | Provides a hint to the user agent indicating what configuration of GPU is suitable for this WebGL context. Default is 'default'.
failIfMajorPerformanceCaveat
boolean | Whether the renderer creation will fail upon low performance is detected. Default is false.
depth
boolean | Whether the drawing buffer has a depth buffer of at least 16 bits. Default is true.
logarithmicDepthBuffer
boolean | Whether to use a logarithmic depth buffer. It may be necessary to use this if dealing with huge differences in scale in a single scene. Note that this setting uses gl_FragDepth if available which disables the Early Fragment Test optimization and can cause a decrease in performance. Default is false.
reversedDepthBuffer
boolean | Whether to use a reverse depth buffer. Requires the EXT_clip_control extension. This is a more faster and accurate version than logarithmic depth buffer. Default is false.
WebGLRenderer Shadow Map.
enabled
boolean | If set to true, use shadow maps in the scene. Default is false.
---|---
autoUpdate
boolean | Enables automatic updates to the shadows in the scene. If you do not require dynamic lighting / shadows, you may set this to false. Default is true.
needsUpdate
boolean | When set to true, shadow maps in the scene will be updated in the next render call. Default is false.
type
BasicShadowMap | PCFShadowMap | PCFSoftShadowMap | VSMShadowMap | Defines the shadow map type. Default is PCFShadowMap.