docs/specs/WL_create_wayland_buffer_from_image.spec

   1 Name
   2
   3     WL_create_wayland_buffer_from_image
   4
   5 Name Strings
   6
   7     EGL_WL_create_wayland_buffer_from_image
   8
   9 Contributors
  10
  11     Neil Roberts
  12     Axel Davy
  13     Daniel Stone
  14
  15 Contact
  16
  17     Neil Roberts <neil.s.roberts@intel.com>
  18
  19 Status
  20
  21     Proposal
  22
  23 Version
  24
  25     Version 2, October 25, 2013
  26
  27 Number
  28
  29     EGL Extension #not assigned
  30
  31 Dependencies
  32
  33     Requires EGL 1.4 or later.  This extension is written against the
  34     wording of the EGL 1.4 specification.
  35
  36     EGL_KHR_base_image is required.
  37
  38 Overview
  39
  40     This extension provides an entry point to create a wl_buffer which shares
  41     its contents with a given EGLImage. The expected use case for this is in a
  42     nested Wayland compositor which is using subsurfaces to present buffers
  43     from its clients. Using this extension it can attach the client buffers
  44     directly to the subsurface without having to blit the contents into an
  45     intermediate buffer. The compositing can then be done in the parent
  46     compositor.
  47
  48     The nested compositor can create an EGLImage from a client buffer resource
  49     using the existing WL_bind_wayland_display extension. It should also be
  50     possible to create buffers using other types of images although there is
  51     no expected use case for that.
  52
  53 IP Status
  54
  55     Open-source; freely implementable.
  56
  57 New Procedures and Functions
  58
  59     struct wl_buffer *eglCreateWaylandBufferFromImageWL(EGLDisplay dpy,
  60                                                         EGLImageKHR image);
  61
  62 New Tokens
  63
  64     None.
  65
  66 Additions to the EGL 1.4 Specification:
  67
  68     To create a client-side wl_buffer from an EGLImage call
  69
  70       struct wl_buffer *eglCreateWaylandBufferFromImageWL(EGLDisplay dpy,
  71                                                           EGLImageKHR image);
  72
  73     The returned buffer will share the contents with the given EGLImage. Any
  74     updates to the image will also be updated in the wl_buffer. Typically the
  75     EGLImage will be generated in a nested Wayland compositor using a buffer
  76     resource from a client via the EGL_WL_bind_wayland_display extension.
  77
  78     If there was an error then the function will return NULL. In particular it
  79     will generate EGL_BAD_MATCH if the implementation is not able to represent
  80     the image as a wl_buffer. The possible reasons for this error are
  81     implementation-dependant but may include problems such as an unsupported
  82     format or tiling mode or that the buffer is in memory that is inaccessible
  83     to the GPU that the given EGLDisplay is using.
  84
  85 Issues
  86
  87     1) Under what circumstances can the EGL_BAD_MATCH error be generated? Does
  88        this include for example unsupported tiling modes?
  89
  90        RESOLVED: Yes, the EGL_BAD_MATCH error can be generated for any reason
  91        which prevents the implementation from representing the image as a
  92        wl_buffer. For example, these problems can be but are not limited to
  93        unsupported tiling modes, inaccessible memory or an unsupported pixel
  94        format.
  95
  96 Revision History
  97
  98     Version 1, September 6, 2013
  99         Initial draft (Neil Roberts)
 100     Version 2, October 25, 2013
 101         Added a note about more possible reasons for returning EGL_BAD_FORMAT.