DreamShaderModule.h

DreamShader » C++ API » DreamShaderModule.h

The runtime module entry point, the plugin's log category, and the path, identifier and file-classification helpers every other module builds on.

Defined in header DreamShaderModule.h.

Synopsis

#include "CoreMinimal.h"
#include "DreamShaderVersionCompat.h"
#include "Modules/ModuleManager.h"

class IPlugin;

DREAMSHADER_API DECLARE_LOG_CATEGORY_EXTERN(LogDreamShader, Log, All);

namespace UE::DreamShader
{
    struct FDreamShaderSourceRoot
    {
        FString Directory;          // absolute, normalized, no trailing slash
        FString PackagesDirectory;  // <Directory>/Packages
        FString DisplayName;        // "Project", or the owning plugin's name
        FString PluginName;         // empty for the project root
        bool bIsProjectRoot = false;
        bool bIsProjectPlugin = false; // true when the plugin is one this project generates into
        bool bWritable = false;     // true for the project root only
    };

    DREAMSHADER_API const TArray<FDreamShaderSourceRoot>& GetSourceShaderRoots();
    DREAMSHADER_API const FDreamShaderSourceRoot* FindSourceRootForFile(const FString& InPath);
    DREAMSHADER_API bool IsWritableSourceFilePath(const FString& InPath);
    DREAMSHADER_API bool IsProjectContentPlugin(const IPlugin& InPlugin);
    DREAMSHADER_API void RefreshSourceShaderRoots();
    DREAMSHADER_API bool IsPathUnderSourceDirectory(const FString& InPath, const FString& InDirectory);

    DREAMSHADER_API FString GetSourceShaderDirectory();
    DREAMSHADER_API FString GetPackageShaderDirectory();
    DREAMSHADER_API FString GetGeneratedShaderDirectory();
    DREAMSHADER_API FString GetGeneratedShaderVirtualDirectory();
    DREAMSHADER_API FString SanitizeIdentifier(const FString& InText);
    DREAMSHADER_API FString NormalizeSourceFilePath(const FString& InPath);
    DREAMSHADER_API bool IsDreamShaderMaterialFile(const FString& InPath);
    DREAMSHADER_API bool IsDreamShaderHeaderFile(const FString& InPath);
    DREAMSHADER_API bool IsDreamShaderFunctionFile(const FString& InPath);
    DREAMSHADER_API bool IsDreamShaderLang2File(const FString& InPath);
    DREAMSHADER_API bool IsDreamShaderInstanceFile(const FString& InPath);
    DREAMSHADER_API bool IsDreamShaderPipelineFile(const FString& InPath);
    DREAMSHADER_API bool IsDreamShaderSourceFile(const FString& InPath);
}

class DREAMSHADER_API FDreamShaderModule : public IModuleInterface
{
public:
    virtual void StartupModule() override;
    virtual void ShutdownModule() override;
};

LogDreamShader

Every message the compiler and the editor log — diagnostics surfaced to the log, generation results, cook progress, bridge and SQLite warnings — goes through this one category. Raise it from a config file or the console:

[Core.Log]
LogDreamShader=Verbose

Directory functions

FString GetSourceShaderDirectory();
FString GetPackageShaderDirectory();
FString GetGeneratedShaderDirectory();
FString GetGeneratedShaderVirtualDirectory();

Resolution of a configured path, in order:

The three configured paths are held in one internal cache. It is refreshed when it has not been initialized or when the settings object is currently readable — that is, UObjectInitialized() && !GExitPurge && !IsEngineExitRequested(). Once the UObject system is live this condition is always true, so the settings are re-read on every call and a mid-session change in Project Settings takes effect immediately. Before UObjects exist, and during exit purge, the getters do not touch GetDefault<UDreamShaderSettings>(): they read SourceDirectory and GeneratedShaderDirectory straight from [/Script/DreamShader.DreamShaderSettings] in the engine ini — the values the settings object will load — and fall back to the defaults when a key is absent. The module starts at PostConfigInit, before the settings object can exist, which is why.

[!WARNING] GetGeneratedShaderDirectory() is not simply the Generated Shader Directory setting. StartupModule registers the /DreamShaderGenerated mapping only if it is absent, and never re-points it. Changing the setting mid-session therefore changes where StartupModule would have mounted, and changes the internal cached value, but GetGeneratedShaderDirectory() keeps returning the directory that was mounted at startup. Restart the editor to move the mount. See Generated HLSL.

[!NOTE] The cache is a plain static with no lock. Treat all four functions as game-thread APIs even though nothing in them is intrinsically thread-affine.

Source roots

(since 1.6.0)

const TArray<FDreamShaderSourceRoot>& GetSourceShaderRoots();
const FDreamShaderSourceRoot* FindSourceRootForFile(const FString& InPath);
bool IsWritableSourceFilePath(const FString& InPath);
bool IsProjectContentPlugin(const IPlugin& InPlugin);
void RefreshSourceShaderRoots();
bool IsPathUnderSourceDirectory(const FString& InPath, const FString& InDirectory);

A source root is one directory tree sources are discovered under, and the unit of import resolution: a file's imports resolve against its own root and that root's Packages folder only.

Only the project root is writable: editor features that rewrite sources in place (VirtualFunction sync, asset rename sync) never touch a plugin root.

FDreamShaderSourceRoot::bIsProjectPlugin carries a second, independent answer about a plugin root — whether its products are the project's to build at all, computed with IsProjectContentPlugin. The cook reads it for a source that failed to generate: under a plugin that is not a project plugin the failure is reported and the cook goes on, because those assets ship with that plugin. See Cook behaviour.

SanitizeIdentifier

DREAMSHADER_API FString SanitizeIdentifier(const FString& InText);

Rewrites arbitrary text into something usable as an HLSL or asset identifier. Pure; touches no engine state; callable from any thread.

[!WARNING] Character classification is done against raw ASCII ranges. Non-ASCII letters are replaced, not preserved — Ünlit becomes _nlit, not Ünlit. Use ASCII identifiers in namespace and function names.

Callers inside the plugin: the transient ThinCustom base-material name in the emitter (MB_DreamThinBase_<package>), the output named-reroute names (DS_<Name>_<Index>), and the MI_<Name> stem of a new instance's .dsi file in the instance factory and the provenance actions. DreamShaderLang cannot link this module, so the legacy front end (flattening A::B to A_B) and the custom-HLSL builder (DreamShaderFn_<Name>) each keep a copy of the same rule (since 2.0.0).

NormalizeSourceFilePath

DREAMSHADER_API FString NormalizeSourceFilePath(const FString& InPath);

Applies FPaths::ConvertRelativePathToFull, then FPaths::NormalizeFilename, then FPaths::MakeStandardFilename. The result is an absolute path with / separators.

This is the canonical key for a source file. The bridge, the diagnostics store, the compiler and the commandlet all normalize before comparing paths, so a path produced by this function compares equal to the one the plugin stores internally.

The four normalizers compared

Four differently-behaving functions have similar names. They are not interchangeable.

The last two are the pair most often confused. NormalizeSettingKey keeps spaces and punctuation, so the setting keys Two Sided and TwoSided are different keys. NormalizeMappingKey removes them, so the values Two Sided Foliage, TwoSidedFoliage and two-sided_foliage all resolve to the same shading model.

File-classification predicates

DREAMSHADER_API bool IsDreamShaderMaterialFile(const FString& InPath);
DREAMSHADER_API bool IsDreamShaderHeaderFile(const FString& InPath);
DREAMSHADER_API bool IsDreamShaderFunctionFile(const FString& InPath);
DREAMSHADER_API bool IsDreamShaderLang2File(const FString& InPath);
DREAMSHADER_API bool IsDreamShaderInstanceFile(const FString& InPath);
DREAMSHADER_API bool IsDreamShaderPipelineFile(const FString& InPath);
DREAMSHADER_API bool IsDreamShaderSourceFile(const FString& InPath);

IsDreamShaderSourceFile is the one predicate everything that scans, watches or lists sources asks — the startup scan, the source-directory watcher, compile -All, the Material Content Browser — so a .dsp is a source to all of them; only the compiler tells the kinds apart. All seven compare the result of FPaths::GetExtension(InPath, /*bIncludeDot*/ true) with ESearchCase::IgnoreCase, so extension matching is case-insensitive: Foo.DSM classifies as a material file. Only the extension is examined — the file need not exist and its contents are never read. Pure; any thread.

FDreamShaderModule

class DREAMSHADER_API FDreamShaderModule : public IModuleInterface
{
public:
    virtual void StartupModule() override;
    virtual void ShutdownModule() override;
};

Registered with IMPLEMENT_MODULE(FDreamShaderModule, DreamShader). The class exposes no state and no accessors; obtain it, if you need to at all, with FModuleManager::LoadModuleChecked<FDreamShaderModule>(TEXT("DreamShader")).

StartupModule()

Runs on the game thread when the module loads, in the PostConfigInit phase — before any material loads, so that a material whose cached include paths name /DreamShaderGenerated finds the mapping registered. It performs five side effects in order.

The plugin's Shaders/ folder holds DreamShaderBuiltins.ush, addressable as /Plugin/DreamShader/DreamShaderBuiltins.ush (see DreamShaderBuiltins.ush), and, (since 2.1.0), the Custom Pass shaders under Pass/ (/Plugin/DreamShader/Pass/…).

Steps 1–3 mean the source and package directories exist from the first editor launch, whether or not the user has authored anything.

ShutdownModule()

Empty.

[!NOTE] The two virtual shader directory mappings registered by StartupModule are never unregistered. In an editor session that unloads and reloads the module, step 4 and step 5 are both no-ops the second time round, and the mounts keep pointing at whatever they were first given.

Notes

• DreamShaderVersionCompat.h is included by this header, so anything that includes DreamShaderModule.h also gets the thirteen version macros. See DreamShaderVersionCompat.h.
• None of the free functions logs, throws or asserts. Failures are expressed as a fallback value — the default path, DreamShaderSymbol, or false.
• This header declares no delegates. The notification that a compile finished is OnDreamShaderSourceGenerated in the DreamShaderCompiler module — see Compiler module; tools outside the editor read the bridge's diagnostics files instead — see Editor bridge.

Example

#include "DreamShaderModule.h"
#include "HAL/FileManager.h"

using namespace UE::DreamShader;

/** Enumerate every DreamShaderLang source under the configured source root. */
void CollectProjectSources(TArray<FString>& OutFiles)
{
    const FString Root = GetSourceShaderDirectory();

    TArray<FString> Found;
    IFileManager::Get().FindFilesRecursive(Found, *Root, TEXT("*.*"), /*Files*/ true, /*Dirs*/ false);

    for (const FString& File : Found)
    {
        if (IsDreamShaderSourceFile(File))
        {
            OutFiles.Add(NormalizeSourceFilePath(File));
        }
    }

    UE_LOG(LogDreamShader, Display, TEXT("Found %d DreamShader source(s) under %s"), OutFiles.Num(), *Root);
}

Typical output with default settings:

LogDreamShader: Found 3 DreamShader source(s) under I:/Project/DShader

A compile writes no helper include (since 2.0.0): an HLSL function becomes the code of a Custom node, with the HLSL functions it calls embedded in that code. The /DreamShaderGenerated mapping is still registered at startup, and Clean Generated Shaders still empties GetGeneratedShaderDirectory() of *.ush files.

See also

• C++ API — modules, headers, and linkage
• DreamShaderTypes.h — NormalizeSettingKey and the parsed-source data model
• DreamShaderSettings.h — SourceDirectory, GeneratedShaderDirectory, NormalizeMappingKey
• DreamShaderVersionCompat.h — the macros this header pulls in
• DreamShaderCompiler — requesting a compile from C++
• DreamShaderLang — the Core-only front end. DreamShaderPreprocessor.h, DreamShaderDefineTable.h and DreamShaderDiagnostic.h moved into it in 2.0; the include spellings did not change. Only DreamShaderDefineResolution.h — the tier merge that reads project settings, the engine version, the plugin descriptor and the command line — stayed in this module
• Project settings — the two directory settings from the user's side
• Generated HLSL — what /DreamShaderGenerated receives
• Packages — the DShader/Packages directory
• Source files — what the three extensions may contain
• DreamShaderBuiltins.ush — the header mounted at /Plugin/DreamShader