Kristian Høgsberg | b7a8893a | 2010-06-04 14:28:59 -0400 | [diff] [blame] | 1 | Name |
| 2 | |
| 3 | MESA_drm_image |
| 4 | |
| 5 | Name Strings |
| 6 | |
| 7 | EGL_MESA_drm_image |
| 8 | |
| 9 | Contact |
| 10 | |
| 11 | Kristian Høgsberg <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 | |
Nicolas Kaiser | ae5776c | 2011-04-10 09:58:50 -0600 | [diff] [blame] | 27 | Requires EGL 1.4 or later. This extension is written against the |
Kristian Høgsberg | b7a8893a | 2010-06-04 14:28:59 -0400 | [diff] [blame] | 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 |
Kristian Høgsberg | e5169e9 | 2011-05-06 10:31:18 -0400 | [diff] [blame] | 69 | EGL_DRM_BUFFER_USE_CURSOR_MESA 0x0004 |
Kristian Høgsberg | b7a8893a | 2010-06-04 14:28:59 -0400 | [diff] [blame] | 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 | |
Kristian Høgsberg | 7db4985 | 2010-11-29 21:04:43 -0500 | [diff] [blame] | 87 | In the attribute list, pass EGL_WIDTH, EGL_HEIGHT and format and |
Kristian Høgsberg | b7a8893a | 2010-06-04 14:28:59 -0400 | [diff] [blame] | 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 |
Kristian Høgsberg | e5169e9 | 2011-05-06 10:31:18 -0400 | [diff] [blame] | 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. |
Kristian Høgsberg | b7a8893a | 2010-06-04 14:28:59 -0400 | [diff] [blame] | 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 |
Nicolas Kaiser | ae5776c | 2011-04-10 09:58:50 -0600 | [diff] [blame] | 141 | client APIs. By referencing an EGLImage in a client API, the |
Kristian Høgsberg | b7a8893a | 2010-06-04 14:28:59 -0400 | [diff] [blame] | 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 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. |