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    Proposal
17
18Version
19
20    Version 1, March 1, 2011
21
22Number
23
24    EGL Extension #not assigned
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_base_image 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_buffer *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
79
80Additions to the EGL 1.4 Specification:
81
82    To bind a server side wl_display to an EGLDisplay, call
83
84        EGLBoolean eglBindWaylandDisplayWL(EGLDisplay dpy,
85                                           struct wl_display *display);
86
87    To unbind a server side wl_display from an EGLDisplay, call
88    
89        EGLBoolean eglUnbindWaylandDisplayWL(EGLDisplay dpy,
90                                             struct wl_display *display);
91
92    eglBindWaylandDisplayWL returns EGL_FALSE when there is already a
93    wl_display bound to EGLDisplay otherwise EGL_TRUE.
94
95    eglUnbindWaylandDisplayWL returns EGL_FALSE when there is no
96    wl_display bound to the EGLDisplay currently otherwise EGL_TRUE.
97
98    A wl_buffer can have several planes, typically in case of planar
99    YUV formats.  Depending on the exact YUV format in use, the
100    compositor will have to create one or more EGLImages for the
101    various planes.  The eglQueryWaylandBufferWL function should be
102    used to first query the wl_buffer texture format using
103    EGL_TEXTURE_FORMAT as the attribute.  If the wl_buffer object is
104    not an EGL wl_buffer (wl_shm and other wayland extensions can
105    create wl_buffer objects of different types), this query will
106    return EGL_FALSE.  In that case the wl_buffer can not be used with
107    EGL and the compositor should have another way to get the buffer
108    contents.
109
110    If eglQueryWaylandBufferWL succeeds, the returned value will be
111    one of EGL_TEXTURE_RGB, EGL_TEXTURE_RGBA, EGL_TEXTURE_Y_U_V_WL,
112    EGL_TEXTURE_Y_UV_WL, EGL_TEXTURE_Y_XUXV_WL.  The value returned
113    describes how many EGLImages must be used, which components will
114    be sampled from each EGLImage and how they map to rgba components
115    in the shader.  The naming conventions separates planes by _ and
116    within each plane, the order or R, G, B, A, Y, U, and V indicates
117    how those components map to the rgba value returned by the
118    sampler.  X indicates that the corresponding component in the rgba
119    value isn't used.
120
121    RGB and RGBA buffer types:
122
123        EGL_TEXTURE_RGB
124                One plane, samples RGB from the texture to rgb in the
125                shader.  Alpha channel is not valid.
126
127        EGL_TEXTURE_RGBA
128                One plane, samples RGBA from the texture to rgba in the
129                shader.
130
131    YUV buffer types:
132
133        EGL_TEXTURE_Y_U_V_WL
134                Three planes, samples Y from the first plane to r in
135                the shader, U from the second plane to r, and V from
136                the third plane to r.
137
138        EGL_TEXTURE_Y_UV_WL
139                Two planes, samples Y from the first plane to r in
140                the shader, U and V from the second plane to rg.
141
142        EGL_TEXTURE_Y_XUXV_WL
143                Two planes, samples Y from the first plane to r in
144                the shader, U and V from the second plane to g and a.
145
146    After querying the wl_buffer layout, create EGLImages for the
147    planes by calling eglCreateImageKHR with wl_buffer as
148    EGLClientBuffer, EGL_WAYLAND_BUFFER_WL as the target, NULL
149    context.  If no attributes are given, an EGLImage will be created
150    for the first plane.  For multi-planar buffers, specify the plane
151    to create the EGLImage for by using the EGL_WAYLAND_PLANE_WL
152    attribute.  The value of the attribute is the index of the plane,
153    as defined by the buffer format.  Writing to an EGLImage created
154    from a wl_buffer in any way (such as glTexImage2D, binding the
155    EGLImage as a renderbuffer etc) will result in undefined behavior.
156
157    Further, eglQueryWaylandBufferWL accepts attributes EGL_WIDTH and
158    EGL_HEIGHT to query the width and height of the wl_buffer.
159
160Issues
161
162Revision History
163
164    Version 1, March 1, 2011
165        Initial draft (Benjamin Franzke)
166    Version 2, July 5, 2012
167        Add EGL_WAYLAND_PLANE_WL attribute to allow creating an EGLImage
168        for different planes of planar buffer. (Kristian Høgsberg)
169    Version 3, July 10, 2012
170        Add eglQueryWaylandBufferWL and the various buffer
171        formats. (Kristian Høgsberg)
172    Version 4, July 19, 2012
173        Use EGL_TEXTURE_FORMAT, EGL_TEXTURE_RGB, and EGL_TEXTURE_RGBA,
174        and just define the new YUV texture formats.  Add support for
175        EGL_WIDTH and EGL_HEIGHT in the query attributes (Kristian Høgsberg)
176