xref: /third_party/openGLES/extensions/NV/NV_copy_image.txt (revision 5bd8dead)

Name

    NV_copy_image

Name Strings

    GL_NV_copy_image
    WGL_NV_copy_image
    GLX_NV_copy_image

Contact

    Michael Gold, NVIDIA Corporation (gold 'at' nvidia.com)

Contributors

    Jeff Bolz, NVIDIA Corporation (jbolz 'at' nvidia.com)
    James Jones, NVIDIA Corporation (jajones 'at' nvidia.com)
    Joe Kain, NVIDIA Corporation (jkain 'at' nvidia.com)
    Benjamin Morris, NVIDIA Corporation (bmorris 'at' nvidia.com)
    Michael Morrison, NVIDIA Corporation (mmorrison 'at' nvidia.com)
    Aaron Plattner, NVIDIA Corporation (aplattner 'at' nvidia.com)
    Thomas Volk, NVIDIA Corporation (tvolk 'at' nvidia.com)
    Eric Werness, NVIDIA Corporation (ewerness 'at' nvidia.com)
    Shazia Rahman, NVIDIA Corporation (srahman 'at' nvidia.com)

Status

    Shipping (July 2009, Release 190)

Version

    Last Modified Date:         8/7/2012
    NVIDIA revision:            5

Number

    376

Dependencies

    OpenGL 1.1 is required.

    The extension is written against the OpenGL 3.1 Specification.

Overview

    This extension enables efficient image data transfer between image
    objects (i.e. textures and renderbuffers) without the need to bind
    the objects or otherwise configure the rendering pipeline.  The
    WGL and GLX versions allow copying between images in different
    contexts, even if those contexts are in different sharelists or
    even on different physical devices.

New Procedures and Functions

    void CopyImageSubDataNV(
        uint srcName, enum srcTarget, int srcLevel,
        int srcX, int srcY, int srcZ,
        uint dstName, enum dstTarget, int dstLevel,
        int dstX, int dstY, int dstZ,
        sizei width, sizei height, sizei depth);

New Tokens

    None

Additions to Chapter 4 of the OpenGL 3.1 Specification (Per-Fragment
Operations and the Frame Buffer)

    Append to section 4.3.3:

    The function

        void CopyImageSubDataNV(
            uint srcName, enum srcTarget, int srcLevel,
            int srcX, int srcY, int srcZ,
            uint dstName, enum dstTarget, int dstLevel,
            int dstX, int dstY, int dstZ,
            sizei width, sizei height, sizei depth);

    may be used to copy a region of texel data between two image
    objects.  An image object may be either a texture or a
    renderbuffer.

    The source object is identified by <srcName> and <srcTarget>.
    Similarly the destination object is identified by <dstName> and
    <dstTarget>.  The interpretation of the name depends on the value
    of the corresponding target parameter.  If the target parameter is
    RENDERBUFFER, the name is interpreted as the name of a
    renderbuffer object.  If the target parameter is a texture target,
    the name is interpreted as a texture object.  All non-proxy
    texture targets are accepted, with the exception of TEXTURE_BUFFER
    and the cubemap face selectors described in table 3.23.

    <srcLevel> and <dstLevel> identify the source and destination
    level of detail.  For textures, this must be a valid level of
    detail in the texture object.  For renderbuffers, this value must
    be zero.

    <srcX>, <srcY>, and <srcZ> specify the lower left texel
    coordinates of a <width>-wide by <height>-high by <depth>-deep
    rectangular subregion of the source texel array.  Negative values
    of <srcX>, <srcY>, and <srcZ> correspond to the coordinates of
    border texels, addressed as in figure 3.10.  Similarly, <dstX>,
    <dstY> and <dstZ> specify the coordinates of a subregion of the
    destination texel array.  The source and destination subregions
    must be contained entirely within the specified level of the
    corresponding image objects.

    Slices of a TEXTURE_1D_ARRAY, TEXTURE_2D_ARRAY, TEXTURE_3D and
    faces of TEXTURE_CUBE_MAP are all compatible provided they share
    an internal format, and multiple slices or faces may be copied
    between these objects with a single call by specifying the
    starting slice with <srcZ> and <dstZ>, and the number of slices to
    be copied with <depth>.  Cubemap textures always have six faces
    which are selected by a zero-based face index, according to the
    order specified in table 3.23.

    CopyImageSubDataNV may fail with any of the following errors:
    INVALID_ENUM is generated if either target is not RENDERBUFFER or
    a valid non-proxy texture target, or is TEXTURE_BUFFER, or is one
    of the cubemap face selectors described in table 3.23, or if the
    target does not match the type of the object.  INVALID_OPERATION
    is generated if either object is a texture and the texture is not
    consistent, or if the source and destination internal formats or
    number of samples do not match.  INVALID_VALUE is generated if
    either name does not correspond to a valid renderbuffer or texture
    object according to the corresponding target parameter, or if the
    specified level is not a valid level for the image, or if the
    dimensions of the either subregion exceeds the boundaries of the
    corresponding image object, or if the image format is compressed
    and the dimensions of the subregion fail to meet the alignment
    constraints of the format.

************************************************************************

Additions to the WGL Specification

    The function

        BOOL wglCopyImageSubDataNV(
            HGLRC hSrcRC, uint srcName, enum srcTarget, int srcLevel,
            int srcX, int srcY, int srcZ,
            HGLRC hDstRC, uint dstName, enum dstTarget, int dstLevel,
            int dstX, int dstY, int dstZ,
            sizei width, sizei height, sizei depth);

    behaves identically to the core function glCopyImageSubDataNV,
    except that the <hSrcRC> and <hDstRC> parameters specify the
    contexts in which to look up the source and destination objects,
    respectively.  A value of zero indicates that the currently bound
    context should be used instead.

    Upon success, the value TRUE is returned.  Upon failure, the value
    FALSE is returned, and the system error code will be set to one of
    the following:

        ERROR_INVALID_HANDLE indicates that either of <hSrcRC> or
        <hDstRC> is non-zero and is not recognized by the
        implementation as a valid context, or is zero and there is no
        valid context bound in the current thread.

        ERROR_INVALID_OPERATION indicates that the call failed, and if
        either the source or the destination context is bound in the
        current thread, a GL error code is set to indicate the cause.
        This error code may be retrieved by calling glGetError().  If
        neither the source nor the destination context is bound in the
        current thread, no GL error is set.

Additions to the GLX Specification

    The function

        void glXCopyImageSubDataNV(Display *dpy,
            GLXContext srcCtx, uint srcName, enum srcTarget, int srcLevel,
            int srcX, int srcY, int srcZ,
            GLXContext dstCtx, uint dstName, enum dstTarget, int dstLevel,
            int dstX, int dstY, int dstZ,
            sizei width, sizei height, sizei depth);

    behaves identically to the core function glCopyImageSubDataNV,
    except that the <srcCtx> and <dstCtx> parameters specify the
    contexts in which to look up the source and destination objects,
    respectively.  A value of NULL for either context indicates that
    the value which is returned by glXGetCurrentContext() should be
    used instead. Both contexts must share the same address space, as
    described in section 2.3.

    If either <srcCtx> or <dstCtx> is not a valid rendering context,
    the error GLXBadContext is generated.

    If the server portion of the contexts do not share the same
    address space, the error BadMatch is generated.

    If an error occurs due to GL parameter validation, the error
    BadMatch will be generated.  Additionally, if either the source or
    destination context is bound to the current thread, a GL error is
    set to indicate the cause. This error code may be retrieved by
    calling glGetError().  If neither the source nor the destination
    context is bound in the current thread, no GL error is set.

GLX Protocol

    One new GLX protocol command is added.

    glXCopyImageSubDataNV
        1       CARD8           opcode (X assigned)
        1       16              GLX opcode (glXVendorPrivate)
        2       20              request length
        4       1360            vendor specific opcode
        4                       unused
        4       GLX_CONTEXT     src_context
        4       CARD32          src_name
        4       ENUM            src_target
        4       INT32           src_level
        4       INT32           src_x
        4       INT32           src_y
        4       INT32           src_z
        4       GLX_CONTEXT     dst_context
        4       CARD32          dst_name
        4       ENUM            dst_target
        4       INT32           dst_level
        4       INT32           dst_x
        4       INT32           dst_y
        4       INT32           dst_z
        4       INT32           width
        4       INT32           height
        4       INT32           depth

    The following rendering command is sent to the server as a part of
    glXRender request:

    CopyImageSubDataNV
        2       64              rendering command length
        2       4291            rendering command opcode
        4       CARD32          src_name
        4       ENUM            src_target
        4       INT32           src_level
        4       INT32           src_x
        4       INT32           src_y
        4       INT32           src_z
        4       CARD32          dst_name
        4       ENUM            dst_target
        4       INT32           dst_level
        4       INT32           dst_x
        4       INT32           dst_y
        4       INT32           dst_z
        4       INT32           width
        4       INT32           height
        4       INT32           depth

Dependencies on EXT_extension_name

    The list of supported image targets depends on the availability of
    such targets in the implementation.

Errors

    CopyImageSubDataNV may fail with any of the following errors:
    INVALID_ENUM is generated if either target is not RENDERBUFFER or
    a valid non-proxy texture target, or is TEXTURE_BUFFER, or is one
    of the cubemap face selectors described in table 3.23, or if the
    target does not match the type of the object.  INVALID_OPERATION
    is generated if either object is a texture and the texture is not
    consistent, or if the source and destination internal formats or
    number of samples do not match.  INVALID_VALUE is generated if
    either name does not correspond to a valid renderbuffer or texture
    object according to the corresponding target parameter, or if the
    specified level is not a valid level for the image, or if the
    dimensions of the either subregion exceeds the boundaries of the
    corresponding image object, or if the image format is compressed
    and the dimensions of the subregion fail to meet the alignment
    constraints of the format.

Sample Code

    TBD

Issues

1) Should there be a single function for all image types, or
   "per-dimensional" functions?

    Resolved.

    A single function can support all image types.  Not only are
    per-dimensional functions an unnecessary convenience, they also
    restrict some of the flexibility offered by this extension,
    e.g. copying a slice of data between a 2D and a 3D image.

2) Should the extension support "deep copies", i.e. multiple slices of
   a 3D texture, a 2D array texture, or a cubemap?

    Resolved.

    Yes, there may be performance advantages in copying a multiple
    slices in a single call.

3) Should renderbuffers be supported by the same function as textures?

    Resolved.

    Yes, there is no fundamental difference between the two object
    classes, and allowing them to be used interchangeably has the
    advantage of allowing data transfers between them.

4) Is the "target" parameter necessary?

    Resolved.

    Yes, given the current object model and texture API, there are two
    obvious applications of the target parameter:

    1) Allows the selection of a single cubemap face.
    2) Differentiate between TEXTURE and RENDERBUFFER targets.

5) Should the target TEXTURE_CUBE_MAP be supported, and with what
   behavior?

    Resolved.

    Given the resolution of issue 7, this is moot.  The
    TEXTURE_CUBE_MAP token is the only way to access a cubemap.

6) Should the "extra" parameters for a given dimension be ignored, or
   should there be required values?

    Resolved.

    All parameters are required to have sensible values, for the
    simple reason that future extensions may give meaning to these
    values.  For dimensions which are currently superfluous, the
    offset must be zero and the size must be one, e.g. if the target
    is TEXTURE_2D, z must be 0 and depth must be 1.

7) Should the per-face cubemap targets be accepted at all?  Why not
   use Z as the selector?

    Resolved.

    The existing per-face targets effectively define the face order:

       face_index = face_target - TEXTURE_CUBE_MAP_POSITIVE_X;

    Therefore it makes sense to generalize a cubemap as an array of
    size 6, and use the Z parameter to select the face(s).

8) Should the WGL/GLX functions accept a source context as well as a
   destination context?

    Resolved.

    Yes, the symmetry and flexibility this offers has advantages, and
    there is no obvious technical reason to disallow this.

Revision History

    Rev.    Date    Author    Changes
    ----  --------  --------  -----------------------------------------
     1              gold      Internal revisions.
     2    09/09/09  mjk       Assign number
     3    09/16/09  Jon Leech Fix hDstRC->hSrcRC in prototype.
     4    10/13/11  srahman   Added protocol for the GL command.
     5    08/07/12  pbrown    Fix the GLX protocol section to clarify that
                              the first set of protocol is for
                              glXCopyImageSubDataNV and not the GL command.