From 8f7338f284cdb1fef64c85e3293d2200d0cc6387 Mon Sep 17 00:00:00 2001 From: Dave Airlie Date: Mon, 3 Mar 2014 13:57:16 +1000 Subject: egl: add initial EGL_MESA_image_dma_buf_export v2.4 At the moment to get an EGL image to a dma-buf file descriptor, you have to use EGL_MESA_drm_image, and then use libdrm to convert this to a file descriptor. This extension just provides an API modelled on EGL_MESA_drm_image, to return a dma-buf file descriptor. v2: update spec for new API proposal add internal queries to get the fourcc back from intel driver. v2.1: add gallium pieces. v2.2: add offsets to spec and API, rename fd->fds, stride->strides in API. rewrite spec a bit more, add some q/a v2.3: add modifiers to query interface and 64-bit type for that (Daniel Stone) specifiy what happens to num fds vs num planes differences. (Chad Versace) v2.4: fix grammar (Daniel Stone) Signed-off-by: Dave Airlie --- docs/specs/MESA_image_dma_buf_export.txt | 142 +++++++++++++++++++++++++++++++ 1 file changed, 142 insertions(+) create mode 100644 docs/specs/MESA_image_dma_buf_export.txt (limited to 'docs/specs') diff --git a/docs/specs/MESA_image_dma_buf_export.txt b/docs/specs/MESA_image_dma_buf_export.txt new file mode 100644 index 0000000..c3794ee --- /dev/null +++ b/docs/specs/MESA_image_dma_buf_export.txt @@ -0,0 +1,142 @@ +Name + + MESA_image_dma_buf_export + +Name Strings + + EGL_MESA_image_dma_buf_export + +Contributors + + Dave Airlie + +Contact + + Dave Airlie (airlied 'at' redhat 'dot' com) + +Status + + Proposal + +Version + + Version 2, Mar 30, 2015 + +Number + + EGL Extension #not assigned + +Dependencies + + Reguires EGL 1.4 or later. This extension is written against the + wording of the EGL 1.4 specification. + + EGL_KHR_base_image is required. + + The EGL implementation must be running on a Linux kernel supporting the + dma_buf buffer sharing mechanism. + +Overview + + This extension provides entry points for integrating EGLImage with the + dma-buf infrastructure. The extension allows creating a Linux dma_buf + file descriptor or multiple file descriptors, in the case of multi-plane + YUV image, from an EGLImage. + + It is designed to provide the complementary functionality to EGL_EXT_image_dma_buf_import. + +IP Status + + Open-source; freely implementable. + +New Types + + This is a 64 bit unsigned integer. + + typedef khronos_uint64_t EGLuint64MESA; + + +New Procedures and Functions + + EGLBoolean eglExportDMABUFImageQueryMESA(EGLDisplay dpy, + EGLImageKHR image, + int *fourcc, + int *num_planes, + EGLuint64MESA *modifiers); + + EGLBoolean eglExportDMABUFImageMESA(EGLDisplay dpy, + EGLImageKHR image, + int *fds, + EGLint *strides, + EGLint *offsets); + +New Tokens + + None + + +Additions to the EGL 1.4 Specification: + + To mirror the import extension, this extension attempts to return + enough information to enable an exported dma-buf to be imported + via eglCreateImageKHR and EGL_LINUX_DMA_BUF_EXT token. + + Retrieving the information is a two step process, so two APIs + are required. + + The first entrypoint + EGLBoolean eglExportDMABUFImageQueryMESA(EGLDisplay dpy, + EGLImageKHR image, + int *fourcc, + int *num_planes, + EGLuint64MESA *modifiers); + + is used to retrieve the pixel format of the buffer, as specified by + drm_fourcc.h, the number of planes in the image and the Linux + drm modifiers. , and may be NULL, + in which case no value is retrieved. + + The second entrypoint retrieves the dma_buf file descriptors, + strides and offsets for the image. The caller should pass + arrays sized according to the num_planes values retrieved previously. + Passing arrays of the wrong size will have undefined results. + If the number of fds is less than the number of planes, then + subsequent fd slots should contain -1. + + EGLBoolean eglExportDMABUFImageMESA(EGLDisplay dpy, + EGLImageKHR image, + int *fds, + EGLint *strides, + EGLint *offsets); + + , , can be NULL if the infomatation isn't + required by the caller. + +Issues + +1. Should the API look more like an attribute getting API? + +ANSWER: No, from a user interface pov, having to iterate across calling +the API up to 12 times using attribs seems like the wrong solution. + +2. Should the API take a plane and just get the fd/stride/offset for that + plane? + +ANSWER: UNKNOWN,this might be just as valid an API. + +3. Does ownership of the file descriptor remain with the app? + +ANSWER: Yes, the app is responsible for closing any fds retrieved. + +4. If number of planes and number of fds differ what should we do? + +ANSWER: Return -1 for the secondary slots, as this avoids having +to dup the fd extra times to make the interface sane. + +Revision History + + Version 2, March, 2015 + Add a query interface (Dave Airlie) + Version 1, June 3, 2014 + Initial draft (Dave Airlie) + -- cgit v1.1