docs/MESA_drm_image.spec

   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     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 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.