1Name 2 3 MESA_query_renderer 4 5Name Strings 6 7 GLX_MESA_query_renderer 8 9Contact 10 11 Ian Romanick <ian.d.romanick@intel.com> 12 13IP Status 14 15 No known IP claims. 16 17Status 18 19 Shipping as of Mesa 10.0 20 21Version 22 23 Version 9, 09 November 2018 24 25Number 26 27 OpenGL Extension #446 28 29Dependencies 30 31 GLX 1.4 is required. 32 33 GLX_ARB_create_context and GLX_ARB_create_context_profile are required. 34 35Overview 36 37 In many situations, applications want to detect characteristics of a 38 rendering device before creating a context for that device. Information 39 gathered at this stage may guide choices the application makes about 40 color depth, number of samples per-pixel, texture quality, and so on. 41 In addition, versions of supported APIs and implementation API 42 preference may also guide start-up decisions made by the application. 43 For example, one implementation may prefer vertex data be supplied using 44 methods only available in a compatibility profile, but another 45 implementation may only support the desired version in a core profile. 46 47 There are also cases where more than one renderer may be available per 48 display. For example, there is typically a hardware implementation and 49 a software based implementation. There are cases where an application 50 may want to pick one over the other. One such situation is when the 51 software implementation supports more features than the hardware 52 implementation. Another situation is when a particular version of the 53 hardware implementation is blacklisted due to known bugs. 54 55 This extension provides a mechanism for the application to query all of 56 the available renderers for a particular display and screen. In 57 addition, this extension provides a mechanism for applications to create 58 contexts with respect to a specific renderer. 59 60New Procedures and Functions 61 62 Bool glXQueryRendererIntegerMESA(Display *dpy, int screen, 63 int renderer, int attribute, 64 unsigned int *value); 65 Bool glXQueryCurrentRendererIntegerMESA(int attribute, unsigned int *value); 66 67 const char *glXQueryRendererStringMESA(Display *dpy, int screen, 68 int renderer, int attribute); 69 70 const char *glXQueryCurrentRendererStringMESA(int attribute); 71 72New Tokens 73 74 Accepted as an <attribute> in glXQueryRendererIntegerMESA and 75 glXQueryCurrentRendererIntegerMESA: 76 77 GLX_RENDERER_VENDOR_ID_MESA 0x8183 78 GLX_RENDERER_DEVICE_ID_MESA 0x8184 79 GLX_RENDERER_VERSION_MESA 0x8185 80 GLX_RENDERER_ACCELERATED_MESA 0x8186 81 GLX_RENDERER_VIDEO_MEMORY_MESA 0x8187 82 GLX_RENDERER_UNIFIED_MEMORY_ARCHITECTURE_MESA 0x8188 83 GLX_RENDERER_PREFERRED_PROFILE_MESA 0x8189 84 GLX_RENDERER_OPENGL_CORE_PROFILE_VERSION_MESA 0x818A 85 GLX_RENDERER_OPENGL_COMPATIBILITY_PROFILE_VERSION_MESA 0x818B 86 GLX_RENDERER_OPENGL_ES_PROFILE_VERSION_MESA 0x818C 87 GLX_RENDERER_OPENGL_ES2_PROFILE_VERSION_MESA 0x818D 88 89 Accepted as an <attribute> in glXQueryRendererStringMESA and 90 glXQueryCurrentRendererStringMESA: 91 92 GLX_RENDERER_VENDOR_ID_MESA 93 GLX_RENDERER_DEVICE_ID_MESA 94 95Additions to the OpenGL / WGL Specifications 96 97 None. This specification is written for GLX. 98 99Additions to the GLX 1.4 Specification 100 101 [Add to Section 3.3.2 "GLX Versioning" of the GLX Specification] 102 103 To obtain information about the available renderers for a particular 104 display and screen, 105 106 Bool glXQueryRendererIntegerMESA(Display *dpy, int screen, int renderer, 107 int attribute, unsigned int *value); 108 109 can be used. The value for <attribute> will be returned in one or more 110 integers specified by <value>. The values, data sizes, and descriptions 111 of each renderer attribute are listed in the table below. 112 113 GLX renderer attribute number description 114 of values 115 ---------------------- --------- ----------- 116 GLX_RENDERER_VENDOR_ID_MESA 1 PCI ID of the device vendor 117 GLX_RENDERER_DEVICE_ID_MESA 1 PCI ID of the device 118 GLX_RENDERER_VERSION_MESA 3 Major, minor, and patch level of 119 the renderer implementation 120 GLX_RENDERER_ACCELERATED_MESA 1 Boolean indicating whether or 121 not the renderer is hardware 122 accelerated 123 GLX_RENDERER_VIDEO_MEMORY_MESA 1 Number of megabytes of video 124 memory available to the renderer 125 GLX_RENDERER_UNIFIED_MEMORY_ARCHITECTURE_MESA 126 1 Boolean indicating whether or 127 not the renderer uses a unified 128 memory architecture or has 129 separate "on-card" and GART 130 memory. 131 GLX_RENDERER_PREFERRED_PROFILE_MESA 132 1 Bitmask of the preferred context 133 profile for this renderer. This 134 value is suitable to be supplied 135 with the 136 GLX_CONTEXT_PROFILE_MASK_ARB 137 attribute to 138 glXCreateContextAttribsARB 139 GLX_RENDERER_OPENGL_CORE_PROFILE_VERSION_MESA 140 2 Maximum core profile major and 141 minor version supported by the 142 renderer 143 GLX_RENDERER_OPENGL_COMPATIBILITY_PROFILE_VERSION_MESA 144 2 Maximum compatibility profile 145 major and minor version 146 supported by the renderer 147 GLX_RENDERER_OPENGL_ES_PROFILE_VERSION_MESA 148 2 Maximum OpenGL ES 1.x 149 major and minor version 150 supported by the renderer 151 GLX_RENDERER_OPENGL_ES2_PROFILE_VERSION_MESA 152 2 Maximum OpenGL ES 2.x or 3.x 153 major and minor version 154 supported by the renderer 155 156 In the table, boolean attributes will have either the value 0 or 1. 157 158 GLX_RENDERER_OPENGL_CORE_PROFILE_VERSION_MESA, 159 GLX_RENDERER_OPENGL_COMPATIBILITY_PROFILE_VERSION_MESA, 160 GLX_RENDERER_OPENGL_ES_PROFILE_VERSION_MESA, and 161 GLX_RENDERER_OPENGL_ES2_PROFILE_VERSION_MESA each return <0, 0> in 162 *value if no version of that profile is supported. 163 164 GLX_RENDERER_VENDOR_ID_MESA and GLX_RENDERER_DEVICE_ID_MESA may return 165 0xFFFFFFFF if the device does not have a PCI ID (because it is not a PCI 166 device) or if the PCI ID is not available. In this case the application 167 should rely on the string query instead. 168 169 If <attribute> is not a recognized value, False is returned, but no GLX 170 error is generated. Otherwise, True is returned. 171 172 String versions of some attributes may also be queried using 173 174 const char *glXQueryRendererStringMESA(Display *dpy, int screen, 175 int renderer, int attribute); 176 177 The value for <attribute> will be returned in one or more 178 integers specified by <value>. The values, data sizes, and descriptions 179 of each renderer attribute are listed in the table below. 180 181 GLX renderer attribute description 182 ---------------------- ----------- 183 GLX_RENDERER_VENDOR_ID_MESA Name of the renderer provider. This may 184 differ from the vendor name of the 185 underlying hardware. 186 GLX_RENDERER_DEVICE_ID_MESA Name of the renderer. This may differ from 187 the name of the underlying hardware (e.g., 188 for a software renderer). 189 190 If <attribute> is not a recognized value, NULL is returned, but no GLX 191 error is generated. 192 193 The string returned for GLX_RENDERER_VENDOR_ID_MESA will have the same 194 format as the string that would be returned by glGetString of GL_VENDOR. 195 It may, however, have a different value. 196 197 The string returned for GLX_RENDERER_DEVICE_ID_MESA will have the same 198 format as the string that would be returned by glGetString of GL_RENDERER. 199 It may, however, have a different value. 200 201Issues 202 203 1) How should the difference between on-card and GART memory be exposed? 204 205 UNRESOLVED. 206 207 2) How should memory limitations of unified memory architecture (UMA) 208 systems be exposed? 209 210 UNRESOLVED. Some hardware has different per-process and global 211 limits for memory that can be accessed within a single draw call. 212 213 3) How should the renderer's API preference be advertised? 214 215 UNRESOLVED. The common case for desktop renderers is to prefer 216 either core or compatibility. However, some renderers may actually 217 prefer an ES context. This leaves the application in a tough spot 218 if it can only support core or compatibility and the renderer says it 219 wants ES. 220 221 4) Should OpenGL ES 2.0 and OpenGL ES 3.0 be treated separately? 222 223 RESOLVED. No. OpenGL ES 3.0 is backwards compatible with OpenGL ES 224 2.0. Applications can detect OpenGL ES 3.0 support by querying 225 GLX_RENDERER_OPENGL_ES2_PROFILE_VERSION_MESA. 226 227 5) How can applications tell the difference between different hardware 228 renderers for the same device? For example, whether the renderer is the 229 open-source driver or the closed-source driver. 230 231 RESOLVED. Assuming this extension is ever implemented outside Mesa, 232 applications can query GLX_RENDERER_VENDOR_ID_MESA from 233 glXQueryRendererStringMESA. This will almost certainly return 234 different strings for open-source and closed-source drivers. 235 236 6) What is the value of GLX_RENDERER_UNIFIED_MEMORY_ARCHITECTURE_MESA for 237 software renderers? 238 239 UNRESOLVED. Video (display) memory and texture memory is not unified 240 for software implementations, so it seems reasonable for this to be 241 False. 242 243 7) How does an application determine the number of available renderers? 244 245 UNRESOLVED. 246 247 8) What happens if a fbconfig is used to create context on a renderer 248 that cannot support it? For example, if a multisampled config is used 249 with a software renderer that does not support multisampling. 250 251 RESOLVED. The language for glXCreateContextAttribsARB already covers 252 this case. Context creation will fail, and BadMatch is generated. 253 254 9) In addition to being able to query the supported versions, should 255 applications also be able to query the supported extensions? 256 257 RESOLVED. No. Desktop OpenGL core profiles and OpenGL ES 3.0 have 258 moved away from the monolithic string returned by glGetString of 259 GL_EXTENSIONS. Providing the newer indexed query would require adding 260 a lot of extra infrastructure, and it would probably provide little 261 benefit to applications. 262 263 10) What combination of values for GLX_RENDERER_PREFERRED_PROFILE_MESA, 264 GLX_RENDERER_OPENGL_COMPATIBILITY_PROFILE_VERSION_MESA, and 265 GLX_RENDERER_OPENGL_CORE_PROFILE_VERSION_MESA should be returned 266 for a renderer that only supports OpenGL 3.1 without the 267 GL_ARB_compatibility extension? 268 269 RESOLVED. The renderer will return GLX_CONTEXT_CORE_PROFILE_BIT_ARB 270 for GLX_RENDERER_PREFERRED_PROFILE_MESA. 271 272 Further, the renderer will return <3,0> for 273 GLX_RENDERER_OPENGL_COMPATIBILITY_PROFILE_VERSION_MESA because OpenGL 274 3.1 without GL_ARB_compatibility is not backwards compatible with 275 previous versions of OpenGL. The render will return <3,1> for 276 GLX_RENDERER_OPENGL_CORE_PROFILE_VERSION_MESA indicating that support 277 for OpenGL 3.1 is available. 278 279 Even though there is no OpenGL 3.1 core profile, the values 280 returned for GLX_RENDERER_PREFERRED_PROFILE_MESA and 281 GLX_RENDERER_OPENGL_CORE_PROFILE_VERSION_MESA can be supplied 282 with the GLX_CONTEXT_PROFILE_MASK_ARB and 283 GLX_CONTEXT_{MAJOR,MINOR}_VERSION_ARB attributes of 284 glXCreateContextAttribsARB without error. If the requested 285 OpenGL version is less than 3.2, the 286 GLX_CONTEXT_PROFILE_MASK_ARB attribute is ignored by 287 glXCreateContextAttribsARB. 288 289 11) How can application learn about multi-GPU (e.g., SLI, CrossFireX, 290 etc.) configurations? 291 292 UNRESOLVED. Based on ISV feedback, this is important information to 293 provide to the application. Given the variety of possible hardware 294 configurations (e.g., Hybrid CrossFireX) and different rendering 295 modes (e.g., split-frame rendering vs. alternate-frame rendering), 296 it's not clear how this information can be communicated. 297 298 It is likely that this will be left to a layered extension. 299 300 12) Should capability queries similar to those in 301 GL_ARB_internalformat_query or GL_ARB_internalformat_query2 be added? 302 303 RESOLVED. No. With the possible exception of the texture size 304 queries, it seems unlikely that applications would ever use this 305 information before creating a context. 306 307 13) Existing GL extensions (e.g., GL_ATI_meminfo and 308 GL_NVX_gpu_memory_info) allow easy queries after context creation. With 309 this extension it is a bit of a pain for a portable application to query 310 the information after context creation. 311 312 RESOLVED. Add versions of the queries that implicitly take the 313 display, screen, and renderer from the currently bound context. 314 315 14) Why not make the queries from issue #13 GL functions (instead of GLX)? 316 317 RESOLVED. It is fairly compelling for the post-creation queries to 318 just use glGetInteger and glGetString. However, the GL enums and 319 the GLX enums would have different names and would almost certainly 320 have different values. It seems like this would cause more problems 321 than it would solve. 322 323 15) Should the string queries be required to return the same values as 324 glGetString(GL_VENDOR) and glGetString(GL_RENDERER)? 325 326 UNRESOLVED. This may be useful for applications that already do 327 device detection based on these strings. 328 329 16) What type should the value parameter of glXQueryRendererIntegerMESA 330 and glXQueryCurrentRendererIntegerMESA be? 331 332 UNRESOLVED. Other similar GLX query functions just use int or 333 unsigned int, so that's what this extension uses for now. However, 334 an expeclitly sized value, such as uint32_t or uint64_t, seems 335 preferable. 336 337 17) What about SoCs and other systems that don't have PCI? 338 339 RESOLVED. The GLX_RENDERER_VENDOR_ID_MESA and 340 GLX_RENDERER_DEVICE_ID_MESA integer queries may return 0xFFFFFFFF if a 341 PCI ID either does not exist or is not available. Implementations 342 should make every attempt to return as much information as is 343 possible. For example, if the implementation is running on a non-PCI 344 SoC with a Qualcomm GPU, GLX_RENDERER_VENDOR_ID_MESA should return 345 0x5143, but GLX_RENDERER_DEVICE_ID_MESA will return 0xFFFFFFFF. 346 347Revision History 348 349 Version 1, 2012/08/27 - Initial version 350 351 Version 2, 2012/09/04 - Specify behavior of implementations that 352 do not support certain profiles. 353 Change wording of issue #8 to be more 354 clear. 355 Make some wording changes to issue #10 to 356 clarify the resolution a bit. 357 358 Version 3, 2012/09/23 - Add issue #11 regarding multi-GPU systems. 359 360 Version 4, 2013/02/01 - Add issue #12 regarding texture / renderbuffer 361 format queries. 362 363 Version 5, 2013/02/14 - Add issues #13 and #14 regarding simpler queires 364 after the context is created and made current. 365 Add issue #15 regarding the string query. 366 Add issue #16 regarding the value type returned 367 by the Integer functions. 368 369 Version 6, 2013/10/25 - Fix a typo. Update the list of functions to 370 which the new enums can be passed. The "Current" 371 versions were previously missing. 372 373 Version 7, 2013/11/07 - Fix a couple more typos. Add issue #17 regarding 374 the PCI queries on systems that don't have PCI. 375 376 Version 8, 2014/02/14 - Fix a couple typos. GLX_RENDER_ID_MESA should 377 read GLX_RENDERER_ID_MESA. The VENDOR/DEVICE_ID 378 example given in issue #17 should be 0x5143 and 379 0xFFFFFFFF respectively. 380 381 Version 9, 2018/11/09 - Remove GLX_RENDERER_ID_MESA, which has never been 382 implemented. Remove the unnecessary interactions 383 with the GLX GLES profile extensions. Note the 384 official GL extension number. Specify the section 385 of the GLX spec to modify. 386