Subversion Repositories Kolibri OS

Rev

Go to most recent revision | Blame | Last modification | View Log | RSS feed

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