Source: https://www.khronos.org/registry/webgl/specs/1.0.1/
Timestamp: 2019-04-26 08:45:53+00:00

Document:
Public discussion of this specification is welcome on the (archived) WebGL mailing list public_webgl@khronos.org (see instructions).
Before using the WebGL API, the author must obtain a WebGLRenderingContext object for a given HTMLCanvasElement [CANVAS] 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].
Let context's canvas be the canvas the getContext() method is associated with.
Set the attributes of contextAttributes based on the properties of the newly created 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. 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.
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 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.
The depth, stencil and antialias attributes are requests, not requirements. The WebGL implementation does not guarantee that they will be obeyed, but should make a best effort to honor them. Combinations of attributes not supported by the WebGL implementation or graphics hardware shall not cause a failure to create a WebGLRenderingContext. The attributes actually used to create the context may be queried by the getContextAttributes() method on the WebGLRenderingContext. 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 the drawing buffer has been modified since the last 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, or using this context as the source image of another context's texImage2D or drawImage call.
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 the WebGL context, the viewport is initialized to a rectangle with origin at (0, 0) and width and height equal to (canvas.width, canvas.height).
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 resources represented by these objects are guaranteed to exist as long as the object exists. Furthermore, the DOM object is guaranteed to exist as long as the author has an explicit valid reference to it or as long as it is bound by the underlying graphics library. When none of these conditions exist the user agent can, at any point, delete the object using the equivalent of a delete call (e.g., deleteTexture). If authors wish to control when the underlying resource is released then the delete call can be made explicitly.
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 renderbuffers 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.
If the texImage2D or texSubImage2D method is called with otherwise correct arguments and an HTMLImageElement, HTMLVideoElement, or HTMLCanvasElement violating these restrictions, a SECURITY_ERR exception must be raised.
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 must explicitly request permission to do so, and the server must 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].
Shaders must not be allowed to read or write array elements that lie outside the bounds of the array. 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 they may return a constant value (such as 0), or the value at any valid index of the same array.
The WebGLContextAttributes interface contains drawing surface attributes and is passed as the second parameter to getContext. A user object may be supplied as this parameter; the specified attributes will be queried from this object.
The following list describes each attribute in the WebGLContextAttributes object and its use. For each attribute the default value is shown. 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.
Default: true. If the value is true, the drawing buffer has an alpha channel for the purposes of performing OpenGL destination alpha operations and compositing with the page. If the value is false, no alpha buffer is available.
Default: true. If the value is true, the drawing buffer has a depth buffer of at least 16 bits. If the value is false, no depth buffer is available.
Default: false. If the value is true, the drawing buffer has a stencil buffer of at least 8 bits. If the value is false, no stencil buffer is available.
Default: true. If the value is true and the implementation supports antialiasing the drawing buffer will perform antialiasing using its choice of technique (multisample/supersample) and quality. If the value is false or the implementation does not support antialiasing, no antialiasing is performed.
Default: true. 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. See Premultiplied Alpha for more information on the effects of the premultipliedAlpha flag.
Default: false. If false, once the drawing buffer is presented as described in theDrawing Buffer section, the contents of the drawing buffer are cleared to their default values. All elements of the drawing buffer (color, depth and stencil) are cleared. If the value is true the buffers will not be cleared and will preserve their values until cleared or overwritten by the author.
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 destroyed as if by calling glDeleteBuffers (OpenGL ES 2.0 §2.9, man page) .
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 destroyed as if by calling glDeleteFramebuffers (OpenGL ES 2.0 §4.4.1, man page) .
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 destroyed as if by calling glDeleteProgram (OpenGL ES 2.0 §2.10.3, man page) .
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 destroyed as if by calling glDeleteRenderbuffers (OpenGL ES 2.0 §4.4.3, man page) .
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 destroyed as if by calling glDeleteShader (OpenGL ES 2.0 §2.10.1, man page) .
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 destroyed as if by calling glDeleteTextures (OpenGL ES 2.0 §3.7.13, man page) .
Vertex, index, texture, and other data is transferred to the WebGL implementation using the ArrayBuffer and views defined in the Typed Array specification [TYPEDARRAYS].
If the called method is in the list of methods with explicit context lost handling, perform the implementation of the called method, return its result and terminate these steps.
If any argument to the method is a WebGLObject with its invalidated flag set, generate an INVALID_OPERATION error and let use default return value be true.
A reference to the canvas element which created this context.
Returns a new WebGLContextAttributes object describing the context creation parameters.
VERSION Returns a version or release number of the form WebGL<space>1.0<space><vendor-specific information>.
SHADING_LANGUAGE_VERSION Returns a version or release number of the form WebGL<space>GLSL<space>ES<space>1.0<space><vendor-specific information>.
The viewport specifies the affine transformation of x and y from normalized device coordinates to window coordinates. The size of the drawing buffer is determined by the HTMLCanvasElement. 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. When enabled drawing can only occur inside the intersection of the viewport, canvas area and the scissor box. When the scissor test is not enabled drawing can only occur inside the intersection of the viewport and canvas area.
Binds the given WebGLBuffer object to the given binding point (target), either ARRAY_BUFFER or ELEMENT_ARRAY_BUFFER. If the buffer is null then any buffer currently bound to this target is unbound. A given WebGLBuffer object may only be bound to one of the ARRAY_BUFFER or ELEMENT_ARRAY_BUFFER target in its lifetime. An attempt to bind a buffer object to the other target will generate an INVALID_OPERATION error, and the current binding will remain untouched.
For the WebGLBuffer object bound to the passed target write the passed data starting at the passed offset. If the data would be written past the end of the buffer object an INVALID_VALUE error is generated.
Delete the buffer object contained in the passed WebGLBuffer as if by calling glDeleteBuffers. If the buffer has already been deleted the call has no effect. Note that the buffer object will be deleted when the WebGLBuffer object is destroyed. This method merely gives the author greater control over when the buffer object is destroyed.
Bind the given 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.
Delete the framebuffer object contained in the passed WebGLFramebuffer as if by calling glDeleteFramebuffers. If the framebuffer has already been deleted the call has no effect. Note that the framebuffer object will be deleted when the WebGLFramebuffer object is destroyed. This method merely gives the author greater control over when the framebuffer object is destroyed.
Bind the given 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.
Delete the renderbuffer object contained in the passed WebGLRenderbuffer as if by calling glDeleteRenderbuffers. If the renderbuffer has already been deleted the call has no effect. Note that the renderbuffer object will be deleted when the WebGLRenderbuffer object is destroyed. This method merely gives the author greater control over when the renderbuffer object is destroyed.
Delete the texture object contained in the passed WebGLTexture as if by calling glDeleteTextures. If the texture has already been deleted the call has no effect. Note that the texture object will be deleted when the WebGLTexture object is destroyed. This method merely gives the author greater control over when the texture object is destroyed.
The source image data is conceptually first converted to the data type and format specified by the format and type arguments, and then transferred to the OpenGL implementation. If a packed pixel format is specified which would imply loss of bits of precision from the image data, this loss of precision must occur.
If the source image is an RGB or RGBA lossless image with 8 bits per channel, the browser guarantees that the full precision of all channels is preserved.
If the original image 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.
If this function is called with an HTMLImageElement or HTMLVideoElement whose origin differs from the origin of the containing Document, or with an HTMLCanvasElement whose origin-clean flag is set to false, a SECURITY_ERR exception must be raised. See Origin Restrictions.
See texImage2D for the interpretation of the format and type arguments.
Delete the program object contained in the passed WebGLProgram as if by calling glDeleteProgram. If the program has already been deleted the call has no effect. Note that the program object will be deleted when the WebGLProgram object is destroyed. This method merely gives the author greater control over when the program object is destroyed.
Delete the shader object contained in the passed WebGLShader as if by calling glDeleteShader. If the shader has already been deleted the call has no effect. Note that the shader object will be deleted when the WebGLShader object is destroyed. This method merely gives the author greater control over when the shader object is destroyed.
Return the list of shaders attached to the passed program.
See Supported GLSL Constructs, Maximum GLSL Token Size, Characters Outside the GLSL Source Character Set, and Maximum Nesting of Structures in GLSL Shaders for additional constraints enforced in, additional constructs supported by, and validation performed by WebGL implementations.
Assign the WebGLBuffer object currently bound to the ARRAY_BUFFER target to the vertex attribute at the passed index. Size is number of components per attribute. Stride and offset are in units of bytes. Passed stride and offset must be appropriate for the passed type and size or an INVALID_OPERATION error will be generated; see Buffer Offset and Stride Requirements. If no WebGLBuffer is bound to the ARRAY_BUFFER target, an INVALID_OPERATION error will be generated. In WebGL, the maximum supported stride is 255; see Vertex Attribute Data Stride.
If first is negative, an INVALID_VALUE error will be generated.
Draw using the currently bound element array buffer. The given offset is in bytes, and must be a valid multiple of the size of the given type or an INVALID_OPERATION 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.
WebGL performs additional error checking beyond that specified in OpenGL ES 2.0 during calls to drawArrays and drawElements. See Enabled Vertex Attributes and Range Checking.
The type of pixels must match the type of the data to be read. For example, if it is UNSIGNED_BYTE, a Uint8Array 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.
If 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 value is generated.
For any pixel lying outside the frame buffer, the value read contains 0 in all channels; see Reading Pixels Outside the Framebuffer.
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. Extension strings are case-insensitive. 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, no mechanism is provided to disable it. Multiple calls to getExtension with the same extension string shall return the same object. 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.
Returns an array of all the supported extension strings. Any string in this list, when passed to getExtension must return a valid object. Any other string passed to getExtension must return null.
Returns an object if the passed extension is supported, or null if not. The object returned from getExtension contains any constants or functions used by the extension, if any. 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 a status change to the WebGL rendering context associated with the HTMLCanvasElement which has a listener for this event. Events are sent using the DOM Event System [DOM3EVENTS]. Event types can include the loss or restoration of state, or the inability to create a context. EventInit is defined in the DOM4 specification [DOM4].
To fire a WebGL context event named e means that an event using the WebGLContextEvent interface, with its type attribute [DOM4] initialized to e, and its isTrusted attribute [DOM4] initialized to true, is to be dispatched at the given object.
Once the context is restored, WebGL resources such as textures and buffers that were created before the context was lost are no longer valid. The application must reinitialize the context's state and recreate all such resources.
The WebGL API does not support client-side arrays. If vertexAttribPointer is called without a WebGLBuffer bound to the ARRAY_BUFFER binding point, an INVALID_OPERATION error is generated. If drawElements is called with a count greater than zero, and no WebGLBuffer is bound to the ELEMENT_ARRAY_BUFFER binding point, an INVALID_OPERATION error is generated.
If a vertex attribute is enabled as an array via enableVertexAttribArray but no buffer is bound to that attribute via bindBuffer and vertexAttribPointer, then calls to drawArrays or drawElements will generate an INVALID_OPERATION error.
If a vertex attribute is enabled as an array, a buffer is bound to that attribute, and the attribute is consumed by the current program, then calls to drawArrays and drawElements will verify that each referenced vertex lies within the storage of the bound buffer. If the range specified in drawArrays or any referenced index in drawElements lies outside the storage of the bound buffer, an INVALID_OPERATION error is generated and no geometry is drawn.
In the WebGL API, functions which read the framebuffer (copyTexImage2D, copyTexSubImage2D, and readPixels) are defined to generate the RGBA value (0, 0, 0, 0) for any pixel which is outside of the bound framebuffer.
In the OpenGL ES 2.0 API, the IMPLEMENTATION_COLOR_READ_FORMAT and IMPLEMENTATION_COLOR_READ_TYPE parameters are used to inform applications of an additional format and type combination that may be passed to ReadPixels, in addition to the required RGBA/UNSIGNED_BYTE pair. In WebGL 1.0, the supported format and type combinations to ReadPixels are documented in the Reading back pixels section. The IMPLEMENTATION_COLOR_READ_FORMAT and IMPLEMENTATION_COLOR_READ_TYPE enumerants have been removed.
In the WebGL API, the enumerants INFO_LOG_LENGTH, SHADER_SOURCE_LENGTH, ACTIVE_UNIFORM_MAX_LENGTH, and ACTIVE_ATTRIB_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.
Typed Array Specification: Editor's Draft , V. Vukicevic, K. Russell, May 2010.
Web IDL: W3C Editor’s Draft , C. McCormack, September 2009.
Additional thanks to: Alan Hudson (Yumetech), Bill Licea Kane (AMD), Cedric Vivier (Zegami), Dan Gessel (Apple), David Ligon (Qualcomm), David Sheets (Ashima Arts), Glenn Maynard, Greg Roth (Nvidia), Jacob Strom (Ericsson), Kari Pulli (Nokia), Leddie Stenvie (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.

References: §2
 §2
 §2
 §4
 §4
 §4
 §2
 §2
 §2
 §4
 §4
 §4
 §2
 §2
 §2
 §3
 §3
 §3
 V.