Half-precision (f16) type aliases for WGSL shaders (playcanvas#8439)

Co-authored-by: Martin Valigursky <mvaligursky@snapchat.com>

Author: mvaligursky

examples/assets/scripts/misc/hatch-material.mjs

@@ -218,27 +218,27 @@ const createHatchMaterial = (device, textures) => {
             fn fragmentMain(input: FragmentInput) -> FragmentOutput
             {
                 var output: FragmentOutput;
-                var colorLinear: vec3f;
+                var colorLinear: half3;
 
                 #ifdef TOON
 
                     // just a simple toon shader - no texture sampling
-                    let level: f32 = f32(i32(input.brightness * uniform.uNumTextures)) / uniform.uNumTextures;
-                    colorLinear = level * uniform.uColor;
+                    let level: half = half(i32(input.brightness * uniform.uNumTextures)) / half(uniform.uNumTextures);
+                    colorLinear = level * half3(uniform.uColor);
 
                 #else
                     // brightness dictates the hatch texture level
-                    let level: f32 = (1.0 - input.brightness) * uniform.uNumTextures;
+                    let level: half = (half(1.0) - half(input.brightness)) * half(uniform.uNumTextures);
 
                     // sample the two nearest levels and interpolate between them
-                    let hatchUnder: vec3f = textureSample(uDiffuseMap, uDiffuseMapSampler, input.uv0 * uniform.uDensity, i32(floor(level))).xyz;
-                    let hatchAbove: vec3f = textureSample(uDiffuseMap, uDiffuseMapSampler, input.uv0 * uniform.uDensity, i32(min(ceil(level), uniform.uNumTextures - 1.0))).xyz;
-                    colorLinear = mix(hatchUnder, hatchAbove, fract(level)) * uniform.uColor;
+                    let hatchUnder: half3 = half3(textureSample(uDiffuseMap, uDiffuseMapSampler, input.uv0 * uniform.uDensity, i32(floor(level))).xyz);
+                    let hatchAbove: half3 = half3(textureSample(uDiffuseMap, uDiffuseMapSampler, input.uv0 * uniform.uDensity, i32(min(ceil(level), half(uniform.uNumTextures - 1.0)))).xyz);
+                    colorLinear = mix(hatchUnder, hatchAbove, fract(level)) * half3(uniform.uColor);
                 #endif
 
                 // handle standard color processing - the called functions are automatically attached to the
                 // shader based on the current fog / tone-mapping / gamma settings
-                let fogged: vec3f = addFog(colorLinear);
+                let fogged: vec3f = addFog(vec3f(colorLinear));
                 let toneMapped: vec3f = toneMap(fogged);
                 output.color = vec4f(gammaCorrectOutput(toneMapped), 1.0);
 

examples/src/examples/compute/edge-detect.compute-shader.wgsl

@@ -1,3 +1,6 @@
+// Include half-precision type aliases (resolves to f16 when supported, f32 otherwise)
+#include "halfTypesCS"
+
 @group(0) @binding(0) var inputTexture: texture_2d<f32>;
 @group(0) @binding(1) var inputTexture_sampler: sampler;
 @group(0) @binding(2) var outputTexture: texture_storage_2d<rgba8unorm, write>;
@@ -14,43 +17,43 @@ fn main(@builtin(global_invocation_id) global_id : vec3u) {
 
     // Sample the center pixel
     let uvFloat = (vec2f(uv) + vec2f(0.5)) / vec2f(texSize);
-    var color = textureSampleLevel(inputTexture, inputTexture_sampler, uvFloat, 0.0);
+    var color = half4(textureSampleLevel(inputTexture, inputTexture_sampler, uvFloat, 0.0));
 
     // Sobel edge detection using 3x3 kernel
     let texelSize = 1.0 / vec2f(texSize);
 
-    // Sample 3x3 neighborhood and convert to grayscale
-    var samples: array<f32, 9>;
+    // Sample 3x3 neighborhood and convert to grayscale (using half precision)
+    var samples: array<half, 9>;
     var idx = 0;
     for (var y = -1; y <= 1; y++) {
         for (var x = -1; x <= 1; x++) {
             let offset = vec2f(f32(x), f32(y)) * texelSize;
             let sampleUV = uvFloat + offset;
-            let sampleColor = textureSampleLevel(inputTexture, inputTexture_sampler, sampleUV, 0.0);
+            let sampleColor = half3(textureSampleLevel(inputTexture, inputTexture_sampler, sampleUV, 0.0).rgb);
             // Convert to grayscale using standard luminance weights
-            samples[idx] = dot(sampleColor.rgb, vec3f(0.299, 0.587, 0.114));
+            samples[idx] = dot(sampleColor, half3(0.299, 0.587, 0.114));
             idx++;
         }
     }
 
     // Sobel horizontal and vertical kernels
     // Horizontal: [-1, 0, 1; -2, 0, 2; -1, 0, 1]
-    let gx = -samples[0] + samples[2] - 2.0 * samples[3] + 2.0 * samples[5] - samples[6] + samples[8];
+    let gx: half = -samples[0] + samples[2] - half(2.0) * samples[3] + half(2.0) * samples[5] - samples[6] + samples[8];
 
     // Vertical: [-1, -2, -1; 0, 0, 0; 1, 2, 1]
-    let gy = -samples[0] - 2.0 * samples[1] - samples[2] + samples[6] + 2.0 * samples[7] + samples[8];
+    let gy: half = -samples[0] - half(2.0) * samples[1] - samples[2] + samples[6] + half(2.0) * samples[7] + samples[8];
 
     // Calculate edge magnitude
-    let edgeStrength = sqrt(gx * gx + gy * gy);
+    let edgeStrength: half = sqrt(gx * gx + gy * gy);
 
     // Make edges red: stronger edges = more red
-    let edgeAmount = clamp(edgeStrength * 3.0, 0.0, 1.0);
-    let edgeColor = vec3f(1.0, 0.0, 0.0); // Red
+    let edgeAmount: half = clamp(edgeStrength * half(3.0), half(0.0), half(1.0));
+    let edgeColor = half3(1.0, 0.0, 0.0); // Red
 
     // Blend original color with red edges
-    var finalColor = mix(color.rgb, edgeColor, edgeAmount);
+    var finalColor: half3 = mix(color.rgb, edgeColor, edgeAmount);
 
-    // Write to output storage texture (no channel swap - keep edges red)
-    textureStore(outputTexture, vec2i(uv), vec4f(finalColor, color.a));
+    // Write to output storage texture (convert half back to f32 for storage)
+    textureStore(outputTexture, vec2i(uv), vec4f(vec3f(finalColor), f32(color.a)));
 }
 

src/platform/graphics/graphics-device.js

@@ -367,6 +367,18 @@ class GraphicsDevice extends EventHandler {
      */
     supportsPrimitiveIndex = false;
 
+    /**
+     * True if the device supports 16-bit floating-point types in shaders (WebGPU only). When
+     * supported, shaders can use native WGSL types: `f16`, `vec2h`, `vec3h`, `vec4h`, `mat2x2h`,
+     * `mat3x3h`, `mat4x4h`. For convenience, PlayCanvas also provides type aliases (`half`,
+     * `half2`, `half3`, `half4`, `half2x2`, `half3x3`, `half4x4`) that resolve to f16 types when
+     * supported, or fall back to f32 types when not supported.
+     *
+     * @type {boolean}
+     * @readonly
+     */
+    supportsShaderF16 = false;
+
     /**
      * True if 32-bit floating-point textures can be used as a frame buffer.
      *
@@ -598,6 +610,7 @@ class GraphicsDevice extends EventHandler {
         if (this.textureFloatRenderable) capsDefines.set('CAPS_TEXTURE_FLOAT_RENDERABLE', '');
         if (this.supportsMultiDraw) capsDefines.set('CAPS_MULTI_DRAW', '');
         if (this.supportsPrimitiveIndex) capsDefines.set('CAPS_PRIMITIVE_INDEX', '');
+        if (this.supportsShaderF16) capsDefines.set('CAPS_SHADER_F16', '');
 
         // Platform defines
         if (platform.desktop) capsDefines.set('PLATFORM_DESKTOP', '');

src/platform/graphics/shader-chunks/frag/half-types.js

@@ -0,0 +1,31 @@
+/**
+ * WGSL shader chunk providing half-precision type aliases. When the device supports f16
+ * (CAPS_SHADER_F16), these resolve to native f16 types. Otherwise, they fall back to f32.
+ *
+ * Available types: half, half2, half3, half4, half2x2, half3x3, half4x4
+ *
+ * Usage in WGSL shaders:
+ * - Vertex/Fragment: automatically included
+ * - Compute: #include "halfTypesCS"
+ *
+ * @ignore
+ */
+export default /* wgsl */`
+#ifdef CAPS_SHADER_F16
+    alias half = f16;
+    alias half2 = vec2<f16>;
+    alias half3 = vec3<f16>;
+    alias half4 = vec4<f16>;
+    alias half2x2 = mat2x2<f16>;
+    alias half3x3 = mat3x3<f16>;
+    alias half4x4 = mat4x4<f16>;
+#else
+    alias half = f32;
+    alias half2 = vec2f;
+    alias half3 = vec3f;
+    alias half4 = vec4f;
+    alias half2x2 = mat2x2f;
+    alias half3x3 = mat3x3f;
+    alias half4x4 = mat4x4f;
+#endif
+`;

src/platform/graphics/shader-definition-utils.js

@@ -15,6 +15,7 @@ import wgslFS from './shader-chunks/frag/webgpu-wgsl.js';
 import wgslVS from './shader-chunks/vert/webgpu-wgsl.js';
 import sharedGLSL from './shader-chunks/frag/shared.js';
 import sharedWGSL from './shader-chunks/frag/shared-wgsl.js';
+import halfTypes from './shader-chunks/frag/half-types.js';
 
 /**
  * @import { GraphicsDevice } from './graphics-device.js'
@@ -115,12 +116,8 @@ class ShaderDefinitionUtils {
 
         const getDefinesWgsl = (isVertex, options) => {
 
-            let code = '';
-
             // Enable directives must come before all global declarations
-            if (!isVertex && device.supportsPrimitiveIndex) {
-                code += 'enable primitive_index;\n';
-            }
+            let code = ShaderDefinitionUtils.getWGSLEnables(device, isVertex ? 'vertex' : 'fragment');
 
             // Define the fragment shader output type, vec4 by default
             if (!isVertex) {
@@ -151,6 +148,7 @@ class ShaderDefinitionUtils {
             vertCode = `
                 ${getDefinesWgsl(true, options)}
                 ${vertexDefinesCode}
+                ${halfTypes}
                 ${wgslVS}
                 ${sharedWGSL}
                 ${options.vertexCode}
@@ -159,6 +157,7 @@ class ShaderDefinitionUtils {
             fragCode = `
                 ${getDefinesWgsl(false, options)}
                 ${fragmentDefinesCode}
+                ${halfTypes}
                 ${wgslFS}
                 ${sharedWGSL}
                 ${options.fragmentCode}
@@ -205,6 +204,26 @@ class ShaderDefinitionUtils {
         };
     }
 
+    /**
+     * Generates WGSL enable directives based on device capabilities. Enable directives must come
+     * before all global declarations in WGSL shaders.
+     *
+     * @param {GraphicsDevice} device - The graphics device.
+     * @param {'vertex'|'fragment'|'compute'} shaderType - The type of shader.
+     * @returns {string} The WGSL enable directives code.
+     * @ignore
+     */
+    static getWGSLEnables(device, shaderType) {
+        let code = '';
+        if (device.supportsShaderF16) {
+            code += 'enable f16;\n';
+        }
+        if (shaderType === 'fragment' && device.supportsPrimitiveIndex) {
+            code += 'enable primitive_index;\n';
+        }
+        return code;
+    }
+
     /**
      * @param {GraphicsDevice} device - The graphics device.
      * @param {Map<string, string>} [defines] - A map containing key-value pairs.

src/platform/graphics/shader.js

@@ -5,6 +5,7 @@ import { Preprocessor } from '../../core/preprocessor.js';
 import { SHADERLANGUAGE_GLSL, SHADERLANGUAGE_WGSL } from './constants.js';
 import { DebugGraphics } from './debug-graphics.js';
 import { ShaderDefinitionUtils } from './shader-definition-utils.js';
+import halfTypes from './shader-chunks/frag/half-types.js';
 
 /**
  * @import { BindGroupFormat } from './bind-group-format.js'
@@ -139,12 +140,20 @@ class Shader {
                 this.cUnmodified = definition.cshader;
             });
 
-            // Prepend defines to compute shader source
+            // Prepend enables and defines to compute shader source
+            const enablesCode = ShaderDefinitionUtils.getWGSLEnables(graphicsDevice, 'compute');
             const definesCode = ShaderDefinitionUtils.getDefinesCode(graphicsDevice, definition.cdefines);
-            const cshader = definesCode + definition.cshader;
+
+            const cshader = enablesCode + definesCode + definition.cshader;
+
+            // Add built-in halfTypesCS include for compute shaders (if not already provided by user)
+            const cincludes = definition.cincludes ?? new Map();
+            if (!cincludes.has('halfTypesCS')) {
+                cincludes.set('halfTypesCS', halfTypes);
+            }
 
             // pre-process compute shader source
-            definition.cshader = Preprocessor.run(cshader, definition.cincludes, {
+            definition.cshader = Preprocessor.run(cshader, cincludes, {
                 sourceName: `compute shader for ${this.label}`,
                 stripDefines: true
             });