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 Hgsberg <krh@bitplanet.net> 12 Benjamin Franzke <benjaminfranzke@googlemail.com> 13 14 Status 15 16 Proposal 17 18 Version 19 20 Version 1, March 1, 2011 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_buffer *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 79 80 Additions 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 160 Issues 161 162 Revision 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 Hgsberg) 169 Version 3, July 10, 2012 170 Add eglQueryWaylandBufferWL and the various buffer 171 formats. (Kristian Hgsberg) 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 Hgsberg) 176
