NV_copy_image
GL_NV_copy_image
WGL_NV_copy_image
GLX_NV_copy_image
Michael Gold, NVIDIA Corporation (gold 'at' nvidia.com)
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)
Shipping (July 2009, Release 190)
Last Modified Date: 07/29/2009
NVIDIA revision: 1
TBD
OpenGL 1.1 is required.
The extension is written against the OpenGL 3.1 Specification.
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);
| 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 hDstRC, 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.
One new GLX protocol command is added.
CopyImageSubDataNV
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
| Dependencies on EXT_extension_name |
The list of supported image targets depends on the availability of
such targets in the implementation.
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
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.
Rev. Date Author Changes
---- -------- -------- -----------------------------------------
1 gold Internal revisions.
1 gold Internal revisions.
 |  | Last update: November 14, 2006.
Cette page doit être lue avec un navigateur récent respectant le standard XHTML 1.1.
|
