MESA_drm_image.spec revision b7a8893a2413adfddf4dc836676a19463fb6ffd7 
1Name
2
3    MESA_drm_image
4
5Name Strings
6
7    EGL_MESA_drm_image
8
9Contact
10
11    Kristian Høgsberg <krh@bitplanet.net>
12
13Status
14
15    Proposal
16
17Version
18
19    Version 2, August 25, 2010
20
21Number
22
23    EGL Extension #not assigned
24
25Dependencies
26
27    Reguires EGL 1.4 or later.  This extension is written against the
28    wording of the EGL 1.4 specification.
29
30    EGL_KHR_base_image is required.
31
32Overview
33
34    This extension provides entry points for integrating EGLImage with the
35    Linux DRM mode setting and memory management drivers.  The extension
36    lets applications create EGLImages without a client API resource and
37    lets the application get the DRM buffer handles.
38
39IP Status
40
41    Open-source; freely implementable.
42
43New Procedures and Functions
44
45    EGLImageKHR eglCreateDRMImageMESA(EGLDisplay dpy,
46                                      const EGLint *attrib_list);
47
48    EGLBoolean eglExportDRMImageMESA(EGLDisplay dpy,
49                                     EGLImageKHR image,
50                                     EGLint *name,
51				     EGLint *handle,
52				     EGLint *stride);
53
54New Tokens
55
56    Accepted in the <attrib_list> parameter of eglCreateDRMImageMESA:
57
58        EGL_DRM_BUFFER_FORMAT_MESA		0x31D0
59        EGL_DRM_BUFFER_USE_MESA			0x31D1
60
61    Accepted as values for the EGL_IMAGE_FORMAT_MESA attribute:
62
63        EGL_DRM_BUFFER_FORMAT_ARGB32_MESA	0x31D2
64
65    Bits accepted in EGL_DRM_BUFFER_USE_MESA:
66
67        EGL_DRM_BUFFER_USE_SCANOUT_MESA		0x0001
68        EGL_DRM_BUFFER_USE_SHARE_MESA		0x0002
69
70    Accepted in the <target> parameter of eglCreateImageKHR:
71
72        EGL_DRM_BUFFER_MESA			0x31D3
73
74    Use when importing drm buffer:
75
76        EGL_DRM_BUFFER_STRIDE_MESA		0x31D4
77        EGL_DRM_BUFFER_FORMAT_MESA		0x31D0
78
79Additions to the EGL 1.4 Specification:
80
81    To create a DRM EGLImage, call
82
83        EGLImageKHR eglCreateDRMImageMESA(EGLDisplay dpy,
84                                          const EGLint *attrib_list);
85
86    In the attribute list, pass EGL_WIDTH, EGL_EIGHT and format and
87    use in the attrib list using EGL_DRM_BUFFER_FORMAT_MESA and
88    EGL_DRM_BUFFER_USE_MESA.  The only format specified by this
89    extension is EGL_DRM_BUFFER_FORMAT_ARGB32_MESA, where each pixel
90    is a CPU-endian, 32-bit quantity, with alpha in the upper 8 bits,
91    then red, then green, then blue.  The bit values accepted by
92    EGL_DRM_BUFFER_USE_MESA are EGL_DRM_BUFFER_USE_SCANOUT_MESA and
93    EGL_DRM_BUFFER_USE_SHARE_MESA.  EGL_DRM_BUFFER_USE_SCANOUT_MESA
94    requests that the created EGLImage should be usable as a scanout
95    buffer with the DRM kernel modesetting API.  The
96    EGL_DRM_BUFFER_USE_SHARE_MESA bit requests that the EGLImage can
97    be shared with other processes by passing the underlying DRM
98    buffer name.
99
100    To create a process local handle or a global DRM name for a
101    buffer, call
102
103        EGLBoolean eglExportDRMImageMESA(EGLDisplay dpy,
104                                         EGLImageKHR image,
105                                         EGLint *name,
106                                         EGLint *handle,
107                                         EGLint *stride);
108
109    If <name> is non-NULL, a global name is assigned to the image and
110    written to <name>, the handle (local to the DRM file descriptor,
111    for use with DRM kernel modesetting API) is written to <handle> if
112    non-NULL and the stride (in bytes) is written to <stride>, if
113    non-NULL.
114
115    Import a shared buffer by calling eglCreateImageKHR with
116    EGL_DRM_BUFFER_MESA as the target, using EGL_WIDTH, EGL_HEIGHT,
117    EGL_DRM_BUFFER_FORMAT_MESA, EGL_DRM_BUFFER_STRIDE_MESA
118    in the attrib list.
119
120Issues
121
122    1.  Why don't we use eglCreateImageKHR with a target that
123        indicates that we want to create an EGLImage from scratch?
124
125        RESOLVED: The eglCreateImageKHR entry point is reserved for
126        creating an EGLImage from an already existing client API
127        resource.  This is fine when we're creating the EGLImage from
128        an existing DRM buffer name, it doesn't seem right to overload
129        the function to also allocate the underlying resource.
130
131    2.  Why don't we use an eglQueryImageMESA type functions for
132        querying the DRM EGLImage attributes (name, handle, and stride)?
133
134        RESOLVED: The eglQueryImage function has been proposed often,
135        but it goes against the EGLImage design.  EGLImages are opaque
136        handles to a 2D array of pixels, which can be passed between
137        client APIs.  By referenceing an EGLImage in a client API, the
138        EGLImage target (a texture, a renderbuffer or such) can be
139        used to query the attributes of the EGLImage.  We don't have a
140        full client API for creating and querying DRM buffers, though,
141        so we use a new EGL extension entry point instead.
142
143Revision History
144
145    Version 1, June 3, 2010
146        Initial draft (Kristian Høgsberg)
147    Version 2, August 25, 2010
148        Flesh out the extension a bit, add final EGL tokens, capture
149        some of the original discussion in the issues section.
150