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 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 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 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 79 Additions 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_HEIGHT 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 120 Issues 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 143 Revision History 144 145 Version 1, June 3, 2010 146 Initial draft (Kristian Hgsberg) 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
