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 9, 09 November 2018
  24
  25 Number
  26
  27     OpenGL Extension #446
  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 Additions to the OpenGL / WGL Specifications
  96
  97     None. This specification is written for GLX.
  98
  99 Additions 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
 201 Issues
 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
 347 Revision 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.