DreamShaderCompiler

DreamShader » C++ API » DreamShaderCompiler

The compiler's back half: the pipeline that drives a source from text to assets, the IR emitter, the asset layer under it, the builtin catalog built from reflection, and the product index. The front half — lexer to validated IR — is DreamShaderLang, which knows nothing about the engine; this module is where a UObject is first touched.

[!IMPORTANT] Changed in 2.0. Through 1.9.x this was a Runtime module holding nothing but the compile interface, and the compiler itself lived privately in DreamShaderEditor. The two swapped places: the interface moved down into the runtime module as DreamShaderCompilerInterface.h, and the compiler moved out of the editor module into this one. DreamShaderCompilerInterfaces.h, FDreamShaderCompileService, the editor's FEditorCompileAdapter and the 1.x FMaterialGenerator are gone.

The interface lives in DreamShader

An Editor-type module is absent from game targets, so nothing outside the editor may depend on it at build time. The request, the result and the interface therefore live in the runtime module, in a header that needs nothing but Core:

#include "DreamShaderCompilerInterface.h"   // module: DreamShader

namespace UE::DreamShader
{
    enum class EThinCustomPersistence : uint8 { Ephemeral, Materialized };

    struct DREAMSHADER_API FDreamShaderCompileRequest
    {
        FString SourceFilePath;
        bool bForce = false;
        EThinCustomPersistence ThinCustomPersistence = EThinCustomPersistence::Materialized;
    };

    struct DREAMSHADER_API FDreamShaderCompileResult
    {
        bool bSucceeded = false;
        FText Message;
        FString Code;
    };

    class DREAMSHADER_API IDreamShaderCompiler
    {
    public:
        virtual ~IDreamShaderCompiler() = default;
        virtual FDreamShaderCompileResult CompileAssets(const FDreamShaderCompileRequest& Request) = 0;
        virtual FDreamShaderCompileResult CompileMaterial(const FDreamShaderCompileRequest& Request) = 0;
    };

    DREAMSHADER_API IDreamShaderCompiler* GetDreamShaderCompiler();
    DREAMSHADER_API void RegisterDreamShaderCompiler(IDreamShaderCompiler* Compiler);
}

The namespace is UE::DreamShader, not UE::DreamShader::Compiler: inside UE::DreamShader::Editor a bare Compiler:: names UE::DreamShader::Editor::Compiler, so a nested namespace here would be hidden from exactly the callers that use it most.

FDreamShaderCompileRequest

[!NOTE] Ephemeral is the editor's normal state for a ThinCustom product, not an exotic flag. The bridge and the preview renderer both ask for it; the commandlet, the cook path and the explicit Materialize action take the Materialized default, so a caller that does not name a state — a headless tool — writes assets to disk. See Ephemeral materials.

FDreamShaderCompileResult

The structured diagnostics of a compile — every error, warning and info with its code, stage, severity and span — are not in the result; ask GetDreamShaderLastCompileDiagnostics for them.

IDreamShaderCompiler

GetDreamShaderCompiler()

The registered compiler, or null. In an editor build the compiler module is loaded on demand when nothing has registered yet — both modules are Default-phase, and start order within a phase is not a contract. Null in a game target, where the module does not exist, and while the engine is shutting down. Every caller must handle null. Game thread only whenever it may have to load the module.

RegisterDreamShaderCompiler is for the compiler module itself: its service from StartupModule, nullptr from ShutdownModule. The registry does not own the object. It is exported, so another module can register a replacement — there is no chaining and no arbitration, the last call wins.

Public headers

Everything here is editor-only API. It is exported so DreamShaderEditor — the commandlet, the bridge, the browser, the decompiler, the tests — can link it; a third-party editor module can too.

DreamShaderCompilerService.h

namespace UE::DreamShader::Editor
{
    DECLARE_MULTICAST_DELEGATE_TwoParams(FOnDreamShaderSourceGenerated, const FString& /*SourceFilePath*/, bool /*bSucceeded*/);
    DREAMSHADERCOMPILER_API FOnDreamShaderSourceGenerated& OnDreamShaderSourceGenerated();
}

namespace UE::DreamShader::Editor::Compiler
{
    class DREAMSHADERCOMPILER_API FDreamShaderCompilerService final : public ::UE::DreamShader::IDreamShaderCompiler
    {
    public:
        static FDreamShaderCompilerService& Get();
        // CompileAssets / CompileMaterial
    };

    DREAMSHADERCOMPILER_API bool GetDreamShaderLastCompileDiagnostics(const FString& SourceFilePath, TArray<FLang2DiagnosticRecord>& OutRecords);
}

DreamShaderCompilePipeline.h

The pipeline is preprocess → parse → bind → lower → passes → validate → emit, and this header is the same driver with its intermediate products handed back instead of dropped.

DreamShaderPassPipelines.h

(since 2.1.0) The Custom Pass half of the compiler as the editor's tools reach it: the HLSL slot registry as dsc pass-registry lists, collects and rebuilds it; the slot pre-check as check -Shaders runs it on a .dsp; and the shader files a .dsp compiles from, which the bridge watches. Nothing here builds an asset. Game thread only. Everything is in UE::DreamShader::Editor::Compiler.

The registry itself — the files under <DShader>/.dreampass/, how a slot is planned, pre-checked and committed — is private to the module; its paths and slot counts are public in the runtime module (DreamShaderPassModule.h).

Thread and context requirements

• Game thread, editor build only. The emit half creates and modifies UPackages, UMaterials and UMaterialInstanceConstants and runs the asset save path; binding reads the builtin catalog, which is built from reflection.
• Outside a commandlet a compile opens an FScopedSlowTask and shows a modal progress dialog after a short delay; Cancel is reported as bCancelled, distinct from a failure.
• The calls are synchronous. There is no async variant, no future, and no completion callback other than OnDreamShaderSourceGenerated.
• (Since 2.1.0) A .dsp compile writes outside its package as well: the HLSL slot registry and its snapshots under <DShader>/.dreampass/. In an editor that renders it then recompiles the slot shaders synchronously; a commandlet does not.

Result messages

FDreamShaderCompileResult::Message keeps the 1.x wire shape on purpose: .skill/dsc.ps1 greps the Generated lines to list the assets a run wrote, and the bridge logs the message verbatim.

Success

One line per product, in emit order, and after a built pipeline's line one per render target of its exported buffers:

Failure

The first error as <file>(<line>,<column>): DSHnnnn: <message>, then every other diagnostic on its own line. Code holds that first DSHnnnn. The codes are catalogued under Diagnostics; the emitter's own are DSH8200–DSH8289, and Custom Pass emission's — the pipeline, its render targets, the HLSL slots and their pre-check — DSH8300–DSH8339 (since 2.1.0).

The build key behind the Skipped line covers the preprocessed text of the file and of every header, the defines the preprocessor read, and — for a .dsi — the parent's object path and any inherited channels materialized by a partial vector override (not the parent's whole schema); for a .dsp, the materials its passes name with the build keys they were built under, the snapshot inputs of its shader files, and the pass layer table; for a .dss that reads an exported buffer, that buffer's export. See Caching.

Example

Requesting a compile without linking the compiler module — this is all a runtime or a third-party editor module needs:

// MyTooling.Build.cs
PrivateDependencyModuleNames.AddRange(new[] { "Core", "DreamShader" });

#include "DreamShaderCompilerInterface.h"
#include "DreamShaderModule.h"

using namespace UE::DreamShader;

void CompileOne(const FString& InPath)
{
    IDreamShaderCompiler* Compiler = GetDreamShaderCompiler();
    if (!Compiler)
    {
        return; // a game target, or the engine is shutting down
    }

    FDreamShaderCompileRequest Request;
    Request.SourceFilePath = InPath;
    Request.ThinCustomPersistence = EThinCustomPersistence::Ephemeral;

    const FDreamShaderCompileResult Result = Compiler->CompileAssets(Request);
    UE_LOG(LogDreamShader, Display, TEXT("%s"), *Result.Message.ToString());
}

A typical successful message for a .dss that exports one function and one material:

Generated MaterialFunction /Game/FX/MF_Tint.MF_Tint from I:/Project/DShader/FX/Glow.dss.
Generated Material /Game/FX/M_Glow.M_Glow from I:/Project/DShader/FX/Glow.dss.

Running the front half only, the way dsc check does:

#include "DreamShaderCompilePipeline.h"      // module: DreamShaderCompiler (editor only)
#include "DreamShaderCompilerDiagnostics.h"  // FormatLang2DiagnosticWireLine

using namespace UE::DreamShader::Editor::Compiler;

bool Check(const FString& InPath)
{
    FDreamShaderLang2PipelineOptions Options;
    Options.bEmitAssets = false;

    FDreamShaderLang2PipelineResult Run;
    const bool bOk = RunDreamShaderLang2Pipeline(InPath, Options, Run);
    for (const UE::DreamShader::Lang::FLangDiagnostic& Diagnostic : Run.Diagnostics.GetDiagnostics())
    {
        UE_LOG(LogTemp, Display, TEXT("%s"), *FormatLang2DiagnosticWireLine(Diagnostic, Run.SourceFilePath));
    }
    return bOk;
}

See also

• C++ API — modules, headers, linkage, and build dependencies
• DreamShaderLang — the front end and the IR this module runs and emits
• DreamShaderModule.h — NormalizeSourceFilePath for building a request
• Generation — what an emitted asset looks like
• Ephemeral materials — what the two states mean in practice
• Caching — the build key bForce bypasses
• Commandlet — -run=DreamShader, the persisting caller
• Editor bridge — the memory-only caller and the JSON diagnostics
• Diagnostics index — every message, by stage
• DreamShaderPass — the runtime module a .dsp compiles for