3 WL_bind_wayland_display
7 EGL_WL_bind_wayland_display
11 Kristian Høgsberg
<krh@bitplanet.net
>
12 Benjamin Franzke
<benjaminfranzke@googlemail.com
>
20 Version 5, July
16, 2013
24 EGL Extension
#not assigned
28 Requires EGL
1.4 or later. This extension is written against the
29 wording of the EGL
1.4 specification.
31 EGL_KHR_base_image is required.
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
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.
49 Open
-source; freely implementable.
51 New Procedures and Functions
53 EGLBoolean eglBindWaylandDisplayWL
(EGLDisplay dpy
,
54 struct wl_display
*display
);
56 EGLBoolean eglUnbindWaylandDisplayWL
(EGLDisplay dpy
,
57 struct wl_display
*display
);
59 EGLBoolean eglQueryWaylandBufferWL
(EGLDisplay dpy
,
60 struct wl_resource
*buffer
,
61 EGLint attribute
, EGLint
*value
);
65 Accepted as
<target
> in eglCreateImageKHR
67 EGL_WAYLAND_BUFFER_WL
0x31D5
69 Accepted
in the
<attrib_list
> parameter of eglCreateImageKHR
:
71 EGL_WAYLAND_PLANE_WL
0x31D6
73 Possible values
for EGL_TEXTURE_FORMAT
:
75 EGL_TEXTURE_Y_U_V_WL
0x31D7
76 EGL_TEXTURE_Y_UV_WL
0x31D8
77 EGL_TEXTURE_Y_XUXV_WL
0x31D9
79 Accepted
in the
<attribute
> parameter of eglQueryWaylandBufferWL
:
81 EGL_TEXTURE_FORMAT
0x3080
82 EGL_WAYLAND_Y_INVERTED_WL
0x31DB
85 Additions to the EGL
1.4 Specification
:
87 To
bind a server side wl_display to an EGLDisplay
, call
89 EGLBoolean eglBindWaylandDisplayWL
(EGLDisplay dpy
,
90 struct wl_display
*display
);
92 To unbind a server side wl_display from an EGLDisplay
, call
94 EGLBoolean eglUnbindWaylandDisplayWL
(EGLDisplay dpy
,
95 struct wl_display
*display
);
97 eglBindWaylandDisplayWL returns EGL_FALSE when there is already a
98 wl_display bound to EGLDisplay otherwise EGL_TRUE.
100 eglUnbindWaylandDisplayWL returns EGL_FALSE when there is no
101 wl_display bound to the EGLDisplay currently otherwise EGL_TRUE.
103 A wl_buffer can have several planes
, typically
in case of planar
104 YUV formats. Depending on the exact YUV format
in use
, the
105 compositor will have to create one or more EGLImages
for the
106 various planes. The eglQueryWaylandBufferWL
function should be
107 used to first query the wl_buffer texture format using
108 EGL_TEXTURE_FORMAT as the attribute. If the wl_buffer object is
109 not an EGL wl_buffer
(wl_shm and other wayland extensions can
110 create wl_buffer objects of different types
), this query will
111 return EGL_FALSE. In that
case the wl_buffer can not be used with
112 EGL and the compositor should have another way to get the buffer
115 If eglQueryWaylandBufferWL succeeds
, the returned value will be
116 one of EGL_TEXTURE_RGB
, EGL_TEXTURE_RGBA
, EGL_TEXTURE_Y_U_V_WL
,
117 EGL_TEXTURE_Y_UV_WL
, EGL_TEXTURE_Y_XUXV_WL. The value returned
118 describes how many EGLImages must be used
, which components will
119 be sampled from each EGLImage and how they map to rgba components
120 in the shader. The naming conventions separates planes by _ and
121 within each plane
, the order or R
, G
, B
, A
, Y
, U
, and V indicates
122 how those components map to the rgba value returned by the
123 sampler. X indicates that the corresponding component
in the rgba
126 RGB and RGBA buffer types
:
129 One plane
, samples RGB from the texture to rgb
in the
130 shader. Alpha channel is not valid.
133 One plane
, samples RGBA from the texture to rgba
in the
139 Three planes
, samples Y from the first plane to r
in
140 the shader
, U from the second plane to r
, and V from
141 the third plane to r.
144 Two planes
, samples Y from the first plane to r
in
145 the shader
, U and V from the second plane to rg.
147 EGL_TEXTURE_Y_XUXV_WL
148 Two planes
, samples Y from the first plane to r
in
149 the shader
, U and V from the second plane to g and a.
151 After querying the wl_buffer layout
, create EGLImages
for the
152 planes by calling eglCreateImageKHR with wl_buffer as
153 EGLClientBuffer
, EGL_WAYLAND_BUFFER_WL as the target
, NULL
154 context. If no attributes are given
, an EGLImage will be created
155 for the first plane. For multi
-planar buffers
, specify the plane
156 to create the EGLImage
for by using the EGL_WAYLAND_PLANE_WL
157 attribute. The value of the attribute is the index of the plane
,
158 as defined by the buffer format. Writing to an EGLImage created
159 from a wl_buffer
in any way
(such as glTexImage2D
, binding the
160 EGLImage as a renderbuffer etc
) will result
in undefined behavior.
162 Further
, eglQueryWaylandBufferWL accepts attributes EGL_WIDTH and
163 EGL_HEIGHT to query the width and height of the wl_buffer.
165 Also
, eglQueryWaylandBufferWL may accept
166 EGL_WAYLAND_Y_INVERTED_WL attribute to query orientation of
167 wl_buffer. If EGL_WAYLAND_Y_INVERTED_WL is supported
168 eglQueryWaylandBufferWL returns EGL_TRUE and value is a boolean
169 that tells
if wl_buffer is y
-inverted or not. If
170 EGL_WAYLAND_Y_INVERTED_WL is not supported
171 eglQueryWaylandBufferWL returns EGL_FALSE
, in that
case
172 wl_buffer should be treated as
if value of
173 EGL_WAYLAND_Y_INVERTED_WL was EGL_TRUE.
179 Version 1, March
1, 2011
180 Initial draft
(Benjamin Franzke
)
181 Version 2, July
5, 2012
182 Add EGL_WAYLAND_PLANE_WL attribute to allow creating an EGLImage
183 for different planes of planar buffer.
(Kristian Høgsberg
)
184 Version 3, July
10, 2012
185 Add eglQueryWaylandBufferWL and the various buffer
186 formats.
(Kristian Høgsberg
)
187 Version 4, July
19, 2012
188 Use EGL_TEXTURE_FORMAT
, EGL_TEXTURE_RGB
, and EGL_TEXTURE_RGBA
,
189 and just define the new YUV texture formats. Add support
for
190 EGL_WIDTH and EGL_HEIGHT
in the query attributes
(Kristian Høgsberg
)
191 Version 5, July
16, 2013
192 Change eglQueryWaylandBufferWL to take a resource pointer to the
193 buffer instead of a pointer to a struct wl_buffer
, as the latter has
194 been deprecated.
(Ander Conselvan de Oliveira
)
195 Version 6, September
16, 2013
196 Add EGL_WAYLAND_Y_INVERTED_WL attribute to allow specifying
197 wl_buffer's orientation.