Benjamin Franzke | 6b369c4 | 2011-02-21 16:22:34 +0100 | [diff] [blame] | 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 | |
Ander Conselvan de Oliveira | 8d29b52 | 2013-07-18 15:11:25 +0300 | [diff] [blame] | 20 | Version 5, July 16, 2013 |
Benjamin Franzke | 6b369c4 | 2011-02-21 16:22:34 +0100 | [diff] [blame] | 21 | |
| 22 | Number |
| 23 | |
| 24 | EGL Extension #not assigned |
| 25 | |
| 26 | Dependencies |
| 27 | |
Nicolas Kaiser | 82cb6e6 | 2011-04-10 05:04:44 -0700 | [diff] [blame] | 28 | Requires EGL 1.4 or later. This extension is written against the |
Benjamin Franzke | 6b369c4 | 2011-02-21 16:22:34 +0100 | [diff] [blame] | 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 | |
Nicolas Kaiser | 82cb6e6 | 2011-04-10 05:04:44 -0700 | [diff] [blame] | 43 | Adding an implementation specific wayland interface, allows the |
Benjamin Franzke | 6b369c4 | 2011-02-21 16:22:34 +0100 | [diff] [blame] | 44 | EGL implementation to define specific wayland requests and events, |
Nicolas Kaiser | 82cb6e6 | 2011-04-10 05:04:44 -0700 | [diff] [blame] | 45 | needed for buffer sharing in an EGL wayland platform. |
Benjamin Franzke | 6b369c4 | 2011-02-21 16:22:34 +0100 | [diff] [blame] | 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 | |
Kristian Høgsberg | e6a3357 | 2012-07-05 16:43:04 -0400 | [diff] [blame] | 59 | EGLBoolean eglQueryWaylandBufferWL(EGLDisplay dpy, |
Ander Conselvan de Oliveira | 8d29b52 | 2013-07-18 15:11:25 +0300 | [diff] [blame] | 60 | struct wl_resource *buffer, |
Kristian Høgsberg | e6a3357 | 2012-07-05 16:43:04 -0400 | [diff] [blame] | 61 | EGLint attribute, EGLint *value); |
| 62 | |
Benjamin Franzke | 6b369c4 | 2011-02-21 16:22:34 +0100 | [diff] [blame] | 63 | New Tokens |
| 64 | |
| 65 | Accepted as <target> in eglCreateImageKHR |
| 66 | |
| 67 | EGL_WAYLAND_BUFFER_WL 0x31D5 |
| 68 | |
Kristian Høgsberg | e6a3357 | 2012-07-05 16:43:04 -0400 | [diff] [blame] | 69 | Accepted in the <attrib_list> parameter of eglCreateImageKHR: |
| 70 | |
| 71 | EGL_WAYLAND_PLANE_WL 0x31D6 |
| 72 | |
Kristian Høgsberg | e23bfdb | 2012-07-19 08:54:05 -0400 | [diff] [blame] | 73 | Possible values for EGL_TEXTURE_FORMAT: |
Kristian Høgsberg | e6a3357 | 2012-07-05 16:43:04 -0400 | [diff] [blame] | 74 | |
Kristian Høgsberg | e23bfdb | 2012-07-19 08:54:05 -0400 | [diff] [blame] | 75 | EGL_TEXTURE_Y_U_V_WL 0x31D7 |
| 76 | EGL_TEXTURE_Y_UV_WL 0x31D8 |
| 77 | EGL_TEXTURE_Y_XUXV_WL 0x31D9 |
Rob Clark | 8ca14b0 | 2012-08-16 17:28:19 -0500 | [diff] [blame] | 78 | EGL_TEXTURE_EXTERNAL_WL 0x31DA |
Kristian Høgsberg | e6a3357 | 2012-07-05 16:43:04 -0400 | [diff] [blame] | 79 | |
Stanislav Vorobiov | 1281a90 | 2013-09-16 13:02:46 +0400 | [diff] [blame] | 80 | Accepted in the <attribute> parameter of eglQueryWaylandBufferWL: |
| 81 | |
Kristian Høgsberg | a1b6e69 | 2013-09-16 22:22:49 -0700 | [diff] [blame] | 82 | EGL_TEXTURE_FORMAT 0x3080 |
Stanislav Vorobiov | 1281a90 | 2013-09-16 13:02:46 +0400 | [diff] [blame] | 83 | EGL_WAYLAND_Y_INVERTED_WL 0x31DB |
| 84 | |
Kristian Høgsberg | e6a3357 | 2012-07-05 16:43:04 -0400 | [diff] [blame] | 85 | |
Benjamin Franzke | 6b369c4 | 2011-02-21 16:22:34 +0100 | [diff] [blame] | 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 | |
Kristian Høgsberg | e6a3357 | 2012-07-05 16:43:04 -0400 | [diff] [blame] | 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 |
Kristian Høgsberg | e23bfdb | 2012-07-19 08:54:05 -0400 | [diff] [blame] | 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 |
Kristian Høgsberg | e6a3357 | 2012-07-05 16:43:04 -0400 | [diff] [blame] | 114 | contents. |
| 115 | |
| 116 | If eglQueryWaylandBufferWL succeeds, the returned value will be |
Kristian Høgsberg | e23bfdb | 2012-07-19 08:54:05 -0400 | [diff] [blame] | 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. |
Kristian Høgsberg | e6a3357 | 2012-07-05 16:43:04 -0400 | [diff] [blame] | 126 | |
| 127 | RGB and RGBA buffer types: |
| 128 | |
Kristian Høgsberg | e23bfdb | 2012-07-19 08:54:05 -0400 | [diff] [blame] | 129 | EGL_TEXTURE_RGB |
Kristian Høgsberg | e6a3357 | 2012-07-05 16:43:04 -0400 | [diff] [blame] | 130 | One plane, samples RGB from the texture to rgb in the |
| 131 | shader. Alpha channel is not valid. |
| 132 | |
Kristian Høgsberg | e23bfdb | 2012-07-19 08:54:05 -0400 | [diff] [blame] | 133 | EGL_TEXTURE_RGBA |
Kristian Høgsberg | e6a3357 | 2012-07-05 16:43:04 -0400 | [diff] [blame] | 134 | One plane, samples RGBA from the texture to rgba in the |
| 135 | shader. |
| 136 | |
| 137 | YUV buffer types: |
| 138 | |
Kristian Høgsberg | e23bfdb | 2012-07-19 08:54:05 -0400 | [diff] [blame] | 139 | EGL_TEXTURE_Y_U_V_WL |
Kristian Høgsberg | e6a3357 | 2012-07-05 16:43:04 -0400 | [diff] [blame] | 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 | |
Kristian Høgsberg | e23bfdb | 2012-07-19 08:54:05 -0400 | [diff] [blame] | 144 | EGL_TEXTURE_Y_UV_WL |
Kristian Høgsberg | e6a3357 | 2012-07-05 16:43:04 -0400 | [diff] [blame] | 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 | |
Kristian Høgsberg | e23bfdb | 2012-07-19 08:54:05 -0400 | [diff] [blame] | 148 | EGL_TEXTURE_Y_XUXV_WL |
Kristian Høgsberg | e6a3357 | 2012-07-05 16:43:04 -0400 | [diff] [blame] | 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 | |
Rob Clark | 8ca14b0 | 2012-08-16 17:28:19 -0500 | [diff] [blame] | 152 | EGL_TEXTURE_EXTERNAL_WL |
| 153 | Treated as a single plane texture, but sampled with |
| 154 | samplerExternalOES according to OES_EGL_image_external |
| 155 | |
Kristian Høgsberg | e6a3357 | 2012-07-05 16:43:04 -0400 | [diff] [blame] | 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. |
Benjamin Franzke | 6b369c4 | 2011-02-21 16:22:34 +0100 | [diff] [blame] | 166 | |
Kristian Høgsberg | d7522ed | 2012-07-19 09:02:25 -0400 | [diff] [blame] | 167 | Further, eglQueryWaylandBufferWL accepts attributes EGL_WIDTH and |
| 168 | EGL_HEIGHT to query the width and height of the wl_buffer. |
| 169 | |
Stanislav Vorobiov | 1281a90 | 2013-09-16 13:02:46 +0400 | [diff] [blame] | 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 | |
Benjamin Franzke | 6b369c4 | 2011-02-21 16:22:34 +0100 | [diff] [blame] | 180 | Issues |
| 181 | |
| 182 | Revision History |
| 183 | |
| 184 | Version 1, March 1, 2011 |
| 185 | Initial draft (Benjamin Franzke) |
Kristian Høgsberg | e6a3357 | 2012-07-05 16:43:04 -0400 | [diff] [blame] | 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) |
Kristian Høgsberg | e23bfdb | 2012-07-19 08:54:05 -0400 | [diff] [blame] | 192 | Version 4, July 19, 2012 |
| 193 | Use EGL_TEXTURE_FORMAT, EGL_TEXTURE_RGB, and EGL_TEXTURE_RGBA, |
Kristian Høgsberg | d7522ed | 2012-07-19 09:02:25 -0400 | [diff] [blame] | 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) |
Ander Conselvan de Oliveira | 8d29b52 | 2013-07-18 15:11:25 +0300 | [diff] [blame] | 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) |
Stanislav Vorobiov | 1281a90 | 2013-09-16 13:02:46 +0400 | [diff] [blame] | 200 | Version 6, September 16, 2013 |
| 201 | Add EGL_WAYLAND_Y_INVERTED_WL attribute to allow specifying |
| 202 | wl_buffer's orientation. |