1-------------------------------------------------------------------------
2drawElements Quality Program Test Specification
3-----------------------------------------------
4
5Copyright 2014 The Android Open Source Project
6
7Licensed under the Apache License, Version 2.0 (the "License");
8you may not use this file except in compliance with the License.
9You may obtain a copy of the License at
10
11     http://www.apache.org/licenses/LICENSE-2.0
12
13Unless required by applicable law or agreed to in writing, software
14distributed under the License is distributed on an "AS IS" BASIS,
15WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16See the License for the specific language governing permissions and
17limitations under the License.
18-------------------------------------------------------------------------
19    Framebuffer completeness tests.
20
21Tests:
22 + dEQP-GLES2.functional.fbo.completeness.renderable.*
23 + dEQP-GLES2.functional.fbo.completeness.attachment_combinations.*
24 + dEQP-GLES2.functional.fbo.completeness.attachment_combinations.exists_supported
25 + dEQP-GLES2.functional.fbo.completeness.size.zero
26 + dEQP-GLES2.functional.fbo.completeness.size.distinct
27
28Includes:
29 + glCheckFramebufferStatus return value check
30 + Single attachments with all standard (and many extension) formats
31 + All combinations of color0, depth and stencil attachments
32   - And other color attachments if GL_NV_fbo_color_attachments is exposed
33 + Existence of a supported combination of formats
34 + Zero-sized attachment
35 + Differently sized attachments
36
37Excludes:
38 + Trying FBO operations on in/complete FBOs.
39 + Completeness status changes after the FBO is modified.
40
41Description:
42
43These tests check that the implementation reports framebuffer completeness
44status correctly. Most test cases create a single framebuffer object, create
45some renderbuffers and/or textures and attach them to the FBO, and then call
46glCheckFramebufferStatus on it. The returned value is compared against a set
47of legal return values that is calculated from the arguments given to image
48creation and attachment functions. The test passes if the return value is
49found in this set. Some test cases may also expect image creation to fail
50before it can be attached.
51
52For each test case, the test log shows the configurations of the created
53images and attachments, the set of expected status values and the actual
54returned status value.
55
56
57The "renderable.*" test cases iterate through all the texture formats and
58attachment points and attach a single texture or renderbuffer with that format
59at that attachment point.
60
61The purpose of these tests is to check that the implementation's notion of
62color/depth/stencil-renderability adheres to the GLES specification and
63extensions. Both renderability and non-renderability of unexpected formats are
64reported as test failures.
65
66Note that the GLES2 spec allows implementations to return
67GL_FRAMEBUFFER_UNSUPPORTED for practically any framebuffer configurations. See
68"attachment_combinations.exists_supported" for a test that ensures that at
69least one combination of attachment formats is supported.
70
71Also note that the GLES2 spec is notoriously ambiguous regarding the
72renderability of unsized formats that correspond to renderable sized formats.
73See Khronos bug 7333 <https://cvs.khronos.org/bugzilla/show_bug.cgi?id=7333>
74for details. This test expects the following behavior:
75
76* The type/unsized-format combinations corresponding to the color-renderable
77  sized formats in table 4.5 are expected to be color-renderable. (Consensus
78  in bug 7333.)
79
80* If OES_rgb8_rgba8 is exposed, the combinations ubyte/RGB and ubyte/RGBA are
81  expected to be color-renderable. (Consensus in bug 7333.)
82
83* If extensions state explicitly the renderability of a format, the
84  implementation is expected to adhere to that.
85
86* If an extension makes another sized format renderable, and there is no text
87  about the renderability of the corresponding type/unsized-format
88  combination, then it is allowed but not required to be renderable.
89
90* If a type/unsized-format combination is not specified to be renderable and
91  does not correspond to a renderable sized format, then it is expected to be
92  unrenderable.
93
94
95The "attachment_combination.*" test cases attach some textures and/or
96renderbuffers with suitable formats to none, some or all of the framebuffer's
97attachment points. The expected status values are as follows:
98
99* If there are no attachments, GL_FRAMEBUFFER_INCOMPLETE_MISSING_ATTACHMENT
100  must be returned.
101
102* Otherwise, GL_FRAMEBUFFER_COMPLETE or GL_FRAMEBUFFER_UNSUPPORTED must be
103  returned.
104
105If the implementation declares support for GL_NV_fbo_color_attachments, all
106color attachments are used in the tests.
107
108Some tests may return the status "NotSupported" because the implementation
109does support a depth- or stencil-renderable texture format.
110
111Note that GLES2, unlike GLES3, allows the depth and stencil attachments to be
112distinct images, and in fact requires them to be, since without extensions
113there is no format that is both depth- and stencil-renderable. When a test
114case has both a depth and a stencil attachment, they are always distinct
115images.
116
117The test case "attachment_combinations.exists_supported" iterates through all
118standard GLES2 renderable formats and attempts to find at least one
119combination of attachments and formats such that the framebuffer checks as
120complete. The test fails if no such combination is found.
121
122
123The "size.*" test cases check that attachment sizes are treated correctly.
124
125The "size.zero" test case creates a framebuffer object with a single
126zero-sized renderbuffer attachment. The glCheckFramebufferStatus call is
127expected to return GL_FRAMEBUFFER_INCOMPLETE_ATTACHMENT. Note that creating
128and attaching the zero-sized renderbuffer is still expected to succeed.
129
130The "size.distinct" test case creates a framebuffer object with two
131attachments with different sizes. The glCheckFramebufferStatus call is
132expected to return GL_FRAMEBUFFER_INCOMPLETE_DIMENSIONS.
133