1 Name 2 3 MESA_drm_image 4 5 Name Strings 6 7 EGL_MESA_drm_image 8 9 Contact 10 11 Kristian Hgsberg <krh@bitplanet.net> 12 13 Status 14 15 Proposal 16 17 Version 18 19 Version 2, August 25, 2010 20 21 Number 22 23 EGL Extension #not assigned 24 25 Dependencies 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 32 Overview 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 39 IP Status 40 41 Open-source; freely implementable. 42 43 New 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 54 New 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 80 Additions 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 124 Issues 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 147 Revision History 148 149 Version 1, June 3, 2010 150 Initial draft (Kristian Hgsberg) 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
