1Name
2
3    WL_bind_wayland_display
4
5Name Strings
6
7    EGL_WL_bind_wayland_display
8
9Contact
10
11    Kristian Høgsberg <krh@bitplanet.net>
12    Benjamin Franzke <benjaminfranzke@googlemail.com>
13
14Status
15
16    Complete
17
18Version
19
20    Version 6, July 14, 2017
21
22Number
23
24    EGL Extension #136
25
26Dependencies
27
28    Requires EGL 1.4 or later.  This extension is written against the
29    wording of the EGL 1.4 specification.
30
31    EGL_KHR_image_base is required.
32
33Overview
34
35    This extension provides entry points for binding and unbinding the
36    wl_display of a Wayland compositor to an EGLDisplay.  Binding a
37    wl_display means that the EGL implementation should provide one or
38    more interfaces in the Wayland protocol to allow clients to create
39    wl_buffer objects.  On the server side, this extension also
40    provides a new target for eglCreateImageKHR, to create an EGLImage
41    from a wl_buffer.
42
43    Adding an implementation-specific Wayland interface, allows the
44    EGL implementation to define specific wayland requests and events,
45    needed for buffer sharing in an EGL Wayland platform.
46
47IP Status
48
49    Open-source; freely implementable.
50
51New Procedures and Functions
52
53    EGLBoolean eglBindWaylandDisplayWL(EGLDisplay dpy,
54                                       struct wl_display *display);
55
56    EGLBoolean eglUnbindWaylandDisplayWL(EGLDisplay dpy,
57                                         struct wl_display *display);
58
59    EGLBoolean eglQueryWaylandBufferWL(EGLDisplay dpy,
60                                       struct wl_resource *buffer,
61                                       EGLint attribute, EGLint *value);
62
63New Tokens
64
65    Accepted as <target> in eglCreateImageKHR
66
67        EGL_WAYLAND_BUFFER_WL                   0x31D5
68
69    Accepted in the <attrib_list> parameter of eglCreateImageKHR:
70
71        EGL_WAYLAND_PLANE_WL                    0x31D6
72
73    Possible values for EGL_TEXTURE_FORMAT:
74
75        EGL_TEXTURE_Y_U_V_WL                    0x31D7
76        EGL_TEXTURE_Y_UV_WL                     0x31D8
77        EGL_TEXTURE_Y_XUXV_WL                   0x31D9
78        EGL_TEXTURE_EXTERNAL_WL                 0x31DA
79
80    Accepted in the <attribute> parameter of eglQueryWaylandBufferWL:
81
82        EGL_TEXTURE_FORMAT                      0x3080
83        EGL_WAYLAND_Y_INVERTED_WL               0x31DB
84
85
86Additions to the EGL 1.4 Specification:
87
88    To bind a server-side wl_display to an EGLDisplay, call
89
90        EGLBoolean eglBindWaylandDisplayWL(EGLDisplay dpy,
91                                           struct wl_display *display);
92
93    To unbind a server-side wl_display from an EGLDisplay, call
94    
95        EGLBoolean eglUnbindWaylandDisplayWL(EGLDisplay dpy,
96                                             struct wl_display *display);
97
98    eglBindWaylandDisplayWL returns EGL_FALSE when there is already a
99    wl_display bound to EGLDisplay otherwise EGL_TRUE.
100
101    eglUnbindWaylandDisplayWL returns EGL_FALSE when there is no
102    wl_display bound to the EGLDisplay currently otherwise EGL_TRUE.
103
104    XXXXXXXX 
105    EGL_WAYLAND_BUFFER_WL
106
107
108    To query attributes of a wl_buffer created by the EGL
109    implementation installed by eglBindWaylandDisplayWL, call:
110
111        EGLBoolean eglQueryWaylandBufferWL(EGLDisplay dpy,
112                                           struct wl_resource *buffer,
113                                           EGLint attribute,
114					   EGLint *value);
115
116    A wl_buffer can have several planes, typically in case of planar
117    YUV formats.  Depending on the exact YUV format in use, the
118    compositor will have to create one or more EGLImages for the
119    various planes.  The eglQueryWaylandBufferWL function should be
120    used to first query the wl_buffer texture format using
121    EGL_TEXTURE_FORMAT as the attribute.  If the wl_buffer object is
122    not an EGL wl_buffer (wl_shm and other wayland extensions can
123    create wl_buffer objects of different types), this query will
124    return EGL_FALSE.  In that case the wl_buffer can not be used with
125    EGL and the compositor should have another way to get the buffer
126    contents.
127
128    If eglQueryWaylandBufferWL succeeds, the returned value will be
129    one of EGL_TEXTURE_RGB, EGL_TEXTURE_RGBA, EGL_TEXTURE_Y_U_V_WL,
130    EGL_TEXTURE_Y_UV_WL, EGL_TEXTURE_Y_XUXV_WL.  The value returned
131    describes how many EGLImages must be used, which components will
132    be sampled from each EGLImage and how they map to rgba components
133    in the shader.  The naming conventions separates planes by _ and
134    within each plane, the order or R, G, B, A, Y, U, and V indicates
135    how those components map to the rgba value returned by the
136    sampler.  X indicates that the corresponding component in the rgba
137    value isn't used.
138
139    RGB and RGBA buffer types:
140
141        EGL_TEXTURE_RGB
142                One plane, samples RGB from the texture to rgb in the
143                shader.  Alpha channel is not valid.
144
145        EGL_TEXTURE_RGBA
146                One plane, samples RGBA from the texture to rgba in the
147                shader.
148
149    YUV buffer types:
150
151        EGL_TEXTURE_Y_U_V_WL
152                Three planes, samples Y from the first plane to r in
153                the shader, U from the second plane to r, and V from
154                the third plane to r.
155
156        EGL_TEXTURE_Y_UV_WL
157                Two planes, samples Y from the first plane to r in
158                the shader, U and V from the second plane to rg.
159
160        EGL_TEXTURE_Y_XUXV_WL
161                Two planes, samples Y from the first plane to r in
162                the shader, U and V from the second plane to g and a.
163
164        EGL_TEXTURE_EXTERNAL_WL
165                Treated as a single plane texture, but sampled with
166                samplerExternalOES according to OES_EGL_image_external
167
168    After querying the wl_buffer layout, create EGLImages for the
169    planes by calling eglCreateImageKHR with wl_buffer as
170    EGLClientBuffer, EGL_WAYLAND_BUFFER_WL as the target, NULL
171    context.  If no attributes are given, an EGLImage will be created
172    for the first plane.  For multi-planar buffers, specify the plane
173    to create the EGLImage for by using the EGL_WAYLAND_PLANE_WL
174    attribute.  The value of the attribute is the index of the plane,
175    as defined by the buffer format.  Writing to an EGLImage created
176    from a wl_buffer in any way (such as glTexImage2D, binding the
177    EGLImage as a renderbuffer etc) will result in undefined behavior.
178
179    Further, eglQueryWaylandBufferWL accepts attributes EGL_WIDTH and
180    EGL_HEIGHT to query the width and height of the wl_buffer.
181
182    Also, eglQueryWaylandBufferWL may accept
183    EGL_WAYLAND_Y_INVERTED_WL attribute to query orientation of
184    wl_buffer. If EGL_WAYLAND_Y_INVERTED_WL is supported
185    eglQueryWaylandBufferWL returns EGL_TRUE and value is a boolean
186    that tells if wl_buffer is y-inverted or not. If
187    EGL_WAYLAND_Y_INVERTED_WL is not supported
188    eglQueryWaylandBufferWL returns EGL_FALSE, in that case
189    wl_buffer should be treated as if value of
190    EGL_WAYLAND_Y_INVERTED_WL was EGL_TRUE.
191
192Issues
193
194Revision History
195
196    Version 1, March 1, 2011
197        Initial draft (Benjamin Franzke)
198    Version 2, July 5, 2012
199        Add EGL_WAYLAND_PLANE_WL attribute to allow creating an EGLImage
200        for different planes of planar buffer. (Kristian Høgsberg)
201    Version 3, July 10, 2012
202        Add eglQueryWaylandBufferWL and the various buffer
203        formats. (Kristian Høgsberg)
204    Version 4, July 19, 2012
205        Use EGL_TEXTURE_FORMAT, EGL_TEXTURE_RGB, and EGL_TEXTURE_RGBA,
206        and just define the new YUV texture formats.  Add support for
207        EGL_WIDTH and EGL_HEIGHT in the query attributes (Kristian Høgsberg)
208    Version 5, July 16, 2013
209        Change eglQueryWaylandBufferWL to take a resource pointer to the
210        buffer instead of a pointer to a struct wl_buffer, as the latter has
211        been deprecated. (Ander Conselvan de Oliveira)
212    Version 6, September 16, 2013
213        Add EGL_WAYLAND_Y_INVERTED_WL attribute to allow specifying
214        wl_buffer's orientation.
215    Version 7, July 14, 2017
216        Add EGL_WAYLAND_BUFFER_WL EGLImage target. Reword for inclusion in
217	Khronos registry.
218