Kristian Høgsberg | b7a8893 | 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 | |
| 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 | |
Kristian Høgsberg | 7db4985 | 2010-11-29 21:04:43 -0500 | [diff] [blame^] | 86 | In the attribute list, pass EGL_WIDTH, EGL_HEIGHT and format and |
Kristian Høgsberg | b7a8893 | 2010-06-04 14:28:59 -0400 | [diff] [blame] | 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 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. |