Subversion Repositories Kolibri OS

Rev

Go to most recent revision | Blame | Last modification | View Log | RSS feed

  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 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 Høgsberg)
  169.     Version 3, July 10, 2012
  170.         Add eglQueryWaylandBufferWL and the various buffer
  171.         formats. (Kristian Høgsberg)
  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 Høgsberg)
  176.