Skip to content

Commit

Permalink
Fill in missing details in WEBGL_multiview spec (#2256)
Browse files Browse the repository at this point in the history 
This adds specs for getFramebufferAttachmentParameter(), and extension
macros in shaders. The added tokens, added functions and errors are
documented with the correct syntax.
  • Loading branch information
@Oletus @kenrussell
Oletus authored and kenrussell committed Jan 14, 2017
1 parent e1bcce7 commit 9e937ec
Showing 1 changed file with 102 additions and 6 deletions.
108 changes: 102 additions & 6 deletions extensions/proposals/WEBGL_multiview/extension.xml
View file
Expand Up @@ -152,9 +152,6 @@

Likewise the shading language preprocessor <code>#define GL_OVR_multiview</code>, will be defined to 1 if the extension is supported.
</addendum>
<addendum>
The maximum number of views can be queried by calling <code>getParameter</code> with the <code>pname</code> parameter set to <code>MAX_VIEWS_OVR</code>. The implementation must support at least 2 views.
</addendum>
<addendum>
Two levels of acceleration are exposed through alternative extension directives: <code>GL_OVR_multiview</code> and <code>GL_OVR_multiview2</code>. Using <code>GL_OVR_multiview</code> instead of <code>GL_OVR_multiview2</code> restricts what can be done in shaders but may enable the WebGL implementation to accelerate multiview rendering using fixed-function hardware specifically designed for this purpose.
</addendum>
Expand Down Expand Up @@ -185,9 +182,6 @@
<addendum>
Attempting to enable both <code>GL_OVR_multiview</code> and <code>GL_OVR_multiview2</code> in the same shader results in a compile error.
</addendum>
<addendum>
Attempting to draw when the number of views in the draw framebuffer does not match the number of views specified in the active program generates an <code>INVALID_OPERATION</code> error.
</addendum>
<addendum>
When the number of views specified in the active program is one, <code>gl_ViewID_OVR</code> will always evaluate to zero.
</addendum>
Expand All @@ -202,6 +196,18 @@
<feature>
Adds support for rendering into multiple views simultaneously.
</feature>
<feature>
When a shader enables, requires, or warns either <code>GL_OVR_multiview</code> or <code>GL_OVR_multiview2</code> with an extension directive:
<ul>
<li><code>gl_ViewID_OVR</code> is a built-in input of the type uint.</li>
</ul>
</feature>
<feature>
The GLSL macro <code>GL_OVR_multiview</code> is defined as 1.
</feature>
<feature>
The GLSL macro <code>GL_OVR_multiview2</code> is defined as 1.
</feature>
</features>
</overview>
<idl xml:space="preserve">
Expand All @@ -217,6 +223,92 @@ interface WEBGL_multiview {
void framebufferTextureMultiviewWEBGL(GLenum target, GLenum attachment, GLuint texture, GLint level, GLint baseViewIndex, GLsizei numViews);
};
</idl>
<newfun>
<function name="framebufferTextureMultiviewWEBGL" type="void">
<param name="target" type="GLenum"/>
<param name="attachment" type="GLenum"/>
<param name="texture" type="GLuint"/>
<param name="level" type="GLint"/>
<param name="baseViewIndex" type="GLint"/>
<param name="numViews" type="GLsizei"/>
</function>
</newfun>
<newtok>
<function name="getParameter" type="any">
<param name="pname" type="GLenum"/>
Calling with the <code>pname</code> set to <code>MAX_VIEWS_OVR</code> returns the maximum number of views. The implementation must support at least 2 views.
<br/>

The return type depends on the parameter queried:
<table width="30%">
<tr><th>pname</th><th>returned type</th></tr>
<tr><td>MAX_VIEWS_OVR</td><td>GLint</td></tr>
</table>
</function>
</newtok>
<newtok>
<function name="getFramebufferAttachmentParameter" type="any">
<param name="target" type="GLenum"/>
<param name="attachment" type="GLenum"/>
<param name="pname" type="GLenum"/>
Calling with the <code>pname</code> parameter set to <code>FRAMEBUFFER_ATTACHMENT_TEXTURE_NUM_VIEWS_OVR</code> returns the number of views of the framebuffer object attachment.
Calling with the <code>pname</code> parameter set to <code>FRAMEBUFFER_ATTACHMENT_TEXTURE_BASE_VIEW_INDEX_OVR</code> returns the base view index of the framebuffer object attachment.
<br/>

The return type depends on the parameter queried:
<table width="30%">
<tr><th>pname</th><th>returned type</th></tr>
<tr><td>FRAMEBUFFER_ATTACHMENT_TEXTURE_NUM_VIEWS_OVR</td><td>GLsizei</td></tr>
<tr><td>FRAMEBUFFER_ATTACHMENT_TEXTURE_BASE_VIEW_INDEX_OVR</td><td>GLint</td></tr>
</table>
</function>
</newtok>
<errors>
<error>
The error <code>INVALID_OPERATION</code> is generated by attempting to enable this extension when the <code>EXT_disjoint_timer_query_webgl2</code> extension is enabled.
</error>
<error>
The error <code>INVALID_OPERATION</code> is generated by attempting to enable the <code>EXT_disjoint_timer_query_webgl2</code> extension when this extension is enabled.
</error>
<error>
The error <code>INVALID_OPERATION</code> is generated by calling <code>framebufferTextureMultiviewWEBGL</code> when transform feedback is active.
</error>
<error>
The error <code>INVALID_OPERATION</code> is generated by calling <code>drawBuffer</code> with the <code>buf</code> parameter set to <code>BACK_LEFT_AND_RIGHT_MULTIVIEW_WEBGL</code> when transform feedback is active.
</error>
<error>
The error <code>INVALID_OPERATION</code> is generated by calling <code>bindFramebuffer</code> with a <code>framebuffer</code> parameter that has multi-view attachments when transform feedback is active.
</error>
<error>
The error <code>INVALID_OPERATION</code> is generated by calling <code>bindFramebuffer</code> to bind the default framebuffer when both the left and right buffers of the stereo default framebuffer are chosen for rendering and transform feedback is active.
</error>
<error>
The error <code>INVALID_OPERATION</code> is generated by calling <code>beginTransformFeedback</code> when a framebuffer with multi-view attachments is bound as the draw framebuffer, or the default framebuffer is bound as the draw framebuffer and both left and right buffers of the stereo default framebuffer are chosen for rendering.
</error>
<error>
The error <code>INVALID_OPERATION</code> is generated by calling <code>framebufferTextureMultiviewWEBGL</code> with a <code>texture</code> parameter that does not identify a 2D array texture.
</error>
<error>
The error <code>INVALID_VALUE</code> is generated by calling <code>framebufferTextureMultiviewWEBGL</code> if <code>numViews</code> is less than 1, if <code>numViews</code> is more than <code>MAX_VIEWS_OVR</code> or with the parameters set so that <code>baseViewIndex</code> + <code>numViews</code> exceeds the value of <code>MAX_ARRAY_TEXTURE_LAYERS</code>.
</error>
<error>
The error <code>INVALID_OPERATION</code> is generated by attempting to bind a framebuffer that has multi-view attachments to <code>READ_FRAMEBUFFER</code>.
</error>
<error>
The error <code>INVALID_FRAMEBUFFER_OPERATION</code> is generated by commands that read from the framebuffer such as <code>BlitFramebuffer</code>, <code>ReadPixels</code>, <code>CopyTexImage*</code>, and <code>CopyTexSubImage*</code>, if the number of views in the current read framebuffer is greater than 1.
</error>
<error>
The error <code>INVALID_OPERATION</code> is generated by attempting to draw if the number of views in the draw framebuffer does not match the number of views declared in the active program.
</error>
</errors>
<samplecode xml:space="preserve">
<pre>
var gl = document.createElement('canvas').getContext('webgl2', {'stereo': true});
var ext = gl.getExtension('WEBGL_multiview');
gl.drawBuffer(ext.BACK_LEFT_AND_RIGHT_MULTIVIEW_WEBGL);
gl.drawElements(...); // draw will be broadcasted to both left and right buffers.
</pre>
</samplecode>
<samplecode xml:space="preserve">
<pre>
#version 300 es
Expand Down Expand Up @@ -244,5 +336,9 @@ interface WEBGL_multiview {
<revision date="2016/12/21">
<change>Specified what happens on invalid num_views declarations and if assignment to gl_Position.x is inside a larger expression.</change>
</revision>

<revision date="2017/01/12">
<change>Filled in getFramebufferAttachmentParameter and extension macro specs, formatted the documentation better, and added a simple API usage example.</change>
</revision>
</history>
</proposal>

0 comments on commit 9e937ec

Please sign in to comment.