oneshaderCookbook
oneshader cookbook
Short recipes for common OneShader tasks, each with complete code you can copy.
Recipes
Compile HLSL to SPIR-V for VulkanCompile an HLSL vertex or pixel shader to SPIR-V for Vulkan with the oneshader command and its DXC-style flags, or from C# with ShaderCompiler, and check the result with spirv-val.Compile HLSL in a C# project with dotnet buildCompile HLSL shaders as part of dotnet build in a C# project, with shader errors reported as build errors on the HLSL line, shared include files, defines, a custom namespace and per-file targets.Match HLSL constant buffers with C# structsGet a C# struct whose field offsets equal an HLSL constant buffer’s packing, 16-byte rows, arrays and matrices included, so you can upload its bytes without hand-written padding.Push constants on Vulkan, Metal and WebGPUDeclare an HLSL push-constant block once and get the C# struct plus where each API takes its bytes: a Vulkan push-constant range, a Metal setVertexBytes index, and a WebGPU uniform buffer, since WebGPU has no push constants.Shader variants with Axes in dotnet buildCompile every combination of an HLSL shader’s keywords during dotnet build with Axes, or hand-picked define sets with OneShaderVariant, and pick a variant at run time with a typed key and no allocation.Specialization constants on Vulkan, Metal and WebGPUDeclare HLSL specialization constants once with [[vk::constant_id]] and set them when the pipeline is created: VkSpecializationInfo on Vulkan, function constants on Metal and pipeline-overridable constants on WebGPU, from one compiled shader.16-bit and 64-bit types: half, int16_t, double and uint64_tUse native 16-bit half and int16_t and 64-bit double and uint64_t in HLSL with OneShader 1.2.0, get the matching C# structs, and see which device features each target needs and what Metal and WebGPU refuse.Read shader reflection in C#: bindings, buffer layouts and vertex inputsRead what a compiled HLSL shader binds, where, in which stages, its buffer layouts and its vertex inputs, from C# or as JSON, and turn it into Vulkan descriptor set layouts, with no native SPIRV-Reflect.Reload shaders while the app runsRecompile an HLSL shader when its file changes, swap in the new code while the app keeps running, and find out when an edit changed the interface the generated C# was built against, such as a constant-buffer offset.Shader variants with defines and includesCompile several variants of one HLSL source at run time with preprocessor defines, and resolve #include from memory instead of the file system, with an asset pack, a database or an editor buffer as the source.Cache shader compiles at run timeKeep compiled HLSL variants in memory with ShaderCompileCache, so a material system or editor that asks for the same shader again gets it without recompiling. An edited include is noticed, and concurrent requests for one variant compile it once.Write an HLSL compute shader for Vulkan and WebGPUWrite one HLSL compute shader, compile it to SPIR-V and WGSL with dotnet build, and get the thread-group size for the dispatch and the descriptor and bind group layouts for both APIs from C#.InterlockedAdd in HLSL, and what to do for floatsCount with InterlockedAdd in an HLSL compute shader on Vulkan, Metal and WebGPU, and add floats atomically with a compare-exchange loop, since there is no float InterlockedAdd. Includes what OneShader 1.2.0 doesn’t compile.HLSL wave intrinsics on Vulkan, Metal and WebGPUUse HLSL wave (subgroup) intrinsics such as WavePrefixCountBits, WaveActiveSum and WaveReadLaneFirst in one shader compiled to Vulkan, Metal and WebGPU, and find out which subgroup features the device has to support.The HLSL precise keyword on Vulkan, Metal and WebGPUWhat HLSL’s precise keyword does when one shader is compiled to SPIR-V, Metal Shading Language and WGSL with OneShader: NoContraction on Vulkan, fast-math pragmas off on Metal, and a warning on WebGPU, which can’t forbid fused multiply-adds.Convert HLSL to WGSL for WebGPUCompile an HLSL vertex, pixel or compute shader to WGSL for WebGPU with OneShader, from the command line, from C# or during dotnet build, check it with naga, and see what WGSL can’t express.Compile HLSL to Metal Shading LanguageCompile HLSL vertex, pixel and compute shaders to Metal Shading Language with OneShader, and get from C# the function names, the buffer, texture and sampler index of every resource, and the MTLVertexDescriptor data.Switch from the DXC command lineReplace dxc -spirv with oneshader in a Makefile, CMake or script build: which DXC flags it takes unchanged, what it adds (MSL and WGSL targets, reflection JSON, a dependency file), and which DXC options it rejects.