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