xref: /third_party/openGLES/extensions/NV/NV_memory_attachment.txt

Name

    NV_memory_attachment

Name Strings

    GL_NV_memory_attachment

Contributors

    Carsten Rohde, NVIDIA
    Christoph Kubisch, NVIDIA
    James Jones, NVIDIA

Contact

    Carsten Rohde, NVIDIA (crohde 'at' nvidia.com)

Status

    Complete

Version

    Last Modified Date: Aug 27, 2018
    Revision: 2

Number

    524
    OpenGL ES Extension #305

Dependencies

    Requires GL_EXT_memory_object and ARB_texture_storage or a version of
    OpenGL or OpenGL ES that incorporates it.

    Written against the OpenGL 4.6 and OpenGL ES 3.2 specifications.

    Interacts with ARB_direct_state_access (OpenGL) when OpenGL < 4.5 is used.

    Interacts with NV_shader_buffer_load.

    Interacts with NV_bindless_texture and ARB_bindless_texture.

Overview

    This extension extends the memory objects introduced with EXT_memory_object
    to allow existing textures and buffers to be migrated to an imported memory
    allocation.  The primary use-case of this extension is plug-in development
    where resource management (creation, deletion, sizing etc.) is handled by
    inaccessible host application code.

New Procedures and Functions

    If the GL_NV_memory_attachment string is reported, the following
    commands are added:

        void GetMemoryObjectDetachedResourcesuivNV(uint memory,
                                                   enum pname,
                                                   int first,
                                                   sizei count,
                                                   uint *params)

        void ResetMemoryObjectParameterNV(uint memory,
                                          enum pname);

        void TexAttachMemoryNV(enum target,
                               uint memory,
                               uint64 offset);

        void BufferAttachMemoryNV(enum target,
                                  uint memory,
                                  uint64 offset);

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

        void TextureAttachMemoryNV(uint texture,
                                   uint memory,
                                   uint64 offset);

        void NamedBufferAttachMemoryNV(uint buffer,
                                       uint memory,
                                       uint64 offset);

New Tokens

    If the GL_NV_memory_attachment string is reported, the following tokens
    are added:

    Accepted by the <pname> parameter of TexParameter{ifx}{v},
    TexParameterI{i ui}v, TextureParameter{if}{v}, TextureParameterI{i ui}v,
    GetTexParameter{if}v, GetTexParameterI{i ui}v, GetTextureParameter{if}v,
    GetTextureParameterI{i ui}v, GetBufferParameter{i|i64}v and
    GetNamedBufferParameter{i|i64}v:

      ATTACHED_MEMORY_OBJECT_NV           0x95A4
      ATTACHED_MEMORY_OFFSET_NV           0x95A5
      MEMORY_ATTACHABLE_ALIGNMENT_NV      0x95A6
      MEMORY_ATTACHABLE_SIZE_NV           0x95A7
      MEMORY_ATTACHABLE_NV                0x95A8

    Accepted by the <pname> parameter of GetBooleanv, GetDoublev, GetFloatv,
    GetIntegerv, GetInteger64v, GetUnsignedBytevEXT,
    GetMemoryObjectParameterivEXT, and the <target> parameter of GetBooleani_v,
    GetIntegeri_v,GetFloati_v, GetDoublei_v, GetInteger64i_v and
    GetUnsignedBytei_vEXT:

      DETACHED_MEMORY_INCARNATION_NV      0x95A9

    Accepted by the <pname> parameter of GetMemoryObjectParameterivEXT,
    GetMemoryObjectDetachedResourcesuivNV and ResetMemoryObjectParameterNV:

      DETACHED_TEXTURES_NV                0x95AA
      DETACHED_BUFFERS_NV                 0x95AB

    Accepted by the <pname> parameter of MemoryObjectParameterivEXT,
    GetMemoryObjectParameterivEXT:

      MAX_DETACHED_TEXTURES_NV            0x95AC
      MAX_DETACHED_BUFFERS_NV             0x95AD


Additions to Chapter 6 of the EXT_external_objects Specification
(Memory Objects)

    Add a new sections after 6.2 (Memory object parameters)

        6.3 Attaching memory to existing resources

        MEMORY_ATTACHABLE_NV should be used to query if it is valid to attach
        a memory object to an existing resource (buffer or texture).  The
        memory region size and offset alignment required by a resource can be
        queried using MEMORY_ATTACHABLE_SIZE_NV and
        MEMORY_ATTACHABLE_ALIGNMENT_NV respectively.  The current attached
        memory object and the used offset for a resource can be queried by
        ATTACHED_MEMORY_OBJECT_NV and ATTACHED_MEMORY_OFFSET_NV.

        If a resource which has memory attached is resized, the attached memory
        will be detached and a new data store will be allocated.  If a resource
        which has memory attached is deleted, the attached memory will first be
        detached.  If any such detachment occurs, a global incarnation counter
        will be increased and the current value will be stored in the detached
        memory object.  The incarnation counter can be queried by
        DETACHED_MEMORY_INCARNATION_EXT either globally or for a specific
        memory object.

        The command

            void GetMemoryObjectDetachedResourcesuivNV(uint memory,
                                                       enum pname,
                                                       int first,
                                                       sizei count,
                                                       uint *params)

        will return a list of detached buffers (if <pname> is
        DETACHED_BUFFERS_NV) or textures (if <pname> is DETACHED_TEXTURES_NV)
        in <params> for memory object <memory>.  It will return <count> items
        beginning with <first> item.  The number of available items can be
        queried by calling GetMemoryObjectParameterivEXT with <pname> set to
        DETACHED_TEXTURES_NV or DETACHED_BUFFERS_NV.  An INVALID_VALUE error is
        generated by GetMemoryObjectDetachedResourcesuivNV if <memory> is 0.
        An INVALID_OPERATION error is generated if <memory> names a valid
        memory object which has no associated memory.  An INVALID_VALUE error
        is generated if <pname> is neither DETACHED_BUFFERS_NV nor
        DETACHED_TEXTURES_NV.  An INVALID_VALUE error is generated if
        <first> + <count> is greater than the number of available items in the
        list.  An INVALID_VALUE error is generated if <params> is NULL.
        MemoryObjectParameterivEXT must be called with <pname> set to
        MAX_DETACHED_TEXTURES_NV or MAX_DETACHED_BUFFERS_NV before calling
        GetMemoryObjectDetachedResourcesuivNV to set the maximum number of
        items in the list of detached textures or buffers.  The default values
        are 0 which means that tracking of detached textures and buffers is
        disabled by default.

        The command

        void ResetMemoryObjectParameterNV(uint memory,
                                          enum pname);

        will reset the list of detached buffers (if <pname> is
        DETACHED_BUFFERS_NV) or textures (if <pname> is DETACHED_TEXTURES_NV)
        for memory object <memory>.  An INVALID_VALUE error is generated by
        ResetMemoryObjectParameterNV if <memory> is 0.  An INVALID_OPERATION
        error is generated if <memory> names a valid memory object which has
        no associated memory.  An INVALID_VALUE error is generated if <pname>
        is neither DETACHED_BUFFERS_NV nor DETACHED_TEXTURES_NV.


Additions to Chapter 6 of the OpenGL 4.6 Specification (Buffer Objects)

    Add a new section after 6.2.1 (Clearing Buffer Object Data Stores)

        6.2.2 Attaching a memory object to a buffer object

        The commands

            void BufferAttachMemoryNV(enum target,
                                      uint memory,
                                      uint64 offset);

            void NamedBufferAttachMemoryNV(uint buffer,
                                           uint memory,
                                           uint64 offset);

        will attach a region of a memory object to a buffer object.  For
        BufferAttachMemoryNV, the buffer object is that bound to <target>,
        which must be one of the values listed in table 6.1.  For
        NamedBufferAttachMemoryNV, <buffer> is the name of the buffer
        object.  <memory> and <offset> define a region of memory that will
        replace the data store for <buffer>. The content of the original data
        store will be preserved by a server side copy and the original data
        store will be deleted after that copy.  The implementation may restrict
        which values of <offset> are valid for a given memory object and buffer
        parameter combination.  These restrictions are outside the scope of
        this extension and must be determined by querying the API or mechanism
        which created the resource which <memory> refers to.  If an invalid
        offset is specified an INVALID_VALUE error is generated.  An
        INVALID_VALUE error is generated by BufferAttachMemoryNV and
        NamedBufferAttachMemoryNV if <memory> is 0. An INVALID_OPERATION error
        is generated if <memory> names a valid memory object which has no
        associated memory.  An INVALID_OPERATION error is generated if the
        specified buffer was created with MAP_PERSISTENT_BIT flag.  An
        INVALID_OPERATION error is generated if the specified buffer is
        currently mapped by client.

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

    Add a new section between sections 8.19, "Immutable-Format Texture Images"
    and section 8.20, "Invalidating Texture Image Data"

        8.20 Attaching a memory object to a texture image

        The commands

            void TexAttachMemoryNV(enum target,
                                   uint memory,
                                   uint64 offset);

            void TextureAttachMemoryNV(uint texture,
                                       uint memory,
                                       uint64 offset);

        will attach a region of a memory object to a texture.  For
        TexAttachMemoryNV, the texture is that bound to <target>, which must be
        one of TEXTURE_1D, TEXTURE_2D, TEXTURE_3D, TEXTURE_1D_ARRAY,
        TEXTURE_2D_ARRAY, TEXTURE_RECTANGLE, TEXTURE_CUBE_MAP,
        TEXTURE_CUBE_MAP_ARRAY, TEXTURE_2D_MULTISAMPLE, or
        TEXTURE_2D_MULTISAMPLE_ARRAY.  For TextureAttachMemoryNV, <texture> is
        the name of the texture.  <memory> and <offset> define a region of
        memory that will replace the data store for <texture>. The content of
        the original data store will be preserved by a server side copy and the
        original data store will be deleted after that copy.  The
        implementation may restrict which values of <offset> are valid for a
        given memory object and texture parameter combination.  These
        restrictions are outside the scope of this extension and must be
        determined by querying the API or mechanism which created the resource
        which <memory> refers to.  If an invalid offset is specified an
        INVALID_VALUE error is generated.  An INVALID_VALUE error is generated
        by TexAttachMemoryNV and TextureAttachMemoryNV if <memory> is 0.  An
        INVALID_OPERATION error is generated if <memory> names a valid memory
        object which has no associated memory.

Errors

New State

Sample

    // host: code not visible to the plug-in developer
    // plug-in: code written by plug-in developer

    uint tex0;
    uint tex1;

    // host
    {
        // sets up textures as usual
    }

    // plug-in
    {
        int attachable0;
        int attachable1;
        GetTextureParameteriv(tex0, MEMORY_ATTACHABLE_NV, &attachable0);
        GetTextureParameteriv(tex1, MEMORY_ATTACHABLE_NV, &attachable1);

        if (attachable0 && attachable1){

            // allocate memory within vulkan and import it as specified in
            // EXT_memory_object

            // attach imported vulkan memory
            TextureAttachMemoryNV(tex0, memobj, memoffset0);

            // ... do same for tex1
            TextureAttachMemoryNV(tex1, memobj, memoffset1);
        }
    }

    ///////////////////////////////
    // Querying mutations by host

    int incarnationExpected;

    // plug-in
    {
        // global query
        GetIntegerv(DETACHED_MEMORY_INCARNATION_NV, &incarnationExpected);

        // if we have multiple memory objects
        for each memobj {
          GetMemoryObjectParameterivEXT(memobj.id,
                                        DETACHED_MEMORY_INCARNATION_NV,
                                        &memobj.incarnation);
          GLint maxDetachedTextures = 64;
          MemoryObjectParameterivEXT(memobj.id,
                                     MAX_DETACHED_TEXTURES_NV,
                                     &maxDetachedTextures);
        }
    }

    // host
    {
        // deletion triggers a detach
        glDeleteTextures(1, &tex1);
    }

    // plug-in
    {
        // global query if resources of context were affected
        int incarnation;
        GetIntegerv(DETACHED_MEMORY_INCARNATION_NV, &incarnation);

        if (incarnation != incarnationExpected) {
            incarnationExpected = incarnation;

            // narrow down search which memory object was affected
            for each memobj {
                GetMemoryObjectParameterivEXT(memobj.id,
                                              DETACHED_MEMORY_INCARNATION_NV,
                                              &incarnation);

                if (incarnation != memobj.incarnation) {
                    memobj.incarnation = incarnation;

                    int removedTexCount;
                    GetMemoryObjectParameterivEXT(memobj.id,
                                                  DETACHED_TEXTURES_NV,
                                                  &removedTexCount);

                    std::vector<uint> removedTexs(removedTexCount);

                    GetMemoryObjectDetachedResourcesuivNV(
                        memobj.id,
                        DETACHED_TEXTURES_NV,
                        0, removedTexCount,
                        removedTexs.data());

                    for (int i = 0; i < removedTexCount; i++) {
                        uint tex = removedTexs[i];
                        // look up tex in custom allocator and
                        // mark its memory as available again
                    }

                    ResetMemoryObjectParameter(memobj.id,
                                               DETACHED_TEXTURES_NV);
                }
            }
        }
    }

Issues

    1)  Do we need to introduce allocation done within OpenGL
        or is attaching existing resources to imported allocation
        sufficient?

        RESOLVED: No.  No need to duplicate work which has already been done
        in Vulkan.

    2)  Should binding memory only work on immutable resources?

        RESOLVED: No.  To improve compatibility with existing GL resources,
        allow mutable resources as well. A global and local incarnation counter
        was introduced to test against changes, as well as detecting the
        detached resources.

    3)  Do we support client-mappable resources?

        RESOLVED: Yes.  Client-mappable resources are supported but not
        when they are persistent. When memory is attached resource must be
        unmapped.

    4)  What are the affects on TextureViews?

        RESOLVED: TextureViews inherit the memory state.

    5)  Do bindless resources change?

        RESOLVED: Yes.  The existing handles and GPU addresses become invalid
        when memory is attached and must be queried afterwards.

    6)  Should we support resources that were migrated to host memory by driver?

        RESOLVED: Yes, but the attached memory is independ from this state.

    7)  Do we need an "attachable" per-resource state?

        RESOLVED: Yes.

    8)  How is bindless residency affected?

        RESOLVED: A memory object becomes resident if at least one attached
        resource is resident.


Revision History

    Revision 2, 2018-08-20 (Carsten Rohde, Christoph Kubisch)
        - Added spec body describing new commands.
        - Added non-DSA functions
        - Resolve issues

    Revision 1, 2018-05-07 (Carsten Rohde, Christoph Kubisch)
        - Initial draft.