doc/testspecs/GLES3/functional.shaders.builtin_functions.precision.txt

   1 -------------------------------------------------------------------------
   2 drawElements Quality Program Test Specification
   3 -----------------------------------------------
   4
   5 Copyright 2014 The Android Open Source Project
   6
   7 Licensed under the Apache License, Version 2.0 (the "License");
   8 you may not use this file except in compliance with the License.
   9 You may obtain a copy of the License at
  10
  11      http://www.apache.org/licenses/LICENSE-2.0
  12
  13 Unless required by applicable law or agreed to in writing, software
  14 distributed under the License is distributed on an "AS IS" BASIS,
  15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16 See the License for the specific language governing permissions and
  17 limitations under the License.
  18 -------------------------------------------------------------------------
  19     Precision tests for built-in functions
  20
  21 Tests:
  22  + dEQP-GLES3.functional.shaders.builtin_functions.precision.*
  23
  24
  25 These tests check that the GLSL built-in numerical functions produce
  26 results that are compliant with the range and precision requirements in
  27 the GLSL ES specification.
  28
  29 The tests operate by calling the functions with predefined (mostly
  30 random) input values in either the vertex or the fragment shader. The
  31 result is stored in a transform feedback buffer or in a framebuffer
  32 pixel, and then read and compared to a reference interval of acceptable
  33 values. Functions are tested with all possible vector and matrix sizes.
  34 In the test log floating point numbers are printed out as hexadecimal
  35 constants of the form used in e.g. C99.
  36
  37 Where the GLSL specification does not specify a particular precision,
  38 the tests try to make reasonable requirements. When behavior at
  39 infinities hasn't been otherwise specified, C99 Appendix F is used as a
  40 reference. Moreover, the highp precision requirements have been adapted
  41 to lowp and mediump precisions even though the GLSL specification
  42 doesn't provide any guarantees about them. For instance, mediump and
  43 lowp operations are expected to produce either an infinity or the
  44 maximum/minimum value on overflow.
  45
  46 The acceptable results are constrained further by only allowing values
  47 from within the codomain of the function. Thus, for instance, sin(x) is
  48 not allowed to return a number greater than 1 even when when the nominal
  49 error bound would be greater.
  50
  51 A number of functions have been defined as derived forms. This means
  52 that they are required to produce only results that their expansions
  53 could produce, given the precision requirements for the constituent
  54
  55 operations.
  56
  57 * Arithmetic operations
  58
  59 These 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
  71 The precisions for trigonometric functions have been adapted from OpenCL
  72 fast relaxed math and half-float specifications. Hyperbolic functions
  73 take their precisions from standard formulae as derived forms.
  74
  75 Primitives:
  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
  94 Derived 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
 111 The precisions for exponential functions for mediump and lowp have been
 112 adapted from the OpenCL half-float specification.
 113
 114 Primitives:
 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
 136 Derived 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
 146 The operations that don't do any arithmetic are required to produce
 147 exact results. The round() function is allowed to round in either
 148 direction on a tie.
 149
 150 Primitives:
 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
 167 Derived 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
 180 These are generally defined as derived forms with reference algorithms.
 181 For determinant and inverse operations only 2x2 matrices are tested:
 182 there are a number of possible algorithms for larger matrices, and the
 183 specification does not provide precision requirements for these operations.