Name ARB_get_texture_sub_image Name Strings GL_ARB_get_texture_sub_image Contact Brian Paul, VMware Inc. (brianp 'at' vmware.com) Contributors Brian Paul Daniel Koch, NVIDIA Notice Copyright (c) 2014 The Khronos Group Inc. Copyright terms at http://www.khronos.org/registry/speccopyright.html Specification Update Policy Khronos-approved extension specifications are updated in response to issues and bugs prioritized by the Khronos OpenGL Working Group. For extensions which have been promoted to a core Specification, fixes will first appear in the latest version of that core Specification, and will eventually be backported to the extension document. This policy is described in more detail at https://www.khronos.org/registry/OpenGL/docs/update_policy.php Status Complete. Approved by the ARB on June 26, 2014. Ratified by the Khronos Board of Promoters on August 7, 2014. Version Date: June 16, 2014 Revision: 7 Number ARB Extension #165 Dependencies OpenGL 2.0 is required The extension is written against the OpenGL 4.4 Specification, Core Profile, March 19, 2014. Overview This extension adds a new function to get sub-regions of texture images. IP Status No known IP claims. New Procedures and Functions void GetTextureSubImage(uint texture, int level, int xoffset, int yoffset, int zoffset, sizei width, sizei height, sizei depth, enum format, enum type, sizei bufSize, void *pixels); void GetCompressedTextureSubImage(uint texture, int level, int xoffset, int yoffset, int zoffset, sizei width, sizei height, sizei depth, sizei bufSize, void *pixels); New Types None New Tokens None Additions to Chapter 8 of the OpenGL 4.4 (Core Profile) Specification (Textures and Samplers) Modify section 8.11.4, Texture Image Queries p. 224 (insert before the discussion of GetCompressedTexImage) Sub-regions of a texture image may be obtained from a texture object with the command void GetTextureSubImage(uint texture, int level, int xoffset, int yoffset, int zoffset, sizei width, sizei height, sizei depth, enum format, enum type, sizei bufSize, void *pixels); is the name of the source texture object. and must not be a buffer or multisample texture. The effective parameter is the value of TEXTURE_TARGET for texture. , , and have the same meaning as for GetTexImage. is the size of the buffer to receive the retrieved pixel data. For cube map textures, the behavior is as though GetTextureImage were called, but only texels from the requested cube map faces (selected by and , as described below) were returned. , and values indicate the position of the subregion to return. , and indicate the size of the region to return. These parameters have the same meaning as for TexSubImage3D, though for one- and two-dimensional textures there are extra restrictions, described in the errors section below). For one-dimensional array textures, is interpreted as the first layer to access and is the number of layers to access. For two-dimensional array textures, is interpreted as the first layer to access and is the number of layers to access. Cube map textures are treated as an array of six slices in the z-dimension, where the value of is interpreted as specifying the cube map face for the corresponding layer in table 9.2 and is the number of faces to access. For cube map array textures, is the first layer-face to access, and is the number of layer- faces to access. Each layer-face is translated into an array layer and a cube map face as described for layer-face numbers in section 8.5.3. Component groups from the specified sub-region are packed and placed into memory as described for GetTextureImage, starting with the texel at (, , ). Errors An INVALID_OPERATION error is generated if is not the name of an existing texture object. An INVALID_OPERATION error is generated if is the name of a buffer or multisample texture. An INVALID_VALUE error is generated if , or are negative. An INVALID_VALUE error is generated by if + is greater than the texture level's width or if + is greater than the texture level's height or if + is greater than the texture level's depth. An INVALID_VALUE error is generated if the effective is TEXTURE_1D and either is not zero, or is not one. An INVALID_VALUE error is generated if the effective is TEXTURE_1D, TEXTURE_1D_ARRAY, TEXTURE_2D, or TEXTURE_RECTANGLE and either is not zero, or is not one. An INVALID_OPERATION error is generated if the buffer size required to store the requested data is greater than . (insert after the discussion of GetCompressedTexSubImage and before section 8.12 begins) If the compressed data are arranged into fixed-size blocks of texels, the command void GetCompressedTextureSubImage(uint texture, int level, int xoffset, int yoffset, int zoffset, sizei width, sizei height, sizei depth, sizei bufSize, void *pixels); can be used to obtain a sub-region of a compressed texture image instead of the whole image. is the name of the source texture object, and must not be a buffer or multisample texture. The effective is the value of TEXTURE_TARGET for . and have the same meaning as the corresponding arguments CompressedTexSubImage3D. indicates the size of the buffer to receive the retrieved pixel data. For cube map textures, the behavior is as though GetCompressedTexImage were called once for each requested face (selected by and , as described below) with corresponding to the requested texture cube map face as indicated by Table 9.2. is offset appropriately for each successive image. , and indicate the position of the subregion to return. , and indicate the size of the region to return. These arguments have the same meaning as for CompressedTexSubImage3D, though there are extra restrictions, described in the errors section below. The mapping between the , , , , , and parameters and the faces, layers, and layer-faces for cube map, array, and cube map array textures is the same as for GetTextureSubImage. The , , , , and values and must be multiples of the values of PACK_COMPRESSED_BLOCK_WIDTH, PACK_COMPRESSED_BLOCK_HEIGHT, and PACK_COMPRESSED_BLOCK_DEPTH respectively, unless the offset is zero and the corresponding size is the same as the texture size in that dimension. Pixel storage modes are treated as for GetCompressedTexSubImage. The texel at (, , ) will be stored at the location indicated by and the current pixel packing parameters. Errors In addition to the same errors generated by GetTextureSubImage with corresponding parameters: An INVALID_VALUE error is generated if , or is not a multiple of the compressed block width, height or depth. An INVALID_VALUE error is generated if , or is not a multiple of the compressed block width, height or depth respectively, unless the offset is zero and the size equals the texture image size. Additions to the AGL/EGL/GLX/WGL Specifications None Dependencies on GL and ES profiles, versions, and other extensions If texture arrays are not supported, ignore references to 1D and 2D-array textures If cube map textures are not supported, ignore references to cube map textures. If cube map arrays texture are not supported, ignore references to cube map array textures. If texture rectangles are not supported, ignore references to rectangle textures. If texture compression is not supported, ignore references to GetCompressedTexSubImage. Dependencies on ARB_direct_state_access If ARB_direct_state_access is not supported, the TEXTURE_TARGET is the that was initially bound with. New State None. New Implementation Dependent State None. Conformance Testing 1) For each type of texture, create a test texture. Read back the whole texture into a buffer with glGet[Compressed]TexImage. Then read back the whole texture into a second buffer, but in sub-image pieces (ex: 4x4 grid). Then compare the two result buffers - they should be identical. Issues 1) Why is this extension necessary? RESOLVED: In some cases one can wrap a texture with an FBO and read back sub-regions with glReadPixels. However, that doesn't work for all texture formats (esp. compressed textures). For some textures such as 2D array textures there's no way to obtain just one slice of a texture. It's very inefficient to get the whole texture when just one slice is needed. An alternate approach to the problem of reading back sub textures is with an extension such as GL_INTEL_map_texture. However, mapping textures involves several difficult issues. Extending glGetTexImage to handle sub-regions is much simpler. 2) What is the behavior of these commands if is exceeded when a pixel pack buffer object is bound? DISCUSSION: When client memory is being used, INVALID_OPERATION is generated if writing more than bytes is necessary to return all the requested data. Similarly, when a PBO is bound, INVALID_OPERATION is generated if more than bytes are required. Note that it can also be an error if *less* than bytes would be required when using a PBO if the space between the offset indicated by and the end of the buffer is insufficient for the requested data. This behavior is inherited from GetTexImage and GetCompressedTexImage. 3) Is the parameter needed? RESOLVED. No. The target is determined by the texture type. For cube map textures the face target is determined by the and parameters by mapping layer numbers to cube map texture faces as per Table 9.2. This is consisten with the DSA variants of GetTextureImage in ARB_direct_state_access which do not include it. Revision History Revision 1, 2014/02/03 - Initial revision Revision 2, 2014/04/10 - Converted GetTexSubImage and GetTexCompressedSubImage to DSA (Direct State Access) style. - Added bufSize parameter, per GL_ARB_robustness convention. Revision 3, 2014/05/26 - dkoch - convert to ARB extension - make function naming and parameter lists consistent - describe the parameter (issue 2). - remove the parameter (issue 3) and fallout. - better describe valid texture types and parameter meanings for the various texture types. Revision 4, 2014/05/30 - dkoch - describe implied parameter for cube map textures - fix remove incorrect language (Bug 12321) - Add additional error language - improve issues 2 and 3 Revision 5, 2014/06/03 - Jon Leech - Use 'pixels' instead of 'img' as formal parameter name for consistency with API spec / dsa. Revision 6, 2014/06/12 - Jon Leech - Sync with core API spec language and errors. Revision 6, 2014/06/16 - Jon Leech - Require GetTextureSubImage for cube map textures to respect the three-dimensional pixel pack state, by referring to GetTextureImage language (Bug 12329).