Name

    ANGLE_external_objects_flags

Name Strings

    GL_ANGLE_memory_object_flags

Contributors

    Shahbaz Youssefi, Google

Contact

    Shahbaz Youssefi, Google (syoussefi 'at' google.com)

Status

    Draft

Version

    Last Modified Date: Aug 3, 2020
    Revision: 1

Number

    TBD

Dependencies

    Written against the OpenGL 4.5 and OpenGL ES 3.2 specifications

    GL_ANGLE_memory_object_flags requires GL_EXT_memory_object.

Overview

    Building upon the OpenGL memory object framework defined in
    EXT_external_objects, this extension introduces new Texture entry points
    for specifying create and usage flags parameters.  These parameters match
    an external Texture's corresponding Vulkan create and usage flags.  This
    allows applications to drop usage flags that are detrimental to
    performance, or add create flags as necessary.

New Procedures and Functions

    The following commands are added:

        void TexStorageMemFlags2DANGLE(enum target,
                                       sizei levels,
                                       enum internalFormat,
                                       sizei width,
                                       sizei height,
                                       uint memory,
                                       uint64 offset,
                                       bitfield createFlags,
                                       bitfield usageFlags);

        void TexStorageMemFlags2DMultisampleANGLE(enum target,
                                                  sizei samples,
                                                  enum internalFormat,
                                                  sizei width,
                                                  sizei height,
                                                  boolean fixedSampleLocations,
                                                  uint memory,
                                                  uint64 offset,
                                                  bitfield createFlags,
                                                  bitfield usageFlags);

        void TexStorageMemFlags3DANGLE(enum target,
                                       sizei levels,
                                       enum internalFormat,
                                       sizei width,
                                       sizei height,
                                       sizei depth,
                                       uint memory,
                                       uint64 offset,
                                       bitfield createFlags,
                                       bitfield usageFlags);

        void TexStorageMemFlags3DMultisampleANGLE(enum target,
                                                  sizei samples,
                                                  enum internalFormat,
                                                  sizei width,
                                                  sizei height,
                                                  sizei depth,
                                                  boolean fixedSampleLocations,
                                                  uint memory,
                                                  uint64 offset,
                                                  bitfield createFlags,
                                                  bitfield usageFlags);

        [[ The following are added if direct state access is supported ]]

        void TextureStorageMemFlags2DANGLE(uint texture,
                                           sizei levels,
                                           enum internalFormat,
                                           sizei width,
                                           sizei height,
                                           uint memory,
                                           uint64 offset,
                                           bitfield createFlags,
                                           bitfield usageFlags);

        void TextureStorageMemFlags2DMultisampleANGLE(uint texture,
                                                      sizei samples,
                                                      enum internalFormat,
                                                      sizei width,
                                                      sizei height,
                                                      boolean fixedSampleLocations,
                                                      uint memory,
                                                      uint64 offset,
                                                      bitfield createFlags,
                                                      bitfield usageFlags);

        void TextureStorageMemFlags3DANGLE(uint texture,
                                           sizei levels,
                                           enum internalFormat,
                                           sizei width,
                                           sizei height,
                                           sizei depth,
                                           uint memory,
                                           uint64 offset,
                                           bitfield createFlags,
                                           bitfield usageFlags);

        void TextureStorageMemFlags3DMultisampleANGLE(uint texture,
                                                      sizei samples,
                                                      enum internalFormat,
                                                      sizei width,
                                                      sizei height,
                                                      sizei depth,
                                                      boolean fixedSampleLocations,
                                                      uint memory,
                                                      uint64 offset,
                                                      bitfield createFlags,
                                                      bitfield usageFlags);

        [[ The following are available in OpenGL only ]]

        void TexStorageMemFlags1DANGLE(enum target,
                                       sizei levels,
                                       enum internalFormat,
                                       sizei width,
                                       uint memory,
                                       uint64 offset,
                                       bitfield createFlags,
                                       bitfield usageFlags);

        [[ The following are availble in OpenGL only, and only when
           direct state access is available ]]

        void TextureStorageMemFlags1DANGLE(uint texture,
                                           sizei levels,
                                           enum internalFormat,
                                           sizei width,
                                           uint memory,
                                           uint64 offset,
                                           bitfield createFlags,
                                           bitfield usageFlags);

New Tokens

    The following tokens are added:

    Accepted by the <createFlags> parameter of TexStorageMemFlags*ANGLE() and
    TextureStorageMemFlags*ANGLE().

        CREATE_SPARSE_BINDING_BIT_ANGLE                    0x00000001
        CREATE_SPARSE_RESIDENCY_BIT_ANGLE                  0x00000002
        CREATE_SPARSE_ALIASED_BIT_ANGLE                    0x00000004
        CREATE_MUTABLE_FORMAT_BIT_ANGLE                    0x00000008
        CREATE_CUBE_COMPATIBLE_BIT_ANGLE                   0x00000010
        CREATE_ALIAS_BIT_ANGLE                             0x00000400
        CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_ANGLE       0x00000040
        CREATE_2D_ARRAY_COMPATIBLE_BIT_ANGLE               0x00000020
        CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT_ANGLE       0x00000080
        CREATE_EXTENDED_USAGE_BIT_ANGLE                    0x00000100
        CREATE_PROTECTED_BIT_ANGLE                         0x00000800
        CREATE_DISJOINT_BIT_ANGLE                          0x00000200
        CREATE_CORNER_SAMPLED_BIT_ANGLE                    0x00002000
        CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_ANGLE 0x00001000
        CREATE_SUBSAMPLED_BIT_ANGLE                        0x00004000

    Accepted by the <usageFlags> parameter of TexStorageMemFlags*ANGLE() and
    TextureStorageMemFlags*ANGLE().

        USAGE_TRANSFER_SRC_BIT_ANGLE                       0x00000001
        USAGE_TRANSFER_DST_BIT_ANGLE                       0x00000002
        USAGE_SAMPLED_BIT_ANGLE                            0x00000004
        USAGE_STORAGE_BIT_ANGLE                            0x00000008
        USAGE_COLOR_ATTACHMENT_BIT_ANGLE                   0x00000010
        USAGE_DEPTH_STENCIL_ATTACHMENT_BIT_ANGLE           0x00000020
        USAGE_TRANSIENT_ATTACHMENT_BIT_ANGLE               0x00000040
        USAGE_INPUT_ATTACHMENT_BIT_ANGLE                   0x00000080
        USAGE_SHADING_RATE_IMAGE_BIT_ANGLE                 0x00000100
        USAGE_FRAGMENT_DENSITY_MAP_BIT_ANGLE               0x00000200

Additions to Chapter 8 of the OpenGL 4.5 Specification (Textures and
Samplers)

    For each list of TexStorage* commands in the 1D, 2D, 3D,
    2DMultisample, and 3DMultisample families, add the following
    variants:

        void TexStorageMemFlags*ANGLE(<existing parameters>,
                                      uint memory,
                                      uint64 offset,
                                      bitfield createFlags,
                                      bitfield usageFlags);

        void TextureStorageMemFlags*ANGLE(<existing parameters>,
                                          uint memory,
                                          uint64 offset,
                                          bitfield createFlags,
                                          bitfield usageFlags);

    For each of the TexStorageMemFlags*ANGLE commands, move the description from
    the corresponding TexStorageMem*EXT from EXT_external_objects under that
    command and add the following language:

        "The implementation should apply the same semantics to the internal
        storage of the texture based on <createFlags> and <usageFlags> as the
        corresonding VK_IMAGE_CREATE_* and VK_IMAGE_USAGE_* flags would have on
        a Vulkan image respectively.  See tables 8.17 and 8.18 for the mapping
        between the GL and Vulkan flags.  It is undefined behavior if the
        application provides create and usage flags that are not identical to
        those used to create the Vulkan image."

        Table 8.17: Create flags and corresponding Vulkan Image Create Flags

        | Create Flag                                        | Equivalent Vulkan Create Flag                             |
        +----------------------------------------------------+-----------------------------------------------------------+
        | CREATE_SPARSE_BINDING_BIT_ANGLE                    | VK_IMAGE_CREATE_SPARSE_BINDING_BIT                        |
        | CREATE_SPARSE_RESIDENCY_BIT_ANGLE                  | VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT                      |
        | CREATE_SPARSE_ALIASED_BIT_ANGLE                    | VK_IMAGE_CREATE_SPARSE_ALIASED_BIT                        |
        | CREATE_MUTABLE_FORMAT_BIT_ANGLE                    | VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT                        |
        | CREATE_CUBE_COMPATIBLE_BIT_ANGLE                   | VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT                       |
        | CREATE_ALIAS_BIT_ANGLE                             | VK_IMAGE_CREATE_ALIAS_BIT                                 |
        | CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_ANGLE       | VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT           |
        | CREATE_2D_ARRAY_COMPATIBLE_BIT_ANGLE               | VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT                   |
        | CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT_ANGLE       | VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT           |
        | CREATE_EXTENDED_USAGE_BIT_ANGLE                    | VK_IMAGE_CREATE_EXTENDED_USAGE_BIT                        |
        | CREATE_PROTECTED_BIT_ANGLE                         | VK_IMAGE_CREATE_PROTECTED_BIT                             |
        | CREATE_DISJOINT_BIT_ANGLE                          | VK_IMAGE_CREATE_DISJOINT_BIT                              |
        | CREATE_CORNER_SAMPLED_BIT_ANGLE                    | VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV                     |
        | CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_ANGLE | VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT |
        | CREATE_SUBSAMPLED_BIT_ANGLE                        | VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT                        |
        +----------------------------------------------------------------------------------------------------------------+

        Table 8.18: Usage flags and corresponding Vulkan Image Usage Flags

        | Usage Flag                               | Equivalent Vulkan Usage Flag                |
        +------------------------------------------+---------------------------------------------+
        | USAGE_TRANSFER_SRC_BIT_ANGLE             | VK_IMAGE_USAGE_TRANSFER_SRC_BIT             |
        | USAGE_TRANSFER_DST_BIT_ANGLE             | VK_IMAGE_USAGE_TRANSFER_DST_BIT             |
        | USAGE_SAMPLED_BIT_ANGLE                  | VK_IMAGE_USAGE_SAMPLED_BIT                  |
        | USAGE_STORAGE_BIT_ANGLE                  | VK_IMAGE_USAGE_STORAGE_BIT                  |
        | USAGE_COLOR_ATTACHMENT_BIT_ANGLE         | VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT         |
        | USAGE_DEPTH_STENCIL_ATTACHMENT_BIT_ANGLE | VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT |
        | USAGE_TRANSIENT_ATTACHMENT_BIT_ANGLE     | VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT     |
        | USAGE_INPUT_ATTACHMENT_BIT_ANGLE         | VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT         |
        | USAGE_SHADING_RATE_IMAGE_BIT_ANGLE       | VK_IMAGE_USAGE_SHADING_RATE_IMAGE_BIT_NV    |
        | USAGE_FRAGMENT_DENSITY_MAP_BIT_ANGLE     | VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT |
        +----------------------------------------------------------------------------------------+

    Add the following errors for each of the TexStorageMemFlags*ANGLE commands:

        "An INVALID_VALUE error is generated if <createFlags> has a bit set
        other than those specified in table 8.17."

        "An INVALID_VALUE error is generated if <usageFlags> has a bit set
        other than those specified in table 8.18."

    For each of the TexStorageMem*EXT commands, change the description of
    TexStorageMem*EXT and TextureStorageMem*EXT as such:

        "Calling TexStorageMem*EXT is equivalent to calling
        TexStorageMemFlags*ANGLE with 0 as <createFlags> and all
        Vulkan-supported usage flags, even if there are no corresponding GL
        flags specified in this extension."

Issues

    1)  Can the GL and Vulkan create and usage flag values diverge?

        RESOLVED: No.  It is expected for the application to provide the flags
        used to create the Vulkan image verbatim.

    2)  What if Vulkan adds new create and usage flags?

        RESOLVED: If the implementation is too old to be aware of those flags,
        the functions from GL_EXT_memory_object must be used instead.  New flags
        can be added through new extensions that build on this extension.

    3)  Should the GL implementation apply the same validation as Vulkan based
        on the create and usage flags?

        RESOLVED: No.  The application has already created an image with these
        flags in Vulkan, so the GL implementation can assume they are valid.
        Validating this is expensive and unnecessary in almost all applications.

Revision History

    Revision 1, 2020-08-03 (Shahbaz Youssefi)
        - Initial draft based on EXT_external_objects.