docs/specs/MESA_query_renderer.spec

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