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    Requires 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        EGL_DRM_BUFFER_USE_CURSOR_MESA		0x0004
70
71    Accepted in the <target> parameter of eglCreateImageKHR:
72
73        EGL_DRM_BUFFER_MESA			0x31D3
74
75    Use when importing drm buffer:
76
77        EGL_DRM_BUFFER_STRIDE_MESA		0x31D4
78        EGL_DRM_BUFFER_FORMAT_MESA		0x31D0
79
80Additions to the EGL 1.4 Specification:
81
82    To create a DRM EGLImage, call
83
84        EGLImageKHR eglCreateDRMImageMESA(EGLDisplay dpy,
85                                          const EGLint *attrib_list);
86
87    In the attribute list, pass EGL_WIDTH, EGL_HEIGHT and format and
88    use in the attrib list using EGL_DRM_BUFFER_FORMAT_MESA and
89    EGL_DRM_BUFFER_USE_MESA.  The only format specified by this
90    extension is EGL_DRM_BUFFER_FORMAT_ARGB32_MESA, where each pixel
91    is a CPU-endian, 32-bit quantity, with alpha in the upper 8 bits,
92    then red, then green, then blue.  The bit values accepted by
93    EGL_DRM_BUFFER_USE_MESA are EGL_DRM_BUFFER_USE_SCANOUT_MESA,
94    EGL_DRM_BUFFER_USE_SHARE_MESA and EGL_DRM_BUFFER_USE_CURSOR_MESA.
95    EGL_DRM_BUFFER_USE_SCANOUT_MESA requests that the created EGLImage
96    should be usable as a scanout buffer with the DRM kernel
97    modesetting API.  EGL_DRM_BUFFER_USE_SHARE_MESA requests that the
98    EGLImage can be shared with other processes by passing the
99    underlying DRM buffer name.  EGL_DRM_BUFFER_USE_CURSOR_MESA
100    requests that the image must be usable as a cursor with KMS.  When
101    EGL_DRM_BUFFER_USE_CURSOR_MESA is set, width and height must both
102    be 64.
103
104    To create a process local handle or a global DRM name for a
105    buffer, call
106
107        EGLBoolean eglExportDRMImageMESA(EGLDisplay dpy,
108                                         EGLImageKHR image,
109                                         EGLint *name,
110                                         EGLint *handle,
111                                         EGLint *stride);
112
113    If <name> is non-NULL, a global name is assigned to the image and
114    written to <name>, the handle (local to the DRM file descriptor,
115    for use with DRM kernel modesetting API) is written to <handle> if
116    non-NULL and the stride (in bytes) is written to <stride>, if
117    non-NULL.
118
119    Import a shared buffer by calling eglCreateImageKHR with
120    EGL_DRM_BUFFER_MESA as the target, using EGL_WIDTH, EGL_HEIGHT,
121    EGL_DRM_BUFFER_FORMAT_MESA, EGL_DRM_BUFFER_STRIDE_MESA
122    in the attrib list.
123
124Issues
125
126    1.  Why don't we use eglCreateImageKHR with a target that
127        indicates that we want to create an EGLImage from scratch?
128
129        RESOLVED: The eglCreateImageKHR entry point is reserved for
130        creating an EGLImage from an already existing client API
131        resource.  This is fine when we're creating the EGLImage from
132        an existing DRM buffer name, it doesn't seem right to overload
133        the function to also allocate the underlying resource.
134
135    2.  Why don't we use an eglQueryImageMESA type functions for
136        querying the DRM EGLImage attributes (name, handle, and stride)?
137
138        RESOLVED: The eglQueryImage function has been proposed often,
139        but it goes against the EGLImage design.  EGLImages are opaque
140        handles to a 2D array of pixels, which can be passed between
141        client APIs.  By referencing an EGLImage in a client API, the
142        EGLImage target (a texture, a renderbuffer or such) can be
143        used to query the attributes of the EGLImage.  We don't have a
144        full client API for creating and querying DRM buffers, though,
145        so we use a new EGL extension entry point instead.
146
147Revision History
148
149    Version 1, June 3, 2010
150        Initial draft (Kristian Høgsberg)
151    Version 2, August 25, 2010
152        Flesh out the extension a bit, add final EGL tokens, capture
153        some of the original discussion in the issues section.
154