← Back to branch summary

~mmach/netext73/mesa-haswell

« back to all changes in this revision

Viewing changes to docs/_extra/specs/MESA_image_dma_buf_export.txt

  • Committer: mmach
  • Date: 2022-09-22 19:56:13 UTC
  • Revision ID: netbit73@gmail.com-20220922195613-wtik9mmy20tmor0i
2022-09-22 21:17:09

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/_extra/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