Neil Roberts | 5cddb1c | 2013-10-28 15:07:03 +0000 | [diff] [blame] | 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. |