← Back to branch summary

~mmach/netext73/mesa-haswell

« back to all changes in this revision

Viewing changes to docs/_extra/specs/WL_bind_wayland_display.spec

  • Committer: mmach
  • Date: 2022-09-22 19:56:13 UTC
  • Revision ID: netbit73@gmail.com-20220922195613-wtik9mmy20tmor0i
2022-09-22 21:17:09

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/_extra/specs/WL_bind_wayland_display.spec
1
 
Name
2
 
 
3
 
    WL_bind_wayland_display
4
 
 
5
 
Name Strings
6
 
 
7
 
    EGL_WL_bind_wayland_display
8
 
 
9
 
Contact
10
 
 
11
 
    Kristian Høgsberg <krh@bitplanet.net>
12
 
    Benjamin Franzke <benjaminfranzke@googlemail.com>
13
 
 
14
 
Status
15
 
 
16
 
    Proposal
17
 
 
18
 
Version
19
 
 
20
 
    Version 5, July 16, 2013
21
 
 
22
 
Number
23
 
 
24
 
    EGL Extension #not assigned
25
 
 
26
 
Dependencies
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
 
 
33
 
Overview
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
 
 
47
 
IP Status
48
 
 
49
 
    Open-source; freely implementable.
50
 
 
51
 
New 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
 
 
63
 
New 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
 
 
86
 
Additions 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
 
    A wl_buffer can have several planes, typically in case of planar
105
 
    YUV formats.  Depending on the exact YUV format in use, the
106
 
    compositor will have to create one or more EGLImages for the
107
 
    various planes.  The eglQueryWaylandBufferWL function should be
108
 
    used to first query the wl_buffer texture format using
109
 
    EGL_TEXTURE_FORMAT as the attribute.  If the wl_buffer object is
110
 
    not an EGL wl_buffer (wl_shm and other wayland extensions can
111
 
    create wl_buffer objects of different types), this query will
112
 
    return EGL_FALSE.  In that case the wl_buffer can not be used with
113
 
    EGL and the compositor should have another way to get the buffer
114
 
    contents.
115
 
 
116
 
    If eglQueryWaylandBufferWL succeeds, the returned value will be
117
 
    one of EGL_TEXTURE_RGB, EGL_TEXTURE_RGBA, EGL_TEXTURE_Y_U_V_WL,
118
 
    EGL_TEXTURE_Y_UV_WL, EGL_TEXTURE_Y_XUXV_WL.  The value returned
119
 
    describes how many EGLImages must be used, which components will
120
 
    be sampled from each EGLImage and how they map to rgba components
121
 
    in the shader.  The naming conventions separates planes by _ and
122
 
    within each plane, the order or R, G, B, A, Y, U, and V indicates
123
 
    how those components map to the rgba value returned by the
124
 
    sampler.  X indicates that the corresponding component in the rgba
125
 
    value isn't used.
126
 
 
127
 
    RGB and RGBA buffer types:
128
 
 
129
 
        EGL_TEXTURE_RGB
130
 
                One plane, samples RGB from the texture to rgb in the
131
 
                shader.  Alpha channel is not valid.
132
 
 
133
 
        EGL_TEXTURE_RGBA
134
 
                One plane, samples RGBA from the texture to rgba in the
135
 
                shader.
136
 
 
137
 
    YUV buffer types:
138
 
 
139
 
        EGL_TEXTURE_Y_U_V_WL
140
 
                Three planes, samples Y from the first plane to r in
141
 
                the shader, U from the second plane to r, and V from
142
 
                the third plane to r.
143
 
 
144
 
        EGL_TEXTURE_Y_UV_WL
145
 
                Two planes, samples Y from the first plane to r in
146
 
                the shader, U and V from the second plane to rg.
147
 
 
148
 
        EGL_TEXTURE_Y_XUXV_WL
149
 
                Two planes, samples Y from the first plane to r in
150
 
                the shader, U and V from the second plane to g and a.
151
 
 
152
 
        EGL_TEXTURE_EXTERNAL_WL
153
 
                Treated as a single plane texture, but sampled with
154
 
                samplerExternalOES according to OES_EGL_image_external
155
 
 
156
 
    After querying the wl_buffer layout, create EGLImages for the
157
 
    planes by calling eglCreateImageKHR with wl_buffer as
158
 
    EGLClientBuffer, EGL_WAYLAND_BUFFER_WL as the target, NULL
159
 
    context.  If no attributes are given, an EGLImage will be created
160
 
    for the first plane.  For multi-planar buffers, specify the plane
161
 
    to create the EGLImage for by using the EGL_WAYLAND_PLANE_WL
162
 
    attribute.  The value of the attribute is the index of the plane,
163
 
    as defined by the buffer format.  Writing to an EGLImage created
164
 
    from a wl_buffer in any way (such as glTexImage2D, binding the
165
 
    EGLImage as a renderbuffer etc) will result in undefined behavior.
166
 
 
167
 
    Further, eglQueryWaylandBufferWL accepts attributes EGL_WIDTH and
168
 
    EGL_HEIGHT to query the width and height of the wl_buffer.
169
 
 
170
 
    Also, eglQueryWaylandBufferWL may accept
171
 
    EGL_WAYLAND_Y_INVERTED_WL attribute to query orientation of
172
 
    wl_buffer. If EGL_WAYLAND_Y_INVERTED_WL is supported
173
 
    eglQueryWaylandBufferWL returns EGL_TRUE and value is a boolean
174
 
    that tells if wl_buffer is y-inverted or not. If
175
 
    EGL_WAYLAND_Y_INVERTED_WL is not supported
176
 
    eglQueryWaylandBufferWL returns EGL_FALSE, in that case
177
 
    wl_buffer should be treated as if value of
178
 
    EGL_WAYLAND_Y_INVERTED_WL was EGL_TRUE.
179
 
 
180
 
Issues
181
 
 
182
 
Revision History
183
 
 
184
 
    Version 1, March 1, 2011
185
 
        Initial draft (Benjamin Franzke)
186
 
    Version 2, July 5, 2012
187
 
        Add EGL_WAYLAND_PLANE_WL attribute to allow creating an EGLImage
188
 
        for different planes of planar buffer. (Kristian Høgsberg)
189
 
    Version 3, July 10, 2012
190
 
        Add eglQueryWaylandBufferWL and the various buffer
191
 
        formats. (Kristian Høgsberg)
192
 
    Version 4, July 19, 2012
193
 
        Use EGL_TEXTURE_FORMAT, EGL_TEXTURE_RGB, and EGL_TEXTURE_RGBA,
194
 
        and just define the new YUV texture formats.  Add support for
195
 
        EGL_WIDTH and EGL_HEIGHT in the query attributes (Kristian Høgsberg)
196
 
    Version 5, July 16, 2013
197
 
        Change eglQueryWaylandBufferWL to take a resource pointer to the
198
 
        buffer instead of a pointer to a struct wl_buffer, as the latter has
199
 
        been deprecated. (Ander Conselvan de Oliveira)
200
 
    Version 6, September 16, 2013
201
 
        Add EGL_WAYLAND_Y_INVERTED_WL attribute to allow specifying
202
 
        wl_buffer's orientation.