extensions/OVR/OVR_multiview_multisampled_render_to_texture.txt - external/github.com/KhronosGroup/OpenGL-Registry - Git at Google

 Name

     OVR_multiview_multisampled_render_to_texture

 Name Strings

     GL_OVR_multiview_multisampled_render_to_texture

 Contact

     Cass Everitt (cass.everitt 'at' oculus.com)

 Contributors

     Jason Allen, NVIDIA Corporation
     Sam Holmes, Qualcomm
     Jan-Harald Fredriksen, ARM

 Status

     Incomplete

 Version

     Last Modified Date: June 25, 2015
     Revision: 0.4

 Number

     OpenGL ES Extension #250

 Dependencies

     OpenGL ES 3.0, EXT_multisampled_render_to_texture, and at least
     one of OVR_multiview or OVR_multiview2 are required. This
     extension is written against the OpenGL ES 3.0 Specification.

 Overview

     This extension brings to multiview rendering the functionality
     originally introduced in EXT_multisampled_render_to_texture.
     Essentially this just means adding one new function for
     multisample multiview array attachments in the framebuffer object.

 IP Status

     No known IP claims.

 New Procedures and Functions

     void FramebufferTextureMultisampleMultiviewOVR(
             enum target, enum attachment,
             uint texture, int level, sizei samples,
             int baseViewIndex, sizei numViews);

 New Tokens

     None.

 Additions to Section 4.4.2 of the OpenGL ES 3.0 Specification
 (Attaching Images to Framebuffer Objects)

    Add the following after the paragraph describing FramebufferTexture2D:
    (Logically, this follows after the paragraph in GL_OVR_multiview
    describing FramebufferTextureMultiviewOVR and the paragraph in GL_EXT_-
    multisampled_render_to_texture describing FramebufferTexture2D-
    MultisampleEXT)

     The command
             void FramebufferTextureMultisampleMultiviewOVR(
             enum target,  enum attachment,
             uint texture, int level, sizei samples,
             int baseViewIndex, sizei numViews);

     operates similarly to FramebufferTextureMultiviewOVR, except that it
     also enables multisampled rendering into the images of a non-multisampled
     texture object similarly to FramebufferTexture2DMultisampleEXT.

     <target>, <attachment>, <texture>, <level>, <baseViewIndex>, and
     <numViews> correspond to the same parameters for FramebufferTexture-
     MultiviewOVR and have the same restrictions and errors. <samples>
     corresponds to the same parameter for FramebufferTexture2DMultisampleEXT
     and has the same restrictions and errors.

     The contents of the multisample buffer of the texture level become
     undefined under the same conditions and operations as for
     FramebufferTexture2DMultisampleEXT.

 Dependencies on GL and ES profiles, versions, and other extensions

     This extension requires EXT_multisampled_render_to_texture, and at least
     one of OVR_multiview or OVR_multiview2 and inherits their dependencies.

 Errors

     INVALID_FRAMEBUFFER_OPERATION is generated by commands that read from the
     framebuffer such as ReadPixels, CopyTexImage*, and CopyTexSubImage*, if
     the number of views in the current read framebuffer is greater than 1.

     INVALID_VALUE is generated by FramebufferTextureMultisampleMultiviewOVR if
     numViews is less than 1, if numViews is more than MAX_VIEWS_OVR or if
     (baseViewIndex + numViews) exceeds GL_MAX_ARRAY_TEXTURE_LAYERS.

     INVALID_VALUE is generated by FramebufferTextureMultisampleMultiviewOVR if
     samples is greater than MAX_SAMPLES.

     INVALID_OPERATION is generated if a rendering command is issued and the
     number of views in the current draw framebuffer is not equal to the number
     of views declared in the currently bound program.

     INVALID_OPERATION is generated if the target type of <texture> specified
     in FramebufferTextureMultisampleMultiviewOVR is not TEXTURE_2D_ARRAY.

 New State

     None.

 New Implementation Dependent State

     None.

 Sample code

     GLsizei width  = ...;
     GLsizei height = ...;
     GLint samples = ...;
     GLsizei views = 2;

     glGenTextures(views, tex);
     glBindTexture(GL_TEXTURE_2D_ARRAY, tex[0]);
     /* Create a color texture */
     glTexStorage3D(GL_TEXTURE_2D_ARRAY, 1, GL_RGBA8, width, height, views );
     /* Create a depth texture */
     glBindTexture(GL_TEXTURE_2D_ARRAY, tex[1]);
     glTexStorage3D(GL_TEXTURE_2D_ARRAY, 1, GL_DEPTH_COMPONENT24, width, height, views )

     /* attach the render targets */
     glFramebufferTextureMultisampleMultiviewOVR(GL_DRAW_FRAMEBUFFER, GL_COLOR_ATTACHMENT0, tex[0], 0, samples, 0, views);
     glFramebufferTextureMultisampleMultiviewOVR(GL_DRAW_FRAMEBUFFER, GL_DEPTH_ATTACHMENT, tex[1], 0, samples, 0, views);

     /* .. draw to multisampled multiview .. */

 Issues

     1. Should there be a way for applications to preserve the multisample
            buffer after a resolve?

     RESOLVED: No. This spec is intended as a lightweight addition to multiview
     support and the added complexity of allowing resolves with preservation goes
     against this intention.

     2. Should there be a way for applications to guarantee preservation of
        the multisample buffer mid-frame.

     RESOLVED: No. On tiling architectures application behavior may implicitly
     trigger a mid-frame resolve. There is no requirement for a backing store
     to be maintained for the samples and in the case of a mid-frame resolve
     sample data may be lost.

     3. Are there any implications on the framebuffer completeness check?

     RESOLVED: No. The framebuffer completeness rules are fully specified
     by the combination of the added rules in EXT_multisampled_render_to_texture
     and OVR_multiview, i.e., the number of views and the number of samples
     must both match across attachments.

     4. Why does reading from multi-view framebuffers generate INVALID_-
            FRAMEBUFFER_OPERATION?

         PROPOSED.

     GL_OVR_multiview tried to avoid reading from multi-view framebuffers
     by specifying that INVALID_OPERATION is generated by FramebufferTexture-
     MultiviewOVR if target is GL_READ_FRAMEBUFFER. This error is not
     sufficient to prevent reads from multi-view targets. It disallows
     attaching a multi-view texture to the current read framebuffer, but
     there is no error that disallows attaching the multi-view texture to the
     current write framebuffer, and later binding that as the read framebuffer.

     Multiple options for resolving this is outlined below. As written, this
     specification assumes Option B.

     Option A: Detect the error on attach / bind
      - keep the existing error on FramebufferTextureMultiviewOVR, but change it
        to also generate an error on GL_FRAMEBUFFER (since that includes
        GL_READ_FRAMEBUFFER).
      - add an error on BindFramebuffer to prevent a multiview framebuffer to
        be bound as the current draw framebuffer
      - extend the error conditions on FramebufferTextureMultiviewOVR to also
        generate an error if <target> is GL_WRITE_FRAMEBUFFER and the current
        write framebuffer is the same as the current read framebuffer.

        This has the benefit of maintaining compatibility with GL_OVR_multiview,
        but it is a complex error condition, and interactions with other
        features / extensions would also need to be considered.

     Option B: Detect the error on read operations.
      - remove the existing error on FramebufferTextureMultiviewOVR
      - add an error condition that applies to all read operations

        This has the benefit of being simple (the error is only generated when
        the illegal operation is detected) and robust (i.e., there are no corner
        cases to consider). The downside is that the error is detected late.

     Option C: Remove the error and define what happens on reads.
      - remove the existing error on FramebufferTextureMultiviewOVR
      - add language similar to that for layered framebuffers, like:
        "When commands such as ReadPixels read from a multi-view framebuffer,
         the image at view zero of the selected attachment is always used to
         obtain pixel values.

        This has the benefit of being aligned with other GL features. The down-
        side is that this adds implementation cost without providing a good
        use-case (i.e., it could only read a single view).

 Revision History

       Rev.    Date      Author    Changes
       ----  ----------  --------  -----------------------------------------
       0.1   04/29/2015  cass      Initial draft
       0.2   05/04/2015  sam       Clarify issues around sample preservation
       0.3   06/01/2015  cass      Remove renderbuffer support
       0.4   06/25/2015  jhf       Clarify error conditions, add language.
	Name

	OVR_multiview_multisampled_render_to_texture

	Name Strings

	GL_OVR_multiview_multisampled_render_to_texture

	Contact

	Cass Everitt (cass.everitt 'at' oculus.com)

	Contributors

	Jason Allen, NVIDIA Corporation
	Sam Holmes, Qualcomm
	Jan-Harald Fredriksen, ARM

	Status

	Incomplete

	Version

	Last Modified Date: June 25, 2015
	Revision: 0.4

	Number

	OpenGL ES Extension #250

	Dependencies

	OpenGL ES 3.0, EXT_multisampled_render_to_texture, and at least
	one of OVR_multiview or OVR_multiview2 are required. This
	extension is written against the OpenGL ES 3.0 Specification.

	Overview

	This extension brings to multiview rendering the functionality
	originally introduced in EXT_multisampled_render_to_texture.
	Essentially this just means adding one new function for
	multisample multiview array attachments in the framebuffer object.

	IP Status

	No known IP claims.

	New Procedures and Functions

	void FramebufferTextureMultisampleMultiviewOVR(
	enum target, enum attachment,
	uint texture, int level, sizei samples,
	int baseViewIndex, sizei numViews);

	New Tokens

	None.

	Additions to Section 4.4.2 of the OpenGL ES 3.0 Specification
	(Attaching Images to Framebuffer Objects)

	Add the following after the paragraph describing FramebufferTexture2D:
	(Logically, this follows after the paragraph in GL_OVR_multiview
	describing FramebufferTextureMultiviewOVR and the paragraph in GL_EXT_-
	multisampled_render_to_texture describing FramebufferTexture2D-
	MultisampleEXT)

	The command
	void FramebufferTextureMultisampleMultiviewOVR(
	enum target, enum attachment,
	uint texture, int level, sizei samples,
	int baseViewIndex, sizei numViews);

	operates similarly to FramebufferTextureMultiviewOVR, except that it
	also enables multisampled rendering into the images of a non-multisampled
	texture object similarly to FramebufferTexture2DMultisampleEXT.

	<target>, <attachment>, <texture>, <level>, <baseViewIndex>, and
	<numViews> correspond to the same parameters for FramebufferTexture-
	MultiviewOVR and have the same restrictions and errors. <samples>
	corresponds to the same parameter for FramebufferTexture2DMultisampleEXT
	and has the same restrictions and errors.

	The contents of the multisample buffer of the texture level become
	undefined under the same conditions and operations as for
	FramebufferTexture2DMultisampleEXT.

	Dependencies on GL and ES profiles, versions, and other extensions

	This extension requires EXT_multisampled_render_to_texture, and at least
	one of OVR_multiview or OVR_multiview2 and inherits their dependencies.

	Errors

	INVALID_FRAMEBUFFER_OPERATION is generated by commands that read from the
	framebuffer such as ReadPixels, CopyTexImage, and CopyTexSubImage, if
	the number of views in the current read framebuffer is greater than 1.

	INVALID_VALUE is generated by FramebufferTextureMultisampleMultiviewOVR if
	numViews is less than 1, if numViews is more than MAX_VIEWS_OVR or if
	(baseViewIndex + numViews) exceeds GL_MAX_ARRAY_TEXTURE_LAYERS.

	INVALID_VALUE is generated by FramebufferTextureMultisampleMultiviewOVR if
	samples is greater than MAX_SAMPLES.

	INVALID_OPERATION is generated if a rendering command is issued and the
	number of views in the current draw framebuffer is not equal to the number
	of views declared in the currently bound program.

	INVALID_OPERATION is generated if the target type of <texture> specified
	in FramebufferTextureMultisampleMultiviewOVR is not TEXTURE_2D_ARRAY.

	New State

	None.

	New Implementation Dependent State

	None.

	Sample code

	GLsizei width = ...;
	GLsizei height = ...;
	GLint samples = ...;
	GLsizei views = 2;

	glGenTextures(views, tex);
	glBindTexture(GL_TEXTURE_2D_ARRAY, tex[0]);
	/* Create a color texture */
	glTexStorage3D(GL_TEXTURE_2D_ARRAY, 1, GL_RGBA8, width, height, views );
	/* Create a depth texture */
	glBindTexture(GL_TEXTURE_2D_ARRAY, tex[1]);
	glTexStorage3D(GL_TEXTURE_2D_ARRAY, 1, GL_DEPTH_COMPONENT24, width, height, views )

	/* attach the render targets */
	glFramebufferTextureMultisampleMultiviewOVR(GL_DRAW_FRAMEBUFFER, GL_COLOR_ATTACHMENT0, tex[0], 0, samples, 0, views);
	glFramebufferTextureMultisampleMultiviewOVR(GL_DRAW_FRAMEBUFFER, GL_DEPTH_ATTACHMENT, tex[1], 0, samples, 0, views);

	/* .. draw to multisampled multiview .. */

	Issues

	1. Should there be a way for applications to preserve the multisample
	buffer after a resolve?

	RESOLVED: No. This spec is intended as a lightweight addition to multiview
	support and the added complexity of allowing resolves with preservation goes
	against this intention.

	2. Should there be a way for applications to guarantee preservation of
	the multisample buffer mid-frame.

	RESOLVED: No. On tiling architectures application behavior may implicitly
	trigger a mid-frame resolve. There is no requirement for a backing store
	to be maintained for the samples and in the case of a mid-frame resolve
	sample data may be lost.

	3. Are there any implications on the framebuffer completeness check?

	RESOLVED: No. The framebuffer completeness rules are fully specified
	by the combination of the added rules in EXT_multisampled_render_to_texture
	and OVR_multiview, i.e., the number of views and the number of samples
	must both match across attachments.

	4. Why does reading from multi-view framebuffers generate INVALID_-
	FRAMEBUFFER_OPERATION?

	PROPOSED.

	GL_OVR_multiview tried to avoid reading from multi-view framebuffers
	by specifying that INVALID_OPERATION is generated by FramebufferTexture-
	MultiviewOVR if target is GL_READ_FRAMEBUFFER. This error is not
	sufficient to prevent reads from multi-view targets. It disallows
	attaching a multi-view texture to the current read framebuffer, but
	there is no error that disallows attaching the multi-view texture to the
	current write framebuffer, and later binding that as the read framebuffer.

	Multiple options for resolving this is outlined below. As written, this
	specification assumes Option B.

	Option A: Detect the error on attach / bind
	- keep the existing error on FramebufferTextureMultiviewOVR, but change it
	to also generate an error on GL_FRAMEBUFFER (since that includes
	GL_READ_FRAMEBUFFER).
	- add an error on BindFramebuffer to prevent a multiview framebuffer to
	be bound as the current draw framebuffer
	- extend the error conditions on FramebufferTextureMultiviewOVR to also
	generate an error if <target> is GL_WRITE_FRAMEBUFFER and the current
	write framebuffer is the same as the current read framebuffer.

	This has the benefit of maintaining compatibility with GL_OVR_multiview,
	but it is a complex error condition, and interactions with other
	features / extensions would also need to be considered.

	Option B: Detect the error on read operations.
	- remove the existing error on FramebufferTextureMultiviewOVR
	- add an error condition that applies to all read operations

	This has the benefit of being simple (the error is only generated when
	the illegal operation is detected) and robust (i.e., there are no corner
	cases to consider). The downside is that the error is detected late.

	Option C: Remove the error and define what happens on reads.
	- remove the existing error on FramebufferTextureMultiviewOVR
	- add language similar to that for layered framebuffers, like:
	"When commands such as ReadPixels read from a multi-view framebuffer,
	the image at view zero of the selected attachment is always used to
	obtain pixel values.

	This has the benefit of being aligned with other GL features. The down-
	side is that this adds implementation cost without providing a good
	use-case (i.e., it could only read a single view).

	Revision History

	Rev. Date Author Changes
	---- ---------- -------- -----------------------------------------
	0.1 04/29/2015 cass Initial draft
	0.2 05/04/2015 sam Clarify issues around sample preservation
	0.3 06/01/2015 cass Remove renderbuffer support
	0.4 06/25/2015 jhf Clarify error conditions, add language.