WebGL and extensions

JSAR implements the WebGL and WebGL 2.0 standards, and also provides some WebGL extensions to enhance the graphics rendering capabilities. Here you can find the references about the WebGL and WebGL extensions that JSAR supports.

Convention

In this document, we will use the following convention to describe implementation status:

Code	Description
NI	Not Implemented
PI	Partially Implemented
YI	Yet to be Implemented

WebGL APIs

In this section, we will provide the implementation status of the WebGL APIs in JSAR.

Class WebGLRenderingContext

The WebGLRenderingContext interface provides the WebGL rendering context for the drawing surface. It is part of the WebGL API and is used to draw graphics on the scene.

Constants

All the constants defined in the WebGLRenderingContext interface are supported in JSAR, see the MDN's WebGL constants page for more details.

The WebGL context

The following properties and methods provide general information and functionality to deal with the WebGL context:

WebGLRenderingContext.canvas

A read-only back-reference to the HTMLCanvasElement. Might be null if it is not associated with a <canvas> element.

WebGLRenderingContext.drawingBufferWidth

The read-only width of the current drawing buffer. Should match the width of the canvas element associated with this context.

WebGLRenderingContext.drawingBufferHeight

The read-only height of the current drawing buffer. Should match the height of the canvas element associated with this context.

WebGLRenderingContext.getContextAttributes()

Returns a WebGLContextAttributes object containing the actual context configuration.

Property	Description
alpha	A Boolean that indicates whether the canvas contains an alpha buffer.
depth	A Boolean that indicates whether the drawing buffer has a depth buffer of at least 16 bits.
stencil	A Boolean that indicates whether the drawing buffer has a stencil buffer of at least 8 bits.
antialias	A Boolean that indicates whether the drawing buffer is antialiased.
failIfMajorPerformanceCaveat	A Boolean that indicates whether a context will be created if the system performance is low.
premultipliedAlpha	A Boolean that indicates whether the page compositor will assume the drawing buffer contains colors with premultiplied alpha.
preserveDrawingBuffer	A Boolean that indicates whether the drawing buffer is preserved after rendering.
powerPreference	A string that indicates the preferred GPU to use.
xrCompatible	A Boolean that indicates whether the context is compatible with the WebXR Device API.

WebGLRenderingContext.isContextLost() (NI)

Returns a Boolean indicating whether the WebGL context has been lost.

WebGLRenderingContext.makeXRCompatible()

Ensures the context is compatible with the user's XR hardware.

At JSAR, you don't need to call this method on the navigator.gl object, because this context is created for XR by default.

Viewing and clipping

WebGLRenderingContext.scissor()

Defines the scissor box.

WebGLRenderingContext.viewport()

Sets the viewport.

State information

WebGLRenderingContext.activeTexture()

Selects the active texture unit.

WebGLRenderingContext.blendColor()

Sets the blend color.

WebGLRenderingContext.blendEquation()

Sets both the RGB blend equation and alpha blend equation to a single equation.

WebGLRenderingContext.blendEquationSeparate()

Sets the RGB blend equation and alpha blend equation separately.

WebGLRenderingContext.blendFunc()

Sets the source and destination blending factors.

WebGLRenderingContext.blendFuncSeparate()

Sets the source and destination blending factors separately for RGB and alpha.

WebGLRenderingContext.clearColor()

Sets the color to clear the color buffer to.

Note that because the JSAR is a mixed-rendering architecture, to avoid the applications clearing the color buffer, the clearColor won't have any effect.

WebGLRenderingContext.clearDepth()

Sets the value to clear the depth buffer to.

See the note in clearColor, the clearDepth won't have any effect, either.

WebGLRenderingContext.clearStencil()

Sets the value to clear the stencil buffer to.

See the note in clearColor, the clearStencil won't have any effect, either.

WebGLRenderingContext.colorMask()

Sets which color components to write to the color buffer.

WebGLRenderingContext.cullFace()

Specifies whether or not front- and/or back-facing polygons can be culled.

WebGLRenderingContext.depthFunc()

Specifies the function used to compare the depth value of a fragment with the depth buffer.

WebGLRenderingContext.depthMask()

Sets whether writing into the depth buffer is enabled or disabled.

WebGLRenderingContext.depthRange()

Specifies a linear mapping of the depth values in the depth buffer.

WebGLRenderingContext.disable()

Disables a GL capability.

WebGLRenderingContext.enable()

Enables a GL capability.

WebGLRenderingContext.frontFace()

Specifies whether front- or back-facing polygons can be culled.

WebGLRenderingContext.getParameter()

Returns the value of a parameter for a given target.

WebGLRenderingContext.getError()

Returns the error value.

WebGLRenderingContext.hint()

Specifies implementation-specific hints.

WebGLRenderingContext.isEnabled() (NI)

Returns whether a GL capability is enabled or not.

WebGLRenderingContext.lineWidth()

Sets the width of rasterized lines.

WebGLRenderingContext.pixelStorei()

Sets the pixel storage modes.

WebGLRenderingContext.polygonOffset()

Sets the scale and units used to calculate depth values.

WebGLRenderingContext.sampleCoverage() (NI)

Specifies multisample coverage parameters.

WebGLRenderingContext.stencilFunc()

Sets the front and back function and reference value for stencil testing.

WebGLRenderingContext.stencilFuncSeparate()

Sets the front and back function and reference value for stencil testing.

WebGLRenderingContext.stencilMask()

Controls the writing of individual bits in the stencil planes.

WebGLRenderingContext.stencilMaskSeparate()

Controls the writing of individual bits in the stencil planes.

WebGLRenderingContext.stencilOp()

Sets the front and back-facing stencil test actions.

WebGLRenderingContext.stencilOpSeparate()

Sets the front and back-facing stencil test actions.

Buffers

WebGLRenderingContext.bindBuffer()

Binds a buffer to a target.

WebGLRenderingContext.bufferData()

Creates and initializes a buffer object's data store.

WebGLRenderingContext.bufferSubData()

Updates a subset of a buffer object's data store.

WebGLRenderingContext.createBuffer()

Creates a buffer object.

WebGLRenderingContext.deleteBuffer()

Deletes buffer objects.

WebGLRenderingContext.isBuffer() (NI)

Returns whether a given object is a buffer.

Framebuffers

WebGLRenderingContext.bindFramebuffer()

Binds a WebGLFramebuffer object to a given target.

WebGLRenderingContext.checkFramebufferStatus()

Checks the completeness status of the WebGLFramebuffer object.

WebGLRenderingContext.createFramebuffer()

Creates a WebGLFramebuffer object.

WebGLRenderingContext.deleteFramebuffer()

Deletes a WebGLFramebuffer object.

WebGLRenderingContext.framebufferRenderbuffer()

Attaches a renderbuffer object to a framebuffer object.

WebGLRenderingContext.framebufferTexture2D()

Attaches a texture object to a framebuffer object.

WebGLRenderingContext.getFramebufferAttachmentParameter() (NI)

Returns information about attachments to a framebuffer object.

WebGLRenderingContext.isFramebuffer() (NI)

Returns whether a given object is a framebuffer.

WebGLRenderingContext.readPixels() (NI)

Reads a block of pixels from the framebuffer.

Renderbuffers

WebGLRenderingContext.bindRenderbuffer()

Binds a WebGLRenderbuffer object to a target.

WebGLRenderingContext.createRenderbuffer()

Creates a WebGLRenderbuffer object.

WebGLRenderingContext.deleteRenderbuffer()

Deletes a WebGLRenderbuffer object.

WebGLRenderingContext.getRenderbufferParameter() (NI)

Returns information about a renderbuffer object.

WebGLRenderingContext.isRenderbuffer() (NI)

Returns whether a given object is a renderbuffer.

WebGLRenderingContext.renderbufferStorage()

Defines storage and format of a renderbuffer object's image.

Textures

WebGLRenderingContext.bindTexture()

Binds a texture to a target.

WebGLRenderingContext.compressedTexImage2D()

Specifies a two-dimensional texture image in a compressed format.

WebGLRenderingContext.compressedTexSubImage2D()

Specifies a sub-rectangle of a two-dimensional texture image in a compressed format.

WebGLRenderingContext.copyTexImage2D()

Copies pixels from the current framebuffer to a texture image.

WebGLRenderingContext.copyTexSubImage2D()

Copies pixels from the current framebuffer to a sub-rectangle of a texture image.

WebGLRenderingContext.createTexture()

Creates a texture object.

WebGLRenderingContext.deleteTexture()

Deletes a texture object.

WebGLRenderingContext.generateMipmap()

Generates a set of mipmaps for a texture object.

WebGLRenderingContext.getTexParameter() (NI)

Returns the value of a texture parameter.

WebGLRenderingContext.isTexture() (NI)

Returns whether a given object is a texture.

WebGLRenderingContext.texImage2D()

Specifies a two-dimensional texture image.

WebGLRenderingContext.texSubImage2D()

Specifies a sub-rectangle of a two-dimensional texture image.

WebGLRenderingContext.texParameterf() (NI)

Sets a float texture parameter.

WebGLRenderingContext.texParameteri()

Sets an integer texture parameter.

Programs and shaders

WebGLRenderingContext.attachShader()

Attaches a shader to a program.

WebGLRenderingContext.bindAttribLocation()

Binds a generic vertex attribute index to a named attribute variable.

WebGLRenderingContext.compileShader()

Compiles a WebGLShader.

WebGLRenderingContext.createProgram()

Creates a WebGLProgram.

WebGLRenderingContext.createShader()

Creates a WebGLShader.

WebGLRenderingContext.deleteProgram()

Deletes a WebGLProgram.

WebGLRenderingContext.deleteShader()

Deletes a WebGLShader.

WebGLRenderingContext.detachShader()

Detaches a shader from a program.

WebGLRenderingContext.getAttachedShaders()

Returns an array of the WebGLShader objects attached to a WebGLProgram.

WebGLRenderingContext.getProgramParameter()

Returns information about a WebGLProgram.

WebGLRenderingContext.getProgramInfoLog()

Returns information about the last link operation.

WebGLRenderingContext.getShaderParameter()

Returns information about a WebGLShader.

WebGLRenderingContext.getShaderPrecisionFormat()

Returns a WebGLShaderPrecisionFormat object describing the precision and range of supported floating-point formats.

WebGLRenderingContext.getShaderInfoLog()

Returns information about the last compile operation.

WebGLRenderingContext.getShaderSource()

Returns the source code of a WebGLShader.

WebGLRenderingContext.isProgram() (NI)

Returns whether a given object is a program.

WebGLRenderingContext.isShader() (NI)

Returns whether a given object is a shader.

WebGLRenderingContext.linkProgram()

Links a WebGLProgram.

WebGLRenderingContext.shaderSource()

Sets the source code in a WebGLShader.

WebGLRenderingContext.useProgram()

Installs a program object as part of the current rendering state.

WebGLRenderingContext.validateProgram() (NI)

Validates a WebGLProgram.

Uniforms and attributes

WebGLRenderingContext.disableVertexAttribArray()

Disables a generic vertex attribute array.

WebGLRenderingContext.enableVertexAttribArray()

Enables a generic vertex attribute array.

WebGLRenderingContext.getActiveAttrib()

Returns information about an active attribute variable.

WebGLRenderingContext.getActiveUniform()

Returns information about an active uniform variable.

WebGLRenderingContext.getAttribLocation()

Returns the location of an attribute variable.

WebGLRenderingContext.getUniform() (NI)

Returns the value of a uniform variable.

WebGLRenderingContext.getUniformLocation()

Returns the location of a uniform variable.

WebGLRenderingContext.getVertexAttrib() (NI)

Returns the value of a vertex attribute.

WebGLRenderingContext.getVertexAttribOffset() (NI)

Returns the byte offset of a vertex attribute.

WebGLRenderingContext.uniform[1234][fi][v]()

Specifies a value for a uniform variable.

WebGLRenderingContext.uniformMatrix[234]fv()

Specifies a matrix value for a uniform variable.

WebGLRenderingContext.vertexAttrib[1234]f[v]() (NI)

Specifies the value of a generic vertex attribute.

WebGLRenderingContext.vertexAttribPointer()

Specifies the location and data format of a vertex attribute array.

Drawing buffers

WebGLRenderingContext.clear()

Clears specified buffers to preset values.

Because JSAR is a mixed-rendering architecture, to avoid the applications clearing the color buffer, the clear won't have any effect.

WebGLRenderingContext.drawArrays()

Renders primitives from array data.

WebGLRenderingContext.drawElements()

Renders primitives from array data.

WebGLRenderingContext.finish() (NI)

Blocks execution until all previously called commands are finished.

WebGLRenderingContext.flush() (NI)

Empties different buffer commands, causing all commands to be executed as quickly as possible.

Color spaces

WebGLRenderingContext.drawingBufferColorSpace (NI)

Specifies the color space of the WebGL drawing buffer.

WebGLRenderingContext.unpackColorSpace (NI)

Specifies the color space to convert to when importing textures.

Working with extensions

WebGLRenderingContext.getSupportedExtensions()

Returns an Array of strings containing all the supported WebGL extensions.

WebGLRenderingContext.getExtension()

Returns an extension object.

Class WebGL2RenderingContext

The WebGL2RenderingContext interface provides the WebGL 2.0 rendering context for the drawing surface. It is part of the WebGL 2.0 API and is used to draw graphics on the scene.

Constants

See the MDN's WebGL constants page.

State information

WebGL2RenderingContext.getIndexedParameter() (NI)

Returns the value of a parameter for a specific target and index.

Buffers

WebGL2RenderingContext.bufferData() (PI)

Initializes and creates the buffer object's data store.

WebGL2RenderingContext.bufferSubData() (PI)

Updates a subset of a buffer object's data store.

WebGL2RenderingContext.copyBufferSubData() (NI)

Copies a block of data from one buffer to another.

WebGL2RenderingContext.getBufferSubData() (NI)

Returns a subset of a buffer object's data store.

Framebuffers

WebGL2RenderingContext.blitFramebuffer()

Transfers a block of pixels from the read framebuffer to the draw framebuffer.

WebGL2RenderingContext.framebufferTextureLayer() (NI)

Attaches a single layer of a texture to a framebuffer object.

WebGL2RenderingContext.invalidateFramebuffer() (NI)

Discards the contents of a framebuffer.

WebGL2RenderingContext.invalidateSubFramebuffer() (NI)

Discards the contents of a region within a framebuffer.

WebGL2RenderingContext.readBuffer()

Specifies the color buffer from which pixels are read.

Renderbuffers

WebGL2RenderingContext.getInternalformatParameter() (NI)

Returns information about the implementation's support for specific internal formats.

WebGL2RenderingContext.renderbufferStorageMultisample()

Defines storage and format of a renderbuffer object's image.

Textures

WebGL2RenderingContext.texStorage2D()

Specifies the storage requirements for a two-dimensional texture.

WebGL2RenderingContext.texStorage3D()

Specifies the storage requirements for a three-dimensional texture.

WebGL2RenderingContext.texImage3D()

Specifies a three-dimensional texture image.

WebGL2RenderingContext.texSubImage3D()

Specifies a sub-rectangle of a three-dimensional texture image.

WebGL2RenderingContext.copyTexSubImage3D() (NI)

Copies pixels from the current framebuffer to a sub-rectangle of a three-dimensional texture image.

WebGL2RenderingContext.compressedTexImage3D() (NI)

Specifies a three-dimensional texture image in a compressed format.

WebGL2RenderingContext.compressedTexSubImage3D() (NI)

Specifies a sub-rectangle of a three-dimensional texture image in a compressed format.

Programs and shaders

WebGL2RenderingContext.getFragDataLocation() (NI)

Returns the location of a fragment output variable.

Uniforms and attributes

WebGL2RenderingContext.uniform[1234][uif][v]() (PI)

Specifies a value for a uniform variable.

WebGL2RenderingContext.uniformMatrix[234]x[234]fv() (PI)

Specifies a matrix value for a uniform variable.

WebGL2RenderingContext.vertexAttribI4[u]i[v]()

Color spaces

WebGL2RenderingContext.drawingBufferColorSpace (NI)

Specifies the color space of the WebGL drawing buffer.

WebGL2RenderingContext.unpackColorSpace (NI)

Specifies the color space to convert to when importing textures.

Drawing buffers

WebGL2RenderingContext.vertexAttribDivisor()

Modifies the rate at which generic vertex attributes advance during instanced rendering.

WebGL2RenderingContext.drawArraysInstanced()

Renders primitives from array data. In addition, it can execute multiple instances of the range of elements.

WebGL2RenderingContext.drawElementsInstanced()

Renders primitives from array data. In addition, it can execute multiple instances of a set of elements.

WebGL2RenderingContext.drawRangeElements()

Renders primitives from array data.

WebGL2RenderingContext.drawBuffers()

Specifies a list of color buffers to be drawn into.

WebGL2RenderingContext.clearBuffer[fiuv]() (NI)

Clears buffers from the currently bound framebuffer.

Query objects

WebGL2RenderingContext.createQuery() (NI)

Creates a new WebGLQuery object.

WebGL2RenderingContext.deleteQuery() (NI)

Deletes a given WebGLQuery object.

WebGL2RenderingContext.isQuery() (NI)

Returns true if a given object is a valid WebGLQuery object.

WebGL2RenderingContext.beginQuery() (NI)

Begins an asynchronous query.

WebGL2RenderingContext.endQuery() (NI)

Marks the end of an asynchronous query.

WebGL2RenderingContext.getQuery() (NI)

Returns the query result.

WebGL2RenderingContext.getQueryParameter() (NI)

Returns information about a query object.

Sampler objects

WebGL2RenderingContext.createSampler() (NI)

Creates a new WebGLSampler object.

WebGL2RenderingContext.deleteSampler() (NI)

Deletes a given WebGLSampler object.

WebGL2RenderingContext.bindSampler() (NI)

Binds a WebGLSampler object to a texture unit.

WebGL2RenderingContext.isSampler() (NI)

Returns true if a given object is a valid WebGLSampler object.

WebGL2RenderingContext.samplerParameter[if]() (NI)

Sets a parameter for a WebGLSampler object.

WebGL2RenderingContext.getSamplerParameter() (NI)

Returns the value of a parameter for a WebGLSampler object.

Sync objects

WebGL2RenderingContext.fenceSync() (NI)

Creates a new WebGLSync object.

WebGL2RenderingContext.isSync() (NI)

Returns true if a given object is a valid WebGLSync object.

WebGL2RenderingContext.deleteSync() (NI)

Deletes a given WebGLSync object.

WebGL2RenderingContext.clientWaitSync() (NI)

Blocks execution until the specified sync object is signaled.

WebGL2RenderingContext.waitSync() (NI)

Blocks execution until the specified sync object is signaled.

WebGL2RenderingContext.getSyncParameter() (NI)

Returns information about a sync object.

Transform feedback

WebGL2RenderingContext.createTransformFeedback() (NI)

Creates a new WebGLTransformFeedback object.

WebGL2RenderingContext.deleteTransformFeedback() (NI)

Deletes a given WebGLTransformFeedback object.

WebGL2RenderingContext.isTransformFeedback() (NI)

Returns true if a given object is a valid WebGLTransformFeedback object.

WebGL2RenderingContext.bindTransformFeedback() (NI)

Binds a WebGLTransformFeedback object.

WebGL2RenderingContext.beginTransformFeedback() (NI)

Starts a transform feedback operation.

WebGL2RenderingContext.endTransformFeedback() (NI)

Ends a transform feedback operation.

WebGL2RenderingContext.transformFeedbackVaryings() (NI)

Specifies output variables for the transform feedback process.

WebGL2RenderingContext.getTransformFeedbackVarying() (NI)

Returns information about an output variable.

WebGL2RenderingContext.pauseTransformFeedback() (NI)

Pauses a transform feedback operation.

WebGL2RenderingContext.resumeTransformFeedback() (NI)

Resumes a transform feedback operation.

Uniform buffer objects

WebGL2RenderingContext.bindBufferBase()

Binds a given WebGLBuffer to a given binding point (target) at a given index.

WebGL2RenderingContext.bindBufferRange()

Binds a range of a given WebGLBuffer to a given binding point (target) at a given index.

WebGL2RenderingContext.getUniformIndices() (NI)

Retrieves the indices of a number of uniforms within a WebGLProgram.

WebGL2RenderingContext.getActiveUniforms() (NI)

Retrieves the values of a number of uniforms within a WebGLProgram.

WebGL2RenderingContext.getUniformBlockIndex()

Retrieves the index of a uniform block within a WebGLProgram.

WebGL2RenderingContext.getActiveUniformBlockParameter() (NI)

Retrieves information about a uniform block within a WebGLProgram.

WebGL2RenderingContext.getActiveUniformBlockName() (NI)

Retrieves the name of a uniform block within a WebGLProgram.

WebGL2RenderingContext.uniformBlockBinding()

Assigns a specific uniform block to a uniform block binding point.

Vertex array objects

WebGL2RenderingContext.createVertexArray()

Creates a new WebGLVertexArrayObject.

WebGL2RenderingContext.deleteVertexArray()

Deletes a given WebGLVertexArrayObject.

WebGL2RenderingContext.isVertexArray()

Returns true if a given object is a valid WebGLVertexArrayObject.

WebGL2RenderingContext.bindVertexArray()

Binds a given WebGLVertexArrayObject.

Supported WebGL extensions

In this section, we list the supported WebGL extensions in the JSAR.

EXT_color_buffer_float

See: https://developer.mozilla.org/en-US/docs/Web/API/EXT_color_buffer_float.

EXT_texture_filter_anisotropic

See: https://developer.mozilla.org/en-US/docs/Web/API/EXT_texture_filter_anisotropic.

This extension added new constants:

const texture = gl.createTexture();
gl.bindTexture(gl.TEXTURE_2D, texture);

const ext = gl.getExtension('EXT_texture_filter_anisotropic');
if (ext) {
  const max = gl.getParameter(ext.MAX_TEXTURE_MAX_ANISOTROPY_EXT);
  gl.texParameterf(gl.TEXTURE_2D, ext.TEXTURE_MAX_ANISOTROPY_EXT, max);
}

OES_element_index_uint

See: https://developer.mozilla.org/en-US/docs/Web/API/OES_element_index_uint.

OES_standard_derivatives

See: https://developer.mozilla.org/en-US/docs/Web/API/OES_standard_derivatives.

OES_texture_float_linear

See: https://developer.mozilla.org/en-US/docs/Web/API/OES_texture_float_linear.

OVR_multiview2

See: https://developer.mozilla.org/en-US/docs/Web/API/OVR_multiview2.

This extension is used to render to multiple views in a single draw call.

There are new constants added.

• FRAMEBUFFER_ATTACHMENT_TEXTURE_NUM_VIEWS_OVR: Number of views of the framebuffer object attachment.
• FRAMEBUFFER_ATTACHMENT_TEXTURE_BASE_VIEW_INDEX_OVR: Base view index of the framebuffer object attachment.
• MAX_VIEWS_OVR: The maximum number of views. Most VR headsets have two views, but there are prototypes of headset with ultra-wide FOV using 4 views which is currently the maximum number of views supported by multiview.
• FRAMEBUFFER_INCOMPLETE_VIEW_TARGETS_OVR: If baseViewIndex is not the same for all framebuffer attachment points where the value of FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE is not NONE, the framebuffer is considered incomplete. Calling checkFramebufferStatus for a framebuffer in this state returns FRAMEBUFFER_INCOMPLETE_VIEW_TARGETS_OVR.

This extension also exposes a new method framebufferTextureMultiviewOVR that is used to attach a texture array to the given framebuffer object. However in JSAR, 3D libraries doesn't need to use this function to create a multiview framebuffer. Instead, the application will use the framebuffer that created by the host, and the library will render to the views of the framebuffer.

To make the existing libraries like Three.js or Babylon.js which multiview rendering are still using framebufferTextureMultiviewOVR(), JSAR implemented this function but nothing will happen when it is called.

OCULUS_multiview

This extension is introduced by Meta Horizon at its blog: Multiview WebGL Rendering.

This extension inherits from OVR_multiview2 and add a new function framebufferTextureMultisampleMultiviewOVR to address the multisampled antialiasing issue in multiview rendering.

Because of JSAR's mixed-rendering architecture, the multiview framebuffer is managed by the host application, so the library doesn't need to use the function framebufferTextureMultisampleMultiviewOVR to enable multisampled antialiasing in multiview rendering.

To 3D libraries in JSAR, using OCULUS_multiview is the same as using OVR_multiview2, and the library only needs to make draw calls on the multiview framebuffer.