← Back to branch summary

~mmach/netext73/mesa-haswell

« back to all changes in this revision

Viewing changes to docs/_extra/specs/MESA_query_renderer.spec

  • Committer: mmach
  • Date: 2022-09-22 19:56:13 UTC
  • Revision ID: netbit73@gmail.com-20220922195613-wtik9mmy20tmor0i
2022-09-22 21:17:09

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/_extra/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.