docs/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.