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 1, October 21, 2019 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 GetRenderbufferImageANGLE(GLenum target, GLint level, GLenum format, 53 GLenum type, void *pixels); 54 55New Tokens 56 57 None 58 59Additions to the OpenGL ES Specification 60 61 Update section 8.11.2 "Texture Parameter Queries": 62 63 Change "<pname> must be one of IMAGE_FORMAT_COMPATIBILITY_TYPE, TEXTURE_- 64 IMMUTABLE_FORMAT, TEXTURE_IMMUTABLE_LEVELS, or one of the symbolic 65 values in table 8.19." to "<pname> must be one of IMAGE_FORMAT_COMPATIBILITY_- 66 TYPE, TEXTURE_IMMUTABLE_FORMAT, TEXTURE_IMMUTABLE_LEVELS, IMPLEMENTATION_- 67 COLOR_READ_TYPE, IMPLEMENTATION_COLOR_READ_FORMAT or one of the symbolic 68 values in table 8.19.". 69 70 Add a paragrah: "Querying <pname> with IMPLEMENTATION_COLOR_READ_TYPE or 71 IMPLEMENTATION_COLOR_READ_FORMAT returns the implementation-dependent read 72 format and type for use with GetTexImageANGLE." 73 74 Update section 9.2.6 "Renderbuffer Object Queries": 75 76 Add a paragraph: "If <pname> is IMPLEMENTATION_COLOR_READ_TYPE or 77 IMPLEMENTATION_COLOR_READ_FORMAT then <params> will contain the 78 implementation-dependent read format and type for use with 79 GetRenderbufferImageANGLE." 80 81 Add a section "Texture and Renderbuffer Image Queries": 82 83 Texture and Renderbuffer images may be obtained from a Texture or 84 Renderbuffer with the commands 85 86 void GetTexImageANGLE(GLenum target, GLint level, GLenum format, GLenum type, 87 void *pixels); 88 89 void GetRenderbufferImageANGLE(GLenum target, GLenum format, GLenum type, 90 void *pixels); 91 92 For GetTexImageANGLE, <target> specifies the target to which the texture 93 object is bound. target must be one of TEXTURE_2D, TEXTURE_3D, 94 TEXTURE_2D_ARRAY, TEXTURE_CUBE_MAP_ARRAY, indicating a two- or three- 95 dimensional, two-dimensional array, cube map array respectively. <target> 96 may also be one of the targets from table 8.20, indicating the 97 corresponding face of a cube map texture. 98 99 For GetRenderbufferImageANGLE, <target> must be RENDERBUFFER. 100 101 <level> is a level-of-detail number, <format> is a pixel format from table 8.5, 102 and <type> is a pixel type from table 8.4. 103 104 These commands obtain component groups from a texture or renderbuffer image 105 with the indicated level-of-detail. If <format> is a color format then the 106 components are assigned among R, G, B, and A, starting with the first group 107 in the first row, and continuing by obtaining groups in order from each row 108 and proceeding from the first row to the last, and from the first image to 109 the last for three-dimensional textures. Two-dimensional array and cube map 110 array textures are treated as three-dimensional images, where the layers are 111 treated as rows or images. Cube map textures are treated as three-dimensional 112 images with a depth of 6, where the cube map faces are ordered as image layers 113 as shown in table 8.24. 114 115 If <format> is DEPTH_COMPONENT, DEPTH_STENCIL, or STENCIL_INDEX, then 116 each depth component and/or stencil index is assigned with the same ordering of 117 rows and images. 118 119 These groups are then packed and placed in client or pixel buffer object memory. 120 If a pixel pack buffer is bound (as indicated by a non-zero value of PIXEL_- 121 PACK_BUFFER_BINDING), <pixels> is an offset into the pixel pack buffer; 122 otherwise, <pixels> is a pointer to client memory. Pixel storage modes that are 123 applicable to ReadPixels are applied, as described in table 16.1 and section 124 16.1.2. 125 126 For three-dimensional, two-dimensional array, cube map array, and cube map 127 textures pixel storage operations are applied as if the image were two- 128 dimensional, except that the additional pixel storage state values 129 PACK_IMAGE_HEIGHT and PACK_SKIP_IMAGES are applied. The correspondence of texels 130 to memory locations is as defined for TexImage3D in section 8.5. 131 132 The row length, number of rows, image depth, and number of images are determined 133 by the size of the texture or renderbuffer image (including any borders). 134 135 Errors: 136 137 An INVALID_ENUM error is generated by GetTexImage if <target> is 138 not one of TEXTURE_2D, TEXTURE_3D, TEXTURE_2D_ARRAY, TEXTURE_CUBE_MAP_ARRAY, 139 or one of the targets from table 8.20. 140 141 An INVALID_ENUM error is generated by GetRenderbufferImage is <target> is not 142 RENDERBUFFER. 143 144 An INVALID_VALUE error is generated if <level> is negative or larger than 145 the maximum allowable level. 146 147 An INVALID_OPERATION error is generated if any of the following mismatches 148 between <format> and the internal format of the texture or renderbuffer image 149 exist: 150 151 * <format> is a color format (one of the formats in table 8.3 whose target is 152 the color buffer) and the base internal format of the texture or renderbuffer 153 image is not a color format. 154 155 * <format> is DEPTH_COMPONENT and the base internal format is not 156 DEPTH_COMPONENT or DEPTH_STENCIL. 157 158 * <format> is DEPTH_STENCIL and the base internal format is not DEPTH_- 159 STENCIL. 160 161 * <format> is STENCIL_INDEX and the base internal format is not 162 STENCIL_INDEX or DEPTH_STENCIL. 163 164 * <format> is one of the integer formats in table 8.5 and the internal format 165 of the texture or renderbuffer image is not integer, or <format> is not one 166 of the integer formats in table 8.5 and the internal format is integer. 167 168 An INVALID_OPERATION error is generated if a pixel pack buffer object 169 is bound and packing the texture or renderbuffer image into the buffer’s 170 memory would exceed the size of the buffer. 171 172 An INVALID_OPERATION error is generated if a pixel pack buffer object 173 is bound and <pixels> is not evenly divisible by the number of basic machine 174 units needed to store in memory the GL data type corresponding to type (see 175 table 8.4). 176 177Dependencies on ARB_texture_rectangle 178 179 TEXTURE_RECTANGLE is accepted by GetTexImageANGLE and GetRenderbufferImageANGLE. 180 181 An INVALID_VALUE error is generated if <level> is non-zero and the effective 182 <target> is TEXTURE_RECTANGLE. 183 184New State 185 186 Add to table 21.10 "Textures (state per texture object)": 187 188 Get Value Type Get Command Initial Value Description Section 189 -------------------------------- ---- ----------- ------------- --------------------------- ------- 190 IMPLEMENTATION_COLOR_READ_FORMAT E GetTextureParameteriv empty Implementation pixel format 8.11.2 191 IMPLEMENTATION_COLOR_READ_TYPE E GetTextureParameteriv empty Implementation pixel type 8.11.2 192 193 Add to table 21.17 "Renderbuffer (state per renderbuffer object)": 194 195 Get Value Type Get Command Initial Value Description Section 196 -------------------------------- ---- ----------- ------------- --------------------------- ------- 197 IMPLEMENTATION_COLOR_READ_FORMAT E GetRenderbufferParameteriv empty Implementation pixel format 9.2.6 198 IMPLEMENTATION_COLOR_READ_TYPE E GetRenderbufferParameteriv empty Implementation pixel type 9.2.6 199 200Issues 201 202 1) Should GetTexImageANGLE/GetRenderbufferImageANGLE only accept IMPLEMENTATION- 203 _COLOR_READ_FORMAT/TYPE or should they behave the same as GetTexImage in GL? 204 205 Resolved: Keep the spec wording closer to the desktop GL version. It should 206 not involve much additional implementation work except for validation. 207 208Revision History 209 210 Rev. Date Author Changes 211 ---- ------------- --------- ---------------------------------------- 212 1 Oct 24, 2019 jmadill Initial version 213