• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1Name
2
3    ARM_pixmap_multisample_discard
4
5Name Strings
6
7    EGL_ARM_pixmap_multisample_discard
8
9Contributors
10
11    Arne Bergene Fossaa
12    Tom Cooksey
13    Endre Sund
14    David Garbett
15
16Contacts
17
18    Tom Cooksey (tom 'dot' cooksey 'at' arm 'dot' com)
19
20Status
21
22    Complete.
23
24Version
25
26    Version 1, March 5, 2013
27
28Number
29
30    EGL Extension #54
31
32Dependencies
33
34    EGL 1.0 is required.
35
36    This extension is written against the wording of the EGL 1.4 Specification.
37
38Overview
39
40    ARM_pixmap_multisample_discard adds an attribute to eglCreatePixmapSurface
41    that allows the client API implementation to resolve a multisampled pixmap
42    surface, therefore allowing the multisample buffer to be discarded.
43
44    Some GPU architectures - such as tile-based renderers - are capable of
45    performing multisampled rendering by storing multisample data in internal
46    high-speed memory and downsampling the data when writing out to external
47    memory after rendering has finished. Since per-sample data is never written
48    out to external memory, this approach saves bandwidth and storage space. In
49    this case multisample data gets discarded, however this is acceptable in
50    most cases.
51
52    The extension provides the EGL_DISCARD_SAMPLES_ARM attribute that allows
53    for implicit resolution when rendering to a pixmap surface. This complements
54    the OpenGL ES EXT_multisampled_render_to_texture extension which provides
55    similar functionality for rendering to an OpenGL ES texture.
56
57New Types
58
59    None
60
61New Procedures and Functions
62
63    None
64
65New Tokens
66
67    Accepted as an attribute name in the <attrib_list> argument of
68    eglCreatePixmapSurface and by the <attribute> parameter of eglQuerySurface:
69
70        EGL_DISCARD_SAMPLES_ARM    0x3286
71
72Changes to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors)
73
74    Modify the second paragraph under "The Multisample Buffer" of Section 3.4,
75    page 18 (Configuration Management)
76
77    "Operations such as posting a surface with eglSwapBuffers (see section
78    3.9.1, copying a surface with eglCopyBuffers (see section 3.9.2), reading
79    from the color buffer using client API commands, binding a client API
80    context to a surface (see section 3.7.3), and flushing to a pixmap surface
81    created with the EGL_DISCARD_SAMPLES_ARM attribute enabled (see
82    section 3.5.4) may cause resolution of the multisample buffer to the color
83    buffer."
84
85    Modify the fifth paragraph under "The Multisample Buffer" of Section 3.4,
86    page 18 (Configuration Management)
87
88    "There are no single-sample depth or stencil buffers for a multisample
89    EGLConfig, or with a pixmap surface created with the
90    EGL_DISCARD_SAMPLES_ARM attribute (see section 3.5.4). The only depth and
91    stencil buffers are those in the multisample buffer. If the color samples
92    in the multisample buffer store fewer bits than are stored in the color
93    buffers, this fact will not be reported accurately.  Presumably a
94    compression scheme is being employed, and is expected to maintain an
95    aggregate resolution equal to that of the color buffers."
96
97    Modify the fifth paragraph of Section 3.5.4, page 34 (Creating Native
98    Pixmap Rendering Surfaces)
99
100    "attrib list specifies a list of attributes for the pixmap. The list has the
101    same structure as described for eglChooseConfig. Attributes that can be
102    specified in attrib list include EGL_VG_COLORSPACE, EGL_VG_ALPHA_FORMAT and
103    EGL_DISCARD_SAMPLES_ARM."
104
105    Add the following between paragraphs eight and nine of Section 3.5.4,
106    page 34 (Creating Native Pixmap Rendering Surfaces)
107
108    "EGL_DISCARD_SAMPLES_ARM specifies whether the client API implementation is
109    allowed to implicitly resolve the multisample buffer. On some GPU
110    architectures - such as tile-based renderers - an implicit resolve can avoid
111    writing the multisample buffer back to external memory as the multisample
112    data is stored in internal high-speed memory.
113
114    The implicit resolve can occur when the client API uses the pixmap as the
115    source or destination of any operation, when flushing to the pixmap or when
116    the client API unbinds (or breaks) the pixmap. When these operations occur
117    is dependent on the client API implementation. They can occur as an explicit
118    part of client API functions (such as glFinish, glReadPixels and
119    glCopyTexImage) or they can occur implicitly.
120
121    Further rendering causes the implementation to read the surface buffer and
122    any ancillary buffers back in as single-sampled data.
123    Therefore use of this attribute may result in lower quality images.
124
125    Valid values are EGL_TRUE, in which case the multisample buffer can be
126    discarded, or EGL_FALSE, in which case the multisample buffer is preserved.
127    The default value is EGL_FALSE.
128
129    Note that the multisample buffer may be discarded during eglMakeCurrent
130    regardless of the value of the EGL_DISCARD_SAMPLES_ARM attribute (see
131    section 3.7.3)."
132
133    Modify the ninth paragraph of Section 3.5.4, page 34 (Creating Native
134    Pixmap Rendering Surfaces)
135
136    "On failure eglCreatePixmapSurface returns EGL_NO_SURFACE. If the attributes
137    of pixmap do not correspond to config, then an EGL_BAD_MATCH error is
138    generated. If config does not support rendering to pixmaps (the
139    EGL_SURFACE_TYPE attribute does not contain EGL_PIXMAP_BIT), an
140    EGL_BAD_MATCH error is generated. If config does not support the colorspace
141    or alpha format attributes specified in attriblist (as defined for
142    eglCreateWindowSurface), an EGL_BAD_MATCH error is generated. If config does
143    not specify non-zero EGL_SAMPLES and EGL_SAMPLE_BUFFERS and the
144    EGL_DISCARD_SAMPLES_ARM attribute is set to EGL_TRUE, then an EGL_BAD_MATCH
145    error is generated. If config is not a valid EGLConfig, an EGL_BAD_CONFIG
146    error is generated. If pixmap is not a valid native pixmap handle, then an
147    EGL_BAD_NATIVE_PIXMAP error should be generated. If there is already an
148    EGLSurface associated with pixmap (as a result of a previous
149    eglCreatePixmapSurface call), then a EGL_BAD_ALLOC error is generated.
150    Finally, if the implementation cannot allocate resources for the new EGL
151    pixmap, an EGL_BAD_ALLOC error is generated."
152
153
154    Add the following entry to Table 3.5, page 36
155    (Queryable surface attributes and types)
156
157    Attribute                 Type    Description
158    ------------------------- ------- ---------------------------------------
159    EGL_DISCARD_SAMPLES_ARM   boolean Multisample resolve when flushing to
160                                      surface
161
162    Add the following paragraph before the last paragraph of Section 3.5.7,
163    page 38 (Surface Attributes)
164
165    "Querying EGL_DISCARD_SAMPLES_ARM returns whether a multisample resolve
166    is forced on every flush to the surface (see section 3.5.4). This will only
167    return EGL_TRUE for pixmap surfaces created with the EGL_DISCARD_SAMPLES_ARM
168    attribute set to EGL_TRUE. EGL_FALSE will be returned for window and
169    pbuffer surfaces."
170
171Issues
172
173    1. Should eglSurfaceAttrib accept EGL_DISCARD_SAMPLES_ARM?
174       RESOLVED: No. The attribute should be decided at surface creation time.
175
176    2. Should eglCreateWindowSurface or eglCreatePbufferSurface accept
177       EGL_DISCARD_SAMPLES_ARM?
178       RESOLVED: No. While the attribute could equally apply to window and
179       pbuffer surfaces, no use case has been identified to justify the
180       additional maintenance this would require.
181
182Revision History
183
184    Version 1, 2013/03/05 - Original release.
185
186