WebGLRenderer - Verge3D User Manual - Soft8Soft
Description: Learn how to use WebGLRenderer in your interactive 3D apps made with Verge3D

# WebGLRenderer

WebGLRenderer displays your 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>` element 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.
  alpha
    Controls the default clear alpha value. When set to `true`, the value is `0`. Otherwise it's `1`. 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`.

## 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

Object with debug parameters:

- 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`.
- disableCompiledShaderCache — disables browser cache for compiled shaders by adding a random constant expression to shader source code. Default is `false`.

### # .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.
maxSamples
  The value of `gl.MAX_SAMPLES`. Maximum number of samples in context of multisample anti-aliasing (MSAA).
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 is greater than 0 (i.e. vertex textures can be used).

### # .domElement : HTMLCanvasElement

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): Checks whether `extensionName` is supported and returns an object with details of the extension if available.

has(extensionName : String): Checks whether `extensionName` is supported.

These methods are known to work the following extensions:

- `ANGLE_instanced_arrays`
- `EXT_blend_minmax`
- `EXT_color_buffer_float`
- `EXT_color_buffer_half_float`
- `EXT_disjoint_timer_query_webgl`
- `EXT_disjoint_timer_query_webgl2`
- `EXT_sRGB`
- `EXT_texture_compression_bptc`
- `EXT_texture_filter_anisotropic`
- `KHR_parallel_shader_compile`
- `OES_element_index_uint`
- `OES_standard_derivatives`
- `OES_texture_float`
- `OES_texture_float_linear`
- `OES_texture_half_float`
- `OES_texture_half_float_linear`
- `OES_vertex_array_object`
- `WEBGL_compressed_texture_etc`
- `WEBGL_compressed_texture_etc1`
- `WEBGL_compressed_texture_pvrtc`
- `WEBGL_compressed_texture_s3tc_srgb`
- `WEBGL_compressed_texture_s3tc`
- `WEBGL_debug_renderer_info`
- `WEBGL_depth_texture`
- `WEBGL_draw_buffers`
- `WEBGL_lose_context`
- `WEBGL_multisampled_render_to_texture`

### # .gtaoMap : Texture

Ambient occlusion map generated by GTAOMapGenerator.

### # .gtaoMapEnabled : Boolean

Defines whether the .gtaoMap should be applied on the rendered objects.

### # .outputEncoding : Integer

Defines the output encoding of the renderer. Default is v3d.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
  - textureSpecs
- render:
  - frame
  - calls
  - triangles
  - points
  - lines
  - customCounter
- programs
- numShaderCompiles

### # .localClippingEnabled : Boolean

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

### # .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. Options are:
  - v3d.BasicShadowMap
  - v3d.BilinearShadowMap
  - v3d.PCFShadowMap (default)
  - v3d.ESMShadowMap
  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 : Float

Exposure level of tone mapping. Default is `1`.

### # .toneMappingLook : Constant

Tone mapping look used for the AgX tone mapping.

### # .unitsScaleFactor : Float

Units scale factor used for calculating light distance attenuation. Default is `1`.

### # .xr : WebXRManager

Provides access to the WebXR related interface of the renderer.

## Methods

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

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

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

### # .clearDepth()

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

### # .clearStencil()

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

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

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

### # .compileAsync(scene : Scene, camera : Camera, progressCb : Function)

Compiles all materials in the scene with the camera asynchronously. This is useful to precompile shaders before the first rendering. The optional `progressCb` function receives a `percentage` parameter.

### # .copyFramebufferToTexture(position : Vector2, texture : FramebufferTexture, level : Integer)

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

### # .copyTextureToTexture(position : Vector2, srcTexture : Texture, dstTexture : Texture, level : Integer)

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 : Integer)

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

Frees the GPU-related resources allocated by this instance. Call this method whenever this instance is no longer used in your app.

### # .forceContextLoss()

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

### # .forceContextRestore()

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 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() → Float

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)

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

Reset the WebGL 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)

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

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

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

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 an async version of .readRenderTargetPixels with increased performance.

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

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

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 or more buffers call .clear.

### # .resetState()

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)

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)

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

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

Sets the clear color and opacity.

### # .setPixelRatio(value : Float)

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

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

- 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. When passing a WebGLArrayRenderTarget or WebGL3DRenderTarget this indicates the z layer to render in to (optional).
- activeMipmapLevel — specifies the active mipmap level (optional).

This method sets the active render target.

### # .setScissor(x : Integer, y : Integer, width : Integer, height : Integer)
# .setScissor(vector : Vector4)

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)

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)

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

### # .setTransparentSort(method : Function)

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

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

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)
# .setViewport(vector : Vector4)

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.

## Source

For more info on how to obtain the source code of this module see this page.