1Name 2 3 ANGLE_get_image 4 5Name Strings 6 7 GL_ANGLE_get_image 8 9Contributors 10 11 Jamie Madill 12 13Contact 14 15 Jamie Madill (jmadill 'at' google.com) 16 17Notice 18 19 Copyright (c) 2019 The Khronos Group Inc. Copyright terms at 20 http://www.khronos.org/registry/speccopyright.html 21 22Status 23 24 Draft 25 26Version 27 28 Version 2, Sept 15, 2021 29 30Number 31 32 OpenGL ES Extension #?? 33 34Dependencies 35 36 Requires OpenGL ES 2.0 37 38 Written against the OpenGL ES 3.2 specification. 39 40Overview 41 42 This extension allows the OpenGL application to query and read back Texture 43 and Renderbuffer pixel data. The OpenGL context exposes new queries for the 44 implementation pixel format and type similar to glReadPixels. The context 45 also exposes new commands to read back pixel data with these parameters. 46 47New Procedures and Functions 48 49 void GetTexImageANGLE(GLenum target, GLint level, GLenum format, GLenum type, 50 void *pixels); 51 52 void GetCompressedTexImageANGLE(enum target, int level, void *pixels); 53 54 void GetRenderbufferImageANGLE(GLenum target, GLint level, GLenum format, 55 GLenum type, void *pixels); 56 57New Tokens 58 59 None 60 61Additions to the OpenGL ES Specification 62 63 Update section 8.11.2 "Texture Parameter Queries": 64 65 Change "<pname> must be one of IMAGE_FORMAT_COMPATIBILITY_TYPE, TEXTURE_- 66 IMMUTABLE_FORMAT, TEXTURE_IMMUTABLE_LEVELS, or one of the symbolic 67 values in table 8.19." to "<pname> must be one of IMAGE_FORMAT_COMPATIBILITY_- 68 TYPE, TEXTURE_IMMUTABLE_FORMAT, TEXTURE_IMMUTABLE_LEVELS, IMPLEMENTATION_- 69 COLOR_READ_TYPE, IMPLEMENTATION_COLOR_READ_FORMAT or one of the symbolic 70 values in table 8.19.". 71 72 Add a paragrah: "Querying <pname> with IMPLEMENTATION_COLOR_READ_TYPE or 73 IMPLEMENTATION_COLOR_READ_FORMAT returns the implementation-dependent read 74 format and type for use with GetTexImageANGLE." 75 76 Update section 9.2.6 "Renderbuffer Object Queries": 77 78 Add a paragraph: "If <pname> is IMPLEMENTATION_COLOR_READ_TYPE or 79 IMPLEMENTATION_COLOR_READ_FORMAT then <params> will contain the 80 implementation-dependent read format and type for use with 81 GetRenderbufferImageANGLE." 82 83 Add a section "Texture and Renderbuffer Image Queries": 84 85 Texture and Renderbuffer images may be obtained from a Texture or 86 Renderbuffer with the commands 87 88 void GetTexImageANGLE(GLenum target, GLint level, GLenum format, GLenum type, 89 void *pixels); 90 91 void GetCompressedTexImageANGLE(GLenum target, GLint level, void *pixels); 92 93 void GetRenderbufferImageANGLE(GLenum target, GLenum format, GLenum type, 94 void *pixels); 95 96 For GetTexImageANGLE and GetCompressedTexImageANGLE, <target> specifies the 97 target to which the texture object is bound. target must be one of 98 TEXTURE_2D, TEXTURE_3D, TEXTURE_2D_ARRAY, TEXTURE_CUBE_MAP_ARRAY, indicating 99 a two- or three-dimensional, two-dimensional array, cube map array 100 respectively. <target> may also be one of the targets from table 8.20, 101 indicating the corresponding face of a cube map texture. 102 103 For GetRenderbufferImageANGLE, <target> must be RENDERBUFFER. 104 105 <level> is a level-of-detail number, <format> is a pixel format from table 8.5, 106 and <type> is a pixel type from table 8.4. 107 108 GetTexImageANGLE and GetRenderbufferImageANGLE obtain component groups 109 from a texture or renderbuffer image with the indicated level-of-detail. 110 If <format> is a color format then the components are assigned among R, 111 G, B, and A, starting with the first group in the first row, and 112 continuing by obtaining groups in order from each row and proceeding from 113 the first row to the last, and from the first image to the last for 114 three-dimensional textures. Two-dimensional array and cube map array 115 textures are treated as three-dimensional images, where the layers are 116 treated as rows or images. Cube map textures are treated as 117 three-dimensional images with a depth of 6, where the cube map faces are 118 ordered as image layers as shown in table 8.24. 119 120 If <format> is DEPTH_COMPONENT, DEPTH_STENCIL, or STENCIL_INDEX, then 121 each depth component and/or stencil index is assigned with the same ordering of 122 rows and images. 123 124 These groups are then packed and placed in client or pixel buffer object memory. 125 If a pixel pack buffer is bound (as indicated by a non-zero value of PIXEL_- 126 PACK_BUFFER_BINDING), <pixels> is an offset into the pixel pack buffer; 127 otherwise, <pixels> is a pointer to client memory. Pixel storage modes that are 128 applicable to ReadPixels are applied, as described in table 16.1 and section 129 16.1.2. 130 131 When called, GetCompressedTexImageANGLE writes n ubytes of compressed 132 image data to the pixel pack buffer or client memory pointed to by pixels. 133 n is the value of TEXTURE_COMPRESSED_IMAGE_SIZE for the texture image. The 134 compressed image data is formatted according to the definition of the texture's 135 internal format. 136 137 For three-dimensional, two-dimensional array, cube map array, and cube map 138 textures pixel storage operations are applied as if the image were two- 139 dimensional, except that the additional pixel storage state values 140 PACK_IMAGE_HEIGHT and PACK_SKIP_IMAGES are applied. The correspondence of texels 141 to memory locations is as defined for TexImage3D in section 8.5. 142 143 The row length, number of rows, image depth, and number of images are determined 144 by the size of the texture or renderbuffer image (including any borders). 145 146 Errors: 147 148 An INVALID_ENUM error is generated by GetTexImage if <target> is 149 not one of TEXTURE_2D, TEXTURE_3D, TEXTURE_2D_ARRAY, TEXTURE_CUBE_MAP_ARRAY, 150 or one of the targets from table 8.20. 151 152 An INVALID_ENUM error is generated by GetRenderbufferImage is <target> is not 153 RENDERBUFFER. 154 155 An INVALID_VALUE error is generated if <level> is negative or larger than 156 the maximum allowable level. 157 158 An INVALID_OPERATION error is generated if any of the following mismatches 159 between <format> and the internal format of the texture or renderbuffer image 160 exist: 161 162 * <format> is a color format (one of the formats in table 8.3 whose target is 163 the color buffer) and the base internal format of the texture or renderbuffer 164 image is not a color format. 165 166 * <format> is DEPTH_COMPONENT and the base internal format is not 167 DEPTH_COMPONENT or DEPTH_STENCIL. 168 169 * <format> is DEPTH_STENCIL and the base internal format is not DEPTH_- 170 STENCIL. 171 172 * <format> is STENCIL_INDEX and the base internal format is not 173 STENCIL_INDEX or DEPTH_STENCIL. 174 175 * <format> is one of the integer formats in table 8.5 and the internal format 176 of the texture or renderbuffer image is not integer, or <format> is not one 177 of the integer formats in table 8.5 and the internal format is integer. 178 179 An INVALID_OPERATION error is generated if a pixel pack buffer object 180 is bound and packing the texture or renderbuffer image into the buffer’s 181 memory would exceed the size of the buffer. 182 183 An INVALID_OPERATION error is generated if a pixel pack buffer object 184 is bound and <pixels> is not evenly divisible by the number of basic machine 185 units needed to store in memory the GL data type corresponding to type (see 186 table 8.4). 187 188 An INVALID_OPERATION error is generated by GetCompressedTexImageANGLE if the 189 texture image is stored with an uncompressed internal format. 190 191Dependencies on ARB_texture_rectangle 192 193 TEXTURE_RECTANGLE is accepted by GetTexImageANGLE and GetRenderbufferImageANGLE. 194 195 An INVALID_VALUE error is generated if <level> is non-zero and the effective 196 <target> is TEXTURE_RECTANGLE. 197 198New State 199 200 Add to table 21.10 "Textures (state per texture object)": 201 202 Get Value Type Get Command Initial Value Description Section 203 -------------------------------- ---- ----------- ------------- --------------------------- ------- 204 IMPLEMENTATION_COLOR_READ_FORMAT E GetTextureParameteriv empty Implementation pixel format 8.11.2 205 IMPLEMENTATION_COLOR_READ_TYPE E GetTextureParameteriv empty Implementation pixel type 8.11.2 206 207 Add to table 21.17 "Renderbuffer (state per renderbuffer object)": 208 209 Get Value Type Get Command Initial Value Description Section 210 -------------------------------- ---- ----------- ------------- --------------------------- ------- 211 IMPLEMENTATION_COLOR_READ_FORMAT E GetRenderbufferParameteriv empty Implementation pixel format 9.2.6 212 IMPLEMENTATION_COLOR_READ_TYPE E GetRenderbufferParameteriv empty Implementation pixel type 9.2.6 213 214Issues 215 216 1) Should GetTexImageANGLE/GetRenderbufferImageANGLE only accept IMPLEMENTATION- 217 _COLOR_READ_FORMAT/TYPE or should they behave the same as GetTexImage in GL? 218 219 Resolved: Keep the spec wording closer to the desktop GL version. It should 220 not involve much additional implementation work except for validation. 221 222Revision History 223 224 Rev. Date Author Changes 225 ---- ------------- --------- ---------------------------------------- 226 2 Sept 15, 2021 jmadill Add GetCompressedTexImageANGLE 227 1 Oct 24, 2019 jmadill Initial version 228