aboutsummaryrefslogtreecommitdiff
path: root/mesalib/docs/specs
diff options
context:
space:
mode:
Diffstat (limited to 'mesalib/docs/specs')
-rw-r--r--mesalib/docs/specs/MESA_image_dma_buf_export.txt142
1 files changed, 142 insertions, 0 deletions
diff --git a/mesalib/docs/specs/MESA_image_dma_buf_export.txt b/mesalib/docs/specs/MESA_image_dma_buf_export.txt
new file mode 100644
index 000000000..c3794ee36
--- /dev/null
+++ b/mesalib/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. <fourcc>, <num_planes> and <modifiers> 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);
+
+ <fds>, <strides>, <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)
+