← Back to branch summary

~mmach/netext73/mesa-haswell

« back to all changes in this revision

Viewing changes to docs/_extra/specs/MESA_drm_image.spec

  • Committer: mmach
  • Date: 2022-09-22 19:56:13 UTC
  • Revision ID: netbit73@gmail.com-20220922195613-wtik9mmy20tmor0i
2022-09-22 21:17:09

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/_extra/specs/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.