Dave Airlie | 8f7338f | 2014-03-03 13:57:16 +1000 | [diff] [blame] | 1 | Name |
| 2 | |
| 3 | MESA_image_dma_buf_export |
| 4 | |
| 5 | Name Strings |
| 6 | |
| 7 | EGL_MESA_image_dma_buf_export |
| 8 | |
| 9 | Contributors |
| 10 | |
| 11 | Dave Airlie |
| 12 | |
| 13 | Contact |
| 14 | |
| 15 | Dave Airlie (airlied 'at' redhat 'dot' com) |
| 16 | |
| 17 | Status |
| 18 | |
Dave Airlie | b5045e2 | 2015-05-05 09:10:34 +1000 | [diff] [blame] | 19 | Complete, shipping. |
Dave Airlie | 8f7338f | 2014-03-03 13:57:16 +1000 | [diff] [blame] | 20 | |
| 21 | Version |
| 22 | |
Dave Airlie | b5045e2 | 2015-05-05 09:10:34 +1000 | [diff] [blame] | 23 | Version 3, May 5, 2015 |
Dave Airlie | 8f7338f | 2014-03-03 13:57:16 +1000 | [diff] [blame] | 24 | |
| 25 | Number |
| 26 | |
Dave Airlie | b5045e2 | 2015-05-05 09:10:34 +1000 | [diff] [blame] | 27 | EGL Extension #87 |
Dave Airlie | 8f7338f | 2014-03-03 13:57:16 +1000 | [diff] [blame] | 28 | |
| 29 | Dependencies |
| 30 | |
Dave Airlie | b5045e2 | 2015-05-05 09:10:34 +1000 | [diff] [blame] | 31 | Requires EGL 1.4 or later. This extension is written against the |
Dave Airlie | 8f7338f | 2014-03-03 13:57:16 +1000 | [diff] [blame] | 32 | wording of the EGL 1.4 specification. |
| 33 | |
| 34 | EGL_KHR_base_image is required. |
| 35 | |
| 36 | The EGL implementation must be running on a Linux kernel supporting the |
| 37 | dma_buf buffer sharing mechanism. |
| 38 | |
| 39 | Overview |
| 40 | |
| 41 | This extension provides entry points for integrating EGLImage with the |
| 42 | dma-buf infrastructure. The extension allows creating a Linux dma_buf |
| 43 | file descriptor or multiple file descriptors, in the case of multi-plane |
| 44 | YUV image, from an EGLImage. |
| 45 | |
Dave Airlie | b5045e2 | 2015-05-05 09:10:34 +1000 | [diff] [blame] | 46 | It is designed to provide the complementary functionality to |
| 47 | EGL_EXT_image_dma_buf_import. |
Dave Airlie | 8f7338f | 2014-03-03 13:57:16 +1000 | [diff] [blame] | 48 | |
| 49 | IP Status |
| 50 | |
| 51 | Open-source; freely implementable. |
| 52 | |
| 53 | New Types |
| 54 | |
Dave Airlie | b5045e2 | 2015-05-05 09:10:34 +1000 | [diff] [blame] | 55 | This extension uses the 64-bit unsigned integer type EGLuint64KHR |
| 56 | first introduced by the EGL_KHR_stream extension, but does not |
| 57 | depend on that extension. The typedef may be reproduced separately |
| 58 | for this extension, if not already present in eglext.h. |
Dave Airlie | 8f7338f | 2014-03-03 13:57:16 +1000 | [diff] [blame] | 59 | |
Dave Airlie | b5045e2 | 2015-05-05 09:10:34 +1000 | [diff] [blame] | 60 | typedef khronos_uint64_t EGLuint64KHR; |
Dave Airlie | 8f7338f | 2014-03-03 13:57:16 +1000 | [diff] [blame] | 61 | |
| 62 | New Procedures and Functions |
| 63 | |
| 64 | EGLBoolean eglExportDMABUFImageQueryMESA(EGLDisplay dpy, |
| 65 | EGLImageKHR image, |
| 66 | int *fourcc, |
| 67 | int *num_planes, |
Dave Airlie | b5045e2 | 2015-05-05 09:10:34 +1000 | [diff] [blame] | 68 | EGLuint64KHR *modifiers); |
Dave Airlie | 8f7338f | 2014-03-03 13:57:16 +1000 | [diff] [blame] | 69 | |
| 70 | EGLBoolean eglExportDMABUFImageMESA(EGLDisplay dpy, |
| 71 | EGLImageKHR image, |
| 72 | int *fds, |
| 73 | EGLint *strides, |
| 74 | EGLint *offsets); |
| 75 | |
| 76 | New Tokens |
| 77 | |
| 78 | None |
| 79 | |
| 80 | |
| 81 | Additions to the EGL 1.4 Specification: |
| 82 | |
| 83 | To mirror the import extension, this extension attempts to return |
| 84 | enough information to enable an exported dma-buf to be imported |
| 85 | via eglCreateImageKHR and EGL_LINUX_DMA_BUF_EXT token. |
| 86 | |
| 87 | Retrieving the information is a two step process, so two APIs |
| 88 | are required. |
| 89 | |
| 90 | The first entrypoint |
| 91 | EGLBoolean eglExportDMABUFImageQueryMESA(EGLDisplay dpy, |
| 92 | EGLImageKHR image, |
| 93 | int *fourcc, |
| 94 | int *num_planes, |
Dave Airlie | b5045e2 | 2015-05-05 09:10:34 +1000 | [diff] [blame] | 95 | EGLuint64KHR *modifiers); |
Dave Airlie | 8f7338f | 2014-03-03 13:57:16 +1000 | [diff] [blame] | 96 | |
| 97 | is used to retrieve the pixel format of the buffer, as specified by |
| 98 | drm_fourcc.h, the number of planes in the image and the Linux |
| 99 | drm modifiers. <fourcc>, <num_planes> and <modifiers> may be NULL, |
| 100 | in which case no value is retrieved. |
| 101 | |
| 102 | The second entrypoint retrieves the dma_buf file descriptors, |
| 103 | strides and offsets for the image. The caller should pass |
| 104 | arrays sized according to the num_planes values retrieved previously. |
| 105 | Passing arrays of the wrong size will have undefined results. |
| 106 | If the number of fds is less than the number of planes, then |
| 107 | subsequent fd slots should contain -1. |
| 108 | |
| 109 | EGLBoolean eglExportDMABUFImageMESA(EGLDisplay dpy, |
| 110 | EGLImageKHR image, |
| 111 | int *fds, |
| 112 | EGLint *strides, |
| 113 | EGLint *offsets); |
| 114 | |
| 115 | <fds>, <strides>, <offsets> can be NULL if the infomatation isn't |
| 116 | required by the caller. |
| 117 | |
| 118 | Issues |
| 119 | |
| 120 | 1. Should the API look more like an attribute getting API? |
| 121 | |
| 122 | ANSWER: No, from a user interface pov, having to iterate across calling |
| 123 | the API up to 12 times using attribs seems like the wrong solution. |
| 124 | |
| 125 | 2. Should the API take a plane and just get the fd/stride/offset for that |
| 126 | plane? |
| 127 | |
| 128 | ANSWER: UNKNOWN,this might be just as valid an API. |
| 129 | |
| 130 | 3. Does ownership of the file descriptor remain with the app? |
| 131 | |
| 132 | ANSWER: Yes, the app is responsible for closing any fds retrieved. |
| 133 | |
| 134 | 4. If number of planes and number of fds differ what should we do? |
| 135 | |
| 136 | ANSWER: Return -1 for the secondary slots, as this avoids having |
| 137 | to dup the fd extra times to make the interface sane. |
| 138 | |
| 139 | Revision History |
| 140 | |
Dave Airlie | b5045e2 | 2015-05-05 09:10:34 +1000 | [diff] [blame] | 141 | Version 3, May, 2015 |
| 142 | Just use the KHR 64-bit type. |
Dave Airlie | 8f7338f | 2014-03-03 13:57:16 +1000 | [diff] [blame] | 143 | Version 2, March, 2015 |
| 144 | Add a query interface (Dave Airlie) |
| 145 | Version 1, June 3, 2014 |
| 146 | Initial draft (Dave Airlie) |
| 147 | |