<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8">
<title>WebGL 2 Specification</title>
- <meta name="generator" content="BBEdit 9.1">
<link rel="stylesheet" type="text/css" href="../../../resources/Khronos-WD.css" />
<script src="../../../resources/jquery-1.3.2.min.js" type="text/javascript"></script>
<script src="../../../resources/generateTOC.js" type="text/javascript"></script>
<!--end-logo-->
<h1>WebGL 2 Specification</h1>
- <h2 class="no-toc">Editor's Draft 10 September 2014</h2>
+ <h2 class="no-toc">Editor's Draft 17 October 2014</h2>
<dl>
<dt>This version:
<dd>
</p>
<p>
- WebGL 2 is not entirely backwards compatible with WebGL 1. Existing content written against
- the core WebGL 1 specification without extensions will often run in WebGL 2 without
+ WebGL 2 is not entirely backwards compatible with WebGL 1. Existing error-free content written
+ against the core WebGL 1 specification without extensions will often run in WebGL 2 without
modification, but this is not always the case. All exceptions to backwards compatibility are
recorded in the <a href="#BACKWARDS_INCOMPATIBILITY">Backwards Incompatibility</a> section.
To access the new behavior provided in this specification, the content explicitly requests
// MapBufferRange, in particular its read-only and write-only modes,
// can not be exposed safely to JavaScript. GetBufferSubData
// replaces it for the purpose of fetching data back from the GPU.
- typedef (ArrayBuffer or ArrayBufferView) GetBufferDataDest;
- void getBufferSubData(GLenum target, GLintptr offset, GetBufferDataDest returnedData);
+ void getBufferSubData(GLenum target, GLintptr offset, ArrayBufferData returnedData);
/* Framebuffer objects */
void blitFramebuffer(GLint srcX0, GLint srcY0, GLint srcX1, GLint srcY1, GLint dstX0, GLint dstY0,
void texStorage2D(GLenum target, GLsizei levels, GLenum internalformat, GLsizei width, GLsizei height);
void texStorage3D(GLenum target, GLsizei levels, GLenum internalformat, GLsizei width, GLsizei height,
GLsizei depth);
+ void texImage3D(GLenum target, GLint level, GLint internalformat,
+ GLsizei width, GLsizei height, GLsizei depth, GLint border, GLenum format,
+ GLenum type, ArrayBufferView? pixels);
void texSubImage3D(GLenum target, GLint level, GLint xoffset, GLint yoffset, GLint zoffset,
GLsizei width, GLsizei height, GLsizei depth, GLenum format, GLenum type,
ArrayBufferView? pixels);
See <a href="COPYING_BUFFERS">Copying Buffers</a> for restrictions imposed by the WebGL 2 API.
</dd>
<dt>
- <p class="idl-code">void getBufferSubData(GLenum target, GLintptr offset, GetBufferDataDest returnedData)
+ <p class="idl-code">void getBufferSubData(GLenum target, GLintptr offset, ArrayBufferData returnedData)
</p>
</dt>
<dd>
The image contents are set as if a buffer of sufficient size initialized to 0 would be passed to
each texImage2D call in the pseudocode in The OpenGL ES 3.0 specification section 3.8.4
<span class="gl-spec">(<a href="http://www.khronos.org/registry/gles/specs/3.0/es_spec_3.0.3.pdf#nameddest=section-3.8.4">OpenGL ES 3.0.3 §3.8.4</a>)</span>.
+
+ <div class="note"><code>texStorage2D</code> should be considered a preferred alternative to
+ <code>texImage2D</code>. It may have lower memory costs than <code>texImage2D</code> in some
+ implementations.</div>
</dd>
<dt>
- <p class="idl-code">void texStorage3D(GLenum target, GLsizei levels, GLenum internalformat, GLsizei width, GLsizei height, GLsizei depth)
+ <p class="idl-code"><a name="TEXSTORAGE3D">void texStorage3D</a>(GLenum target, GLsizei levels, GLenum internalformat, GLsizei width, GLsizei height, GLsizei depth)
<span class="gl-spec">
(<a href="http://www.khronos.org/registry/gles/specs/3.0/es_spec_3.0.3.pdf#nameddest=section-3.8.4">OpenGL ES 3.0.3 §3.8.4</a>,
<a href="http://www.khronos.org/opengles/sdk/docs/man3/html/glTexStorage3D.xhtml" class="nonnormative">man page</a>)
each texImage3D call in the pseudocode in The OpenGL ES 3.0 specification section 3.8.4
<span class="gl-spec">(<a href="http://www.khronos.org/registry/gles/specs/3.0/es_spec_3.0.3.pdf#nameddest=section-3.8.4">OpenGL ES 3.0.3 §3.8.4</a>)</span>.
</dd>
+ <dt class="idl-code">void texImage3D(GLenum target, GLint level, GLenum internalformat,
+ GLsizei width, GLsizei height, GLsizei depth, GLint border, GLenum format,
+ GLenum type, ArrayBufferView? pixels)
+ <span class="gl-spec">(<a href="http://www.khronos.org/registry/gles/specs/3.0/es_full_spec_3.0.3.pdf#nameddest=section-3.8.3">OpenGL ES 3.0.3 §3.8.4</a>, <a class="nonnormative" href="https://www.khronos.org/opengles/sdk/docs/man3/html/glTexImage3D.xhtml">man page</a>)</span>
+ </dt>
+ <dd>
+ Allocates and initializes the specified mipmap level of a three-dimensional or
+ two-dimensional array texture. <br><br>
+
+ If <code>pixels</code> is null, a buffer of sufficient size initialized to 0 is
+ passed. <br><br>
+
+ <div class="note editor">Needs update to determine restrictions for <em>format</em> and
+ <em>pixels</em>. These restrictions also need to be updated for texImage2D and texSubImage2D
+ inherited from the WebGL 1.0 API.</div>
+
+ If an attempt is made to call this function with no WebGLTexture bound (see above), an
+ <code>INVALID_OPERATION</code> error is generated. <br><br>
+
+ <div class="note editor">Needs update to determine restrictions for <em>type</em></div>
+
+ See <a href="#PIXEL_STORAGE_PARAMETERS">Pixel Storage Parameters</a> for WebGL-specific
+ pixel storage parameters that affect the behavior of this function. <br><br>
+
+ <div class="note">It is recommended to use <a href="#TEXSTORAGE3D">texStorage3D</a>
+ instead of texImage3D to allocate three-dimensional textures. texImage3D may impose a
+ higher memory cost compared to texStorage3D in some implementations.</div>
+ </dd>
<dt>
<p class="idl-code">void texSubImage3D(GLenum target, GLint level, GLint xoffset, GLint yoffset, GLint zoffset, GLsizei width, GLsizei height, GLsizei depth, GLenum format, GLenum type, ArrayBufferView? pixels)
<span class="gl-spec">
<p class="idl-code">WebGLSync? fenceSync(GLenum condition, GLbitfield flags)
<span class="gl-spec">
(<a href="http://www.khronos.org/registry/gles/specs/3.0/es_spec_3.0.3.pdf#nameddest=section-5.2">OpenGL ES 3.0.3 §5.2</a>,
- <a href="http://www.khronos.org/opengles/sdk/docs/man3/html/glBindSampler.xhtml" class="nonnormative">man page</a>)
+ <a href="http://www.khronos.org/opengles/sdk/docs/man3/html/glFenceSync.xhtml" class="nonnormative">man page</a>)
</span>
</p>
</dt>
</p>
</dt>
<dd>
- Block execution until the passed sync object is signaled or the specified timeout has passed. Returns
- <code>ALREADY_SIGNALED</code>, <code>TIMEOUT_EXPIRED</code>, or <code>CONDITION_SATISFIED</code>.
+ <p>
+ Block execution until the passed sync object is signaled or the specified timeout has
+ passed. <code>timeout</code> is in units of nanoseconds.
+ </p>
+
+ <p>
+ Returns one of four status values. A return value of <code>ALREADY_SIGNALED</code> indicates
+ that <code>sync</code> was signaled at the time <code>clientWaitSync</code> was
+ called. <code>ALREADY_SIGNALED</code> will always be returned if <code>sync</code> was signaled, even
+ if <code>timeout</code> was zero. A return value of <code>TIMEOUT_EXPIRED</code> indicates that the specified
+ timeout period expired before <code>sync</code> was signaled. A return value of <code>CONDITION_SATISFIED</code>
+ indicates that <code>sync</code> was signaled before the timeout expired. Finally, if an error occurs, in
+ addition to generating an error as specified below, returns <code>WAIT_FAILED</code> without blocking.
+ </p>
+
+ <p>
+ <code>flags</code> controls command flushing behavior and may include <code>SYNC_FLUSH_COMMANDS_BIT</code>. If
+ any other bit is set in <code>flags</code> an <code>INVALID_OPERATION</code> error is
+ generated. If <code>SYNC_FLUSH_COMMANDS_BIT</code> is set in <code>flags</code> and <code>sync</code> is
+ unsignaled when <code>clientWaitSync</code> is called, then the equivalent of <code>flush</code> will be
+ performed before blocking on <code>sync</code>.
+ </p>
+
+ <p>
+ As discussed in the <a href="#CLIENT_WAIT_SYNC">differences section</a>, WebGL implementations must impose a
+ short maximum timeout to prevent blocking the main thread either indefinitely or for long periods of time.
+ </p>
+
+ <div class="note">
+ The implementation-defined maximum timeout is not specified. It should be set low enough to keep applications
+ from compromising interactivity by waiting for long periods of time. It is acceptable for an implementation to
+ impose a zero maximum timeout. WebGL applications should not use clientWaitSync to block execution for long
+ periods of time.
+ </div>
+
+ <p>Returns <code>WAIT_FAILED</code> if any OpenGL errors are generated during the execution of this
+ function.</p>
+
</dd>
<dt>
<p class="idl-code">void waitSync(WebGLSync? sync, GLbitfield flags, GLuint64 timeout)
Return immediately, but wait on the GL server until the passed sync object is signaled or an
implementation-dependent timeout has passed. The passed <em>timeout</em> must be set to
<code>TIMEOUT_IGNORED</code>.
+
+ <div class="note">
+ In the absence of the possibility of synchronizing between multiple GL contexts, calling waitSync is effectively a no-op.
+ </div>
</dd>
<dt class="idl-code">any getSyncParameter(WebGLSync? sync, GLenum pname)
<span class="gl-spec">(<a href="http://www.khronos.org/registry/gles/specs/3.0/es_spec_3.0.3.pdf#nameddest=section-6.1.8">OpenGL ES 3.0.3 §6.1.8</a>, <a class="nonnormative" href="http://www.khronos.org/opengles/sdk/docs/man3/html/glGetSynciv.xhtml">man page</a>)</span>
</div>
<h3><a name="BACKWARDS_INCOMPATIBILITY">Backwards Incompatibility</a></h3>
-
+
+ <h4>Errors</h4>
+
+ <p>
+ The WebGL 2 API may behave differently in cases where the WebGL 1 API generates an error.
+ Code written against the WebGL 1 API that generates errors is not guaranteed to be
+ forward-compatible with WebGL 2.
+ </p>
+
+ <h4>Extensions</h4>
+
<p>
Some extensions that may have been supported in the WebGL 1 API are removed from the WebGL
2 API. For more details, see the
language extensions, porting shaders to GLSL ES 3.00 is typically required.
</div>
+ <h4>Non-Power-of-Two Texture Access</h4>
+
+ <p>
+ Texture access works in the WebGL 2 API as in the OpenGL ES 3.0 API. Sampling a
+ non-power-of-two image with wrapping mode other than CLAMP_TO_EDGE and minification filter
+ other than NEAREST or LINEAR does not always return (R, G, B, A) = (0, 0, 0, 1) in the
+ WebGL 2 API, i.e. mipmapping and all wrapping modes are supported for non-power-of-two
+ images.
+ </p>
+
<h3>New Features Supported in the WebGL 2 API</h3>
<ul>
these prefixes must not be allowed to load.
</p>
+ <h4>Maximum GLSL Token Size</h4>
+
+ <p>
+ WebGL 1.0 supports tokens up to 256 characters in length. WebGL 2.0 follows The OpenGL ES Shading Language, Version 3.00
+ <span class="gl-spec">(<a href="http://www.khronos.org/registry/gles/specs/3.0/es_spec_3.0.3.pdf#nameddest=section-3.8">OpenGL ES 3.0.3 §3.8</a>)</span>
+ and allows tokens up to 1024 characters in length. Shaders containing tokens longer than 1024 characters must fail to compile.
+ </p>
+
<h3>Vertex Attribute Divisor</h3>
<p>
shaders in the WebGL 2 API.
</p>
- <h3>No TexImage3D</h3>
+ <h3>No MapBufferRange</h3>
<p>
- The <code>texImage3D</code> entry point is removed from the WebGL 2.0 API. Defining 3D texture images
- is supported with <code>texStorage3D</code> and <code>compressedTexImage3D</code>.
+ The <code>MapBufferRange</code>, <code>FlushMappedBufferRange</code>, and <code>UnmapBuffer</code>
+ entry points are removed from the WebGL 2.0 API. The following enum values are also removed:
+ <code>BUFFER_ACCESS_FLAGS</code>, <code>BUFFER_MAP_LENGTH</code>, and <code>BUFFER_MAP_OFFSET</code>.
</p>
<div class="note">
- <code>texStorage2D</code> should also be considered a preferred alternative to
- <code>texImage2D</code>, even though <code>texImage2D</code> is supported in the WebGL 2.0 API.
+ Instead of using <code>MapBufferRange</code>, buffer data may be read by using the
+ <code>getBufferSubData</code> entry point.
</div>
- <h3>No MapBufferRange</h3>
+ <h3><a name="CLIENT_WAIT_SYNC">clientWaitSync</a></h3>
+ <p>
+ In the WebGL 2.0 API, WebGL implementations must enforce a short maximum timeout on calls to clientWaitSync in
+ order to avoid blocking execution of the main thread for excessive periods of time.
+ </p>
+ <div class="note">
+ The implementation-defined maximum timeout is not specified. It is acceptable for an implementation to enforce a
+ zero maximum timeout.
+ </div>
+ <h3><a name="VERTEX_ATTRIBUTE_ALIASING">Vertex Attribute Aliasing</a></h3>
+ <p>
+ In the WebGL 2.0 API, if more than one active attribute name is bound to the same location, it is considered
+ aliased, regardless whether there exists a path through the shader that consumes more than of these
+ attributes. Such definition of aliasing is broader than what is defined in
+ <span class="gl-spec">(<a href="http://www.khronos.org/registry/gles/specs/3.0/es_spec_3.0.3.pdf#nameddest=section-2.11.5">OpenGL ES 3.0.3 §2.11.5</a>)</span>.
+ </p>
<p>
- The <code>MapBufferRange</code> entry point is removed from the WebGL 2.0 API. The following enum values are removed together with it: <code>BUFFER_ACCESS_FLAGS</code>, <code>BUFFER_MAP_LENGTH</code>, <code>BUFFER_MAP_OFFSET</code>.
+ A link error is required when aliasing exists.
</p>
<!-- ======================================================================================================= -->
projects / platform / framework / web / crosswalk.git / blobdiff