aboutsummaryrefslogtreecommitdiff
path: root/mesalib/docs/WL_bind_wayland_display.spec
blob: e1aca538003e9e493ec019da483019989e5bba09 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
Name

    WL_bind_wayland_display

Name Strings

    EGL_WL_bind_wayland_display

Contact

    Kristian Høgsberg <krh@bitplanet.net>
    Benjamin Franzke <benjaminfranzke@googlemail.com>

Status

    Proposal

Version

    Version 1, March 1, 2011

Number

    EGL Extension #not assigned

Dependencies

    Requires EGL 1.4 or later.  This extension is written against the
    wording of the EGL 1.4 specification.

    EGL_KHR_base_image is required.

Overview

    This extension provides entry points for binding and unbinding the
    wl_display of a Wayland compositor to an EGLDisplay.  Binding a
    wl_display means that the EGL implementation should provide one or
    more interfaces in the Wayland protocol to allow clients to create
    wl_buffer objects.  On the server side, this extension also
    provides a new target for eglCreateImageKHR, to create an EGLImage
    from a wl_buffer

    Adding an implementation specific wayland interface, allows the
    EGL implementation to define specific wayland requests and events,
    needed for buffer sharing in an EGL wayland platform.

IP Status

    Open-source; freely implementable.

New Procedures and Functions

    EGLBoolean eglBindWaylandDisplayWL(EGLDisplay dpy,
                                       struct wl_display *display);

    EGLBoolean eglUnbindWaylandDisplayWL(EGLDisplay dpy,
                                         struct wl_display *display);

    EGLBoolean eglQueryWaylandBufferWL(EGLDisplay dpy,
                                       struct wl_buffer *buffer,
                                       EGLint attribute, EGLint *value);

New Tokens

    Accepted as <target> in eglCreateImageKHR

        EGL_WAYLAND_BUFFER_WL                   0x31D5

    Accepted in the <attrib_list> parameter of eglCreateImageKHR:

        EGL_WAYLAND_PLANE_WL                    0x31D6


    Accepted as a eglQueryWaylandBufferWL attribute:

        EGL_WAYLAND_BUFFER_COMPONENTS_WL	0x31D7

    Possible values for EGL_WAYLAND_BUFFER_COMPONENTS_WL:    

        EGL_WAYLAND_BUFFER_RGB_WL               0x31D8
        EGL_WAYLAND_BUFFER_RGBA_WL              0x31D9
        EGL_WAYLAND_BUFFER_Y_U_V_WL             0x31Da
        EGL_WAYLAND_BUFFER_Y_UV_WL              0x31Db
        EGL_WAYLAND_BUFFER_Y_XUXV_WL            0x31Dc


Additions to the EGL 1.4 Specification:

    To bind a server side wl_display to an EGLDisplay, call

        EGLBoolean eglBindWaylandDisplayWL(EGLDisplay dpy,
                                           struct wl_display *display);

    To unbind a server side wl_display from an EGLDisplay, call
    
        EGLBoolean eglUnbindWaylandDisplayWL(EGLDisplay dpy,
                                             struct wl_display *display);

    eglBindWaylandDisplayWL returns EGL_FALSE when there is already a
    wl_display bound to EGLDisplay otherwise EGL_TRUE.

    eglUnbindWaylandDisplayWL returns EGL_FALSE when there is no
    wl_display bound to the EGLDisplay currently otherwise EGL_TRUE.

    A wl_buffer can have several planes, typically in case of planar
    YUV formats.  Depending on the exact YUV format in use, the
    compositor will have to create one or more EGLImages for the
    various planes.  The eglQueryWaylandBufferWL function should be
    used to first query the wl_buffer components using
    EGL_WAYLAND_BUFFER_COMPONENTS_WL as the attribute.  If the
    wl_buffer object is not an EGL wl_buffer (wl_shm and other wayland
    extensions can create wl_buffer objects), this query will return
    EGL_FALSE.  In that case the wl_buffer can not be used with EGL
    and the compositor should have another way to get the buffer
    contents.

    If eglQueryWaylandBufferWL succeeds, the returned value will be
    one of EGL_WAYLAND_BUFFER_RGB_WL, EGL_WAYLAND_BUFFER_RGBA_WL,
    EGL_WAYLAND_BUFFER_Y_U_V_WL, EGL_WAYLAND_BUFFER_Y_UV_WL,
    EGL_WAYLAND_BUFFER_Y_XUXV_WL.  The value returned describes how
    many EGLImages must be used, which components will be sampled from
    each EGLImage and how they map to rgba components in the shader.
    The naming conventions separates planes by _ and within each
    plane, the order or R, G, B, A, Y, U, and V indicates how those
    components map to the rgba value returned by the sampler.  X
    indicates that the corresponding component in the rgba value isn't
    used.

    RGB and RGBA buffer types:

        EGL_WAYLAND_BUFFER_RGB_WL
                One plane, samples RGB from the texture to rgb in the
                shader.  Alpha channel is not valid.

        EGL_WAYLAND_BUFFER_RGBA_WL              0x31D9
                One plane, samples RGBA from the texture to rgba in the
                shader.

    YUV buffer types:

        EGL_WAYLAND_BUFFER_Y_U_V_WL             0x31Da
                Three planes, samples Y from the first plane to r in
                the shader, U from the second plane to r, and V from
                the third plane to r.

        EGL_WAYLAND_BUFFER_Y_UV_WL              0x31Db
                Two planes, samples Y from the first plane to r in
                the shader, U and V from the second plane to rg.

        EGL_WAYLAND_BUFFER_Y_XUXV_WL            0x31Dc
                Two planes, samples Y from the first plane to r in
                the shader, U and V from the second plane to g and a.

    After querying the wl_buffer layout, create EGLImages for the
    planes by calling eglCreateImageKHR with wl_buffer as
    EGLClientBuffer, EGL_WAYLAND_BUFFER_WL as the target, NULL
    context.  If no attributes are given, an EGLImage will be created
    for the first plane.  For multi-planar buffers, specify the plane
    to create the EGLImage for by using the EGL_WAYLAND_PLANE_WL
    attribute.  The value of the attribute is the index of the plane,
    as defined by the buffer format.  Writing to an EGLImage created
    from a wl_buffer in any way (such as glTexImage2D, binding the
    EGLImage as a renderbuffer etc) will result in undefined behavior.

Issues

Revision History

    Version 1, March 1, 2011
        Initial draft (Benjamin Franzke)
    Version 2, July 5, 2012
        Add EGL_WAYLAND_PLANE_WL attribute to allow creating an EGLImage
        for different planes of planar buffer. (Kristian Høgsberg)
    Version 3, July 10, 2012
        Add eglQueryWaylandBufferWL and the various buffer
        formats. (Kristian Høgsberg)