docs/specs/MESA_image_dma_buf_export.txt

   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
  19     Complete, shipping.
  20
  21 Version
  22
  23     Version 3, May 5, 2015
  24
  25 Number
  26
  27     EGL Extension #87
  28
  29 Dependencies
  30
  31     Requires EGL 1.4 or later.  This extension is written against the
  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
  46     It is designed to provide the complementary functionality to
  47     EGL_EXT_image_dma_buf_import.
  48
  49 IP Status
  50
  51     Open-source; freely implementable.
  52
  53 New Types
  54
  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.
  59
  60     typedef khronos_uint64_t EGLuint64KHR;
  61
  62 New Procedures and Functions
  63
  64     EGLBoolean eglExportDMABUFImageQueryMESA(EGLDisplay dpy,
  65                                   EGLImageKHR image,
  66                                   int *fourcc,
  67                                   int *num_planes,
  68                                   EGLuint64KHR *modifiers);
  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,
  95                                   EGLuint64KHR *modifiers);
  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
 141     Version 3, May, 2015
 142         Just use the KHR 64-bit type.
 143     Version 2, March, 2015
 144         Add a query interface (Dave Airlie)
 145     Version 1, June 3, 2014
 146         Initial draft (Dave Airlie)
 147