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