ThreeJS Renderers

WebGLMultipleRenderTargets

A special render target that enables a fragment shader to write to several textures. This approach is useful for advanced rendering techniques like post-processing or deferred rendering. Heads up: WebGLMultipleRenderTargets can only be used with a WebGL 2 rendering context.

Constructor

WebGLMultipleRenderTargets(width : Number, height : Number, count : Number, options : Object)

width - The width of the render target.

height - The height of the render target.

count - The number of render targets.

options - (optional object that holds texture parameters for an auto-generated target texture and depthBuffer/stencilBuffer booleans. For an explanation of the texture parameters see Texture. For a list of valid options, see WebGLRenderTarget.

Properties

.isWebGLMultipleRenderTargets : Boolean

Read-only flag to check whether a given object is of type WebGLMultipleRenderTargets.

.texture : Array

The texture property is overwritten in WebGLMultipleRenderTargets and replaced with an array. This array holds the texture references of the respective render targets.

WebGLRenderTarget properties are available on this class.

Methods

WebGLRenderTarget methods are available on this class.

WebGLRenderer

The WebGL renderer displays your beautifully crafted scenes using WebGL.

Constructor

WebGLRenderer( parameters : Object )

parameters - (optional) object with properties defining the renderer's behaviour. The constructor also accepts no parameters at all. In all cases, it will assume sane defaults when parameters are missing. The following are valid parameters:

canvas - A canvas where the renderer draws its output. This corresponds to the domElement property below. If not passed in here, a new canvas element will be created.

context - This can be used to attach the renderer to an existing RenderingContext. Default is null.

precision - Shader precision. Can be "highp", "mediump" or "lowp". Defaults to "highp" if supported by the device. See the note in "Things to Avoid" here.

alpha - whether the canvas contains an alpha (transparency) buffer or not. Default is false.

premultipliedAlpha - whether the renderer will assume that colors have premultiplied alpha. Default is true.

antialias - whether to perform antialiasing. Default is false.

stencil - whether the drawing buffer has a stencil buffer of at least 8 bits. Default is true.

preserveDrawingBuffer - whether to preserve the buffers until manually cleared or overwritten. Default is false.

powerPreference - Provides a hint to the user agent indicating what configuration of GPU is suitable for this WebGL context. Can be "high-performance", "low-power" or "default". Default is "default". See WebGL spec for details.

failIfMajorPerformanceCaveat - whether the renderer creation will fail upon low performance is detected. Default is false. See WebGL spec for details.

depth - whether the drawing buffer has a depth buffer of at least 16 bits. Default is true.

logarithmicDepthBuffer - 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. See the camera / logarithmicdepthbuffer example.

Properties

.autoClear : Boolean

Defines whether the renderer should automatically clear its output before rendering a frame.

.autoClearColor : Boolean

If autoClear is true, defines whether the renderer should clear the color buffer. Default is true.

.autoClearDepth : Boolean

If autoClear is true, defines whether the renderer should clear the depth buffer. Default is true.

.autoClearStencil : Boolean

If autoClear is true, defines whether the renderer should clear the stencil buffer. Default is true.

.debug : Object

- 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. Default is true.

.capabilities : Object

An object containing details about the capabilities of the current RenderingContext.

• - floatFragmentTextures: whether the context supports the OES_texture_float extension.
• - floatVertexTextures: true if floatFragmentTextures and vertexTextures are both true.
• - getMaxAnisotropy(): Returns the maximum available anisotropy.
• - getMaxPrecision(): Returns the maximum available precision for vertex and fragment shaders.
• - isWebGL2: true if the context in use is a WebGL2RenderingContext object.
• - logarithmicDepthBuffer: true if the logarithmicDepthBuffer was set to true in the constructor and the context supports the EXT_frag_depth extension.
• - maxAttributes: The value of gl.MAX_VERTEX_ATTRIBS.
• - maxCubemapSize: The value of gl.MAX_CUBE_MAP_TEXTURE_SIZE. Maximum height * width of cube map textures that a shader can use.
• - maxFragmentUniforms: The value of gl.MAX_FRAGMENT_UNIFORM_VECTORS. The number of uniforms that can be used by a fragment shader.
• - maxTextureSize: The value of gl.MAX_TEXTURE_SIZE. Maximum height * width of a texture that a shader use.
• - maxTextures: The value of gl.MAX_TEXTURE_IMAGE_UNITS. The maximum number of textures that can be used by a shader.
• - maxVaryings: The value of gl.MAX_VARYING_VECTORS. The number of varying vectors that can used by shaders.
• - maxVertexTextures: The value of gl.MAX_VERTEX_TEXTURE_IMAGE_UNITS. The number of textures that can be used in a vertex shader.
• - maxVertexUniforms: The value of gl.MAX_VERTEX_UNIFORM_VECTORS. The maximum number of uniforms that can be used in a vertex shader.
• - precision: The shader precision currently being used by the renderer.
• - vertexTextures: true if .maxVertexTextures : Integeris greater than 0 (i.e. vertex textures can be used).

.clippingPlanes : Array

User-defined clipping planes specified as THREE.Plane objects in world space. These planes apply globally. Points in space whose dot product with the plane is negative are cut away. Default is [].

.domElement : DOMElement

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 );

.extensions : Object

- get( extensionName : String ): Used to check whether various extensions are supported and returns an object with details of the extension if available. This method can check for the following extensions:

• WEBGL_depth_texture
• EXT_texture_filter_anisotropic
• WEBGL_compressed_texture_s3tc
• WEBGL_compressed_texture_pvrtc
• WEBGL_compressed_texture_etc1

.outputEncoding : number

Defines the output encoding of the renderer. Default is THREE.LinearEncoding.

If a render target has been set using .setRenderTarget then renderTarget.texture.encoding will be used instead.

See the texture constants page for details of other formats.

.info : Object

An object with a series of statistical information about the graphics board memory and the rendering process. Useful for debugging or just for the sake of curiosity. The object contains the following fields:

• memory:
  • geometries
  • Textures
• render:
  • calls
  • triangles
  • points
  • lines
  • Frame
• programs

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();

.localClippingEnabled : Boolean

Defines whether the renderer respects object-level clipping planes. Default is false.

.physicallyCorrectLights : Boolean

Whether to use physically correct lighting mode. Default is false. See the lights / physical example.

.properties : Object

Used internally by the renderer to keep track of various sub object properties.

.renderLists : WebGLRenderLists

Used internally to handle ordering of scene object rendering.

.shadowMap : WebGLShadowMap

This contains the reference to the shadow map, if used.

- enabled: If set, use shadow maps in the scene. Default is false.

- autoUpdate: Enables automatic updates to the shadows in the scene. Default is true.

If you do not require dynamic lighting / shadows, you may set this to false when the renderer is instantiated.

- needsUpdate: When set to true, shadow maps in the scene will be updated in the next render call. Default is false.

If you have disabled automatic updates to shadow maps (shadowMap.autoUpdate = false), you will need to set this to true and then make a render call to update the shadows in your scene.

- type: Defines shadow map type (unfiltered, percentage close filtering, percentage close filtering with bilinear filtering in shader). Options are:

• BasicShadowMap
• PCFShadowMap (default)
• PCFSoftShadowMap
• VSMShadowMap

See Renderer constants for details.

.sortObjects : Boolean

Defines whether the renderer should sort objects. Default is true.

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.

.state : Object

Contains functions for setting various properties of the WebGLRenderer.context state.

.toneMapping : Constant

Default is NoToneMapping. See the Renderer constants for other choices.

.toneMappingExposure : Number

Exposure level of tone mapping. Default is 1.

.xr : WebXRManager

Provides access to the WebXR related interface of the renderer.

Methods

.clear ( color : Boolean, depth : Boolean, stencil : Boolean ) : undefined

Tells the renderer to clear its color, depth or stencil drawing buffer(s). This method initializes the color buffer to the current clear color value.

Arguments default to true.

.clearColor ( ) : undefined

Clear the color buffer. Equivalent to calling .clear( true, false, false ).

.clearDepth ( ) : undefined

Clear the depth buffer. Equivalent to calling .clear( false, true, false ).

.clearStencil ( ) : undefined

Clear the stencil buffers. Equivalent to calling .clear( false, false, true ).

.compile ( scene : Object3D, camera : Camera ) : undefined

Compiles all materials in the scene with the camera. This is useful to precompile shaders before the first rendering.

.copyFramebufferToTexture ( position : Vector2, texture : FramebufferTexture, level : Number ) : undefined

Copies pixels from the current WebGLFramebuffer into a 2D texture. Enables access to WebGLRenderingContext.copyTexImage2D.

.copyTextureToTexture ( position : Vector2, srcTexture : Texture, dstTexture : Texture, level : Number ) : undefined

Copies all pixels of a texture to an existing texture starting from the given position. Enables access to WebGLRenderingContext.texSubImage2D.

.copyTextureToTexture3D ( sourceBox : Box3, position : Vector3, srcTexture : Texture, dstTexture : Texture, level : Number ) : undefined

Copies the pixels of a texture in the bounds 'sourceBox' in the destination texture starting from the given position. Enables access to WebGL2RenderingContext.texSubImage3D.

.dispose ( ) : undefined

Dispose of the current rendering context.

.forceContextLoss () : undefined

Simulate loss of the WebGL context. This requires support for the WEBGL_lose_context extensions.

.forceContextRestore ( ) : undefined

Simulate restore of the WebGL context. This requires support for the WEBGL_lose_context extensions.

.getClearAlpha () : Float

Returns a float with the current clear alpha. Ranges from 0 to 1.

.getClearColor ( target : Color ) : Color

Returns a THREE.Color instance with the current clear color.

.getContext () : WebGL2RenderingContext

Return the current WebGL context.

.getContextAttributes () : WebGLContextAttributes

Returns an object that describes the attributes set on the WebGL context when it was created.

.getActiveCubeFace () : Integer

Returns the current active cube face.

.getActiveMipmapLevel () : Integer

Returns the current active mipmap level.

.getRenderTarget () : RenderTarget

Returns the current RenderTarget if there are; returns null otherwise.

.getCurrentViewport ( target : Vector4 ) : Vector4

target — the result will be copied into this Vector4.

Returns the current viewport.

.getDrawingBufferSize ( target : Vector2 ) : Vector2

target — the result will be copied into this Vector2.

Returns the width and height of the renderer's drawing buffer, in pixels.

.getPixelRatio () : number

Returns current device pixel ratio used.

.getScissor ( target : Vector4 ) : Vector4

target — the result will be copied into this Vector4.

Returns the scissor region.

.getScissorTest () : Boolean

Returns true if scissor test is enabled; returns false otherwise.

.getSize ( target : Vector2 ) : Vector2

target — the result will be copied into this Vector2.

Returns the width and height of the renderer's output canvas, in pixels.

.getViewport ( target : Vector4 ) : Vector4

target — the result will be copied into this Vector4.

Returns the viewport.

.initTexture ( texture : Texture ) : undefined

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).

.resetGLState ( ) : undefined

Reset the GL state to default. Called internally if the WebGL context is lost.

.readRenderTargetPixels ( renderTarget : WebGLRenderTarget, x : Float, y : Float, width : Float, height : Float, buffer : TypedArray, activeCubeFaceIndex : Integer ) : undefined

buffer - Uint8Array is the only destination type supported in all cases, other types are renderTarget and platform dependent. See WebGL spec for details.

Reads the pixel data from the renderTarget into the buffer you pass in. This is a wrapper around WebGLRenderingContext.readPixels().

See the interactive / cubes / gpu example.

For reading out a WebGLCubeRenderTarget use the optional parameter activeCubeFaceIndex to determine which face should be read.

.render ( scene : Object3D, camera : Camera ) : undefined

Render a scene or another type of object using a camera.

The render is done to a previously specified renderTarget set by calling .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 set either the autoClearColor, autoClearStencil or autoClearDepth properties to false. To forcibly clear one ore more buffers call .clear.

.resetState () : undefined

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.

.setAnimationLoop ( callback : Function ) : undefined

callback — The function will be called every available frame. If `null` is passed it will stop any already ongoing animation.

A built in function that can be used instead of requestAnimationFrame. For WebXR projects this function must be used.

.setClearAlpha ( alpha : Float ) : undefined

Sets the clear alpha. Valid input is a float between 0.0 and 1.0.

.setClearColor ( color : Color, alpha : Float ) : undefined

Sets the clear color and opacity.

.setPixelRatio ( value : number ) : undefined

Sets device pixel ratio. This is usually used for HiDPI device to prevent blurring output canvas.

.setRenderTarget ( renderTarget : WebGLRenderTarget, activeCubeFace : Integer, activeMipmapLevel : Integer ) : undefined

renderTarget -- The renderTarget that needs to be activated. When null is given, the canvas is set as the active render target instead.

activeCubeFace -- Specifies the active cube side (PX 0, NX 1, PY 2, NY 3, PZ 4, NZ 5) of WebGLCubeRenderTarget (optional).

activeMipmapLevel -- Specifies the active mipmap level (optional).

This method sets the active rendertarget.

.setScissor ( x : Integer, y : Integer, width : Integer, height : Integer ) : undefined

.setScissor ( vector : Vector4 ) : undefined

The x, y, width, and height parameters of the scissor region.

Optionally, a 4-component vector specifying the parameters of the region.

Sets the scissor region from (x, y) to (x + width, y + height).

(x, y) is the lower-left corner of the scissor region.

.setScissorTest ( boolean : Boolean ) : undefined

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.

.setOpaqueSort ( method : Function ) : undefined

Sets the custom opaque sort function for the WebGLRenderLists. Pass null to use the default painterSortStable function.

.setTransparentSort ( method : Function ) : undefined

Sets the custom transparent sort function for the WebGLRenderLists. Pass null to use the default reversePainterSortStable function.

.setSize ( width : Integer, height : Integer, updateStyle : Boolean ) : undefined

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.

.setViewport ( x : Integer, y : Integer, width : Integer, height : Integer ) : undefined

.setViewport ( vector : Vector4 ) : undefined

The x, y, width, and height parameters of the viewport.

Optionally, a 4-component vector specifying the parameters of a viewport.

Sets the viewport to render from (x, y) to (x + width, y + height).

(x, y) is the lower-left corner of the region.

WebGL1Renderer

Since r118 WebGLRenderer automatically uses a WebGL 2 rendering context. When upgrading an existing project to => r118, applications might break because of two reasons:

Custom shader code needs to be GLSL 3.0 conform.

WebGL 1 extension checks have to be changed.

If you can't afford the time to upgrade your code but still want to use the latest version, you can use WebGL1Renderer. This version of the renderer will enforce a WebGL 1 rendering context.

Constructor

WebGL1Renderer( parameters : Object )

Creates a new WebGL1Renderer.

Properties

See the base WebGLRenderer class for common properties.

.isWebGL1Renderer : Boolean

Read-only flag to check whether a given object is of type WebGL1Renderer.

Methods

See the base WebGLRenderer class for common methods.

WebGLRenderTarget

A render target is a buffer where the video card draws pixels for a scene that is being rendered in the background. It is used in different effects, such as applying postprocessing to a rendered image before displaying it on the screen.

Constructor

WebGLRenderTarget(width : Number, height : Number, options : Object)

width - The width of the renderTarget.

height - The height of the renderTarget.

options - (optional object that holds texture parameters for an auto-generated target texture and depthBuffer/stencilBuffer booleans. For an explanation of the texture parameters see Texture. The following are valid options:

wrapS - default is ClampToEdgeWrapping.

wrapT - default is ClampToEdgeWrapping.

magFilter - default is LinearFilter.

minFilter - default is LinearFilter.

generateMipmaps - default is false.

format - default is RGBAFormat.

type - default is UnsignedByteType.

anisotropy - default is 1. See Texture.anisotropy

encoding - default is LinearEncoding.

depthBuffer - default is true.

stencilBuffer - default is false.

Creates a new WebGLRenderTarget

Properties

.isWebGLRenderTarget : Boolean

Read-only flag to check whether a given object is of type WebGLRenderTarget.

.width : number

The width of the render target.

.height : number

The height of the render target.

.scissor : Vector4

A rectangular area inside the render target's viewport. Fragments that are outside the area will be discarded.

.scissorTest : Boolean

Indicates whether the scissor test is active or not.

.viewport : Vector4

The viewport of this render target.

.texture : Texture

This texture instance holds the rendered pixels. Use it as input for further processing.

.depthBuffer : Boolean

Renders to the depth buffer. Default is true.

.stencilBuffer : Boolean

Renders to the stencil buffer. Default is false.

.depthTexture : DepthTexture

If set, the scene depth will be rendered to this texture. Default is null.

.samples : Number

Defines the count of MSAA samples. Can only be used with WebGL 2. Default is 0.

Methods

.setSize ( width : Number, height : Number ) : undefined

Sets the size of the render target.

.clone () : WebGLRenderTarget

Creates a copy of this render target.

.copy ( source : WebGLRenderTarget ) : this

Adopts the settings of the given render target.

.dispose () : undefined

Dispatches a dispose event.

EventDispatcher methods are available on this class.

WebGL3DRenderTarget

Represents a three-dimensional render target.

Constructor

WebGL3DRenderTarget( width : Number, height : Number, depth : Number )

width - the width of the render target, in pixels.

height - the height of the render target, in pixels.

depth - the depth of the render target.

Creates a new WebGL3DRenderTarget.

Properties

See WebGLRenderTarget for inherited properties

.depth : number

The depth of the render target.

.texture : Data3DTexture

The texture property is overwritten with an instance of Data3DTexture.

Methods

See WebGLRenderTarget for inherited methods

WebGLArrayRenderTarget

This type of render target represents an array of textures.

Examples

WebGL 2 / render target / array

Constructor

WebGLArrayRenderTarget( width : Number, height : Number, depth : Number )

width - the width of the render target, in pixels.

height - the height of the render target, in pixels.

depth - the depth/layer count of the render target.

Creates a new WebGLArrayRenderTarget.

Properties

See WebGLRenderTarget for inherited properties

.depth : number

The depth of the render target.

.texture : DataArrayTexture

The texture property is overwritten with an instance of DataArrayTexture.

Methods

See WebGLRenderTarget for inherited methods

WebGLCubeRenderTarget

Used by the CubeCamera as its WebGLRenderTarget.

Examples

See CubeCamera for examples.

Constructor

WebGLCubeRenderTarget(size : Number, options : Object)

size - the size, in pixels.

options - (optional) object that holds texture parameters for an auto-generated target texture and depthBuffer/stencilBuffer booleans. For an explanation of the texture parameters see Texture. The following are valid options:

wrapS - default is ClampToEdgeWrapping.

wrapT - default is ClampToEdgeWrapping.

magFilter - default is .LinearFilter.

minFilter - default is LinearFilter.

generateMipmaps - default is false.

format - default is RGBAFormat.

type - default is UnsignedByteType.

anisotropy - default is 1. See Texture.anisotropy

encoding - default is LinearEncoding.

depthBuffer - default is true.

stencilBuffer - default is false.

Creates a new WebGLCubeRenderTarget

Properties

See WebGLRenderTarget for inherited properties

Methods

See WebGLRenderTarget for inherited methods

.fromEquirectangularTexture ( renderer : WebGLRenderer, texture : Texture ) : this

renderer — the renderer.

texture — the equirectangular texture.

Use this method if you want to convert an equirectangular panorama to the cube map format.

.clear ( renderer : WebGLRenderer, color : Boolean, depth : Boolean, stencil : Boolean ) : undefined

Call this to clear the renderTarget's color, depth, and/or stencil buffers. The color buffer is set to the renderer's current clear color. Arguments default to true.