Upgrading projects to the Vulkan renderer¶
TiXL used to render with Direct3D 11 and compile shaders with Microsoft's FXC. It now renders with Vulkan and compiles with Slang. If you have been using TiXL for years and have a folder full of projects and custom shaders, this page tells you what to expect, what TiXL translates for you, and the handful of things you may have to fix by hand.
The short answer¶
Your projects open as before. The .t3 project format did not change, operators did not change, and your parameters, animations and presets are untouched.
Most shaders compile unchanged too, because TiXL passes the compiler a set of compatibility flags described below. What is left falls into two groups, and the second is the one to watch:
- It does not compile. Slang rejects some things FXC quietly accepted. You get an error, you fix it, you move on.
- It compiles but looks different. A few constructs were always undefined, and FXC happened to do what you wanted. These are silent, and they are the ones worth reading this page for.
What actually changed¶
Four names get used interchangeably in bug reports, so it helps to separate them:
| Before | Now | |
|---|---|---|
| Graphics API | Direct3D 11 | Vulkan |
| Shader language | HLSL | HLSL — unchanged |
| Shader compiler | FXC | Slang |
| Compiled shader format | DXBC | SPIR-V |
The important line is the second one. You still write HLSL. Slang is a superset of it, so the language you know is the language you keep using. What changed is the program that reads your HLSL and the bytecode it produces.
Vulkan is the reason for the move: it runs on Linux and macOS, where Direct3D does not. SPIR-V is simply what Vulkan consumes instead of DXBC, and Slang is the compiler that produces it.
How TiXL compiles your shaders¶
TiXL runs slangc once per shader, roughly like this:
slangc your-shader.hlsl \
-entry psMain -stage pixel \
-target spirv -profile sm_5_0 -capability spirv_1_5 \
-D sampler=SamplerState \
-fvk-use-dx-layout \
-fvk-s-shift <n> 0 -fvk-b-shift <n> 0 \
-fvk-t-shift <n> 0 -fvk-u-shift <n> 0 \
-I <include directories>
Each of those flags exists to keep your existing shaders working:
-D sampler=SamplerStatemaps the D3D9-erasamplerkeyword to the modern type. FXC acceptedsampler; Slang does not. Around 225 of TiXL's own shaders still use it, so this mapping is permanent — you do not need to rewritesampler texSampler : register(s0);.-fvk-use-dx-layoutkeeps D3D's constant-buffer packing rules. Yourcbuffermembers sit at the same offsets they always did, which matters because the C# side of an operator writes those bytes.-fvk-*-shiftmaps HLSL register slots onto Vulkan descriptor bindings. Vulkan has one binding space where D3D had four separate ones, so each register class gets its own range: samplers from 0, constant buffers from 16, textures and other shader resources from 32, and UAVs from 160. Each stage is offset by a further 200, so a vertex shader'st0and a pixel shader'st0do not collide.-profile sm_5_0keeps the shader model your shaders were written against.
The practical consequence: register(t0), register(b0) and register(s0) still mean what they meant. Keep writing them.
Errors you may actually hit¶
Mixing vector sizes¶
This is the most common hard failure.
error[E39999]: no overload for '-' applicable to arguments of type (vector<float,4>, vector<float,3>)
FXC silently truncated the float4 to a float3 and carried on. Slang refuses to guess. Say which components you meant:
This one bit TiXL's own SDF operators during the port, so it is worth grepping your shaders for arithmetic between differently sized vectors.
The same applies to assignments, return values and compound operators:
float3 color = tex.Sample(s, uv); // error: type mismatch -> .rgb
c.rgb *= tex.Sample(s, uv); // error: no overload -> .rgb
Two cbuffers with the same name¶
Rename one of them, for example to Params2. Only the register connects a cbuffer to its operator, so nothing else has to change.
Writing to a constant¶
Copy the value into a local variable and change that instead.
"Undefined identifier" on a type name¶
If Slang reports an undefined identifier where you used a type, it is usually a D3D9-era name that the compatibility define does not cover. sampler is handled; others are not. Replace it with the modern spelling — SamplerState, Texture2D, and so on. sampler2D and tex2D are the usual suspects: use a Texture2D with a SamplerState and call Sample().
Names that left TiXL's shared includes¶
Projects from older TiXL versions can also fail on names that are simply gone from shared/*.hlsl. This has nothing to do with Slang.
| Removed | Use instead |
|---|---|
LegacyPoint (removed in 4.3) |
Point. The layout is the same, but W is now FX1, Stretch is Scale and Selected is FX2. |
rotate_vector(v, q) |
qRotateVec3(v, q) |
Compiles, but cannot run yet¶
Buffer<T> compiles, but the Vulkan backend cannot bind it, and TiXL logs a warning when it finds one. Use StructuredBuffer<T> until it does.
Differences that compile but change the picture¶
These produce no error at all. If a shader went black or subtly wrong after the upgrade, start here.
Uninitialised struct members¶
struct Fragment { float3 color; float fog; };
Fragment f;
f.color = albedo; // f.fog is never written
return float4(f.color * (1 - f.fog), 1);
Slang accepts this. The value of f.fog is undefined, and in practice it can come through as NaN — which propagates through every multiply and turns the whole surface black. FXC frequently left such members as zero, so the bug never showed.
Initialise the struct:
This was a real bug in TiXL's own PBR shading during the port, and it cost a day to find because nothing reports it.
smoothstep with a descending edge¶
Swapped edges still work on all current compilers and drivers. Strictly, the SPIR-V spec leaves edge0 > edge1 undefined, so 1.0 - smoothstep(0.0, 1.0, x) is the portable spelling. Equal edges (edge0 == edge1) divide by zero everywhere — that one is always a bug.
A function named after an intrinsic¶
If you define your own fmod, saturate or similar, Slang resolves the call to your function. That may or may not be what the old build did, and the two compilers are not obliged to agree. The failure is silent and looks like "this function suddenly behaves differently".
Rename your version — myFmod, wrapMod — and the ambiguity disappears.
Implicit conversions now warn¶
These still compile and still do what you expect. Slang warns because the intent is easy to misread, not because the result changed. You can leave them alone, or be explicit:
When a shader fails to compile¶
The first error appears in the log window with its line number and file, plus a hint if it is one of the causes on this page. Later errors are left out because they are often consequences of the first.
A shader only compiles when something uses it. An operator you have not opened since the upgrade may still be broken, so open the projects you depend on before you rely on them, and go through the scenes that are only reached at certain times on the timeline.
For a generated shader — anything TiXL assembles from a field graph — there is no file on disk to open. TiXL therefore writes the exact source it handed the compiler into a Log/ShaderErrors folder inside its settings folder, named after the shader and the entry point. Open that file to see the code the error line numbers refer to, and compile it by hand if you want to iterate quickly:
slangc ShaderErrors/PixelShader_psMain.01.hlsl -entry psMain -stage fragment -target spirv -D sampler=SamplerState -o /tmp/out.spv
Custom operators written against SharpDX¶
Operators you wrote in C# used SharpDX's Direct3D 11 types, either through the aliases every project carries (Buffer, SamplerState, TextureAddressMode, ...) or spelled out as SharpDX.Direct3D11.…. These types now live in TiXL's own graphics layer, and the editor moves a project over the first time it opens it:
- The project's aliases and assembly references point at
T3.GraphicsandT3.Graphics.Compatinstead of SharpDX. - Your operator sources get the same rename:
using SharpDX.Direct3D11;becomesusing T3.Graphics.Compat;, qualified names such asSharpDX.Direct3D11.TextureAddressModelose their SharpDX prefix, and the interop value typesRawVector4,RawRectangleandRawViewportFbecomeVector4,ScissorRectandViewport. Sources that never mentioned SharpDX are not touched. - The project recompiles once. A backup of the untouched project is pinned under its
.temp/Backup/folder beforehand. The rewritten operators no longer compile in TiXL 4.3 or earlier, so use that backup if you need to go back.
Types that have no counterpart in the graphics layer stay as they are and are listed in the log: image decoding through SharpDX.WIC, shader compilation through SharpDX.D3DCompiler, and Direct2D. A project that still uses one of them keeps its SharpDX references so it continues to compile on Windows; running it on Linux or macOS needs that code replaced by hand.