C++ API

DreamShader » C++ API

The plugin's public C++ surface: five modules, 69 public headers, and one compile interface every caller goes through.

Modules

All five are declared in DreamShader.uplugin. DreamShaderLang, DreamShader and DreamShaderPass load at PostConfigInit — early enough that the settings object and the shader-directory mappings exist before anything asks for them, and, for DreamShaderPass, before the engine commits its shader type list, which its global shader types join when the module loads — and the two Editor modules at Default. DreamShaderLang is listed first in the descriptor: every other module depends on it, directly or through DreamShader, and the phase alone does not order them. DreamShaderPass follows DreamShader, and DreamShaderCompiler is listed before DreamShaderEditor, for the same reason; a caller that runs before the compiler has started still gets one: GetDreamShaderCompiler() loads the module on demand. The plugin is EnabledByDefault and CanContainContent; IsBetaVersion is false.

Public headers

Namespaces: everything in DreamShaderModule.h, DreamShaderTypes.h, DreamShaderCompilerInterface.h, DreamShaderDefineResolution.h, DreamShaderDefineTable.h and DreamShaderPreprocessor.h lives in UE::DreamShader — the two that moved to DreamShaderLang in 2.0 kept that namespace, so a caller of theirs needs no source change. The language is UE::DreamShader::Lang and UE::DreamShader::IR; the compiler module is UE::DreamShader::Editor::Compiler. FDreamShaderModule, FDreamShaderCompilerModule, UDreamShaderSettings, UDreamShaderMaterialInstance and EDreamShaderDefaultBackend are at global scope. DreamShaderPass (since 2.1.0) puts its reflected types — UDreamPassPipeline, UDreamPassSubsystem, ADreamPassVolume, the EDreamPass* enums and FDreamPass* structs — at global scope, as reflected types must be, and its free functions in UE::DreamPass.

Linkage

[!WARNING] DreamShaderEditor exports nothing and cannot be linked against. It has no Public/ folder at all, its Build.cs declares no PublicDependencyModuleNames, and DREAMSHADEREDITOR_API — which UnrealBuildTool defines for every module — has zero occurrences anywhere in the plugin's source. Its module class FDreamShaderEditorModule is declared inside the .cpp, not in a header, so it cannot be named from outside either. Everything the editor module does is reachable only through UE's module system, through UI actions, or through the commandlet. Compiling is no longer among those things: since 2.0 the compiler is its own module, reached through IDreamShaderCompiler.

UE_PLUGIN_NAME is "DreamShader" for all five modules.

None of the headers guards its export macro with an #ifndef; all of them require the UBT-generated definitions.

There are no module singletons

The plugin declares no Get(), IsAvailable() or GetChecked() accessor on any module class. Use the stock module manager — or, for the compiler, GetDreamShaderCompiler(), which is the one registry the plugin has:

FDreamShaderModule& Module = FModuleManager::LoadModuleChecked<FDreamShaderModule>(TEXT("DreamShader"));

In practice nothing is needed from the module object itself — the exported free functions in UE::DreamShader are usable as soon as the module is loaded.

Build dependencies

DreamShader.Build.cs

DreamShaderPass.Build.cs

(since 2.1.0)

The engine gate is in the build rules rather than in the descriptor, which has no per-module engine field, and the define is public so that DreamShaderCompiler and DreamShaderEditor ask it the same question instead of deriving it again.

DreamShaderCompiler.Build.cs

The public dependencies are public because the public headers expose them: UMaterial* and EMaterialProperty (Engine), FTextShaderDefinition and the compile interface (DreamShader), FLangDiagnosticSink / FModule / FIRModule (DreamShaderLang). An Editor-type module cannot be a dependency of a Runtime one, which is why the interface itself lives in DreamShader.

DreamShaderPass, RenderCore, RHI and TargetPlatform are the .dsp half (since 2.1.0): DreamShaderPass for the asset a .dsp compiles to, its settings and its slot paths; the other three for the HLSL slots — the shader source mappings, the pre-check's in-process compile, the global shader types it finds by name, the shader platforms and the formats the target platforms cook. No public header of the module names them, so they are private.

DreamShaderEditor.Build.cs

Plugin dependencies

DreamShader.uplugin enables exactly two other plugins. Both are used only by DreamShaderEditor.

Pages

Notes

• Asking for a compile needs only the runtime module. GetDreamShaderCompiler() hands back the compiler the editor side registered, or null where none exists (a game target). Generation itself is editor-only and lives in DreamShaderCompiler.
• The language is engine-independent. Everything in DreamShaderLang — parsing either syntax, binding, lowering to IR, printing, migrating — is string and data processing over Core; it creates no UObjects and loads no assets. Binding needs an FBuiltinCatalog, which dsc export-catalog writes as JSON for tools that run outside the editor.
• DreamShader exports two UCLASSes, UDreamShaderSettings and UDreamShaderMaterialInstance. DreamShaderPass (since 2.1.0) exports seven with DREAMSHADERPASS_API — the pipeline, the settings, the subsystem, the volume, the two components and the Blueprint library — and declares its two material expressions MinimalAPI. UDreamShaderCommandlet exists in the editor module's Private/ folder with no API macro, so it is reachable only through UE's reflection system and -run=DreamShader.
• Config/FilterPlugin.ini contains only the stock commented template — the plugin declares no extra packaged files.

Example

A consuming module that wants to parse DreamShaderLang and request compiles:

// MyTooling.Build.cs
PrivateDependencyModuleNames.AddRange(new[]
{
    "Core",
    "CoreUObject",
    "Engine",
    "DreamShaderLang",      // the language: parse, print, bind, IR
    "DreamShader"           // paths, settings, the compile interface
});

#include "DreamShaderCompilerInterface.h"
#include "DreamShaderModule.h"
#include "Lang/LangParser.h"

using namespace UE::DreamShader;

void InspectSource(const FString& InPath)
{
    if (!IsDreamShaderSourceFile(InPath))
    {
        return;
    }

    FString SourceText;
    const FString Path = NormalizeSourceFilePath(InPath);
    if (!FFileHelper::LoadFileToString(SourceText, *Path))
    {
        return;
    }

    // Auto picks the front end from the extension: .dss / .dsi / .dsp / .dsh are 2.0, .dsm / .dsf are 1.x.
    const Lang::FLangSourceText Source(Path, SourceText);
    const Lang::FLangParseResult Parsed = Lang::ParseDreamShaderLang(Source);
    UE_LOG(LogDreamShader, Display, TEXT("%s: %d declaration(s), %d diagnostic(s)."),
        *Path,
        Parsed.Module.IsValid() ? Parsed.Module->Declarations.Num() : 0,
        Parsed.Diagnostics.GetDiagnostics().Num());

    if (Parsed.Succeeded())
    {
        if (IDreamShaderCompiler* Compiler = GetDreamShaderCompiler())
        {
            FDreamShaderCompileRequest Request;
            Request.SourceFilePath = Path;
            Compiler->CompileAssets(Request);
        }
    }
}

ParseDreamShaderLang does not read files and does not follow #include / import: includes are resolved at bind time, by the resolver the host hands the binder.

See also

• DreamShaderModule.h — the module entry point and its exported helpers
• DreamShaderCompiler — the compile interface, the service and the pipeline
• DreamShaderPass — the Custom Pass runtime
• Project settings — UDreamShaderSettings from the user's side
• Generation — what an emitted asset looks like
• Commandlet — -run=DreamShader, the headless entry point
• Editor bridge — the WebSocket server and request-file protocol
• Workspace — the bridge.db cache and the exported manifests
• Contributing — building the plugin from source