DreamShaderPass

DreamShader » C++ API » DreamShaderPass

The Custom Pass runtime: the asset a .dsp compiles to, what decides which pipelines apply to a view, and the scene view extension that runs their passes inside the renderer. This page is the module's C++ and Blueprint surface; what the passes do at run time is Custom Pass runtime.

Public headers

DREAMSHADER_WITH_CUSTOM_PASS

A public definition of the module, set by DreamShaderPass.Build.cs from the target engine: 1 on 5.8 and later, 0 below — or on any engine built with -ProjectDefine:DREAMSHADER_FORCE_NO_CUSTOM_PASS, for testing. Every module that depends on this one reads the same answer.

• Reflected types exist on every engine — the asset, the settings, the subsystem, the volume and the components compile anywhere, so a project that opens on an older engine still loads and saves them.
• Everything that touches the renderer is compiled out at 0: the scene view extension, the passes, the global and mesh-pass shaders. Nothing runs, and the module says so once in the log at startup.

Activating a pipeline

From C++, through the world's subsystem:

#include "DreamPassSubsystem.h"

UDreamPassSubsystem* Passes = UDreamPassSubsystem::Get(GetWorld());
FDreamPassHandle Handle = Passes->AddPipeline(HighlightPipeline, /*Priority*/ 0.0f, /*Overrides*/ {});
Passes->SetParameter(Handle, TEXT("Thickness"), FDreamPassParameterValue::MakeFloat(3.0f));
Passes->SetWeight(Handle, 0.5f);
// ...
Passes->RemovePipeline(Handle);

From Blueprints, the same calls are on UDreamPassBlueprintLibrary with a world context, plus SetFloatParameter, SetColorParameter, SetBoolParameter, SetIntParameter, SetTextureParameter and the Make…Value helpers.

Or place a source in the level — an ADreamPassVolume, a UDreamPassComponent — or list the pipeline in the project settings. How the four kinds combine is in What makes a pipeline apply.

UDreamPassSubsystem

A UWorldSubsystem of game, PIE and editor worlds; an editor preview world has none. Game thread only.

FDreamPassHandle is a BlueprintType struct; a default one is not valid (IsValid()).

ADreamPassVolume

An AVolume that runs its pipeline in the views inside it, with a post-process volume's arithmetic.

SetEnabled, SetBlendWeight and SetParameter(Name, Value) are Blueprint-callable; GetWeightAt(Location) is the weight a view there would get. Outside a game world the volume follows its editor visibility: hiding it in the outliner takes it out of the editor viewports. A volume spawned at runtime has no brush, and applies only when unbound.

UDreamPassComponent

An actor component that runs its pipeline from any actor.

SetEnabled, SetWeight, SetParameter, SetFloatParameter and SetColorParameter are Blueprint-callable; SetColorParameter sets a float3 or a float4 parameter, whichever the pipeline declares.

Writing an activation source

Anything can activate pipelines by implementing IDreamPassActivationSource and registering with the subsystem while it should apply:

class FMyGameModeSource : public IDreamPassActivationSource
{
public:
    virtual void GatherDreamPassActivations(const FDreamPassViewQuery& View, TArray<FDreamPassActivation>& Out) const override
    {
        if (View.PlayerIndex == 0)   // the first player only
        {
            FDreamPassActivation& Activation = Out.AddDefaulted_GetRef();
            Activation.Pipeline = Pipeline;
            Activation.Weight = Fade;
        }
    }

    UDreamPassPipeline* Pipeline = nullptr;   // keep it referenced elsewhere: the subsystem does not
    float Fade = 1.0f;
};

Subsystem->RegisterSource(Owner, &Source);   // Owner: the UObject whose lifetime bounds the registration
Subsystem->UnregisterSource(Owner);

GatherDreamPassActivations is called on the game thread for every view of every frame, so it should be cheap. FDreamPassViewQuery gives the view's location, local player, view target, kind and capabilities; an activation's Overrides is a view into storage the source owns, valid for the call.

UDreamPassPipeline

The compiled pipeline. Its fields mirror the .dsp — Order, DefaultInjection, Views, Requires, EnabledParameter, Parameters, Buffers, Passes, the exported render targets — and SourceFilePath and SourceHash say which source built it. Edit the .dsp, not the asset: a compile overwrites it, and an edit made in the details panel is a divergence to adopt or discard. A pass's HLSL written in the .dsp is kept in the editor's data only -- HlslSource on the pass says where its code is, InlineHlsl and InlineHlslLine hold its own hlsl block, and the pipeline's SharedHlsl the file's -- for the way back to text: what runs is the slot's snapshot, and a cook carries no HLSL text.

The HLSL slot registry

The counts are overridable from a Target.cs (GlobalDefinitions.Add("DREAMSHADER_PASS_COMPUTE_SLOTS=48")); raising one recompiles the two global shader types, nothing else. How the registry is written is HLSL passes.

See also

• Custom Pass runtime
• Custom Pass pipelines — .dsp
• HLSL passes
• Custom Pass material nodes
• Project settings