1Name
2
3    EXT_device_query
4
5Name Strings
6
7    EGL_EXT_device_query
8
9Contributors
10
11    James Jones, NVIDIA  (jajones 'at' nvidia.com)
12    Jamie Madill, Google  (jmadill 'at' google.com)
13
14Contacts
15
16    Jamie Madill, Google  (jmadill 'at' google.com)
17
18Status
19
20    Draft
21
22Version
23
24    Version 1 - Mar 25rd, 2015
25
26Number
27
28    EGL Extension #XXX
29
30Extension Type
31
32    EGL client extension
33
34Dependencies
35
36    Written against the wording of EGL 1.5.
37
38    Requires EGL 1.5 or an earlier verison of EGL with the
39    EGL_EXT_client_extensions extension.
40
41Overview
42
43    Increasingly, EGL and its client APIs are being used in place of
44    "native" rendering APIs to implement the basic graphics
45    functionality of native windowing systems.  This creates demand
46    for a method to access native GPU or device objects directly
47    rather than calling EGL or GL entry points.
48
49    This extension defines the method for an application to query
50    native device objects from an EGL Display.
51
52New Types
53
54    This is the type of a handle that represents an EGLDeviceEXT
55    object.
56
57        typedef void* EGLDeviceEXT;
58
59    If EGL 1.5 is not supported, the following type is added, as
60    defined in the EGL 1.5 specification:
61
62        typedef intptr_t EGLAttrib;
63
64New Functions
65
66    EGLBoolean eglQueryDeviceAttribEXT(EGLDeviceEXT device,
67                                       EGLint attribute,
68                                       EGLAttrib *value);
69
70    const char *eglQueryDeviceStringEXT(EGLDeviceEXT device,
71                                        EGLint name);
72
73    EGLBoolean eglQueryDisplayAttribEXT(EGLDisplay dpy,
74                                        EGLint attribute,
75                                        EGLAttrib *value);
76
77New Tokens
78
79    Functions with a return type of EGLDeviceEXT will return this
80    value on failure:
81
82        EGL_NO_DEVICE_EXT                      ((EGLDeviceEXT)0)
83
84    This error value will be generated by functions that take an
85    EGLDeviceEXT object as a parameter:
86
87        EGL_BAD_DEVICE_EXT                     0x322B
88
89    Accepted by the <attribute> parameter of
90    eglQueryDisplayAttribEXT:
91
92        EGL_DEVICE_EXT                         0x322C
93
94Add a new section "2.1.2 Devices" after "2.1.1 Scalar Types"
95
96    All EGL operations occur on an EGLDeviceEXT.  However, devices
97    themselves expose no functionality.  They are simple abstract
98    objects that exist only for the sake of enumeration and
99    defining a namespace.
100
101Modify the last sentence of section "2.1.3" Displays" to read:
102
103    Besides devices, objects are always specified by the combination
104    of an EGLDisplay parameter with a parameter representing the
105    handle of the object.
106
107Add a new extension type to the list in section "2.8 Extensions"
108
109    Device Extensions
110        A *device extension* adds functionality to an individual
111        EGLDeviceEXT.  Different instances of EGLDeviceEXT may support
112        different sets of device extensions
113
114Add a new error to section "3.1 Errors"
115
116    EGL_BAD_DEVICE_EXT
117        An EGLDeviceEXT argument does not refer to a valid
118        EGLDeviceEXT.  Any command taking an EGLDeviceEXT parameter
119        may generate this error.
120
121Add a section "3.2 Devices" after "3.1 Errors"
122
123    To query the properties of a device, use:
124
125        EGLBoolean eglQueryDeviceAttribEXT(EGLDeviceEXT device,
126                                           EGLint attribute,
127                                           EGLAttrib *value);
128
129    On success, EGL_TRUE is returned and the requested attribute value
130    is returned in <value>.  Currently there are no valid values of
131    <attribute> defined.
132
133    On failure, EGL_FALSE is returned.  An EGL_BAD_ATTRIBUTE error is
134    generated if <attribute> is not a valid attribute.  An
135    EGL_BAD_DEVICE_EXT error is generated if <device> is not a valid
136    EGLDeviceEXT.
137
138        const char *eglQueryDeviceStringEXT(EGLDeviceEXT device,
139                                            EGLint name);
140
141    returns a pointer to a static, zero-terminated string describing
142    some aspect of the specified EGLDeviceEXT.  <name> must be
143    EGL_EXTENSIONS.
144
145    The EGL_EXTENSIONS string describes which device extensions are
146    supported by <device>.  The string is of the same format specified
147    for display and client extension strings in section 3.4. Note that
148    device extensions are properties of the device, and are distinct
149    from other extension strings.
150
151    On failure, NULL is returned.  An EGL_BAD_DEVICE_EXT error is
152    generated if <device> is not a valid EGLDeviceEXT.  An
153    EGL_BAD_PARAMETER error is generated if <name> is not one of the
154    values described above.
155
156Add a section "3.4 Display Attributes" after "3.3 EGL Versioning"
157
158    To query attributes of an initialized display, use:
159
160        EGLBoolean eglQueryDisplayAttribEXT(EGLDisplay dpy,
161                                            EGLint name,
162                                            EGLAttrib *value);
163
164    On success, EGL_TRUE is returned.  If <name> is EGL_DEVICE_EXT,
165    the EGLDeviceEXT associated with <dpy> is returned in <value>.
166    All displays have an associated EGLDeviceEXT, regardless of how
167    they were created.  A successful query of EGL_DEVICE_EXT will
168    never return EGL_NO_DEVICE_EXT.
169
170    On failure, EGL_FALSE is returned.  An EGL_NOT_INITIALIZED error
171    is generated if EGL is not initialized for <dpy>.  An
172    EGL_BAD_ATTRIBUTE error is generated if <name> is not a valid
173    value.
174
175    Because the EGLDeviceEXT is a property of <dpy>, any use of an
176    associated EGLDeviceEXT after <dpy> has been terminated gives
177    undefined results. Querying an EGL_DEVICE_EXT from <dpy> after a
178    call to eglTerminate() (and subsequent re-initialization) may
179    return a different value.
180
181Issues
182
183    None.
184
185Revision History:
186
187    #1  (Mar 25rd, 2015) Jamie Madill
188        - Initial Draft based on EGL_EXT_device_base
189