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.
