This specification describes an additional rendering context and support objects for the HTML 5 canvas element [CANVAS]. This context allows rendering using an API that conforms closely to the OpenGL ES 2.0 API.
This document is an editor's draft. Do not cite this document as other than work in progress.
Public discussion of this specification is welcome on the [email protected] mailing list (instructions, archives).
Please file bugs against the specification or its conformance tests in the issue tracker. Pull requests are welcome against the Github repository.
WebGL™ is an immediate mode 3D rendering API designed for the web. It is derived from OpenGL® ES 2.0, and provides similar rendering functionality, but in an HTML context. WebGL is designed as a rendering context for the HTML Canvas element. The HTML Canvas provides a destination for programmatic rendering in web pages, and allows for performing that rendering using different rendering APIs. The only such interface described as part of the Canvas specification is the 2D canvas rendering context, CanvasRenderingContext2D. This document describes another such interface, WebGLRenderingContext, which presents the WebGL API.
The immediate mode nature of the API is a divergence from most web APIs. Given the many use cases of 3D graphics, WebGL chooses the approach of providing flexible primitives that can be applied to any use case. Libraries can provide an API on top of WebGL that is more tailored to specific areas, thus adding a convenience layer to WebGL that can accelerate and simplify development. However, because of its OpenGL ES 2.0 heritage, it should be straightforward for developers familiar with modern desktop OpenGL or OpenGL ES 2.0 development to transition to WebGL development.
Many functions described in this document contain links to OpenGL ES man pages. While every effort is made to make these pages match the OpenGL ES 2.0 specification [GLES20], they may contain errors. In the case of a contradiction, the OpenGL ES 2.0 specification is the final authority.
The remaining sections of this document are intended to be read in conjunction with the OpenGL ES 2.0 specification (2.0.25 at the time of this writing, available from the Khronos OpenGL ES API Registry). Unless otherwise specified, the behavior of each method is defined by the OpenGL ES 2.0 specification. This specification may diverge from OpenGL ES 2.0 in order to ensure interoperability or security, often defining areas that OpenGL ES 2.0 leaves implementation-defined. These differences are summarized in the Differences Between WebGL and OpenGL ES 2.0 section.
Before using the WebGL API, the author must obtain a WebGLRenderingContext
object for a given HTMLCanvasElement [CANVAS] or
OffscreenCanvas [OFFSCREENCANVAS] as described
below. This object is used to manage OpenGL state and render to the drawing buffer, which
must be created at the time of context creation.
Each WebGLRenderingContext has an
associated canvas, set upon creation, which is
a canvas [CANVAS] or offscreen
canvas [OFFSCREENCANVAS].
Each WebGLRenderingContext has context
creation parameters, set upon creation, in
a WebGLContextAttributes object.
Each WebGLRenderingContext has actual
context parameters, set each time the drawing buffer is created, in
a WebGLContextAttributes object.
Each WebGLRenderingContext has a webgl
context lost flag, which is initially unset.
When the getContext() method of a canvas element
or offscreen canvas object is to return a new object for
the contextId webgl [CANVASCONTEXTS],
the user agent must perform the following steps:
WebGLRenderingContext object, context.
getContext() method is associated with.
WebGLContextAttributes object, contextAttributes.
getContext() was invoked with a second argument, options, set
the attributes of contextAttributes from those specified in options.
WebGLContextAttributes object, actualAttributes.
The canvas context type 'experimental-webgl' has historically been used to provide access to WebGL implementations which are not yet complete or conformant.
If the user agent supports both the webgl and experimental-webgl
canvas context types, they shall be treated as aliases. For example, if a call
to getContext('webgl') successfully creates a WebGLRenderingContext, a subsequent
call to getContext('experimental-webgl') shall return the same context object.
The drawing buffer into which the API calls are rendered shall be defined upon creation of the WebGLRenderingContext object. The following description defines how to create a drawing buffer.
The table below shows all the buffers which make up the drawing buffer, along with their
minimum sizes and whether they are defined or not by default. The size of this drawing
buffer shall be determined by the width and height attributes of
the HTMLCanvasElement or OffscreenCanvas. The table below also shows the value to which
these buffers shall be cleared when first created, when the size is changed, or after
presentation when the preserveDrawingBuffer context creation attribute
is false.
| Buffer | Clear value | Minimum size | Defined by default? |
|---|---|---|---|
| Color | (0, 0, 0, 0) | 8 bits per component | yes |
| Depth | 1.0 | 16 bit integer | yes |
| Stencil | 0 | 8 bits | no |
HTMLCanvasElement.width and .height values less than 1 are treated as 1.
A 0x0 canvas will yield a 1x1 drawingBufferWidth/Height.
If the requested width or height cannot be satisfied, either when the drawing buffer is first
created or when the width and height attributes of the
HTMLCanvasElement or OffscreenCanvas are changed, a drawing buffer
with smaller dimensions shall be created. The dimensions actually used are implementation
dependent and there is no guarantee that a buffer with the same aspect ratio will be
created. The actual drawing buffer size can be obtained from
the drawingBufferWidth and drawingBufferHeight attributes.
A WebGL implementation must not perform any automatic scaling of the size of the drawing
buffer on high-definition displays. The context's drawingBufferWidth
and drawingBufferHeight must match the canvas's width
and height attributes as closely as possible, modulo implementation-dependent
constraints.
The constraint above does not change the amount of space the canvas element consumes on the web page, even on a high-definition display. The canvas's intrinsic dimensions [CANVAS] equal the size of its coordinate space, with the numbers interpreted in CSS pixels, and CSS pixels are resolution-independent [CSS].
A WebGL application can achieve a 1:1 ratio between drawing buffer pixels and on-screen
pixels on high-definition displays by examining properties
like window.devicePixelRatio, scaling the canvas's width
and height by that factor, and setting its CSS width and height to the
original width and height. An application can simulate the effect of running on a
higher-resolution display simply by scaling up the canvas's width
and height properties.
The optional WebGLContextAttributes object may be used
to change whether or not the buffers are defined. It can also be used to define whether the
color buffer will include an alpha channel. If defined, the alpha channel is used by the
HTML compositor to combine the color buffer with the rest of the page. The
WebGLContextAttributes object is only used on the first call to
getContext. No facility is provided to change the attributes of the drawing
buffer after its creation.
The depth, stencil and antialias attributes, when set
to true, are requests, not requirements. The WebGL implementation should make a best effort
to honor them. When any of these attributes is set to false, however, the WebGL
implementation must not provide the associated functionality. Combinations of attributes not
supported by the WebGL implementation or graphics hardware shall not cause a failure to
create a WebGLRenderingContext. The actual context
parameters are set to the attributes of the created drawing buffer. The
alpha, premultipliedAlpha and preserveDrawingBuffer
attributes must be obeyed by the WebGL implementation.
WebGL presents its drawing buffer to the HTML page compositor immediately before a compositing operation, but only if at least one of the following have been called since the previous compositing operation:
Before the drawing buffer is presented for compositing the implementation shall ensure that all rendering operations have been flushed to the drawing buffer. By default, after compositing the contents of the drawing buffer shall be cleared to their default values, as shown in the table above.
This default behavior can be changed by setting the preserveDrawingBuffer
attribute of the WebGLContextAttributes object. If
this flag is true, the contents of the drawing buffer shall be preserved until the author
either clears or overwrites them. If this flag is false, attempting to perform operations
using this context as a source image after the rendering function has returned can lead to
undefined behavior. This includes readPixels or toDataURL calls,
using this context as the source image of another context's texImage2D or
drawImage call, or creating
an ImageBitmap [HTML]
from this context's canvas.
While it is sometimes desirable to preserve the drawing buffer, it can cause significant
performance loss on some platforms. Whenever possible this flag should remain false
and other techniques used. Techniques like synchronous drawing buffer access (e.g.,
calling readPixels or toDataURL in the same function that
renders to the drawing buffer) can be used to get the contents of the drawing buffer.
If the author needs to render to the same drawing buffer over a series of calls, a
Framebuffer Object can be used.
Implementations may optimize away the required implicit clear operation of the Drawing Buffer as long as a guarantee can be made that the author cannot gain access to buffer contents from another process. For instance, if the author performs an explicit clear then the implicit clear is not needed.
renderbufferStorage as used on Renderbuffers.
Clearing behavior is equivalent to setting HTMLCanvasElement.width and HTMLCanvasElement.height, followed by changing the drawing buffer format.
This method respects WebGLContextAttributes.antialias.
drawingBufferStorage allows for efficiently respecifying width and height together simultaneously.
With HTMLCanvasElement.width and HTMLCanvasElement.height,
setting one and then the other can incur intermediate reallocations, though User Agents do try to optimize these out.
drawingBufferStorage is successful, the drawingBufferFormat becomes sizedFormat.
drawingBufferWidth and drawingBufferHeight become width and height respectively.
Operations on the default framebuffer therefore behave as if operating on a non-default framebuffer with an attachment of sizedFormat.
E.g. after drawingBufferStorage(gl.RGBA16F, 1, 1), because the framebuffer is "floatish",
readPixels's main format/type pair is RGBA/FLOAT instead of RGBA/UNSIGNED_BYTE.
If WebGLContextAttributes.alpha is false, generate INVALID_OPERATION.
RGBA8 is always supported for sizedFormat.
Additionally, the following enums are supported if they are currently valid for renderbufferStorage:
RGBA8
SRGB8_ALPHA8 (0x8C43) (E.g. from EXT_sRGB)
RGBA16F (0x881A) (E.g. from EXT_color_buffer_half_float)
sizedFormat is not currently supported, generate INVALID_ENUM.
In WebGL 1.0, SRGB8_ALPHA8 requires the extension EXT_sRGB.
In WebGL 2.0, SRGB8_ALPHA8 does not require an extension.
In WebGL 1.0, RGBA16F requires the extension EXT_color_buffer_half_float.
In WebGL 2.0, RGBA16F requires the extension EXT_color_buffer_float.
width or height are greater than the limit MAX_RENDERBUFFER_SIZE,
generate INVALID_VALUE.
If allocation fails, generate OUT_OF_MEMORY.
OpenGL manages a rectangular viewport as part of its state which defines the placement of the rendering results in the drawing buffer. Upon creation of WebGL context context, the viewport is initialized to a rectangle with origin at (0, 0) and width and height equal to (context.drawingBufferWidth, context.drawingBufferHeight).
A WebGL implementation shall not affect the state of the OpenGL viewport in response to resizing of the canvas element.
var canvas = document.getElementById('canvas1');
var gl = canvas.getContext('webgl');
canvas.width = newWidth;
canvas.height = newHeight;
gl.viewport(0, 0, gl.drawingBufferWidth, gl.drawingBufferHeight);
Rationale: automatically setting the viewport will interfere with applications that set
it manually. Applications are expected to use onresize handlers to respond to
changes in size of the canvas and set the OpenGL viewport in turn.
The OpenGL API allows the application to modify the blending modes used during rendering,
and for this reason allows control over how alpha values in the drawing buffer are
interpreted; see the premultipliedAlpha parameter in
the WebGLContextAttributes section.
The HTML Canvas APIs toDataURL and drawImage must respect
the premultipliedAlpha context creation parameter. When toDataURL
is called against a Canvas into which WebGL content is being rendered, then if the requested
image format does not specify premultiplied alpha and the WebGL context has
the premultipliedAlpha parameter set to true, then the pixel values must be
de-multiplied; i.e., the color channels are divided by the alpha channel. Note that
this operation is lossy.
Passing a WebGL-rendered Canvas to the drawImage method
of CanvasRenderingContext2D may or may not need to modify the the rendered
WebGL content during the drawing operation, depending on the premultiplication needs of the
CanvasRenderingContext2D implementation.
When passing a WebGL-rendered Canvas to the texImage2D API, then depending on
the setting of the premultipliedAlpha context creation parameter of the passed
canvas and the UNPACK_PREMULTIPLY_ALPHA_WEBGL pixel store parameter of the
destination WebGL context, the pixel data may need to be changed to or from premultiplied
form.
OpenGL manages several types of resources as part of its state. These are identified by integer object names and are obtained from OpenGL by various creation calls. In contrast WebGL represents these resources as DOM objects. Each object is derived from the WebGLObject interface. Currently supported resources are: textures, buffers (i.e., VBOs), framebuffers, renderbuffers, shaders and programs. The WebGLRenderingContext interface has a method to create a WebGLObject subclass for each type. Data from the underlying graphics library are stored in these objects and are fully managed by them. The DOM object will stay alive not only as long as the author retains an explicit reference to it, but also as long as it is in use by the underlying graphics library. When the DOM object is destroyed, it marks its resources for deletion. If authors wish to mark an object for deletion prior to the DOM object being destroyed, they may explicitly call the respective delete function. (e.g. deleteTexture)
WebGL resources such as textures and vertex buffer objects (VBOs) must always
contain initialized data, even if they were created without initial user
data values. Creating a resource without initial values is commonly used to
reserve space for a texture or VBO, which is then modified using texSubImage or
bufferSubData calls. If initial data is not provided to these calls, the WebGL
implementation must initialize their contents to 0; depth resources must be cleared to
the default 1.0 clear depth. This may require creating a zeroed temporary buffer the size
of a requested VBO, so that it can be initialized correctly. All other forms of loading
data into a texture or VBO involve either ArrayBuffers or DOM objects such as images, and
are therefore already required to be initialized.
When WebGL resources are accessed by shaders through a call such as
drawElements or drawArrays, the WebGL implementation must ensure
that the shader cannot access either out of bounds or uninitialized data.
See Enabled Vertex Attributes and Range Checking
for restrictions which must be enforced by the WebGL implementation.
In order to prevent information leakage, WebGL disallows uploading as textures:
If the texImage2D or texSubImage2D method is called with otherwise
correct arguments and an HTMLImageElement, HTMLVideoElement,
HTMLCanvasElement, or ImageBitmap violating these restrictions, a
SECURITY_ERR exception must be thrown.
WebGL necessarily imposes stronger restrictions on the use of cross-domain media than other APIs such as the 2D canvas rendering context, because shaders can be used to indirectly deduce the contents of textures which have been uploaded to the GPU.
WebGL applications may utilize images and videos that come from other domains, with the cooperation of the server hosting the media, using Cross-Origin Resource Sharing [CORS]. In order to use such media, the application needs to explicitly request permission to do so, and the server needs to explicitly grant permission. Successful CORS-enabled fetches of image and video elements from other domains cause the origin of these elements to be set to that of the containing Document [HTML].
The following ECMAScript example demonstrates how to issue a CORS request for an image coming from another domain. The image is fetched from the server without any credentials, i.e., cookies.
var gl = ...; var image = new Image(); // The onload handler should be set to a function which uploads the HTMLImageElement // using texImage2D or texSubImage2D. image.onload = ...; image.crossOrigin = "anonymous"; image.src = "http://other-domain.com/image.jpg";
Note that these rules imply that the origin-clean flag for a canvas rendered using WebGL will never be set to false.
For more information on issuing CORS requests for image and video elements, consult:
A WebGL implementation must only accept shaders which conform to The OpenGL ES Shading Language, Version 1.00 [GLES20GLSL], and which do not exceed the minimum functionality mandated in Sections 4 and 5 of Appendix A. In particular:
for loops must conform to the structural constraints in Appendix A. while and do-while loops are disallowed, since they are
optional in Appendix A.In addition to the reserved identifiers in the aforementioned specification, identifiers starting with "webgl_" and "_webgl_" are reserved for use by WebGL. A shader which declares a function, variable, structure name, or structure field starting with these prefixes must not be allowed to load.
WebGL 1.0 implementations must additionally support the line continuation character '\' in shaders.
It is possible to create, either intentionally or unintentionally, combinations of shaders and geometry that take an undesirably long time to render. This issue is analogous to that of long-running scripts, for which user agents already have safeguards. However, long-running draw calls can cause loss of interactivity for the entire window system, not just the user agent.
In the general case it is not possible to impose limits on the structure of incoming shaders to guard against this problem. Experimentation has shown that even very strict structural limits are insufficient to prevent long rendering times, and such limits would prevent shader authors from implementing common algorithms.
User agents should implement safeguards to prevent excessively long rendering times and associated loss of interactivity. Suggested safeguards include:
The supporting infrastructure at the OS and graphics API layer is expected to improve over time, which is why the exact nature of these safeguards is not specified.
Shaders must not be allowed to read or write array elements that lie outside of the application's own
data. This includes any variable of array type, as well as vector or matrix types such as
vec3 or mat4 when accessed using array subscripting syntax. If
detected during compilation, such accesses must generate an error and prevent the shader
from compiling. Otherwise, at runtime, out-of-range reads shall return any of the following values:
Out-of-range writes are either discarded or modify an unspecified value in the storage accessible to the program.
This behavior replicates that defined in [KHRROBUSTACCESS].
See Supported GLSL Constructs for more information on restrictions which simplify static analysis of the array indexing operations in shaders.
This section describes the interfaces and functionality added to the DOM to support runtime access to the functionality described above.
The following types are used in all interfaces in the following section.
typedef unsigned long GLenum;
typedef boolean GLboolean;
typedef unsigned long GLbitfield;
typedef byte GLbyte; /* 'byte' should be a signed 8 bit type. */
typedef short GLshort;
typedef long GLint;
typedef long GLsizei;
typedef long long GLintptr;
typedef long long GLsizeiptr;
// Ideally the typedef below would use 'unsigned byte', but that doesn't currently exist in Web IDL.
typedef octet GLubyte; /* 'octet' should be an unsigned 8 bit type. */
typedef unsigned short GLushort;
typedef unsigned long GLuint;
typedef unrestricted float GLfloat;
typedef unrestricted float GLclampf;
// The power preference settings are documented in the WebGLContextAttributes
// section of the specification.
enum WebGLPowerPreference { "default", "low-power", "high-performance" };
The WebGLContextAttributes dictionary contains drawing surface attributes and
is passed as the second parameter to getContext.
dictionary WebGLContextAttributes {
boolean alpha = true;
boolean depth = true;
boolean stencil = false;
boolean antialias = true;
boolean premultipliedAlpha = true;
boolean preserveDrawingBuffer = false;
WebGLPowerPreference powerPreference = "default";
boolean failIfMajorPerformanceCaveat = false;
boolean desynchronized = false;
};
The following list describes each attribute in the WebGLContextAttributes object and its
use. The default value for each attribute is shown above. The default value is used either
if no second parameter is passed to getContext, or if a user object is passed
which has no attribute of the given name.
If the value is true the page compositor will assume the drawing buffer contains colors with premultiplied alpha. If the value is false the page compositor will assume that colors in the drawing buffer are not premultiplied. This flag is ignored if the alpha flag is false.
With premultipliedAlpha:true, any pixels sent to the page
compositor shall have color values less-than-or-equal-to their alpha value,
otherwise the colors resulting from compositing such out-of-range pixel values
are undefined.
premultipliedAlpha:true
vec4(1.0, 0.0, 0.0, 0.5) might display as green
instead of red, possibly due to optimized packed compositing math overflows.
This is left undefined due to the intractible performance impact of requiring
consistent behavior.
See Premultiplied Alpha for more
information on the effects of the premultipliedAlpha flag.
On some hardware setting the preserveDrawingBuffer flag
to true can have significant performance implications.
Provides a hint to the user agent indicating what configuration of GPU is suitable for this WebGL context. This may influence which GPU is used in a system with multiple GPUs. For example, a dual-GPU system might have one GPU that consumes less power at the expense of rendering performance. Note that this property is only a hint and a WebGL implementation may choose to ignore it.
WebGL implementations use context lost and restored events to regulate power and memory consumption, regardless of the value of this attribute.
The allowed values are:
default
Let the user agent decide which GPU configuration is most suitable. This is the default value.
high-performance
Indicates a request for a GPU configuration that prioritizes rendering performance over power consumption. Developers are encouraged to only specify this value if they believe it is absolutely necessary, since it may significantly decrease battery life on mobile devices. Implementations may decide to initially respect this request and, after some time, lose the context and restore a new context ignoring the request.
Applications that request high-performance should test and
maintain robust context loss handling, as User Agents are very likely to decide
to lose background high-performance contexts.
low-power
Indicates a request for a GPU configuration that prioritizes power saving over rendering performance. Generally, content should use this if it is unlikely to be constrained by drawing performance; for example, if it renders only one frame per second, draws only relatively simple geometry with simple shaders, or uses a small HTML canvas element. Developers are encouraged to use this value if their content allows, since it may significantly improve battery life on mobile devices.
false. Applications that require high performance may
set this parameter to true, and if context creation fails then the
application may prefer to use a fallback rendering path such as a 2D canvas context.
Alternatively the application can retry WebGL context creation with this parameter
set to false, with the knowledge that a reduced-fidelity rendering mode
should be used to improve performance.
If the value is true, then the user agent may optimize the rendering of the canvas to reduce the latency, as measured from input events to rasterization, by desynchronizing the canvas paint cycle from the event loop, bypassing the ordinary user agent rendering algorithm, or both. Insofar as this mode involves bypassing the usual paint mechanisms, rasterization, or both, it might introduce visible tearing artifacts.
The user agent usually renders on a buffer which is not being displayed, quickly
swapping it and the one being scanned out for presentation; the former buffer is
called back buffer and the latter front buffer. A popular technique for
reducing latency is called front buffer rendering, also known as single
buffer rendering, where rendering happens inparallel and racily with the
scanning out process. This technique reduces the latency at the price of
potentially introducing tearing artifacts and can be used to implement in total or
part of the desynchronized
boolean. [MULTIPLEBUFFERING]
The desynchronized boolean can be useful when implementing certain
kinds of applications, such as drawing applications, where the latency between
input and rasterization is critical.
getContext. It assumes the presence of a canvas element named "canvas1" on the
page.
var canvas = document.getElementById('canvas1');
var context = canvas.getContext('webgl',
{ antialias: false,
stencil: true });
The WebGLObject interface is the parent interface for all GL objects.
Each WebGLObject has
an internal invalidated flag, which is initially unset.
Each WebGLObject has a .label attribute, which defaults to "".
Implementations should use this application-provided label string to improve debugging,
e.g. in error messages,
and/or providing the label to any underlying driver where possible to assist in native-level debugging tools.
Implementations must not change behavior due to a label.
[Exposed=(Window,Worker)]
interface WebGLObject {
attribute USVString label;
};
The WebGLBuffer interface represents an OpenGL Buffer Object. The
underlying object is created as if by calling glGenBuffers
(OpenGL ES 2.0 §2.9, man page)
, bound as if by calling glBindBuffer
(OpenGL ES 2.0 §2.9, man page)
and marked for deletion as if by calling glDeleteBuffers
(OpenGL ES 2.0 §2.9, man page)
.
[Exposed=(Window,Worker)]
interface WebGLBuffer : WebGLObject {
};
The WebGLFramebuffer interface represents an OpenGL Framebuffer Object. The
underlying object is created as if by calling glGenFramebuffers
(OpenGL ES 2.0 §4.4.1, man page)
, bound as if by calling glBindFramebuffer
(OpenGL ES 2.0 §4.4.1, man page)
and marked for deletion as if by calling glDeleteFramebuffers
(OpenGL ES 2.0 §4.4.1, man page)
.
[Exposed=(Window,Worker)]
interface WebGLFramebuffer : WebGLObject {
};
The WebGLProgram interface represents an OpenGL Program Object. The
underlying object is created as if by calling glCreateProgram
(OpenGL ES 2.0 §2.10.3, man page)
, used as if by calling glUseProgram
(OpenGL ES 2.0 §2.10.3, man page)
and marked for deletion as if by calling glDeleteProgram
(OpenGL ES 2.0 §2.10.3, man page)
.
[Exposed=(Window,Worker)]
interface WebGLProgram : WebGLObject {
};
The WebGLRenderbuffer interface represents an OpenGL Renderbuffer Object. The
underlying object is created as if by calling glGenRenderbuffers
(OpenGL ES 2.0 §4.4.3, man page)
, bound as if by calling glBindRenderbuffer
(OpenGL ES 2.0 §4.4.3, man page)
and marked for deletion as if by calling glDeleteRenderbuffers
(OpenGL ES 2.0 §4.4.3, man page)
.
[Exposed=(Window,Worker)]
interface WebGLRenderbuffer : WebGLObject {
};
The WebGLShader interface represents an OpenGL Shader Object. The
underlying object is created as if by calling glCreateShader
(OpenGL ES 2.0 §2.10.1, man page)
, attached to a Program as if by calling glAttachShader
(OpenGL ES 2.0 §2.10.3, man page)
and marked for deletion as if by calling glDeleteShader
(OpenGL ES 2.0 §2.10.1, man page)
.
[Exposed=(Window,Worker)]
interface WebGLShader : WebGLObject {
};
The WebGLTexture interface represents an OpenGL Texture Object. The
underlying object is created as if by calling glGenTextures
(OpenGL ES 2.0 §3.7.13, man page)
, bound as if by calling glBindTexture
(OpenGL ES 2.0 §3.7.13, man page)
and marked for deletion as if by calling glDeleteTextures
(OpenGL ES 2.0 §3.7.13, man page)
.
[Exposed=(Window,Worker)]
interface WebGLTexture : WebGLObject {
};
The WebGLUniformLocation interface represents the location of a uniform variable
in a shader program.
[Exposed=(Window,Worker)]
interface WebGLUniformLocation {
};
The WebGLActiveInfo interface represents the information returned
from the getActiveAttrib and getActiveUniform calls.
[Exposed=(Window,Worker)]
interface WebGLActiveInfo {
readonly attribute GLint size;
readonly attribute GLenum type;
readonly attribute DOMString name;
};
The following attributes are available:
size
of type GLint
type
of type GLenum
name
of type DOMString
The WebGLShaderPrecisionFormat interface represents the information returned
from the getShaderPrecisionFormat call.
[Exposed=(Window,Worker)]
interface WebGLShaderPrecisionFormat {
readonly attribute GLint rangeMin;
readonly attribute GLint rangeMax;
readonly attribute GLint precision;
};
The following attributes are available:
rangeMin
of type GLint
rangeMax
of type GLint
precision
of type GLint
Vertex, index, texture, and other data is transferred to the WebGL implementation using ArrayBuffers, Typed Arrays and DataViews as defined in the ECMAScript specification [ECMASCRIPT].
Typed Arrays support the creation of interleaved, heterogeneous vertex data; uploading of distinct blocks of data into a large vertex buffer object; and most other use cases required by OpenGL programs.
var numVertices = 100; // for example
// Compute the size needed for the buffer, in bytes and floats
var vertexSize = 3 * Float32Array.BYTES_PER_ELEMENT +
4 * Uint8Array.BYTES_PER_ELEMENT;
var vertexSizeInFloats = vertexSize / Float32Array.BYTES_PER_ELEMENT;
// Allocate the buffer
var buf = new ArrayBuffer(numVertices * vertexSize);
// Map this buffer to a Float32Array to access the positions
var positionArray = new Float32Array(buf);
// Map the same buffer to a Uint8Array to access the color
var colorArray = new Uint8Array(buf);
// Set up the initial offset of the vertices and colors within the buffer
var positionIdx = 0;
var colorIdx = 3 * Float32Array.BYTES_PER_ELEMENT;
// Initialize the buffer
for (var i = 0; i < numVertices; i++) {
positionArray[positionIdx] = ...;
positionArray[positionIdx + 1] = ...;
positionArray[positionIdx + 2] = ...;
colorArray[colorIdx] = ...;
colorArray[colorIdx + 1] = ...;
colorArray[colorIdx + 2] = ...;
colorArray[colorIdx + 3] = ...;
positionIdx += vertexSizeInFloats;
colorIdx += vertexSize;
}
The WebGLRenderingContext represents the API allowing
OpenGL ES 2.0 style rendering into the canvas element.
Before performing the implementation of any method of the WebGLRenderingContext
interface or any method of an interface returned by the getExtension method,
the following steps must be performed:
[WebGLHandlesContextLoss] extended attribute appears on the called
method, perform the implementation of the called method, return its result and terminate
these steps. WebGLObject with
its invalidated flag set, generate
an INVALID_OPERATION error and let use default return value be
true. any or any nullable type,
return null. See the context lost event for further details.
typedef (ImageBitmap or
ImageData or
HTMLImageElement or
HTMLCanvasElement or
HTMLVideoElement or
OffscreenCanvas or
VideoFrame) TexImageSource;
typedef ([AllowShared] Float32Array or sequence<GLfloat>) Float32List;
typedef ([AllowShared] Int32Array or sequence<GLint>) Int32List;
interface mixin WebGLRenderingContextBase
{
/* ClearBufferMask */
const GLenum DEPTH_BUFFER_BIT = 0x00000100;
const GLenum STENCIL_BUFFER_BIT = 0x00000400;
const GLenum COLOR_BUFFER_BIT = 0x00004000;
/* BeginMode */
const GLenum POINTS = 0x0000;
const GLenum LINES = 0x0001;
const GLenum LINE_LOOP = 0x0002;
const GLenum LINE_STRIP = 0x0003;
const GLenum TRIANGLES = 0x0004;
const GLenum TRIANGLE_STRIP = 0x0005;
const GLenum TRIANGLE_FAN = 0x0006;
/* AlphaFunction (not supported in ES20) */
/* NEVER */
/* LESS */
/* EQUAL */
/* LEQUAL */
/* GREATER */
/* NOTEQUAL */
/* GEQUAL */
/* ALWAYS */
/* BlendingFactorDest */
const GLenum ZERO = 0;
const GLenum ONE = 1;
const GLenum SRC_COLOR = 0x0300;
const GLenum ONE_MINUS_SRC_COLOR = 0x0301;
const GLenum SRC_ALPHA = 0x0302;
const GLenum ONE_MINUS_SRC_ALPHA = 0x0303;
const GLenum DST_ALPHA = 0x0304;
const GLenum ONE_MINUS_DST_ALPHA = 0x0305;
/* BlendingFactorSrc */
/* ZERO */
/* ONE */
const GLenum DST_COLOR = 0x0306;
const GLenum ONE_MINUS_DST_COLOR = 0x0307;
const GLenum SRC_ALPHA_SATURATE = 0x0308;
/* SRC_ALPHA */
/* ONE_MINUS_SRC_ALPHA */
/* DST_ALPHA */
/* ONE_MINUS_DST_ALPHA */
/* BlendEquationSeparate */
const GLenum FUNC_ADD = 0x8006;
const GLenum BLEND_EQUATION = 0x8009;
const GLenum BLEND_EQUATION_RGB = 0x8009; /* same as BLEND_EQUATION */
const GLenum BLEND_EQUATION_ALPHA = 0x883D;
/* BlendSubtract */
const GLenum FUNC_SUBTRACT = 0x800A;
const GLenum FUNC_REVERSE_SUBTRACT = 0x800B;
/* Separate Blend Functions */
const GLenum BLEND_DST_RGB = 0x80C8;
const GLenum BLEND_SRC_RGB = 0x80C9;
const GLenum BLEND_DST_ALPHA = 0x80CA;
const GLenum BLEND_SRC_ALPHA = 0x80CB;
const GLenum CONSTANT_COLOR = 0x8001;
const GLenum ONE_MINUS_CONSTANT_COLOR = 0x8002;
const GLenum CONSTANT_ALPHA = 0x8003;
const GLenum ONE_MINUS_CONSTANT_ALPHA = 0x8004;
const GLenum BLEND_COLOR = 0x8005;
/* Buffer Objects */
const GLenum ARRAY_BUFFER = 0x8892;
const GLenum ELEMENT_ARRAY_BUFFER = 0x8893;
const GLenum ARRAY_BUFFER_BINDING = 0x8894;
const GLenum ELEMENT_ARRAY_BUFFER_BINDING = 0x8895;
const GLenum STREAM_DRAW = 0x88E0;
const GLenum STATIC_DRAW = 0x88E4;
const GLenum DYNAMIC_DRAW = 0x88E8;
const GLenum BUFFER_SIZE = 0x8764;
const GLenum BUFFER_USAGE = 0x8765;
const GLenum CURRENT_VERTEX_ATTRIB = 0x8626;
/* CullFaceMode */
const GLenum FRONT = 0x0404;
const GLenum BACK = 0x0405;
const GLenum FRONT_AND_BACK = 0x0408;
/* DepthFunction */
/* NEVER */
/* LESS */
/* EQUAL */
/* LEQUAL */
/* GREATER */
/* NOTEQUAL */
/* GEQUAL */
/* ALWAYS */
/* EnableCap */
/* TEXTURE_2D */
const GLenum CULL_FACE = 0x0B44;
const GLenum BLEND = 0x0BE2;
const GLenum DITHER = 0x0BD0;
const GLenum STENCIL_TEST = 0x0B90;
const GLenum DEPTH_TEST = 0x0B71;
const GLenum SCISSOR_TEST = 0x0C11;
const GLenum POLYGON_OFFSET_FILL = 0x8037;
const GLenum SAMPLE_ALPHA_TO_COVERAGE = 0x809E;
const GLenum SAMPLE_COVERAGE = 0x80A0;
/* ErrorCode */
const GLenum NO_ERROR = 0;
const GLenum INVALID_ENUM = 0x0500;
const GLenum INVALID_VALUE = 0x0501;
const GLenum INVALID_OPERATION = 0x0502;
const GLenum OUT_OF_MEMORY = 0x0505;
/* FrontFaceDirection */
const GLenum CW = 0x0900;
const GLenum CCW = 0x0901;
/* GetPName */
const GLenum LINE_WIDTH = 0x0B21;
const GLenum ALIASED_POINT_SIZE_RANGE = 0x846D;
const GLenum ALIASED_LINE_WIDTH_RANGE = 0x846E;
const GLenum CULL_FACE_MODE = 0x0B45;
const GLenum FRONT_FACE = 0x0B46;
const GLenum DEPTH_RANGE = 0x0B70;
const GLenum DEPTH_WRITEMASK = 0x0B72;
const GLenum DEPTH_CLEAR_VALUE = 0x0B73;
const GLenum DEPTH_FUNC = 0x0B74;
const GLenum STENCIL_CLEAR_VALUE = 0x0B91;
const GLenum STENCIL_FUNC = 0x0B92;
const GLenum STENCIL_FAIL = 0x0B94;
const GLenum STENCIL_PASS_DEPTH_FAIL = 0x0B95;
const GLenum STENCIL_PASS_DEPTH_PASS = 0x0B96;
const GLenum STENCIL_REF = 0x0B97;
const GLenum STENCIL_VALUE_MASK = 0x0B93;
const GLenum STENCIL_WRITEMASK = 0x0B98;
const GLenum STENCIL_BACK_FUNC = 0x8800;
const GLenum STENCIL_BACK_FAIL = 0x8801;
const GLenum STENCIL_BACK_PASS_DEPTH_FAIL = 0x8802;
const GLenum STENCIL_BACK_PASS_DEPTH_PASS = 0x8803;
const GLenum STENCIL_BACK_REF = 0x8CA3;
const GLenum STENCIL_BACK_VALUE_MASK = 0x8CA4;
const GLenum STENCIL_BACK_WRITEMASK = 0x8CA5;
const GLenum VIEWPORT = 0x0BA2;
const GLenum SCISSOR_BOX = 0x0C10;
/* SCISSOR_TEST */
const GLenum COLOR_CLEAR_VALUE = 0x0C22;
const GLenum COLOR_WRITEMASK = 0x0C23;
const GLenum UNPACK_ALIGNMENT = 0x0CF5;
const GLenum PACK_ALIGNMENT = 0x0D05;
const GLenum MAX_TEXTURE_SIZE = 0x0D33;
const GLenum MAX_VIEWPORT_DIMS = 0x0D3A;
const GLenum SUBPIXEL_BITS = 0x0D50;
const GLenum RED_BITS = 0x0D52;
const GLenum GREEN_BITS = 0x0D53;
const GLenum BLUE_BITS = 0x0D54;
const GLenum ALPHA_BITS = 0x0D55;
const GLenum DEPTH_BITS = 0x0D56;
const GLenum STENCIL_BITS = 0x0D57;
const GLenum POLYGON_OFFSET_UNITS = 0x2A00;
/* POLYGON_OFFSET_FILL */
const GLenum POLYGON_OFFSET_FACTOR = 0x8038;
const GLenum TEXTURE_BINDING_2D = 0x8069;
const GLenum SAMPLE_BUFFERS = 0x80A8;
const GLenum SAMPLES = 0x80A9;
const GLenum SAMPLE_COVERAGE_VALUE = 0x80AA;
const GLenum SAMPLE_COVERAGE_INVERT = 0x80AB;
/* GetTextureParameter */
/* TEXTURE_MAG_FILTER */
/* TEXTURE_MIN_FILTER */
/* TEXTURE_WRAP_S */
/* TEXTURE_WRAP_T */
const GLenum COMPRESSED_TEXTURE_FORMATS = 0x86A3;
/* HintMode */
const GLenum DONT_CARE = 0x1100;
const GLenum FASTEST = 0x1101;
const GLenum NICEST = 0x1102;
/* HintTarget */
const GLenum GENERATE_MIPMAP_HINT = 0x8192;
/* DataType */
const GLenum BYTE = 0x1400;
const GLenum UNSIGNED_BYTE = 0x1401;
const GLenum SHORT = 0x1402;
const GLenum UNSIGNED_SHORT = 0x1403;
const GLenum INT = 0x1404;
const GLenum UNSIGNED_INT = 0x1405;
const GLenum FLOAT = 0x1406;
/* PixelFormat */
const GLenum DEPTH_COMPONENT = 0x1902;
const GLenum ALPHA = 0x1906;
const GLenum RGB = 0x1907;
const GLenum RGBA = 0x1908;
const GLenum LUMINANCE = 0x1909;
const GLenum LUMINANCE_ALPHA = 0x190A;
/* PixelType */
/* UNSIGNED_BYTE */
const GLenum UNSIGNED_SHORT_4_4_4_4 = 0x8033;
const GLenum UNSIGNED_SHORT_5_5_5_1 = 0x8034;
const GLenum UNSIGNED_SHORT_5_6_5 = 0x8363;
/* Shaders */
const GLenum FRAGMENT_SHADER = 0x8B30;
const GLenum VERTEX_SHADER = 0x8B31;
const GLenum MAX_VERTEX_ATTRIBS = 0x8869;
const GLenum MAX_VERTEX_UNIFORM_VECTORS = 0x8DFB;
const GLenum MAX_VARYING_VECTORS = 0x8DFC;
const GLenum MAX_COMBINED_TEXTURE_IMAGE_UNITS = 0x8B4D;
const GLenum MAX_VERTEX_TEXTURE_IMAGE_UNITS = 0x8B4C;
const GLenum MAX_TEXTURE_IMAGE_UNITS = 0x8872;
const GLenum MAX_FRAGMENT_UNIFORM_VECTORS = 0x8DFD;
const GLenum SHADER_TYPE = 0x8B4F;
const GLenum DELETE_STATUS = 0x8B80;
const GLenum LINK_STATUS = 0x8B82;
const GLenum VALIDATE_STATUS = 0x8B83;
const GLenum ATTACHED_SHADERS = 0x8B85;
const GLenum ACTIVE_UNIFORMS = 0x8B86;
const GLenum ACTIVE_ATTRIBUTES = 0x8B89;
const GLenum SHADING_LANGUAGE_VERSION = 0x8B8C;
const GLenum CURRENT_PROGRAM = 0x8B8D;
/* StencilFunction */
const GLenum NEVER = 0x0200;
const GLenum LESS = 0x0201;
const GLenum EQUAL = 0x0202;
const GLenum LEQUAL = 0x0203;
const GLenum GREATER = 0x0204;
const GLenum NOTEQUAL = 0x0205;
const GLenum GEQUAL = 0x0206;
const GLenum ALWAYS = 0x0207;
/* StencilOp */
/* ZERO */
const GLenum KEEP = 0x1E00;
const GLenum REPLACE = 0x1E01;
const GLenum INCR = 0x1E02;
const GLenum DECR = 0x1E03;
const GLenum INVERT = 0x150A;
const GLenum INCR_WRAP = 0x8507;
const GLenum DECR_WRAP = 0x8508;
/* StringName */
const GLenum VENDOR = 0x1F00;
const GLenum RENDERER = 0x1F01;
const GLenum VERSION = 0x1F02;
/* TextureMagFilter */
const GLenum NEAREST = 0x2600;
const GLenum LINEAR = 0x2601;
/* TextureMinFilter */
/* NEAREST */
/* LINEAR */
const GLenum NEAREST_MIPMAP_NEAREST = 0x2700;
const GLenum LINEAR_MIPMAP_NEAREST = 0x2701;
const GLenum NEAREST_MIPMAP_LINEAR = 0x2702;
const GLenum LINEAR_MIPMAP_LINEAR = 0x2703;
/* TextureParameterName */
const GLenum TEXTURE_MAG_FILTER = 0x2800;
const GLenum TEXTURE_MIN_FILTER = 0x2801;
const GLenum TEXTURE_WRAP_S = 0x2802;
const GLenum TEXTURE_WRAP_T = 0x2803;
/* TextureTarget */
const GLenum TEXTURE_2D = 0x0DE1;
const GLenum TEXTURE = 0x1702;
const GLenum TEXTURE_CUBE_MAP = 0x8513;
const GLenum TEXTURE_BINDING_CUBE_MAP = 0x8514;
const GLenum TEXTURE_CUBE_MAP_POSITIVE_X = 0x8515;
const GLenum TEXTURE_CUBE_MAP_NEGATIVE_X = 0x8516;
const GLenum TEXTURE_CUBE_MAP_POSITIVE_Y = 0x8517;
const GLenum TEXTURE_CUBE_MAP_NEGATIVE_Y = 0x8518;
const GLenum TEXTURE_CUBE_MAP_POSITIVE_Z = 0x8519;
const GLenum TEXTURE_CUBE_MAP_NEGATIVE_Z = 0x851A;
const GLenum MAX_CUBE_MAP_TEXTURE_SIZE = 0x851C;
/* TextureUnit */
const GLenum TEXTURE0 = 0x84C0;
const GLenum TEXTURE1 = 0x84C1;
const GLenum TEXTURE2 = 0x84C2;
const GLenum TEXTURE3 = 0x84C3;
const GLenum TEXTURE4 = 0x84C4;
const GLenum TEXTURE5 = 0x84C5;
const GLenum TEXTURE6 = 0x84C6;
const GLenum TEXTURE7 = 0x84C7;
const GLenum TEXTURE8 = 0x84C8;
const GLenum TEXTURE9 = 0x84C9;
const GLenum TEXTURE10 = 0x84CA;
const GLenum TEXTURE11 = 0x84CB;
const GLenum TEXTURE12 = 0x84CC;
const GLenum TEXTURE13 = 0x84CD;
const GLenum TEXTURE14 = 0x84CE;
const GLenum TEXTURE15 = 0x84CF;
const GLenum TEXTURE16 = 0x84D0;
const GLenum TEXTURE17 = 0x84D1;
const GLenum TEXTURE18 = 0x84D2;
const GLenum TEXTURE19 = 0x84D3;
const GLenum TEXTURE20 = 0x84D4;
const GLenum TEXTURE21 = 0x84D5;
const GLenum TEXTURE22 = 0x84D6;
const GLenum TEXTURE23 = 0x84D7;
const GLenum TEXTURE24 = 0x84D8;
const GLenum TEXTURE25 = 0x84D9;
const GLenum TEXTURE26 = 0x84DA;
const GLenum TEXTURE27 = 0x84DB;
const GLenum TEXTURE28 = 0x84DC;
const GLenum TEXTURE29 = 0x84DD;
const GLenum TEXTURE30 = 0x84DE;
const GLenum TEXTURE31 = 0x84DF;
const GLenum ACTIVE_TEXTURE = 0x84E0;
/* TextureWrapMode */
const GLenum REPEAT = 0x2901;
const GLenum CLAMP_TO_EDGE = 0x812F;
const GLenum MIRRORED_REPEAT = 0x8370;
/* Uniform Types */
const GLenum FLOAT_VEC2 = 0x8B50;
const GLenum FLOAT_VEC3 = 0x8B51;
const GLenum FLOAT_VEC4 = 0x8B52;
const GLenum INT_VEC2 = 0x8B53;
const GLenum INT_VEC3 = 0x8B54;
const GLenum INT_VEC4 = 0x8B55;
const GLenum BOOL = 0x8B56;
const GLenum BOOL_VEC2 = 0x8B57;
const GLenum BOOL_VEC3 = 0x8B58;
const GLenum BOOL_VEC4 = 0x8B59;
const GLenum FLOAT_MAT2 = 0x8B5A;
const GLenum FLOAT_MAT3 = 0x8B5B;
const GLenum FLOAT_MAT4 = 0x8B5C;
const GLenum SAMPLER_2D = 0x8B5E;
const GLenum SAMPLER_CUBE = 0x8B60;
/* Vertex Arrays */
const GLenum VERTEX_ATTRIB_ARRAY_ENABLED = 0x8622;
const GLenum VERTEX_ATTRIB_ARRAY_SIZE = 0x8623;
const GLenum VERTEX_ATTRIB_ARRAY_STRIDE = 0x8624;
const GLenum VERTEX_ATTRIB_ARRAY_TYPE = 0x8625;
const GLenum VERTEX_ATTRIB_ARRAY_NORMALIZED = 0x886A;
const GLenum VERTEX_ATTRIB_ARRAY_POINTER = 0x8645;
const GLenum VERTEX_ATTRIB_ARRAY_BUFFER_BINDING = 0x889F;
/* Read Format */
const GLenum IMPLEMENTATION_COLOR_READ_TYPE = 0x8B9A;
const GLenum IMPLEMENTATION_COLOR_READ_FORMAT = 0x8B9B;
/* Shader Source */
const GLenum COMPILE_STATUS = 0x8B81;
/* Shader Precision-Specified Types */
const GLenum LOW_FLOAT = 0x8DF0;
const GLenum MEDIUM_FLOAT = 0x8DF1;
const GLenum HIGH_FLOAT = 0x8DF2;
const GLenum LOW_INT = 0x8DF3;
const GLenum MEDIUM_INT = 0x8DF4;
const GLenum HIGH_INT = 0x8DF5;
/* Framebuffer Object. */
const GLenum FRAMEBUFFER = 0x8D40;
const GLenum RENDERBUFFER = 0x8D41;
const GLenum RGBA4 = 0x8056;
const GLenum RGB5_A1 = 0x8057;
const GLenum RGBA8 = 0x8058;
const GLenum RGB565 = 0x8D62;
const GLenum DEPTH_COMPONENT16 = 0x81A5;
const GLenum STENCIL_INDEX8 = 0x8D48;
const GLenum DEPTH_STENCIL = 0x84F9;
const GLenum RENDERBUFFER_WIDTH = 0x8D42;
const GLenum RENDERBUFFER_HEIGHT = 0x8D43;
const GLenum RENDERBUFFER_INTERNAL_FORMAT = 0x8D44;
const GLenum RENDERBUFFER_RED_SIZE = 0x8D50;
const GLenum RENDERBUFFER_GREEN_SIZE = 0x8D51;
const GLenum RENDERBUFFER_BLUE_SIZE = 0x8D52;
const GLenum RENDERBUFFER_ALPHA_SIZE = 0x8D53;
const GLenum RENDERBUFFER_DEPTH_SIZE = 0x8D54;
const GLenum RENDERBUFFER_STENCIL_SIZE = 0x8D55;
const GLenum FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE = 0x8CD0;
const GLenum FRAMEBUFFER_ATTACHMENT_OBJECT_NAME = 0x8CD1;
const GLenum FRAMEBUFFER_ATTACHMENT_TEXTURE_LEVEL = 0x8CD2;
const GLenum FRAMEBUFFER_ATTACHMENT_TEXTURE_CUBE_MAP_FACE = 0x8CD3;
const GLenum COLOR_ATTACHMENT0 = 0x8CE0;
const GLenum DEPTH_ATTACHMENT = 0x8D00;
const GLenum STENCIL_ATTACHMENT = 0x8D20;
const GLenum DEPTH_STENCIL_ATTACHMENT = 0x821A;
const GLenum NONE = 0;
const GLenum FRAMEBUFFER_COMPLETE = 0x8CD5;
const GLenum FRAMEBUFFER_INCOMPLETE_ATTACHMENT = 0x8CD6;
const GLenum FRAMEBUFFER_INCOMPLETE_MISSING_ATTACHMENT = 0x8CD7;
const GLenum FRAMEBUFFER_INCOMPLETE_DIMENSIONS = 0x8CD9;
const GLenum FRAMEBUFFER_UNSUPPORTED = 0x8CDD;
const GLenum FRAMEBUFFER_BINDING = 0x8CA6;
const GLenum RENDERBUFFER_BINDING = 0x8CA7;
const GLenum MAX_RENDERBUFFER_SIZE = 0x84E8;
const GLenum INVALID_FRAMEBUFFER_OPERATION = 0x0506;
/* WebGL-specific enums */
const GLenum UNPACK_FLIP_Y_WEBGL = 0x9240;
const GLenum UNPACK_PREMULTIPLY_ALPHA_WEBGL = 0x9241;
const GLenum CONTEXT_LOST_WEBGL = 0x9242;
const GLenum UNPACK_COLORSPACE_CONVERSION_WEBGL = 0x9243;
const GLenum BROWSER_DEFAULT_WEBGL = 0x9244;
readonly attribute (HTMLCanvasElement or OffscreenCanvas) canvas;
readonly attribute GLsizei drawingBufferWidth;
readonly attribute GLsizei drawingBufferHeight;
readonly attribute GLenum drawingBufferFormat;
/* Upon context creation, drawingBufferColorSpace and unpackColorSpace both
default to the value "srgb". */
attribute PredefinedColorSpace drawingBufferColorSpace;
attribute PredefinedColorSpace unpackColorSpace;
[WebGLHandlesContextLoss] WebGLContextAttributes? getContextAttributes();
[WebGLHandlesContextLoss] boolean isContextLost();
sequence<DOMString>? getSupportedExtensions();
object? getExtension(DOMString name);
undefined drawingBufferStorage(GLenum sizedFormat, unsigned long width, unsigned long height);
undefined activeTexture(GLenum texture);
undefined attachShader(WebGLProgram program, WebGLShader shader);
undefined bindAttribLocation(WebGLProgram program, GLuint index, DOMString name);
undefined bindBuffer(GLenum target, WebGLBuffer? buffer);
undefined bindFramebuffer(GLenum target, WebGLFramebuffer? framebuffer);
undefined bindRenderbuffer(GLenum target, WebGLRenderbuffer? renderbuffer);
undefined bindTexture(GLenum target, WebGLTexture? texture);
undefined blendColor(GLclampf red, GLclampf green, GLclampf blue, GLclampf alpha);
undefined blendEquation(GLenum mode);
undefined blendEquationSeparate(GLenum modeRGB, GLenum modeAlpha);
undefined blendFunc(GLenum sfactor, GLenum dfactor);
undefined blendFuncSeparate(GLenum srcRGB, GLenum dstRGB,
GLenum srcAlpha, GLenum dstAlpha);
[WebGLHandlesContextLoss] GLenum checkFramebufferStatus(GLenum target);
undefined clear(GLbitfield mask);
undefined clearColor(GLclampf red, GLclampf green, GLclampf blue, GLclampf alpha);
undefined clearDepth(GLclampf depth);
undefined clearStencil(GLint s);
undefined colorMask(GLboolean red, GLboolean green, GLboolean blue, GLboolean alpha);
undefined compileShader(WebGLShader shader);
undefined copyTexImage2D(GLenum target, GLint level, GLenum internalformat,
GLint x, GLint y, GLsizei width, GLsizei height,
GLint border);
undefined copyTexSubImage2D(GLenum target, GLint level, GLint xoffset, GLint yoffset,
GLint x, GLint y, GLsizei width, GLsizei height);
WebGLBuffer createBuffer();
WebGLFramebuffer createFramebuffer();
WebGLProgram createProgram();
WebGLRenderbuffer createRenderbuffer();
WebGLShader? createShader(GLenum type);
WebGLTexture createTexture();
undefined cullFace(GLenum mode);
undefined deleteBuffer(WebGLBuffer? buffer);
undefined deleteFramebuffer(WebGLFramebuffer? framebuffer);
undefined deleteProgram(WebGLProgram? program);
undefined deleteRenderbuffer(WebGLRenderbuffer? renderbuffer);
undefined deleteShader(WebGLShader? shader);
undefined deleteTexture(WebGLTexture? texture);
undefined depthFunc(GLenum func);
undefined depthMask(GLboolean flag);
undefined depthRange(GLclampf zNear, GLclampf zFar);
undefined detachShader(WebGLProgram program, WebGLShader shader);
undefined disable(GLenum cap);
undefined disableVertexAttribArray(GLuint index);
undefined drawArrays(GLenum mode, GLint first, GLsizei count);
undefined drawElements(GLenum mode, GLsizei count, GLenum type, GLintptr offset);
undefined enable(GLenum cap);
undefined enableVertexAttribArray(GLuint index);
undefined finish();
undefined flush();
undefined framebufferRenderbuffer(GLenum target, GLenum attachment,
GLenum renderbuffertarget,
WebGLRenderbuffer? renderbuffer);
undefined framebufferTexture2D(GLenum target, GLenum attachment, GLenum textarget,
WebGLTexture? texture, GLint level);
undefined frontFace(GLenum mode);
undefined generateMipmap(GLenum target);
WebGLActiveInfo? getActiveAttrib(WebGLProgram program, GLuint index);
WebGLActiveInfo? getActiveUniform(WebGLProgram program, GLuint index);
sequence<WebGLShader>? getAttachedShaders(WebGLProgram program);
[WebGLHandlesContextLoss] GLint getAttribLocation(WebGLProgram program, DOMString name);
any getBufferParameter(GLenum target, GLenum pname);
any getParameter(GLenum pname);
[WebGLHandlesContextLoss] GLenum getError();
any getFramebufferAttachmentParameter(GLenum target, GLenum attachment,
GLenum pname);
any getProgramParameter(WebGLProgram program, GLenum pname);
DOMString? getProgramInfoLog(WebGLProgram program);
any getRenderbufferParameter(GLenum target, GLenum pname);
any getShaderParameter(WebGLShader shader, GLenum pname);
WebGLShaderPrecisionFormat? getShaderPrecisionFormat(GLenum shadertype, GLenum precisiontype);
DOMString? getShaderInfoLog(WebGLShader shader);
DOMString? getShaderSource(WebGLShader shader);
any getTexParameter(GLenum target, GLenum pname);
any getUniform(WebGLProgram program, WebGLUniformLocation location);
WebGLUniformLocation? getUniformLocation(WebGLProgram program, DOMString name);
any getVertexAttrib(GLuint index, GLenum pname);
[WebGLHandlesContextLoss] GLintptr getVertexAttribOffset(GLuint index, GLenum pname);
undefined hint(GLenum target, GLenum mode);
[WebGLHandlesContextLoss] GLboolean isBuffer(WebGLBuffer? buffer);
[WebGLHandlesContextLoss] GLboolean isEnabled(GLenum cap);
[WebGLHandlesContextLoss] GLboolean isFramebuffer(WebGLFramebuffer? framebuffer);
[WebGLHandlesContextLoss] GLboolean isProgram(WebGLProgram? program);
[WebGLHandlesContextLoss] GLboolean isRenderbuffer(WebGLRenderbuffer? renderbuffer);
[WebGLHandlesContextLoss] GLboolean isShader(WebGLShader? shader);
[WebGLHandlesContextLoss] GLboolean isTexture(WebGLTexture? texture);
undefined lineWidth(GLfloat width);
undefined linkProgram(WebGLProgram program);
undefined pixelStorei(GLenum pname, GLint param);
undefined polygonOffset(GLfloat factor, GLfloat units);
undefined renderbufferStorage(GLenum target, GLenum internalformat,
GLsizei width, GLsizei height);
undefined sampleCoverage(GLclampf value, GLboolean invert);
undefined scissor(GLint x, GLint y, GLsizei width, GLsizei height);
undefined shaderSource(WebGLShader shader, DOMString source);
undefined stencilFunc(GLenum func, GLint ref, GLuint mask);
undefined stencilFuncSeparate(GLenum face, GLenum func, GLint ref, GLuint mask);
undefined stencilMask(GLuint mask);
undefined stencilMaskSeparate(GLenum face, GLuint mask);
undefined stencilOp(GLenum fail, GLenum zfail, GLenum zpass);
undefined stencilOpSeparate(GLenum face, GLenum fail, GLenum zfail, GLenum zpass);
undefined texParameterf(GLenum target, GLenum pname, GLfloat param);
undefined texParameteri(GLenum target, GLenum pname, GLint param);
undefined uniform1f(WebGLUniformLocation? location, GLfloat x);
undefined uniform2f(WebGLUniformLocation? location, GLfloat x, GLfloat y);
undefined uniform3f(WebGLUniformLocation? location, GLfloat x, GLfloat y, GLfloat z);
undefined uniform4f(WebGLUniformLocation? location, GLfloat x, GLfloat y, GLfloat z, GLfloat w);
undefined uniform1i(WebGLUniformLocation? location, GLint x);
undefined uniform2i(WebGLUniformLocation? location, GLint x, GLint y);
undefined uniform3i(WebGLUniformLocation? location, GLint x, GLint y, GLint z);
undefined uniform4i(WebGLUniformLocation? location, GLint x, GLint y, GLint z, GLint w);
undefined useProgram(WebGLProgram? program);
undefined validateProgram(WebGLProgram program);
undefined vertexAttrib1f(GLuint index, GLfloat x);
undefined vertexAttrib2f(GLuint index, GLfloat x, GLfloat y);
undefined vertexAttrib3f(GLuint index, GLfloat x, GLfloat y, GLfloat z);
undefined vertexAttrib4f(GLuint index, GLfloat x, GLfloat y, GLfloat z, GLfloat w);
undefined vertexAttrib1fv(GLuint index, Float32List values);
undefined vertexAttrib2fv(GLuint index, Float32List values);
undefined vertexAttrib3fv(GLuint index, Float32List values);
undefined vertexAttrib4fv(GLuint index, Float32List values);
undefined vertexAttribPointer(GLuint index, GLint size, GLenum type,
GLboolean normalized, GLsizei stride, GLintptr offset);
undefined viewport(GLint x, GLint y, GLsizei width, GLsizei height);
};
interface mixin WebGLRenderingContextOverloads
{
undefined bufferData(GLenum target, GLsizeiptr size, GLenum usage);
undefined bufferData(GLenum target, AllowSharedBufferSource? data, GLenum usage);
undefined bufferSubData(GLenum target, GLintptr offset, AllowSharedBufferSource data);
undefined compressedTexImage2D(GLenum target, GLint level, GLenum internalformat,
GLsizei width, GLsizei height, GLint border,
[AllowShared] ArrayBufferView data);
undefined compressedTexSubImage2D(GLenum target, GLint level,
GLint xoffset, GLint yoffset,
GLsizei width, GLsizei height, GLenum format,
[AllowShared] ArrayBufferView data);
undefined readPixels(GLint x, GLint y, GLsizei width, GLsizei height,
GLenum format, GLenum type, [AllowShared] ArrayBufferView? pixels);
undefined texImage2D(GLenum target, GLint level, GLint internalformat,
GLsizei width, GLsizei height, GLint border, GLenum format,
GLenum type, [AllowShared] ArrayBufferView? pixels);
undefined texImage2D(GLenum target, GLint level, GLint internalformat,
GLenum format, GLenum type, TexImageSource source); // May throw DOMException
undefined texSubImage2D(GLenum target, GLint level, GLint xoffset, GLint yoffset,
GLsizei width, GLsizei height,
GLenum format, GLenum type, [AllowShared] ArrayBufferView? pixels);
undefined texSubImage2D(GLenum target, GLint level, GLint xoffset, GLint yoffset,
GLenum format, GLenum type, TexImageSource source); // May throw DOMException
undefined uniform1fv(WebGLUniformLocation? location, Float32List v);
undefined uniform2fv(WebGLUniformLocation? location, Float32List v);
undefined uniform3fv(WebGLUniformLocation? location, Float32List v);
undefined uniform4fv(WebGLUniformLocation? location, Float32List v);
undefined uniform1iv(WebGLUniformLocation? location, Int32List v);
undefined uniform2iv(WebGLUniformLocation? location, Int32List v);
undefined uniform3iv(WebGLUniformLocation? location, Int32List v);
undefined uniform4iv(WebGLUniformLocation? location, Int32List v);
undefined uniformMatrix2fv(WebGLUniformLocation? location, GLboolean transpose, Float32List value);
undefined uniformMatrix3fv(WebGLUniformLocation? location, GLboolean transpose, Float32List value);
undefined uniformMatrix4fv(WebGLUniformLocation? location, GLboolean transpose, Float32List value);
};
[Exposed=(Window,Worker)]
interface WebGLRenderingContext
{
};
WebGLRenderingContext includes WebGLRenderingContextBase;
WebGLRenderingContext includes WebGLRenderingContextOverloads;
The following attributes are available:
canvas
of type (HTMLCanvasElement or OffscreenCanvas)
drawingBufferWidth
of type GLsizei
width attribute of the HTMLCanvasElement if
the implementation is unable to satisfy the requested widthor height.
drawingBufferHeight
of type GLsizei
height attribute of the HTMLCanvasElement if
the implementation is unable to satisfy the requested width or height.
drawingBufferFormat
of type GLenum
RGBA8 or RGB8 for alpha:true and alpha:false respectively.
drawingBufferColorSpace
of type PredefinedColorSpace
(specification)
unpackColorSpace
of type PredefinedColorSpace
(specification)
TexImageSource sources are
converted when uploading them to textures in this context.
OpenGL ES 2.0 maintains state values for use in rendering. All the calls in this group behave identically to their OpenGL counterparts unless otherwise noted.
blendColor clamps its arguments to the range 0 to 1 in WebGL 1.0, unless EXT_color_buffer_half_float or WEBGL_color_buffer_float are enabled.
depth value is clamped to the range 0 to 1.
zNear and zFar values are clamped to the range 0 to 1 and
zNear must be less than or equal to zFar; see
Viewport Depth Range.
| pname | returned type |
|---|---|
| ACTIVE_TEXTURE | GLenum |
| ALIASED_LINE_WIDTH_RANGE | Float32Array (with 2 elements) |
| ALIASED_POINT_SIZE_RANGE | Float32Array (with 2 elements) |
| ALPHA_BITS | GLint |
| ARRAY_BUFFER_BINDING | WebGLBuffer |
| BLEND | GLboolean |
| BLEND_COLOR | Float32Array (with 4 values) |
| BLEND_DST_ALPHA | GLenum |
| BLEND_DST_RGB | GLenum |
| BLEND_EQUATION_ALPHA | GLenum |
| BLEND_EQUATION_RGB | GLenum |
| BLEND_SRC_ALPHA | GLenum |
| BLEND_SRC_RGB | GLenum |
| BLUE_BITS | GLint |
| COLOR_CLEAR_VALUE | Float32Array (with 4 values) |
| COLOR_WRITEMASK | sequence<GLboolean> (with 4 values) |
| COMPRESSED_TEXTURE_FORMATS | Uint32Array |
| CULL_FACE | GLboolean |
| CULL_FACE_MODE | GLenum |
| CURRENT_PROGRAM | WebGLProgram |
| DEPTH_BITS | GLint |
| DEPTH_CLEAR_VALUE | GLfloat |
| DEPTH_FUNC | GLenum |
| DEPTH_RANGE | Float32Array (with 2 elements) |
| DEPTH_TEST | GLboolean |
| DEPTH_WRITEMASK | GLboolean |
| DITHER | GLboolean |
| ELEMENT_ARRAY_BUFFER_BINDING | WebGLBuffer |
| FRAMEBUFFER_BINDING | WebGLFramebuffer |
| FRONT_FACE | GLenum |
| GENERATE_MIPMAP_HINT | GLenum |
| GREEN_BITS | GLint |
| IMPLEMENTATION_COLOR_READ_FORMAT | GLenum |
| IMPLEMENTATION_COLOR_READ_TYPE | GLenum |
| LINE_WIDTH | GLfloat |
| MAX_COMBINED_TEXTURE_IMAGE_UNITS | GLint |
| MAX_CUBE_MAP_TEXTURE_SIZE | GLint |
| MAX_FRAGMENT_UNIFORM_VECTORS | GLint |
| MAX_RENDERBUFFER_SIZE | GLint |
| MAX_TEXTURE_IMAGE_UNITS | GLint |
| MAX_TEXTURE_SIZE | GLint |
| MAX_VARYING_VECTORS | GLint |
| MAX_VERTEX_ATTRIBS | GLint |
| MAX_VERTEX_TEXTURE_IMAGE_UNITS | GLint |
| MAX_VERTEX_UNIFORM_VECTORS | GLint |
| MAX_VIEWPORT_DIMS | Int32Array (with 2 elements) |
| PACK_ALIGNMENT | GLint |
| POLYGON_OFFSET_FACTOR | GLfloat |
| POLYGON_OFFSET_FILL | GLboolean |
| POLYGON_OFFSET_UNITS | GLfloat |
| RED_BITS | GLint |
| RENDERBUFFER_BINDING | WebGLRenderbuffer |
| RENDERER | DOMString |
| SAMPLE_ALPHA_TO_COVERAGE | GLboolean |
| SAMPLE_BUFFERS | GLint |
| SAMPLE_COVERAGE | GLboolean |
| SAMPLE_COVERAGE_INVERT | GLboolean |
| SAMPLE_COVERAGE_VALUE | GLfloat |
| SAMPLES | GLint |
| SCISSOR_BOX | Int32Array (with 4 elements) |
| SCISSOR_TEST | GLboolean |
| SHADING_LANGUAGE_VERSION | DOMString |
| STENCIL_BACK_FAIL | GLenum |
| STENCIL_BACK_FUNC | GLenum |
| STENCIL_BACK_PASS_DEPTH_FAIL | GLenum |
| STENCIL_BACK_PASS_DEPTH_PASS | GLenum |
| STENCIL_BACK_REF | GLint |
| STENCIL_BACK_VALUE_MASK | GLuint |
| STENCIL_BACK_WRITEMASK | GLuint |
| STENCIL_BITS | GLint |
| STENCIL_CLEAR_VALUE | GLint |
| STENCIL_FAIL | GLenum |
| STENCIL_FUNC | GLenum |
| STENCIL_PASS_DEPTH_FAIL | GLenum |
| STENCIL_PASS_DEPTH_PASS | GLenum |
| STENCIL_REF | GLint |
| STENCIL_TEST | GLboolean |
| STENCIL_VALUE_MASK | GLuint |
| STENCIL_WRITEMASK | GLuint |
| SUBPIXEL_BITS | GLint |
| TEXTURE_BINDING_2D | WebGLTexture |
| TEXTURE_BINDING_CUBE_MAP | WebGLTexture |
| UNPACK_ALIGNMENT | GLint |
| UNPACK_COLORSPACE_CONVERSION_WEBGL | GLenum |
| UNPACK_FLIP_Y_WEBGL | GLboolean |
| UNPACK_PREMULTIPLY_ALPHA_WEBGL | GLboolean |
| VENDOR | DOMString |
| VERSION | DOMString |
| VIEWPORT | Int32Array (with 4 elements) |
All queries returning sequences or typed arrays return a new object each time.
If pname is not in the table above, generates an INVALID_ENUM error and returns null.
If pname is IMPLEMENTATION_COLOR_READ_FORMAT
or IMPLEMENTATION_COLOR_READ_TYPE, and the currently bound framebuffer is
not framebuffer complete, generates an INVALID_OPERATION error and
returns null.
The following pname arguments return a string describing some aspect of the current WebGL implementation:
| VERSION | Returns a version or release number of the form WebGL<space>1.0<optional><space><vendor-specific information></optional>. |
| SHADING_LANGUAGE_VERSION | Returns a version or release number of the form WebGL<space>GLSL<space>ES<space>1.0<optional><space><vendor-specific information></optional>. |
| VENDOR | Returns the company responsible for this WebGL implementation. This name does not change from release to release. |
| RENDERER | Returns the name of the renderer. This name is typically specific to a particular configuration of a hardware platform. It does not change from release to release. |
See Extension Queries for information on querying the available extensions in the current WebGL implementation.
CONTEXT_LOST_WEBGL the first time this method is
called. Afterward, returns NO_ERROR until the context has
been restored.
isEnabled query, the same boolean value can be obtained via
getParameter.
UNPACK_FLIP_Y_WEBGL,
UNPACK_PREMULTIPLY_ALPHA_WEBGL
and UNPACK_COLORSPACE_CONVERSION_WEBGL. See Pixel
Storage Parameters for documentation of these parameters.
Drawing commands can only modify pixels inside the currently bound framebuffer. In addition, the viewport and the scissor box affect drawing.
The viewport specifies the affine transformation of x and y from normalized device
coordinates to window coordinates. The size of the viewport is initially determined
as specified in section The WebGL Viewport.
The scissor box defines a rectangle which constrains drawing. When the scissor test is
enabled only pixels that lie within the scissor box can be modified by drawing commands
including clear, and primitives can only be drawn inside the intersection
of the viewport, the currently bound framebuffer, and the scissor box. When the scissor
test is not enabled primitives can only be drawn inside the intersection of the viewport
and the currently bound framebuffer.
Buffer objects (sometimes referred to as VBOs) hold vertex attribute data for the GLSL shaders.
buffer was generated by a different WebGLRenderingContext
than this one, generates an INVALID_OPERATION error. INVALID_OPERATION error, and the
current binding will remain untouched.
An attempt to bind an object marked for deletion will generate an
INVALID_OPERATION error, and the current binding will remain untouched.
INVALID_VALUE error is generated.
void bufferSubData(GLenum target, GLintptr offset, AllowSharedBufferSource data) (OpenGL ES 2.0 §2.9, man page)
INVALID_VALUE error is generated. If data is null then
an INVALID_VALUE error is generated.
buffer was generated by a different WebGLRenderingContext
than this one, generates an INVALID_OPERATION error. | pname | returned type |
|---|---|
| BUFFER_SIZE | GLint |
| BUFFER_USAGE | GLenum |
If pname is not in the table above, generates an INVALID_ENUM error.
If an OpenGL error is generated, returns null.
WebGLRenderingContext than this one. Framebuffer objects provide an alternative rendering target to the drawing buffer. They are a collection of color, alpha, depth and stencil buffers and are often used to render an image that will later be used as a texture.
framebuffer was generated by a
different WebGLRenderingContext than this one, generates
an INVALID_OPERATION error. WebGLFramebuffer object to the given binding point
(target), which must be FRAMEBUFFER.
If framebuffer is null, the default framebuffer provided by the context
is bound and attempts to modify or query state on target FRAMEBUFFER
will generate an INVALID_OPERATION error.
An attempt to bind an object marked for deletion will generate an
INVALID_OPERATION error, and the current binding will remain untouched.
FRAMEBUFFER_UNSUPPORTED if the
context's webgl context lost flag is set.
framebuffer was generated by a different WebGLRenderingContext
than this one, generates an INVALID_OPERATION error. renderbuffer was generated by a different WebGLRenderingContext
than this one, generates an INVALID_OPERATION error. texture was generated by a different WebGLRenderingContext
than this one, generates an INVALID_OPERATION error. | pname | returned type |
|---|---|
| FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE | GLenum |
| FRAMEBUFFER_ATTACHMENT_OBJECT_NAME | WebGLRenderbuffer or WebGLTexture |
| FRAMEBUFFER_ATTACHMENT_TEXTURE_LEVEL | GLint |
| FRAMEBUFFER_ATTACHMENT_TEXTURE_CUBE_MAP_FACE | GLint |
If pname is not in the table above, generates an INVALID_ENUM error.
If an OpenGL error is generated, returns null.
WebGLRenderingContext than this one. Renderbuffer objects are used to provide storage for the individual buffers used in a framebuffer object.
renderbuffer was generated by a
different WebGLRenderingContext than this one, generates
an INVALID_OPERATION error. WebGLRenderbuffer object to the given binding point
(target), which must be RENDERBUFFER.
If renderbuffer is null the renderbuffer object currently bound to
this target is unbound.
An attempt to bind an object marked for deletion will generate an
INVALID_OPERATION error, and the current binding will remain untouched.
renderbuffer was generated by a different WebGLRenderingContext
than this one, generates an INVALID_OPERATION error. | pname | returned type |
|---|---|
| RENDERBUFFER_WIDTH | GLint |
| RENDERBUFFER_HEIGHT | GLint |
| RENDERBUFFER_INTERNAL_FORMAT | GLenum |
| RENDERBUFFER_RED_SIZE | GLint |
| RENDERBUFFER_GREEN_SIZE | GLint |
| RENDERBUFFER_BLUE_SIZE | GLint |
| RENDERBUFFER_ALPHA_SIZE | GLint |
| RENDERBUFFER_DEPTH_SIZE | GLint |
| RENDERBUFFER_STENCIL_SIZE | GLint |
If pname is not in the table above, generates an INVALID_ENUM error.
If an OpenGL error is generated, returns null.
WebGLRenderingContext than this one.
Texture objects provide storage and state for texturing operations. If no WebGLTexture is bound
(e.g., passing null or 0 to bindTexture) then attempts to modify or query the texture object shall
generate an INVALID_OPERATION error. This is indicated in the functions below.
texture was generated by a different WebGLRenderingContext
than this one, generates an INVALID_OPERATION error. INVALID_OPERATION error, and the current binding will remain untouched.
void compressedTexImage2D(GLenum target, GLint level, GLenum internalformat, GLsizei width, GLsizei height, GLint border, [AllowShared] ArrayBufferView pixels) (OpenGL ES 2.0 §3.7.3, man page)
void compressedTexSubImage2D(GLenum target, GLint level, GLint xoffset, GLint yoffset, GLsizei width, GLsizei height, GLenum format, [AllowShared] ArrayBufferView pixels) (OpenGL ES 2.0 §3.7.3, man page)
INVALID_OPERATION error is generated. INVALID_ENUM error and return
immediately. See Compressed Texture Support.
INVALID_OPERATION error is generated. texImage2D were called with null data, followed
by copyTexSubImage2D.
As in copyTexSubImage2D, for any source pixels lying outside the
framebuffer, the corresponding destination texels are left untouched, and so they retain
their zero-initialized contents as if texImage2D was called with null data.
This has the combined effect that, for source pixels lying outside the
framebuffer, corresponding destination pixels will have all channels of the associated
texels initialized to 0;
see Reading Pixels Outside the Framebuffer. INVALID_OPERATION error is generated
per Reading from a Missing Attachment.
INVALID_OPERATION error is generated. INVALID_OPERATION error is generated
per Reading from a Missing Attachment.
texture was generated by a different WebGLRenderingContext
than this one, generates an INVALID_OPERATION error. INVALID_OPERATION error is generated.
| pname | returned type |
|---|---|
| TEXTURE_MAG_FILTER | GLenum |
| TEXTURE_MIN_FILTER | GLenum |
| TEXTURE_WRAP_S | GLenum |
| TEXTURE_WRAP_T | GLenum |
If pname is not in the table above, generates an INVALID_ENUM error.
If an attempt is made to call this function with no WebGLTexture bound (see above), generates an
INVALID_OPERATION error.
If an OpenGL error is generated, returns null.
WebGLRenderingContext than this one. pixels is null, a buffer of sufficient size initialized to 0 is
passed. pixels is non-null, the type of pixels must match the type
of the data to be read. If it is UNSIGNED_BYTE, a Uint8Array or Uint8ClampedArray must
be supplied; if it is UNSIGNED_SHORT_5_6_5, UNSIGNED_SHORT_4_4_4_4, or
UNSIGNED_SHORT_5_5_5_1, a Uint16Array must be supplied. If the types do not match, an
INVALID_OPERATION error is generated.
INVALID_OPERATION error is generated. pixels is non-null but its size is less than what is required by the specified width, height, format, type, and pixel storage parameters, generates an INVALID_OPERATION error.
void texImage2D(GLenum target, GLint level, GLint internalformat, GLenum format, GLenum type, TexImageSource source) /* May throw DOMException */ (OpenGL ES 2.0 §3.7.1, man page)
UNPACK_COLORSPACE_CONVERSION_WEBGL pixel storage parameter is set
to NONE. ImageBitmap objects as well, though
other texture unpack parameters do not apply to ImageBitmaps because they
are expected to be specified during ImageBitmap construction.
Implementation experience revealed that it was beneficial to
perform ImageBitmaps' color space conversion as late as possible when
uploading to WebGL textures.
| Source DOM Image Format | Target WebGL Format | ||||
|---|---|---|---|---|---|
| ALPHA | RGB | RGBA | LUMINANCE | LUMINANCE_ALPHA | |
| Grayscale (1 channel) | A = 255 (1.0) | R = sourceGray G = sourceGray B = sourceGray |
R = sourceGray G = sourceGray B = sourceGray A = 255 (1.0) |
L = sourceGray | L = sourceGray A = 255 (1.0) |
| Grayscale + Alpha (2 channels) | A = sourceAlpha | R = sourceGray G = sourceGray B = sourceGray |
R = sourceGray G = sourceGray B = sourceGray A = sourceAlpha |
L = sourceGray |
L = sourceGray A = sourceAlpha |
| Color (3 channels) | A = 255 (1.0) | R = sourceRed G = sourceGreen B = sourceBlue |
R = sourceRed G = sourceGreen B = sourceBlue A = 255 (1.0) |
L = sourceRed | L = sourceRed A = 255 (1.0) |
| Color + Alpha (4 channels) | A = sourceAlpha | R = sourceRed G = sourceGreen B = sourceBlue |
R = sourceRed G = sourceGreen B = sourceBlue A = sourceAlpha |
L = sourceRed | L = sourceRed A = sourceAlpha |
ImageBitmap. UNPACK_FLIP_Y_WEBGL pixel storage
parameter, except for ImageBitmap arguments, as described in the
abovementioned section. HTMLImageElement or ImageBitmap containing
an RGB or RGBA lossless image with 8 bits per channel, the browser guarantees that the
full precision of all channels is preserved. HTMLImageElement contains an alpha channel and the
UNPACK_PREMULTIPLY_ALPHA_WEBGL pixel storage parameter is false, then the
RGB values are guaranteed to never have been premultiplied by the alpha channel, whether
those values are derived directly from the original file format or converted from some
other color format. UNPACK_PREMULTIPLY_ALPHA_WEBGL pixel storage parameter set to false, the
color channels will have to be un-multiplied by the alpha channel, which is a lossy
operation. The WebGL implementation therefore can not guarantee that colors with alpha
< 1.0 will be preserved losslessly when first drawn to a canvas via
CanvasRenderingContext2D and then uploaded to a WebGL texture when
the UNPACK_PREMULTIPLY_ALPHA_WEBGL pixel storage parameter is set to false.
INVALID_OPERATION error is generated. ImageData whose data
attribute has been neutered, an INVALID_VALUE error is generated. ImageBitmap that has been neutered,
an INVALID_VALUE error is generated. HTMLImageElement
or HTMLVideoElement whose origin differs from the origin of the containing
Document, or with an HTMLCanvasElement, ImageBitmap
or OffscreenCanvas whose bitmap's origin-clean flag is set to false,
a SECURITY_ERR exception must be
thrown. See Origin Restrictions.source is null then an INVALID_VALUE error is
generated. INVALID_OPERATION error is generated.
INVALID_OPERATION error is generated.
INVALID_OPERATION error is generated. INVALID_OPERATION error is generated. pixels is null then an INVALID_VALUE error is
generated. pixels is non-null but its size is less than what is required by the specified width, height, format, type, and pixel storage parameters, generates an INVALID_OPERATION error. void texSubImage2D(GLenum target, GLint level, GLint xoffset, GLint yoffset, GLenum format, GLenum type, TexImageSource source) /* May throw DOMException */ (OpenGL ES 2.0 §3.7.2, man page)
UNPACK_FLIP_Y_WEBGL pixel storage
parameter, except for ImageBitmap arguments, as described in the
abovementioned section. INVALID_OPERATION error is generated. INVALID_OPERATION error is generated. ImageData whose data
attribute has been neutered, an INVALID_VALUE error is generated. ImageBitmap that has been neutered,
an INVALID_VALUE error is generated. HTMLImageElement
or HTMLVideoElement whose origin differs from the origin of the containing
Document, or with an HTMLCanvasElement, ImageBitmap,
or OffscreenCanvas whose bitmap's origin-clean flag is set to false,
a SECURITY_ERR exception must be thrown. See
Origin Restrictions.source is null then an INVALID_VALUE error is
generated. Rendering with OpenGL ES 2.0 requires the use of shaders, written in OpenGL ES's shading language, GLSL ES. Shaders must be loaded with a source string (shaderSource), compiled (compileShader) and attached to a program (attachShader) which must be linked (linkProgram) and then used (useProgram).
program or shader were generated by a different
WebGLRenderingContext than this one, generates
an INVALID_OPERATION error.
program was generated by a different WebGLRenderingContext
than this one, generates an INVALID_OPERATION error. INVALID_VALUE error. name starts with one of the reserved WebGL prefixes
per GLSL Constructs, generates
an INVALID_OPERATION error. shader was generated by a different WebGLRenderingContext
than this one, generates an INVALID_OPERATION error. program was generated by a different WebGLRenderingContext
than this one, generates an INVALID_OPERATION error. shader was generated by a different WebGLRenderingContext
than this one, generates an INVALID_OPERATION error. program or shader were generated by a different
WebGLRenderingContext than this one, generates
an INVALID_OPERATION error.
program was generated by a different WebGLRenderingContext
than this one, generates an INVALID_OPERATION error. Returns a new object representing the list of shaders attached to the passed program.
Returns null if any OpenGL errors are generated during the execution of this function.
program was generated by a different WebGLRenderingContext
than this one, generates an INVALID_OPERATION error. | pname | returned type |
|---|---|
| DELETE_STATUS | GLboolean |
| LINK_STATUS | GLboolean |
| VALIDATE_STATUS | GLboolean |
| ATTACHED_SHADERS | GLint |
| ACTIVE_ATTRIBUTES | GLint |
| ACTIVE_UNIFORMS | GLint |
If pname is not in the table above, generates an INVALID_ENUM error and returns null.
Returns null if any OpenGL errors are generated during the execution of this function.
program was generated by a different WebGLRenderingContext
than this one, generates an INVALID_OPERATION error. Returns null if any OpenGL errors are generated during the execution of this function.
shader was generated by a different WebGLRenderingContext
than this one, generates an INVALID_OPERATION error. | pname | returned type |
|---|---|
| SHADER_TYPE | GLenum |
| DELETE_STATUS | GLboolean |
| COMPILE_STATUS | GLboolean |
If pname is not in the table above, generates an INVALID_ENUM error and returns null.
Returns null if any OpenGL errors are generated during the execution of this function.
Return a new WebGLShaderPrecisionFormat describing the range and precision
for the specified shader numeric format. The shadertype value can be FRAGMENT_SHADER or
VERTEX_SHADER. The precisiontype value can be LOW_FLOAT, MEDIUM_FLOAT, HIGH_FLOAT,
LOW_INT, MEDIUM_INT or HIGH_INT.
Returns null if any OpenGL errors are generated during the execution of this function.
shader was generated by a different WebGLRenderingContext
than this one, generates an INVALID_OPERATION error. Returns null if any OpenGL errors are generated during the execution of this function.
shader was generated by a different WebGLRenderingContext
than this one, generates an INVALID_OPERATION error. Returns null if any OpenGL errors are generated during the execution of this function.
WebGLRenderingContext than this one. WebGLRenderingContext than this one. program was generated by a different WebGLRenderingContext
than this one, generates an INVALID_OPERATION error. useProgram, below, then:
INVALID_OPERATION error.
See Current program invalidated upon unsuccessful
link.
shader was generated by a different WebGLRenderingContext
than this one, generates an INVALID_OPERATION error. program was generated by a different WebGLRenderingContext
than this one, generates an INVALID_OPERATION error. program was generated by a different WebGLRenderingContext
than this one, generates an INVALID_OPERATION error. Values used by the shaders are passed in as uniforms or vertex attributes.
index as an array. WebGL imposes additional
rules beyond OpenGL ES 2.0 regarding enabled vertex attributes;
see Enabled Vertex Attributes and Range
Checking.
program was generated by a different WebGLRenderingContext
than this one, generates an INVALID_OPERATION error. WebGLActiveInfo object describing the size, type and name of
the vertex attribute at the passed index of the passed program object. If the passed
index is out of range, generates an INVALID_VALUE error and returns null.
Returns null if any OpenGL errors are generated during the execution of this function.
program was generated by a different WebGLRenderingContext
than this one, generates an INVALID_OPERATION error. WebGLActiveInfo object describing the size, type and name of
the uniform at the passed index of the passed program object. If the passed index is out
of range, generates an INVALID_VALUE error and returns null.
Returns null if any OpenGL errors are generated during the execution of this function.
program was generated by a different WebGLRenderingContext
than this one, generates an INVALID_OPERATION error and returns -1. INVALID_VALUE error and returns -1. name starts with one of the reserved WebGL prefixes
per GLSL Constructs. INVALID_OPERATION error and returns
-1. program or location were generated by a
different WebGLRenderingContext than this one, generates
an INVALID_OPERATION error. | uniform type | returned type |
|---|---|
| boolean | GLboolean |
| int | GLint |
| float | GLfloat |
| vec2 | Float32Array (with 2 elements) |
| ivec2 | Int32Array (with 2 elements) |
| bvec2 | sequence<GLboolean> (with 2 elements) |
| vec3 | Float32Array (with 3 elements) |
| ivec3 | Int32Array (with 3 elements) |
| bvec3 | sequence<GLboolean> (with 3 elements) |
| vec4 | Float32Array (with 4 elements) |
| ivec4 | Int32Array (with 4 elements) |
| bvec4 | sequence<GLboolean> (with 4 elements) |
| mat2 | Float32Array (with 4 elements) |
| mat3 | Float32Array (with 9 elements) |
| mat4 | Float32Array (with 16 elements) |
| sampler2D | GLint |
| samplerCube | GLint |
All queries returning sequences or typed arrays return a new object each time.
Returns null if any OpenGL errors are generated during the execution of this function.
program was generated by a different WebGLRenderingContext
than this one, generates an INVALID_OPERATION error. Return a new WebGLUniformLocation that represents the location of a
specific uniform variable within a program object. The return value is null if name does
not correspond to an active uniform variable in the passed program.
If the passed name is longer than the restriction defined
in Maximum Uniform and Attribute Location Lengths,
generates an INVALID_VALUE error and returns null.
Returns null if name starts with one of the reserved WebGL prefixes
per GLSL Constructs.
See Characters Outside the GLSL Source Character Set for additional validation performed by WebGL implementations.
Returns null if any OpenGL errors are generated during the execution of this function.
| pname | returned type |
|---|---|
| VERTEX_ATTRIB_ARRAY_BUFFER_BINDING | WebGLBuffer |
| VERTEX_ATTRIB_ARRAY_ENABLED | GLboolean |
| VERTEX_ATTRIB_ARRAY_SIZE | GLint |
| VERTEX_ATTRIB_ARRAY_STRIDE | GLint |
| VERTEX_ATTRIB_ARRAY_TYPE | GLenum |
| VERTEX_ATTRIB_ARRAY_NORMALIZED | GLboolean |
| CURRENT_VERTEX_ATTRIB | Float32Array (with 4 elements) |
All queries returning sequences or typed arrays return a new object each time.
If pname is not in the table above, generates an INVALID_ENUM error.
If an OpenGL error is generated, returns null.
void uniform[1234][fi](WebGLUniformLocation? location, ...)
void uniform[1234][fi]v(WebGLUniformLocation? location, ...)
void uniformMatrix[234]fv(WebGLUniformLocation? location, GLboolean transpose, ...) (OpenGL ES 2.0 §2.10.4, man page)
location is not null and was not obtained
from the currently used program via an earlier call to getUniformLocation,
an INVALID_OPERATION error will be generated. If the passed
location is null, the data passed in will be silently ignored and
no uniform variables will be changed.
v) has an
invalid length, an INVALID_VALUE error will be generated. The length is
invalid if it is too short for or is not an integer multiple of the assigned type.
uniform1i to update sampler uniforms. To change the texture
referenced by a sampler uniform, binding a new texture to the texture unit referenced
by the uniform should be preferred over using uniform1i to update the
uniform itself.void vertexAttrib[1234]f(GLuint index, ...)
void vertexAttrib[1234]fv(GLuint index, ...) (OpenGL ES 2.0 §2.7, man page)
vertexAttrib are guaranteed to be returned from the getVertexAttrib function
with the CURRENT_VERTEX_ATTRIB param, even if there have been intervening calls to
drawArrays or drawElements.
v) is too
short, an INVALID_VALUE error will be generated.
INVALID_OPERATION error will be generated;
see Buffer Offset and Stride Requirements. If
offset is negative, an INVALID_VALUE error will be generated. If no
WebGLBuffer is bound to the ARRAY_BUFFER target and offset is non-zero,
an INVALID_OPERATION error will be generated. In WebGL, the maximum
supported stride is 255; see Vertex Attribute Data Stride.
OpenGL ES 2.0 has several calls which are allowed to write to the currently bound (draw) framebuffer. WebGL categorizes all such calls as [Draw Operations].
Furthermore, rendering can be directed to the drawing buffer or to a Framebuffer object. When rendering is directed to the drawing buffer, making any of the rendering calls shall cause the drawing buffer to be presented to the HTML page compositor at the start of the next compositing operation.
These include, but (due to additions in extensions or in WebGL 2.0) are not limited to:
cleardrawArraysdrawElementsdrawArraysInstancedANGLE, and
WebGL 2.0
adds drawArraysInstanced.
If any one of these calls attempts to draw to a missing attachment of a complete framebuffer, nothing is drawn to that attachment and no error is generated per Drawing to a Missing Attachment.
INVALID_VALUE error will be generated.
If the CURRENT_PROGRAM is null, an INVALID_OPERATION error will be generated.
INVALID_OPERATION
error will be generated; in addition the offset must be non-negative or an
INVALID_VALUE error will be generated; see
Buffer Offset and Stride Requirements. If count is greater than zero,
then a non-null WebGLBuffer must be bound to the ELEMENT_ARRAY_BUFFER
binding point or an INVALID_OPERATION error will be generated.INVALID_OPERATION error will be generated.
drawArrays
and drawElements. See Enabled Vertex
Attributes and Range Checking.
OpenGL ES 2.0 has several calls which are allowed to read from the currently bound (read) framebuffer. WebGL categorizes all such calls as [Read Operations].
These include, but (due to additions in extensions or in WebGL 2.0) are not limited to:
copyTexImage2DcopyTexSubImage2DreadPixelspixels with the pixel data in the specified rectangle of the frame
buffer. The data returned from readPixels must be up-to-date as of the most recently
sent drawing command.
pixels must match the type of the data to be read. For example,
if it is UNSIGNED_BYTE, a Uint8Array or Uint8ClampedArray must be supplied; if it is
UNSIGNED_SHORT_5_6_5, UNSIGNED_SHORT_4_4_4_4, or UNSIGNED_SHORT_5_5_5_1, a Uint16Array
must be supplied; if it is FLOAT, a Float32Array must be supplied. If the types do not
match, an INVALID_OPERATION error is generated.
format and type are accepted. The
first is format RGBA and type UNSIGNED_BYTE. The second is an
implementation-chosen format. The values of format and type
for this format may be determined by calling
getParameter with the symbolic constants
IMPLEMENTATION_COLOR_READ_FORMAT and IMPLEMENTATION_COLOR_READ_TYPE, respectively. The
implementation-chosen format may vary depending on the format of the currently bound
rendering surface. Unsupported combinations of format and type
will generate an INVALID_OPERATION error.
readPixels will not necessarily
generate INVALID_ENUM.
pixels is null, an INVALID_VALUE error is generated. If
pixels is non-null, but is not large enough to retrieve all of the pixels
in the specified rectangle taking into account pixel store modes, an INVALID_OPERATION
error is generated.
INVALID_OPERATION error is generated
per Reading from a Missing Attachment.
Occurrences such as power events on mobile devices may cause the WebGL rendering context to be lost at any time and require the application to rebuild it; see WebGLContextEvent for more details. The following method assists in detecting context lost events.
An implementation of WebGL must not support any additional parameters, constants or functions
without first enabling that functionality through the extension mechanism. The
getSupportedExtensions function returns an array of the extension strings
supported by this implementation. An extension is enabled by passing one of those strings to
the getExtension function. This call returns an object which contains any
constants or functions defined by that extension. The definition of that object is specific
to the extension and must be defined by the extension specification.
Once an extension is enabled, it is only disabled if the WebGL rendering context is lost (see
below), with the exception of the "WEBGL_lose_context" extension which remains active through
any loss of context. Any objects referenced by a disabled extension, such as the object returned
by getExtension, are no longer associated with the WebGL rendering context. Any
extension objects that derive from WebGLObject have their
invalidated flag set to true. Behavior of
extensions' methods after context loss is defined by the steps in the
section "The WebGL context".
There are no other mechanisms to disable an extension.
Multiple calls to getExtension with the same extension string, taking into account
case-insensitive comparison, must return the same object as long as the extension is enabled. An
attempt to use any features of an extension without first calling getExtension to enable it must
generate an appropriate GL error and must not make use of the feature.
This specification does not define any extensions. A separate WebGL extension registry defines extensions that may be supported by a particular WebGL implementation.
getSupportedExtensions; otherwise, returns null. The
object returned from getExtension contains any constants or functions
provided by the extension. A returned object may have no constants or functions if the
extension does not define any, but a unique object must still be returned. That object
is used to indicate that the extension has been enabled.
WebGL generates a WebGLContextEvent event in response to important changes in status of a
WebGL rendering context. Events are sent using the DOM Event System [DOM3EVENTS],
and are dispatched to the HTMLCanvasElement or OffscreenCanvas associated with the WebGL rendering context.
The types of status changes that can trigger a WebGLContextEvent event are
the loss of the context, the restoration of the context, and
the inability to create a context.
To fire a WebGL context event named e means
that an event using
the WebGLContextEvent interface, with
its type
attribute [DOM4] initialized to e, its
cancelable attribute initialized to true, and
its isTrusted
attribute [DOM4] initialized to true, is to
be dispatched at the
given object.
[Exposed=(Window,Worker)]
interface WebGLContextEvent : Event {
constructor(DOMString type, optional WebGLContextEventInit eventInit = {});
readonly attribute DOMString statusMessage;
};
// EventInit is defined in the DOM4 specification.
dictionary WebGLContextEventInit : EventInit {
DOMString statusMessage = "";
};
The task source for all tasks queued [HTML] in this section is the WebGL task source.
The following attributes are available:
statusMessage of type DOMString
When the user agent detects that the drawing buffer associated with
a WebGLRenderingContext context has been lost, it must run the
following steps:
WebGLObject instance created by this context. statusMessage attribute set
to "".
A WebGLObject created while the context is lost
(e.g. a WebGLBuffer via createBuffer())
begins life with its invalidated flag set.
webglcontextlost
event and enables the webglcontextrestored event to be delivered:
canvas.addEventListener("webglcontextlost", function(e) { e.preventDefault(); }, false);
When the user agent is to restore the drawing
buffer for a WebGLRenderingContext context, it must run the
following steps:
statusMessage attribute set
to "".
function initializeGame() {
initializeWorld();
initializeResources();
}
function initializeResources() {
initializeShaders();
initializeBuffers();
initializeTextures();
// ready to draw, start the main loop
renderFrame();
}
function renderFrame() {
updateWorld();
drawSkyBox();
drawWalls();
drawMonsters();
requestId = window.requestAnimationFrame(
renderFrame, canvas);
}
canvas.addEventListener(
"webglcontextlost", function (event) {
// inform WebGL that we handle context restoration
event.preventDefault();
// Stop rendering
window.cancelAnimationFrame(requestId);
}, false);
canvas.addEventListener(
"webglcontextrestored", function (event) {
initializeResources();
}, false);
initializeGame();
When the user agent is to fire a WebGL context creation error at a canvas, it must perform the following steps:
statusMessage
attribute set to a platform dependent string about the nature of the failure. var errorInfo = "";
function onContextCreationError(event) {
canvas.removeEventListener(
"webglcontextcreationerror",
onContextCreationError, false);
errorInfo = e.statusMessage || "Unknown";
}
canvas.addEventListener(
"webglcontextcreationerror",
onContextCreationError, false);
var gl = canvas.getContext("webgl");
if(!gl) {
alert("A WebGL context could not be created.\nReason: " +
errorInfo);
}
This section describes changes made to the WebGL API relative to the OpenGL ES 2.0 API to improve portability across various operating systems and devices.
In the WebGL API, a given buffer object may only be bound to one of the ARRAY_BUFFER or
ELEMENT_ARRAY_BUFFER binding points in its lifetime. This restriction implies that a
given buffer object may contain either vertices or indices, but not both.
The type of a WebGLBuffer is initialized the first time it is passed as an argument
to bindBuffer. A subsequent call to bindBuffer which attempts to bind the
same WebGLBuffer to the other binding point will generate an INVALID_OPERATION error, and
the state of the binding point will remain untouched.
The WebGL API does not support client-side arrays.
If a vertex attribute is enabled as an array via enableVertexAttribArray but no buffer
is bound to that attribute (generally via bindBuffer and
vertexAttribPointer), then draw commands (drawArrays or
drawElements) will generate an INVALID_OPERATION error.
If an indexed draw command (drawElements) is called and no WebGLBuffer is
bound to the ELEMENT_ARRAY_BUFFER binding point, an INVALID_OPERATION
error is generated.
If vertexAttribPointer is called without a WebGLBuffer bound to the
ARRAY_BUFFER binding point, and offset is non-zero, an
INVALID_OPERATION error is generated.
Allowing setting VERTEX_ATTRIB_ARRAY_BUFFER_BINDING to null even though client-side arrays are never supported allows for clearing the binding to its original state, which isn't strictly possible otherwise.
This also matches the behavior in OpenGL ES 3.0.5 [GLES30] p25 for non-default VAO objects.
The WebGL API does not support default textures. A non-null WebGLTexture object must be
bound in order for texture-related operations and queries to succeed.
Accessing binary representations of compiled shaders is not supported in the WebGL API. This
includes the OpenGL ES 2.0 ShaderBinary entry point. In addition, querying shader
binary formats and the availability of a shader compiler via getParameter is not
supported in the WebGL API.
All WebGL implementations must implicitly support an on-line shader compiler.
The offset arguments to drawElements and vertexAttribPointer,
and the stride argument to vertexAttribPointer, must be a multiple of the
size of the data type passed to the call, or an INVALID_OPERATION error is generated.
This enforces the following requirement from OpenGL ES 2.0.25 [GLES20] p24:
"Clients must align data elements consistent with the requirements of the client
platform, with an additional base-level requirement that an offset within a buffer
to a datum comprising N basic machine units be a multiple of
N."
In addition the offset argument to drawElements must be non-negative or
an INVALID_VALUE error is generated.
It is possible for draw commands to request data outside the bounds of a WebGLBuffer by calling a
drawing command that requires fetching data for an active vertex attribute, when it is enabled as an
array, either directly (drawArrays), or indirectly from an indexed draw
(drawElements).
If this occurs, then one of the following behaviors will result:
If a vertex attribute is enabled as an array, a buffer is bound to that attribute, but the attribute
is not consumed by the current program, then regardless of the size of the bound buffer, it will not
cause any error to be generated during a call to drawArrays
or drawElements.
Calling an indexed drawing command (drawElements) that fetches index elements outside
the bounds of ELEMENT_ARRAY_BUFFER will result in an INVALID_OPERATION error.
WebGL adds the DEPTH_STENCIL_ATTACHMENT framebuffer object attachment point and
the DEPTH_STENCIL renderbuffer internal format. To attach both depth and stencil
buffers to a framebuffer object, call renderbufferStorage with
the DEPTH_STENCIL internal format, and then call framebufferRenderbuffer
with the DEPTH_STENCIL_ATTACHMENT attachment point.
A renderbuffer attached to the DEPTH_ATTACHMENT attachment point must be allocated with
the DEPTH_COMPONENT16 internal format. A renderbuffer attached to
the STENCIL_ATTACHMENT attachment point must be allocated with
the STENCIL_INDEX8 internal format. A renderbuffer attached to
the DEPTH_STENCIL_ATTACHMENT attachment point must be allocated with
the DEPTH_STENCIL internal format.
In the WebGL API, it is an error to concurrently attach renderbuffers to the following combinations of attachment points:
DEPTH_ATTACHMENT + DEPTH_STENCIL_ATTACHMENT
STENCIL_ATTACHMENT + DEPTH_STENCIL_ATTACHMENT
DEPTH_ATTACHMENT + STENCIL_ATTACHMENT
checkFramebufferStatus must return FRAMEBUFFER_UNSUPPORTED.
INVALID_FRAMEBUFFER_OPERATION error and return early, leaving the contents of
the framebuffer, destination texture or destination memory untouched.
COLOR_ATTACHMENT0 = RGBA/UNSIGNED_BYTE texture
COLOR_ATTACHMENT0 = RGBA/UNSIGNED_BYTE texture + DEPTH_ATTACHMENT = DEPTH_COMPONENT16 renderbuffer
COLOR_ATTACHMENT0 = RGBA/UNSIGNED_BYTE texture + DEPTH_STENCIL_ATTACHMENT = DEPTH_STENCIL renderbuffer
Unless width and height parameters are explicitly specified, the width
and height of the texture set by texImage2D and the width and height of the
sub-rectangle updated by texSubImage2D are determined based on the uploaded
TexImageSource source object:
source of type ImageData
ImageData object.
source of type HTMLImageElement
HTMLImageElement object.
source of type HTMLCanvasElement or
OffscreenCanvas
HTMLCanvasElement or OffscreenCanvas
object.
source of type HTMLVideoElement or VideoFrame[WEBCODECS]
The WebGL API supports the following additional parameters to pixelStorei.
UNPACK_FLIP_Y_WEBGL of type boolean
texImage2D or
texSubImage2D, the source data is flipped along the vertical axis, so that conceptually
the last row is the first one transferred. The initial value is false. Any non-zero
value is interpreted as true.
UNPACK_PREMULTIPLY_ALPHA_WEBGL of type boolean
texImage2D
or texSubImage2D, the alpha channel of the source data, if present, is multiplied into
the color channels during the data transfer. The initial value is false. Any non-zero
value is interpreted as true.
UNPACK_COLORSPACE_CONVERSION_WEBGL of type unsigned long
BROWSER_DEFAULT_WEBGL, then the browser's default colorspace conversion
(e.g. converting a display-p3 image to srgb)
is applied during subsequent texture data upload calls
(e.g. texImage2D and texSubImage2D) that take an argument of TexImageSource.
The precise conversions may be specific to both the browser and file type.
If set to NONE, no colorspace conversion is applied, other than conversion to RGBA.
(For example, a rec709 YUV video is still converted to rec709 RGB data, but not then converted to e.g. srgb RGB data)
The initial value is BROWSER_DEFAULT_WEBGL.
If the TexImageSource is an ImageBitmap, then these three parameters will
be ignored. Instead the equivalent
ImageBitmapOptions should be used to
create an ImageBitmap with the desired format.
For [Read Operations], reads from out-of-bounds pixels sub-areas do not touch their corresponding destination sub-areas.
WebGL (behaves as if it) pre-initializes resources to zeros.
Therefore for example copyTexImage2D will have zeros in sub-areas that correspond to
out-of-bounds framebuffer reads.
In the WebGL API, if stencil testing is enabled and the currently bound framebuffer has a stencil buffer,
then it is illegal to draw while any of the following cases are true.
Doing so will generate an INVALID_OPERATION error.
(STENCIL_WRITEMASK & maxStencilValue) != (STENCIL_BACK_WRITEMASK & maxStencilValue)
stencilMaskSeparate for the mask parameter associated with the FRONT and BACK values of face, respectively)
(STENCIL_VALUE_MASK & maxStencilValue) != (STENCIL_BACK_VALUE_MASK & maxStencilValue)
stencilFuncSeparate for the mask parameter associated with the FRONT and BACK values of face, respectively)
clamp(STENCIL_REF, 0, maxStencilValue) != clamp(STENCIL_BACK_REF, 0, maxStencilValue)
stencilFuncSeparate for the ref parameter associated with the FRONT and BACK values of face, respectively)
where maxStencilValue is ((1 << s) - 1),
where s is the number of stencil bits in the draw framebuffer.
(When no stencil bits are present, these checks always pass.)
The WebGL API supports vertex attribute data strides up to 255 bytes. A call to
vertexAttribPointer will generate an INVALID_VALUE error if the value for
the stride parameter exceeds 255.
The WebGL API does not support depth ranges with where the near plane is mapped to a value greater
than that of the far plane. A call to depthRange will generate an
INVALID_OPERATION error if zNear is greater than zFar.
In the WebGL API, constant color and constant alpha cannot be used together as source and
destination factors in the blend function. A call to blendFunc will generate an
INVALID_OPERATION error if one of the two factors is set to CONSTANT_COLOR
or ONE_MINUS_CONSTANT_COLOR and the other to CONSTANT_ALPHA or
ONE_MINUS_CONSTANT_ALPHA. A call to blendFuncSeparate will generate an
INVALID_OPERATION error if srcRGB is set to CONSTANT_COLOR
or ONE_MINUS_CONSTANT_COLOR and dstRGB is set to CONSTANT_ALPHA or
ONE_MINUS_CONSTANT_ALPHA or vice versa.
GL_FIXED data type.
Per Supported GLSL Constructs, identifiers starting with "webgl_" and "_webgl_" are reserved for use by WebGL.
In the OpenGL ES 2.0 API, the available extensions are determined by calling
glGetString(GL_EXTENSIONS), which returns a space-separated list of extension strings.
In the WebGL API, the EXTENSIONS enumerant has been removed.
Instead, getSupportedExtensions must be called to determine the set of available
extensions.
The core WebGL specification does not define any supported compressed texture formats. Therefore, in the absence of any other extensions being enabled:
compressedTexImage2D
and compressedTexSubImage2D methods
generate an INVALID_ENUM error. getParameter with the
argument COMPRESSED_TEXTURE_FORMATS returns a zero-length array (of
type Uint32Array). WebGL implementations should only expose compressed texture formats that are more efficient than the uncompressed form.
The GLSL ES spec [GLES20GLSL] does not define a limit to the length of tokens. WebGL requires support of tokens up to 256 characters in length. Shaders containing tokens longer than 256 characters must fail to compile.
WebGL supports passing any HTML DOMString [DOMSTRING] to shaderSource without error.
However during shader compilation, after GLSL preprocessing and comment stripping, all remaining characters MUST be within the character set of [GLES20GLSL].
Otherwise, the shader MUST fail to compile.
In particular, this allows for:
// 你好
#ifdef __cplusplus #line 42 "foo.glsl" #endif(The double-quote character is outside the GLSL character set, but since it is removed by preprocessing, this is allowed in shader sources)
The GLSL ES spec [GLES20GLSL] defines the source character set for the OpenGL ES shading language as a subset of ISO/IEC 646:1991, commonly called ASCII [ASCII]. Some GLSL implementations disallow any characters outside the ASCII range, even in comments. While browsers MUST correctly handle preprocessing the full DOMString character set, WebGL implementations generally must ensure that the shader source sent to a GLSL driver only contains ASCII for safety. Implementations SHOULD preserve line numbers for debugging purposes, potentially by inserting blank lines as needed.
If a string containing a character not in this set is passed to any of the other shader-related entry points
bindAttribLocation,
getAttribLocation,
or getUniformLocation,
an INVALID_VALUE error will be generated.
WebGL imposes a limit on the nesting of structures in GLSL shaders. Nesting occurs when a field in a struct refers to another struct type; the GLSL ES spec [GLES20GLSL] forbids embedded structure definitions. The fields in a top-level struct definition have a nesting level of 1.
WebGL requires support of a structure nesting level of 4. Shaders containing structures nested more than 4 levels deep must fail to compile.
WebGL imposes a limit of 256 characters on the lengths of uniform and attribute locations.
In the WebGL API, the enumerants INFO_LOG_LENGTH, SHADER_SOURCE_LENGTH,
ACTIVE_UNIFORM_MAX_LENGTH, and ACTIVE_ATTRIBUTE_MAX_LENGTH have been removed. In
the OpenGL ES 2.0 API, these enumerants are needed to determine the size of buffers passed to calls
like glGetActiveAttrib. In the WebGL API, the analogous calls (getActiveAttrib,
getActiveUniform, getProgramInfoLog, getShaderInfoLog, and
getShaderSource) all return DOMString.
In the WebGL API, the type argument passed to texSubImage2D must match the
type used to originally define the texture object (i.e., using texImage2D).
The OpenGL ES Shading Language, Version 1.00 [GLES20GLSL], Appendix A, Section 7 "Counting of Varyings and Uniforms" defines a conservative algorithm for computing the storage required for all of the uniform and varying variables in a shader. The GLSL ES specification requires that if the packing algorithm defined in Appendix A succeeds, then the shader must succeed compilation on the target platform. The WebGL API further requires that if the packing algorithm fails either for the uniform variables of a shader or for the varying variables of a program, compilation or linking must fail.
Instead of using a fixed size grid of registers, the number of rows in the target architecture is determined in the following ways:
getParameter(MAX_VERTEX_UNIFORM_VECTORS)
getParameter(MAX_FRAGMENT_UNIFORM_VECTORS)
getParameter(MAX_VARYING_VECTORS)
The text above defines the circumstances under which compilation or linking of a shader or program must fail due to the constraints enforced by the packing algorithm. It is not guaranteed that a shader which uses more variables than the minimum required amount whose variables pack successfully according to this algorithm will compile successfully. Inefficiencies have been observed in implementations, including expansion of scalar arrays to consume multiple columns. Developers should avoid relying heavily upon automatic packing of multiple variables into columns. Instead, define larger variables (like vec4) and explicitly pack values into the rightmost columns.
In the OpenGL ES 2.0 API, it's possible to make calls that both write to and read from the same texture, creating a feedback loop. It specifies that where these feedback loops exist, undefined behavior results.
In the WebGL API, such operations that would cause such feedback loops (by the definitions
in the OpenGL ES 2.0 spec) will instead generate an INVALID_OPERATION error.
In the OpenGL ES 2.0 API, it is not specified what happens when a command tries to source data from a missing attachment, such as ReadPixels of color data from a complete framebuffer that does not have a color attachment.
In the WebGL API, any [Read Operations] that require data from an attachment that is missing will
generate an INVALID_OPERATION error.
In the OpenGL ES 2.0 API, it is not specified what happens when a command tries to draw to a missing attachment, such as clearing a draw buffer from a complete framebuffer that does not have a color attachment.
In the WebGL API, any [Draw Operations] that draw to an attachment that is missing will draw nothing to that attachment. No error is generated.
In the WebGL API, if the width parameter passed to lineWidth is set
to NaN, an INVALID_VALUE error is generated and the line width is not changed.
It is possible for an application to bind more than one attribute name to the
same location. This is referred to as aliasing. When more than one attributes that
are aliased to the same location are active in the executable program,
linkProgram should fail.
The GLSL ES [GLES20GLSL] spec leaves the value of
gl_Position as undefined unless it is written to in a vertex shader. WebGL guarantees
that gl_Position's initial value is (0,0,0,0).
The GLSL ES 1.00 [GLES20GLSL] spec restricts global variable
initializers to be constant expressions. In the WebGL API, it is allowed to use other global
variables not qualified with the const qualifier and uniform values in global
variable initializers in GLSL ES 1.00 shaders. Global variable initializers must be global
initializer expressions, which are defined as one of:
The following may not be used in global initializer expressions:
Compilers should generate a warning when a global variable initializer is in violation of the unmodified GLSL ES spec i.e. when a global variable initializer is not a constant expression.
The C++ standard, which the GLSL ES preprocessor specification refers to, has undefined behavior
when the defined operator is generated by macro replacement when parsing the
controlling expression of an #if or #elif directive. When shader code
processed by the WebGL API generates the token defined during macro replacement
inside a preprocessor expression, that must result in a compiler error.
This has no effect on macro expansion outside preprocessor directives that handle the
defined operator.
Using defined as a macro name also has undefined behavior in the C++ standard. In
the WebGL API, using defined as a macro name must result in a compiler error.
The GLSL ES 1.00 [GLES20GLSL] specification mandates that
#extension directives must occur before any non-preprocessor tokens unless the
extension specification says otherwise. In the WebGL API, #extension directives
may always occur after non-preprocessor tokens in GLSL ES 1.00 shaders. The scope of
#extension directives in GLSL ES 1.00 shaders is always the whole shader, and
#extension directives that occur later override those seen earlier for the whole
shader.
#extension directives should be placed has
resulted in a lot of room for interpretation in the spec. In practice GLES implementations have
not enforced the rule that's written in the GLSL ES spec, and neither have WebGL
implementations, so relaxing the rule is the only way to make the spec well-defined while being
compatible with existing content.
In the WebGL API, a face of a cube map that is not cube complete is not framebuffer attachment
complete. Querying framebuffer status when a face of an incomplete cube map is attached must
return FRAMEBUFFER_INCOMPLETE_ATTACHMENT.
Any command that transfers vertices to the GL generates INVALID_OPERATION if the
CURRENT_PROGRAM is null. This includes drawElements and
drawArrays.
If a fragment shader writes to neither gl_FragColor nor gl_FragData,
the values of the fragment colors following shader execution are untouched.
The GLSL ES [GLES20GLSL] spec leaves the value of
local and global variables as undefined unless they are initialized by the
shader. WebGL guarantees that such variables are initialized to zero:
0.0, vec4(0.0), 0, false, etc.
The OpenGL ES 2.0 spec [GLES20] section 2.1.2 "Data Conversions", subsection "Conversion from Integer to Floating-Point" defines conversion from a normalized signed integer c, where the bit width of the type is b, to floating-point value f as:
If any of the shaders attached to a WebGL program declare a uniform that has the same name as a statically used vertex attribute, program linking should fail.
POINTS primitives may or may not be discarded if the vertex lies outside the clip
volume, but within the near and far clip planes.
Clipping of wide points works differently in GLES and GL, and this difference in behavior is prohibitive to work around in implementations.
OpenGL ES 2.0.25 p46:
If the primitive under consideration is a point, then clipping discards it if it lies outside the near or far clip plane; otherwise it is passed unchanged.
OpenGL 3.2 Core p97:
If the primitive under consideration is a point, then clipping passes it unchanged if it lies within the clip volume; otherwise, it is discarded.
In the WebGL API, if the program passed to linkProgram is also the current program
object in use as defined by useProgram, and the link is unsuccessful, then the
executable code referenced by the current rendering state is immediately invalidated. Further
draw calls that utilize the current program generate an INVALID_OPERATION error.
Rejecting draw calls eagerly against programs whose relink has failed makes WebGL implementations more robust. The OpenGL ES API's behavior is that the current executable is preserved until the current program is changed. Correctly implementing this behavior in all scenarios is challenging, and has led to security bugs.
This specification is produced by the Khronos WebGL Working Group.
Special thanks to: Arun Ranganathan (Mozilla), Chris Marrin (Apple), Jon Leech, Kenneth Russell (Google), Kenneth Waters (Google), Mark Callow (HI), Mark Steele (Mozilla), Oliver Hunt (Apple), Tim Johansson (Opera), Vangelis Kokkevis (Google), Vladimir Vukicevic (Mozilla), Gregg Tavares (Google)
Additional thanks to: Alan Hudson (Yumetech), Benoit Jacob (Mozilla), Bill Licea Kane (AMD), Boris Zbarsky (Mozilla), Cameron McCormack (Mozilla), Cedric Vivier (Zegami), Dan Gessel (Apple), David Ligon (Qualcomm), David Sheets (Ashima Arts), Glenn Maynard, Greg Roth (Nvidia), Jacob Strom (Ericsson), Jeff Gilbert (Mozilla), Kari Pulli (Nokia), Teddie Stenvi (ST-Ericsson), Neil Trevett (Nvidia), Per Wennersten (Ericsson), Per-Erik Brodin (Ericsson), Shiki Okasaka (Google), Tom Olson (ARM), Zhengrong Yao (Ericsson), and the members of the Khronos WebGL Working Group.