1Name
2
3    WL_create_wayland_buffer_from_image
4
5Name Strings
6
7    EGL_WL_create_wayland_buffer_from_image
8
9Contributors
10
11    Neil Roberts
12    Axel Davy
13    Daniel Stone
14
15Contact
16
17    Neil Roberts <neil.s.roberts@intel.com>
18
19Status
20
21    Proposal
22
23Version
24
25    Version 2, October 25, 2013
26
27Number
28
29    EGL Extension #not assigned
30
31Dependencies
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
38Overview
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
53IP Status
54
55    Open-source; freely implementable.
56
57New Procedures and Functions
58
59    struct wl_buffer *eglCreateWaylandBufferFromImageWL(EGLDisplay dpy,
60                                                        EGLImageKHR image);
61
62New Tokens
63
64    None.
65
66Additions 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
85Issues
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
96Revision 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.
102