1Name
2
3    MESA_image_dma_buf_export
4
5Name Strings
6
7    EGL_MESA_image_dma_buf_export
8
9Contributors
10
11    Dave Airlie
12
13Contact
14
15    Dave Airlie (airlied 'at' redhat 'dot' com)
16
17Status
18
19    Complete, shipping.
20
21Version
22
23    Version 3, May 5, 2015
24
25Number
26
27    EGL Extension #87
28
29Dependencies
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
39Overview
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
49IP Status
50
51    Open-source; freely implementable.
52
53New 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
62New 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
76New Tokens
77
78    None
79
80
81Additions 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
118Issues
119
1201. Should the API look more like an attribute getting API?
121
122ANSWER: No, from a user interface pov, having to iterate across calling
123the API up to 12 times using attribs seems like the wrong solution.
124
1252. Should the API take a plane and just get the fd/stride/offset for that
126   plane?
127
128ANSWER: UNKNOWN,this might be just as valid an API.
129
1303. Does ownership of the file descriptor remain with the app?
131
132ANSWER: Yes, the app is responsible for closing any fds retrieved.
133
1344. If number of planes and number of fds differ what should we do?
135
136ANSWER: Return -1 for the secondary slots, as this avoids having
137to dup the fd extra times to make the interface sane.
138
139Revision 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
148