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    Precision tests for built-in functions
20
21Tests:
22 + dEQP-GLES3.functional.shaders.builtin_functions.precision.*
23
24
25These tests check that the GLSL built-in numerical functions produce
26results that are compliant with the range and precision requirements in
27the GLSL ES specification.
28
29The tests operate by calling the functions with predefined (mostly
30random) input values in either the vertex or the fragment shader. The
31result is stored in a transform feedback buffer or in a framebuffer
32pixel, and then read and compared to a reference interval of acceptable
33values. Functions are tested with all possible vector and matrix sizes.
34In the test log floating point numbers are printed out as hexadecimal
35constants of the form used in e.g. C99.
36
37Where the GLSL specification does not specify a particular precision,
38the tests try to make reasonable requirements. When behavior at
39infinities hasn't been otherwise specified, C99 Appendix F is used as a
40reference. Moreover, the highp precision requirements have been adapted
41to lowp and mediump precisions even though the GLSL specification
42doesn't provide any guarantees about them. For instance, mediump and
43lowp operations are expected to produce either an infinity or the
44maximum/minimum value on overflow.
45
46The acceptable results are constrained further by only allowing values
47from within the codomain of the function. Thus, for instance, sin(x) is
48not allowed to return a number greater than 1 even when when the nominal
49error bound would be greater.
50
51A number of functions have been defined as derived forms. This means
52that they are required to produce only results that their expansions
53could produce, given the precision requirements for the constituent
54
55operations.
56
57* Arithmetic operations
58
59These are as defined in the GLSL ES specification.
60
61| operation | precision | domain                      |
62|-----------+-----------+-----------------------------|
63| x + y     | < 1 ULP   |                             |
64| x / y     | 2.5 ULP   | 2^-126 <= abs(y) <= 2^127-1 |
65| x - y     | < 1 ULP   |                             |
66| x * y     | < 1 ULP   |                             |
67
68
69* Trigonometric functions
70
71The precisions for trigonometric functions have been adapted from OpenCL
72fast relaxed math and half-float specifications. Hyperbolic functions
73take their precisions from standard formulae as derived forms.
74
75Primitives:
76
77| function   | precision      | domain              | prec qual     |
78|------------+----------------+---------------------+---------------|
79| sin(x)     | 2^-11          | -pi <= x <= pi      | highp         |
80|            | 2^-12 * abs(x) | elsewhere           | highp         |
81|            | 2 ULP          |                     | mediump, lowp |
82| cos(x)     | 2^-11          | -pi <= x <= pi      | highp         |
83|            | 2^-12 * abs(x) | elsewhere           | highp         |
84|            | 2 ULP          |                     | mediump, lowp |
85| asin(x)    | 4 ULP          | -1 <= x <= 1        | highp         |
86|            | 2 ULP          | -1 <= x <= 1        | mediump, lowp |
87| acos(x)    | 4 ULP          | -1 <= x <= 1        | highp         |
88|            | 2 ULP          | -1 <= x <= 1        | mediump, lowp |
89| atan(x, y) | 6 ULP          | !(x == 0 && y == 0) | highp         |
90|            | 2 ULP          | !(x == 0 && y == 0) | mediump, lowp |
91| atan(x)    | 5 ULP          |                     | highp         |
92|            | 2 ULP          |                     | mediump, lowp |
93
94Derived functions:
95
96| function   | defined as                       |
97|------------+----------------------------------|
98| radians(x) | (pi / 180.0) * x                 |
99| degrees(x) | (180.0 / pi) * x                 |
100| tan(x)     | sin(x) * (1.0 / cos(x))          |
101| sinh(x)    | (exp(x) - exp(-x)) / 2.0         |
102| cosh(x)    | (exp(x) + exp(-x)) / 2.0         |
103| tanh(x)    | sinh(x) / cosh(x)                |
104| asinh(x)   | log(x + sqrt(x * x + 1.0))       |
105| acosh(x)   | log(x + sqrt((x+1.0) * (x-1.0))) |
106| atanh(x)   | 0.5 * log(1.0 + x / (1.0 - x))   |
107
108
109* Exponential functions
110
111The precisions for exponential functions for mediump and lowp have been
112adapted from the OpenCL half-float specification.
113
114Primitives:
115
116| function       | precision            | domain               | prec qual |
117|----------------+----------------------+----------------------+-----------|
118| exp(x)         | (3 + 2 * abs(x)) ULP |                      | highp     |
119|                | (2 + 2 * abs(x)) ULP |                      | mediump   |
120|                | 2 ULP                |                      | lowp      |
121| log(x)         | 2^-21                | 0.5 <= x && x <= 0.5 | highp     |
122|                | 3 ULP                | elsewhere            | highp     |
123|                | 2^-7                 | 0.5 <= x && x <= 0.5 | mediump   |
124|                | 2 ULP                | elsewhere            | mediump   |
125|                | 2 ULP                |                      | lowp      |
126| exp(x)         | (3 + 2 * abs(x)) ULP |                      | highp     |
127|                | (2 + 2 * abs(x)) ULP |                      | mediump   |
128|                | 2 ULP                |                      | lowp      |
129| log2(x)        | 2^-21                | 0.5 <= x && x <= 0.5 | highp     |
130|                | 3 ULP                | elsewhere            | highp     |
131|                | 2^-7                 | 0.5 <= x && x <= 0.5 | mediump   |
132|                | 2 ULP                | elsewhere            | mediump   |
133|                | 2 ULP                |                      | lowp      |
134| inversesqrt(x) | 2 ULP                |                      |           |
135
136Derived functions:
137
138| function | defined as           |
139|----------+----------------------|
140| pow(x)   | exp2(y * log2(x))    |
141| sqrt(x)  | 1.0 / inversesqrt(x) |
142
143
144* Common functions
145
146The operations that don't do any arithmetic are required to produce
147exact results. The round() function is allowed to round in either
148direction on a tie.
149
150Primitives:
151
152| function         | precision |
153|------------------+-----------|
154| abs(x)           |         0 |
155| sign(x)          |         0 |
156| floor(x)         |         0 |
157| trunc(x)         |         0 |
158| round(x)         |   special |
159| roundEven(x)     |         0 |
160| ceil(x)          |         0 |
161| modf(x, i)       |         0 |
162| min(x, y)        |         0 |
163| max(x, y)        |         0 |
164| clamp(x, lo, hi) |         0 |
165| step(edge, x)    |         0 |
166
167Derived functions:
168
169| function              | defined as                                     |
170|-----------------------+------------------------------------------------|
171| fract(x)              | x - floor(x)                                   |
172| mod(x, y)             | x - y * floor(x / y)                           |
173| mix(x, y, a)          | x * (1 - a) + y * a                            |
174| smoothstep(e0, e1, x) | { float t = clamp((x - e0) / (e1 - e0),0,1);   |
175|                       |   return t * t * (3 - 2*t);                  } |
176
177
178* Geometric and matrix functions
179
180These are generally defined as derived forms with reference algorithms.
181For determinant and inverse operations only 2x2 matrices are tested:
182there are a number of possible algorithms for larger matrices, and the
183specification does not provide precision requirements for these operations.
184