1# Shader substitution 2 3ANGLE provides two mechanisms for observing, modifying, and substituting 4the application's shaders. This ability to interpose makes it easier to 5diagnose bugs and to prototype new transforms in the shader translator. 6 7## Environment variables controlling reading/writing shaders to disk 8 9For both the source and translated shaders discussed below, the environment 10variable: 11 12``` 13ANGLE_SHADER_DUMP_PATH 14``` 15 16and the Android property: 17 18``` 19debug.angle.shader_dump_path 20``` 21 22specify the directory in which shader sources and translated shaders will 23be written to, and, in the case of shader substitution, read from. For 24example, on non-Android platforms: 25 26``` 27mkdir -p /path/to/angle_shaders 28export ANGLE_SHADER_DUMP_PATH=/path/to/angle_shaders 29``` 30 31will write all data to the `angle_shaders` directory. 32 33On Android, it's necessary to set the `debug.angle.shader_dump_path` property 34and set up the SD card correctly. (Help expanding this documentation is 35appreciated!) 36 37## ESSL shader dumping and substitution 38 39The ANGLE feature `dumpShaderSource`, when enabled, writes all incoming 40ESSL shader sources to disk, in the shader dump directory specified 41above. File names are computed by hashing the shader sources. Shaders will 42only be written to disk if they were not loaded from disk via substitution, 43below. 44 45The ANGLE feature `enableShaderSubstitution`, when enabled, looks for a 46file in the shader dump directory where the filename is the hash of the 47application's shader source, and substitutes its contents for the 48application's shader. This allows you to dump and edit these files at your 49leisure, and rerun the application to pick up the new versions of the 50shaders. 51 52In Chromium, pass the following command line arguments to enable these 53features: 54 55``` 56--enable-angle-features=dumpShaderSource 57--enable-angle-features=enableShaderSubstitution 58--enable-angle-features=dumpShaderSource,enableShaderSubstitution 59``` 60 61You must also specify `--disable-gpu-sandbox` to allow ANGLE to access 62these on-disk files for reading and writing. **Do not** browse the open web 63with this command line argument specified! 64 65## Translated shader dumping and substitution 66 67The translated shaders produced by ANGLE's shader translator can be dumped 68and substituted as well. This is especially useful when prototyping new 69optimizations in the shader translator. 70 71This mechanism is relatively recent and has not been thoroughly tested. It 72will likely not work in the situation where ANGLE dynamically recompiles 73shaders internally. It should work with all text-based shader translator 74backends (ESSL, GLSL, HLSL, and Metal). See comments in 75`src/libANGLE/Shader.cpp` describing the work needed to make this work with 76the SPIR-V backend. 77 78Translated shaders go into the same shader dump directory specified above 79for shader sources. To enable these features: 80 81``` 82--enable-angle-features=dumpTranslatedShaders,enableTranslatedShaderSubstitution --disable-gpu-sandbox 83``` 84 85## Putting it all together (example: macOS) 86 87``` 88mkdir -p $HOME/tmp/angle_shaders 89export ANGLE_SHADER_DUMP_PATH=$HOME/tmp/angle_shaders 90 91out/Release/Chromium.app/Contents/MacOS/Chromium --disable-gpu-sandbox --use-angle=metal --enable-angle-features=dumpShaderSource,enableShaderSubstitution,dumpTranslatedShaders,enableTranslatedShaderSubstitution 92``` 93 94Run the application once to generate the shader dump. Edit source or 95translated shaders as desired. Rerun with the same command line arguments 96to pick up the new versions of the shaders. 97 98Alternatively, and especially if the application doesn't work with all of 99the shaders in the substitution directory, make a new directory and copy in 100only those source or translated shaders you want to substitute, and run: 101 102``` 103out/Release/Chromium.app/Contents/MacOS/Chromium --disable-gpu-sandbox --use-angle=metal --enable-angle-features=enableShaderSubstitution,enableTranslatedShaderSubstitution 104``` 105