1Name 2 3 EXT_surface_compression 4 5Name Strings 6 7 EGL_EXT_surface_compression 8 9Contributors 10 11 Jan-Harald Fredriksen, Arm 12 Lisa Wu, Arm 13 George Liu, Arm 14 Laurie Hedge, Imagination Technologies 15 16Contact 17 18 Jan-Harald Fredriksen (jan-harald.fredriksen 'at' arm.com) 19 20IP Status 21 22 No known IP claims. 23 24Status 25 26 Complete 27 28Version 29 30 Version 1 - November 15, 2021 31 32Number 33 34 EGL Extension #147 35 36Dependencies 37 38 These extensions are written against the wording of the EGL 1.5 39 specification (August 27, 2014). 40 41 This extension interacts with EGL_EXT_yuv_surface. 42 43Overview 44 45 Applications may wish to take advantage of framebuffer compression. Some 46 platforms may support framebuffer compression at fixed bitrates. Such 47 compression algorithms generally produce results that are visually lossless, 48 but the results are typically not bit exact when compared to a non-compressed 49 result. 50 51 This extension enables applications to opt-in to fixed-rate compression 52 for EGL window surfaces. 53 54 Compression may not be supported for all framebuffer formats. It can still 55 be requested for all formats and applications can query what level of compression 56 was actually enabled. 57 58New Procedures and Functions 59 60 EGLBoolean eglQuerySupportedCompressionRatesEXT( 61 EGLDisplay dpy, EGLConfig config, const EGLAttrib *attrib_list, 62 EGLint *rates, EGLint rate_size, EGLint *num_rates); 63 64New Tokens 65 66 New attributes accepted by the <attrib_list> argument of 67 eglCreatePlatformWindowSurface and eglCreateWindowSurface: 68 EGL_SURFACE_COMPRESSION_EXT 0x34B0 69 70 [Only if EGL_EXT_yuv_surface is supported] 71 EGL_SURFACE_COMPRESSION_PLANE1_EXT 0x328E 72 EGL_SURFACE_COMPRESSION_PLANE2_EXT 0x328F 73 74 Accepted as attribute values for EGL_SURFACE_COMPRESSION_EXT by 75 eglCreatePlatformWindowSurface and eglCreateWindowSurface: 76 EGL_SURFACE_COMPRESSION_FIXED_RATE_NONE_EXT 0x34B1 77 EGL_SURFACE_COMPRESSION_FIXED_RATE_DEFAULT_EXT 0x34B2 78 79 EGL_SURFACE_COMPRESSION_FIXED_RATE_1BPC_EXT 0x34B4 80 EGL_SURFACE_COMPRESSION_FIXED_RATE_2BPC_EXT 0x34B5 81 EGL_SURFACE_COMPRESSION_FIXED_RATE_3BPC_EXT 0x34B6 82 EGL_SURFACE_COMPRESSION_FIXED_RATE_4BPC_EXT 0x34B7 83 EGL_SURFACE_COMPRESSION_FIXED_RATE_5BPC_EXT 0x34B8 84 EGL_SURFACE_COMPRESSION_FIXED_RATE_6BPC_EXT 0x34B9 85 EGL_SURFACE_COMPRESSION_FIXED_RATE_7BPC_EXT 0x34BA 86 EGL_SURFACE_COMPRESSION_FIXED_RATE_8BPC_EXT 0x34BB 87 EGL_SURFACE_COMPRESSION_FIXED_RATE_9BPC_EXT 0x34BC 88 EGL_SURFACE_COMPRESSION_FIXED_RATE_10BPC_EXT 0x34BD 89 EGL_SURFACE_COMPRESSION_FIXED_RATE_11BPC_EXT 0x34BE 90 EGL_SURFACE_COMPRESSION_FIXED_RATE_12BPC_EXT 0x34BF 91 92Modifications to the EGL 1.5 Specification 93 94 Modify section 3.5.1 "Creating On-Screen Rendering Surfaces: 95 96 Add EGL_SURFACE_COMPRESSION_EXT to the list of attributes that can 97 be specified in <attrib_list> for eglCreatePlatformWindowSurface. 98 99 Add the following paragraph: 100 101 EGL_SURFACE_COMPRESSION_EXT specifies the fixed-rate compression that may 102 be enabled for rendering to the window. 103 If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_NONE_EXT, then fixed-rate 104 compression is disabled. 105 If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_DEFAULT_EXT, 106 then the implementation may enable compression at a default, 107 implementation-defined, rate. 108 If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_1BPC_EXT, then the 109 implementation may enable fixed-rate compression with a bitrate of at 110 least 1 bit and less than 2 bits per component. 111 If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_2BPC_EXT, then the 112 implementation may enable fixed-rate compression with a bitrate of at 113 least 2 bits and less than 3 bits per component. 114 If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_3BPC_EXT, then the 115 implementation may enable fixed-rate compression with a bitrate of at 116 least 3 bits and less than 4 bits per component. 117 If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_4BPC_EXT, then the 118 implementation may enable fixed-rate compression with a bitrate of at 119 least 4 bits and less than 5 bits per component. 120 If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_5BPC_EXT, then the 121 implementation may enable fixed-rate compression with a bitrate of at 122 least 5 bits and less than 6 bits per component. 123 If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_6BPC_EXT, then the 124 implementation may enable fixed-rate compression with a bitrate of at 125 least 6 bits and less than 7 bits per component. 126 If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_7BPC_EXT, then the 127 implementation may enable fixed-rate compression with a bitrate of at 128 least 7 bits and less than 8 bits per component. 129 If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_8BPC_EXT, then the 130 implementation may enable fixed-rate compression with a bitrate of at 131 least 8 bits and less than 9 bits per component. 132 If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_9BPC_EXT, then the 133 implementation may enable fixed-rate compression with a bitrate of at 134 least 9 bits and less than 10 bits per component. 135 If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_10BPC_EXT, then the 136 implementation may enable fixed-rate compression with a bitrate of at 137 least 10 bits and less than 11 bits per component. 138 If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_11BPC_EXT, then the 139 implementation may enable fixed-rate compression with a bitrate of at 140 least 11 bits and less than 12 bits per component. 141 If its value is EGL_SURFACE_COMPRESSION_FIXED_RATE_12BPC_EXT, then the 142 implementation may enable fixed-rate compression with a bitrate of at 143 least 12 bits per component. 144 145 For pixel formats with different number of bits per component, the 146 specified fixed-rate compression rate applies to the component with 147 the highest number of bits. 148 149 The default value of EGL_SURFACE_COMPRESSION_EXT is 150 EGL_SURFACE_COMPRESSION_FIXED_RATE_NONE_EXT. 151 152 [Only if EGL_EXT_yuv_surface is supported] 153 154 If _config_ describes a surface with multiple planes (the 155 value of the EGL_YUV_NUMBER_OF_PLANES_EXT attribute is larger than one), 156 then the fixed-rate compression rate can be specified independently for 157 the each plane. 158 In this case, EGL_SURFACE_COMPRESSION_EXT specifies the fixed-rate 159 compression that may be enabled for rendering to plane 0, 160 EGL_SURFACE_COMPRESSION_PLANE1_EXT specifies the fixed-rate 161 compression that may be enabled for rendering to plane 1, and 162 EGL_SURFACE_COMPRESSION_PLANE2_EXT specifies the fixed-rate compression 163 that may be enabled for rendering to plane 2. 164 The supported values of EGL_SURFACE_COMPRESSION_PLANE1_EXT and 165 EGL_SURFACE_COMPRESSION_PLANE2_EXT are the same as for 166 EGL_SURFACE_COMPRESSION_EXT. 167 168 If _config_ has more than one plane and the 169 EGL_SURFACE_COMPRESSION_PLANE1_EXT attribute is not specified, 170 then the value of EGL_SURFACE_COMPRESSION_EXT is used for all planes. 171 If _config_ has more than two planes and the 172 EGL_SURFACE_COMPRESSION_PLANE2_EXT attribute is not specified, 173 then the value of EGL_SURFACE_COMPRESSION_PLANE1_EXT is also used 174 for plane 2. 175 176 The default value of EGL_SURFACE_COMPRESSION_PLANE1_EXT and 177 EGL_SURFACE_COMPRESSION_PLANE2_EXT is EGL_SURFACE_COMPRESSION_FIXED_RATE_NONE_EXT. 178 179 Modify section 3.5.6 "Surface Attributes" 180 181 Add entries to Table 3.5 "Queryable surface attributes and types": 182 183 EGL_SURFACE_COMPRESSION_EXT enum Fixed-rate compression 184 185 [Only if EGL_EXT_yuv_surface is supported] 186 EGL_SURFACE_COMPRESSION_PLANE1_EXT enum Fixed-rate compression for plane 1 187 EGL_SURFACE_COMPRESSION_PLANE2_EXT enum Fixed-rate compression for plane 2 188 189 Add the following paragraph: 190 191 Querying EGL_SURFACE_COMPRESSION_EXT returns the actual fixed-rate 192 compression applied to a surface. For YUV surfaces, the value applied to 193 the luma plane is returned. This value may be different to the one 194 requested when the surface was created. 195 For pbuffer and pixmap surfaces, the contents of <value> are not modified." 196 197 [Only if EGL_EXT_yuv_surface is supported] 198 Querying EGL_SURFACE_COMPRESSION_PLANE1_EXT returns the actual 199 fixed-rate compression applied to plane 1 of a YUV surface. 200 Querying EGL_SURFACE_COMPRESSION_PLANE2_EXT returns the actual 201 fixed-rate compression applied to plane 2 of a YUV surface. 202 These values may be different to the one requested when the surface was created. 203 For pbuffer and pixmap surfaces, the contents of <value> are not modified." 204 205 To get the list of all fixed-rate compression rates that are available on 206 a specified display and EGLConfig, call 207 208 EGLBoolean eglQuerySupportedCompressionRatesEXT( 209 EGLDisplay dpy, EGLConfig config, const EGLAttrib *attrib_list, 210 EGLint *rates, EGLint rate_size, EGLint *num_rates); 211 212 <attrib_list> specifies a list of attributes that will be provided when a surface is created with 213 this combination of display and EGLConfig. The accepted attributes are the same as for 214 eglCreatePlatformWindowSurface. 215 <rates> is a pointer to a buffer containing <rate_size> elements. On success, EGL_TRUE is 216 returned. The number of rates is returned in <num_rates>, and elements 0 through <num_rates>-1 of 217 <rates> are filled in with the available compression rates. 218 No more than <rate_size> compression rates will be returned even if more are available 219 on the specified display and config. However, if eglQuerySupportedCompressionRatesEXT is called with 220 <rates> = NULL, then no rates are returned, but the total number of rates available will be returned 221 in <num_rates>. 222 The possible values returned in <rates> are the attribute values accepted for 223 EGL_SURFACE_COMPRESSION_EXT by eglCreatePlatformWindowSurface and eglCreateWindowSurface, except 224 EGL_SURFACE_COMPRESSION_FIXED_RATE_NONE_EXT and EGL_SURFACE_COMPRESSION_FIXED_RATE_DEFAULT_EXT. 225 226Errors 227 228 [Only if EGL_EXT_yuv_surface is supported] 229 Add to the error section of eglCreatePlatformWindowSurface: 230 231 If the EGL_SURFACE_COMPRESSION_PLANE1_EXT attribute is specified and 232 _config_ does not describe a surface with at least 2 planes (the 233 EGL_YUV_NUMBER_OF_PLANES_EXT attribute is not greater than or 234 equal to 2), an EGL_BAD_MATCH error is generated. 235 236 If the EGL_SURFACE_COMPRESSION_PLANE2_EXT attribute is specified and 237 _config_ does not describe a surface with at least 3 planes (the 238 EGL_YUV_NUMBER_OF_PLANES_EXT attribute is not greater than or 239 equal to 3), an EGL_BAD_MATCH error is generated. 240 241 Add to the section describing eglQuerySupportedCompressionRatesEXT: 242 243 * On failure, EGL_FALSE is returned. 244 * An EGL_NOT_INITIALIZED error is generated if EGL is not initialized on <dpy>. 245 * An EGL_BAD_PARAMETER error is generated if <num_rates> is NULL. 246 247Issues 248 249 1. Should fixed-rate compression be supported for pixmap or pbuffer 250 surfaces? 251 252 No, no use-cases have been identified for this. 253 254 2. What is the result of querying EGL_SURFACE_COMPRESSION_EXT if 255 EGL_SURFACE_COMPRESSION_FIXED_RATE_DEFAULT_EXT was requested? 256 257 Resolved. 258 The result will be the specific compression ratio chosen by the 259 implementation, or EGL_SURFACE_COMPRESSION_FIXED_RATE_NONE_EXT if 260 no fixed-rate compression was applied. 261 262 3. Should we expose different compressions rates per plane in this extension? 263 264 Yes. 265 266 4. How can an application query the set of supported compression rates? 267 268 Resolved. Option B. 269 270 Two options were considered. 271 272 Option A: 273 Reuse eglGetConfigAttrib(EGLDisplay dpy, EGLConfig config, EGLint attribute, EGLint *value); 274 275 This is not ideal because: 276 - the compression modes are currently tied to the surface, not the EGLConfig 277 - we don't want this to affect EGLConfig selection etc. 278 - this query can only return a single value, so you'd need to query each of the 279 12 bit rates separately. 280 281 Option B: 282 Add a new query, specifically for the compression rates. This addresses the concerns 283 with Option A, and is very similar to the mechanism used for the OpenGL ES API. Main 284 downside is that it adds additional functions to the API. 285 286Revision History 287 288 Version 1, 2021/11/15 289 - Internal revisions 290