dsc migrate — 1.x sources to .dss

DreamShader » Tools » Migrate

dsc migrate rewrites .dsm, .dsf and .dsh files as DreamShaderLang 2.0. Nothing forces a migration: the legacy front end keeps building 1.x sources through the same compiler. Migrate when you want what only a .dss has — real expressions and control flow, #include, material instances beside the material, comments that survive tooling.

./dsc.ps1 migrate DShader/Materials/M_Foo.dsm -Check    # prove the rewrite, write nothing
./dsc.ps1 migrate DShader/Materials/M_Foo.dsm           # write M_Foo.dss, move M_Foo.dsm away
./dsc.ps1 migrate -All -Check                           # every 1.x source of the writable roots
./dsc.ps1 migrate -Root MoonToon -Check                 # one source root, by its or its plugin's name

In a set, headers go first, and a header is migrated only when every file that includes it is migrated in the same run: a .dsh may hold both dialects, so a half-migrated project keeps building.

What is proved before anything is written

1. No comment is lost. The comments of the source are counted against the comments of the result (DSH9092).
2. The text builds as 2.0. It is parsed, bound and lowered by the 2.0 front end, and every call in its @custom bodies is matched against the HLSL its callee becomes — what the shader compiler would do, and what nothing else does for a header, which lowers to nothing on its own (DSH9097). A rejected text is kept under Saved/DreamShader/Migrated/Rejected/, and the diagnostics point into it.
3. It builds the same graph. The IR of the 1.x file and the IR of the new text are compared from their roots (DSH9098, a warning with the first differing node). What is one asset written two ways does not count: a literal on a pin against its Const* twin, an identity swizzle, the spacing of Custom node code and where its source markers stand, the name the IR gives a Custom node's first output, \r\n against \n in a description, a number at float precision.
4. The asset stays where it is. If the new file's place would name another asset path, the export gets the /// @name that keeps it (DSH9098 says so when it cannot).

A source with #if lines is refused (DSH9090): only the branch taken today would survive.

Measured on the four source roots of the development project (71 files): all 71 build as 2.0, 68 compare equal, and the three warnings are true differences — two 1.x decompiler artefacts that declared a node narrower than it is, and one explicit .x into a float pin.

What the rewrite does

The legacy front end already reads every 1.x construct into the 2.0 tree. What is left to write out is what only the legacy rules make work, because a .dss is bound without them. Each rule is also a diagnostic on the 1.x source, so dsc check on a .dsm shows what a migration will change.

Comments stay with the statement or declaration they stood by; the comment above a 1.x block goes above the first declaration that block became.

Functions that return nothing (L9)

1.x wrote the HLSL of every Function and GraphFunction that returns nothing as returning its first out, zeroed first. That is what lets a 1.x body call one as a value — fac = Checker(co); — or pass that out as well, Voronoi(co, d, color);, which 1.x read as d = Voronoi(co, color);. A .dss function is emitted exactly as it is declared, so the migrated function is declared that way:

/// @custom
float BLChecker_fac(float3 p)
{
    float result = (float)0;
    ...
    return result;
}

and every call that passed the first out assigns it instead, in bodies and in graphs. The node a graph makes of it is the node 1.x made.

A function of a Namespace block is a library's public entry point: its out parameters are its Custom node's pins and the outputs of the material function made from it, so it keeps them. 1.x could not call one from a body (it did not rewrite N::F there); where a body of the same file reads one's value anyway, the call goes to an adapter migrate adds beside it, N_F_<first out>.

The shape of a function is decided in the file that declares it, so migrate a header before the files that include it, in place — -All and a set do. A call of a 1.x function of a header that is still 1.x is written for that function as it is now, and DSH9094 says which calls will need the new form once the header is migrated: a graph's call of a function that returns nothing, or a body that reads a Namespace function's value.

What can stop a file

See also

• The 2.0 language · Commandlet · Decompiler
• Diagnostics DSH9090–DSH9099