WEBGL_debug_shader_precision WebGL working group (public_webgl 'at' khronos.org) Olli Etuaho, NVIDIA Members of the WebGL working group NN

This extension enables software emulation of mediump and lowp floating point arithmetic in GLSL shaders for the purposes of shader testing. The emulation is enabled for shaders that are compiled after the extension has been enabled. Shaders compiled before the extension is enabled are not subject to emulation. The emulation does not model any specific device, but hypothetical shader units that implement IEEE half-precision floating point and the minimum requirements for lowp in The OpenGL ES Shading Language specification version 1.00.17. It is suggested that the software emulation is implemented in shader code, but a large performance cost on the order of one magnitude is still expected on all operations subject to emulation.

Many varieties of PC GPUs only implement one precision for floating point operations that corresponds to highp in The OpenGL ES Shading Language, so errors in shader code which uses mediump or lowp precision may be undetectable on these GPUs. Testing shaders with this extension enabled is recommended to ensure compatibility with a wide variety of hardware. Due to the large performance cost of emulation, this extension should only be used for testing and not in a production environment.

The emulation applies to:

Examples of operations not subject to emulation:

  • The math operator is unary, so storing the result and the return value are not subject to emulation: my_float++;

Operations listed above resulting in a mediump precision floating point scalar, vector or matrix must perform the following steps on the resulting scalar value or each of the components of the vector or matrix:

  1. Clamp the value to the range [-65504.0, 65504.0].
  2. Determine the floating-point exponent e of the clamped value.
  3. If e < -15, return 0.0, skipping steps 4-6. The sign bit of the return value is undefined in this case.
  4. Let x be the clamped value multiplied by 2^(-e + 10.0).
  5. Let y be sign(x) * floor(abs(x)).
  6. Return y * 2^(e - 10.0).

Operations listed above resulting in a lowp precision floating point scalar, vector or matrix must perform the following steps on the resulting scalar value or each of the components of the vector or matrix:

  1. Clamp the value to the range [-2.0, 2.0].
  2. Let x be the clamped value multiplied by 2^8.
  3. Let y be sign(x) * floor(abs(x)).
  4. Return y * 2^(-8).

sign, floor, and abs in the above steps refer to built-in functions in The OpenGL ES Shading Language.

The handling of positive and negative infinity and NaN by the above steps is undefined.

The #pragma webgl_debug_shader_precision directive is accepted by the shader compiler, and can be used to disable the emulation for specific shaders. By default, emulation is enabled by all shaders, but including #pragma webgl_debug_shader_precision(off) in a shader must disable emulation for that shader.

Due to hardware limitations, it is allowed that some shaders which compile and link successfully when the extension is disabled do not compile or link when the extension is enabled.

[NoInterfaceObject] interface WEBGL_debug_shader_precision { }; Initial revision. Added a #pragma directive to use in shaders and did minor clarifications. Lifted restrictions concerning math operations evaluated as a part of compound assignment. Moved to rejected on grounds of it being easy to provide as a library (with emscripten).