mcpField
U
ue-materials-rendering

ue-materials-rendering

github.com/quodsoler開発4191.3k 回インストール4 週間前に更新
リポジトリ

ue-materials-rendering について

UE 5.8 の C++ によるマテリアルとレンダリング開発向けのコーディングスキルです。一般的な作業に対応する API、シグネチャ、実装方法を、マテリアルやレンダーターゲットなどの分野別にまとめています。

主な機能

  1. 01ランタイムのマテリアルパラメーター制御
  2. 02マテリアルパラメーターコレクション
  3. 03レンダーターゲットとシーンキャプチャ
  4. 04ポストプロセスとデカールのガイダンス
  5. 05UE 5.8 レンダラー機能のリファレンス

活用シーン

  1. 01個々の Actor のマテリアル値の変更
  2. 02複数マテリアルで天候や時刻の値を共有
  3. 03ミニマップ、鏡、カメラ映像の描画
  4. 04ポストプロセス効果やデカールの実装

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/quodsoler/unreal-engine-skills --skill ue-materials-rendering

インストール後、Claude Code で/ue-materials-renderingを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
global-shaders-rdg.md
material-parameter-reference.md
post-process-settings.md

詳細

UE マテリアルとレンダリング

対象エンジン：UE 5.8。以下の API は 5.8 のヘッダーで確認済みです。以前の形式は「非推奨 — 使用しないでください」に記載しています。

ランタイムのマテリアルおよびレンダリング用 C++：UMaterialInstanceDynamic、UMaterialParameterCollection、UTextureRenderTarget2D、USceneCaptureComponent2D、FPostProcessSettings、UDecalComponent、および 5.8 のレンダラー機能（Nanite、Lumen、MegaLights、Substrate、Virtual Shadow Maps、TSR）。マテリアルのヘッダーは Runtime/Engine/Public/Materials にあります。レンダーターゲット、シーン、ポストプロセスボリュームは Runtime/Engine/Classes/Engine にあります。Blueprint ライブラリは Runtime/Engine/Classes/Kismet にあります。Build.cs では、上記すべてに "Engine" を使用します。EShaderPlatform、RDG、グローバルシェーダーを使用する場合に限り、"RenderCore" と "RHI" を追加します。

コンテキスト

.agents/ue-project-context.md が存在する場合は読み込んでください（モジュール名、規約、有効なプラグイン、レンダラー設定）。存在しない場合も作業を止めないでください。

依頼内容とコードベースから該当する領域を特定してください。異なるコードが必要になる解釈が複数ある場合に限り、質問してください。

依頼内容…参照先
メッシュ上のマテリアルパラメーターをランタイムで変更するダイナミックマテリアルインスタンス
複数のマテリアルを 1 つの値で駆動する（天候、時刻）マテリアルパラメーターコレクション
ミニマップ、ミラー、防犯カメラ、ランタイムのテクスチャペイントレンダーターゲット / シーンキャプチャ
ブルーム、露出、DOF、カラーグレーディング、Lumen の品質調整ポストプロセス
マテリアルとして作成する全画面エフェクトポストプロセスマテリアル
弾痕、血痕、投影テクスチャデカール
Nanite メッシュ／マテリアルの互換性、WPO、Nanite のオーバーライドマテリアルNanite
GI、反射、多数のシャドウ付きライトLumen と MegaLights
レイヤー型／複数 BSDF のマテリアルシステムSubstrate
アウトライン、X 線、ステンシルマスク、シャドウ／アンチエイリアス設定シャドウ、アンチエイリアス、カスタムデプス
API が EShaderPlatform を要求するが、手元にあるのがフィーチャーレベルの場合フィーチャーレベルとシェーダープラットフォーム
C++ から実際の HLSL シェーダーパスを記述するグローバルシェーダーとレンダーグラフ

完全なシグネチャ表は material-parameter-reference.md にあります。FPostProcessSettings のフィールド表は post-process-settings.md にあります。グローバルシェーダーと RDG のコードは global-shaders-rdg.md にあります。

ダイナミックマテリアルインスタンス

MID は、親マテリアルのパラメーターをインスタンス単位でオーバーライドしたものです。作成方法は 3 つあります。

必要なもの呼び出し
スロットに割り当てないスタンドアロンの MIDUMaterialInstanceDynamic::Create(Parent, Outer, Name)
コンポーネントのマテリアルスロットに割り当てる MIDUPrimitiveComponent::CreateDynamicMaterialInstance(ElementIndex, SourceMaterial, OptionalName)
Blueprint 対応ライブラリーコードから作成する MIDUKismetMaterialLibrary::CreateDynamicMaterialInstance(WorldContextObject, Parent, OptionalName, CreationFlags)

正確なシグネチャ：

// Materials/MaterialInstanceDynamic.h
static UMaterialInstanceDynamic* Create(class UMaterialInterface* ParentMaterial, class UObject* InOuter, FName Name = NAME_None);

// Components/PrimitiveComponent.h
virtual class UMaterialInstanceDynamic* CreateDynamicMaterialInstance(int32 ElementIndex, class UMaterialInterface* SourceMaterial = NULL, FName OptionalName = NAME_None);

// Kismet/KismetMaterialLibrary.h
static class UMaterialInstanceDynamic* CreateDynamicMaterialInstance(UObject* WorldContextObject, class UMaterialInterface* Parent, FName OptionalName = NAME_None, EMIDCreationFlags CreationFlags = EMIDCreationFlags::None);

一度だけ作成して UPROPERTY にキャッシュし、Tick またはイベントで更新します。

// MyGlowActor.h
#pragma once

#include "CoreMinimal.h"
#include "GameFramework/Actor.h"
#include "MyGlowActor.generated.h"

class UMaterialInstanceDynamic;
class UStaticMeshComponent;

UCLASS()
class MYGAME_API AMyGlowActor : public AActor
{
    GENERATED_BODY()

public:
    AMyGlowActor();
    virtual void BeginPlay() override;

protected:
    UPROPERTY(VisibleAnywhere, Category = "Rendering")
    TObjectPtr<UStaticMeshComponent> Mesh;

    UPROPERTY(Transient)
    TObjectPtr<UMaterialInstanceDynamic> GlowMID;
};

// MyGlowActor.cpp
#include "MyGlowActor.h"

#include "Components/StaticMeshComponent.h"
#include "Materials/MaterialInstanceDynamic.h"

AMyGlowActor::AMyGlowActor()
{
    Mesh = CreateDefaultSubobject<UStaticMeshComponent>(TEXT("Mesh"));
    SetRootComponent(Mesh);
}

void AMyGlowActor::BeginPlay()
{
    Super::BeginPlay();

    GlowMID = Mesh->CreateDynamicMaterialInstance(0);
    if (GlowMID)
    {
        GlowMID->SetVectorParameterValue(TEXT("GlowColor"), FLinearColor(1.f, 0.4f, 0.1f, 1.f));
        GlowMID->SetScalarParameterValue(TEXT("GlowStrength"), 1.f);
    }
}

フレームごとに数十個のパラメーターを変更する場合は、名前検索をインデックス API に置き換えます。まず一度だけ InitializeScalarParameterAndGetIndex を呼び出し、その後はフレームごとに SetScalarParameterByIndex を呼び出します。シグネチャとベクター版については、material-parameter-reference.md を参照してください。

セッター（MaterialInstanceDynamic.h）— 名前は大文字と小文字を区別する FName で、マテリアルのパラメーター名と完全に一致している必要があります。

void SetScalarParameterValue(FName ParameterName, float Value);
void SetVectorParameterValue(FName ParameterName, FLinearColor Value);
void SetDoubleVectorParameterValue(FName ParameterName, FVector4 Value);
void SetTextureParameterValue(FName ParameterName, class UTexture* Value);
void SetRuntimeVirtualTextureParameterValue(FName ParameterName, class URuntimeVirtualTexture* Value);
void SetSparseVolumeTextureParameterValue(FName ParameterName, class USparseVolumeTexture* Value);
void SetTextureCollectionParameterValue(FName ParameterName, UTextureCollection* Value);

ダブルベクターとスパースボリュームのセッターを除くすべてのセッターには ByInfo 版があります。たとえば SetScalarParameterValueByInfo(const FMaterialParameterInfo& ParameterInfo, float Value) です。これを使うと、マテリアルレイヤーまたは関数内のパラメーターにアクセスできます。

値の読み戻し：K2_GetScalarParameterValue(FName)、K2_GetVectorParameterValue(FName)、K2_GetTextureParameterValue(FName) は値を直接返します。UMaterialInterface の型付き形式は bool GetScalarParameterValue(const FHashedMaterialParameterInfo& ParameterInfo, float& OutValue, bool bOveriddenOnly = false) const です。これはパラメーターの info を受け取り、単なる名前は受け取りません。

インスタンス間のコピー：CopyParameterOverrides（オーバーライドされたパラメーターのみ）、CopyInterpParameters（ソース独自のスカラー、ベクター、テクスチャ、フォントのオーバーライド。階層は走査しません）、CopyMaterialUniformParameters（ユニフォーム。スタティックパラメーターはスキップします）、K2_CopyMaterialInstanceParameters（スタティック以外のすべてのパラメーター）、CopyScalarAndVectorParameters(const UMaterialInterface&, EShaderPlatform)、および K2_InterpolateMaterialInstanceParams(SourceA, SourceB, Alpha)。ClearParameterValues() はすべてのオーバーライドを削除します。シグネチャの全文は material-parameter-reference.md を参照してください。

スタティックパラメーター（スタティックスイッチ、スタティックブール値、スタティックコンポーネントマスク）は MID では変更できません。エディターでパーミュテーションごとに UMaterialInstanceConstant を作成し、その上に MID を配置します。

マテリアルパラメーターコレクション

UMaterialParameterCollection は ScalarParameters／VectorParameters 配列を持つアセットです。これを参照するすべてのマテリアルは、ワールドごとに 1 つのユニフォームバッファーから値を読み取ります。UWorld からワールドごとのインスタンスを取得します。

#include "Materials/MaterialParameterCollection.h"
#include "Materials/MaterialParameterCollectionInstance.h"

void AMyWeatherActor::SetRain(float Intensity)
{
    UMaterialParameterCollectionInstance* Inst = GetWorld()->GetParameterCollectionInstance(RainCollection);
    if (Inst)
    {
        Inst->SetScalarParameterValue(TEXT("RainIntensity"), Intensity);
        Inst->SetVectorParameterValue(TEXT("RainTint"), FLinearColor(0.6f, 0.7f, 0.9f, 1.f));
    }
}

名前がコレクションにない場合、両方のセッターは false を返します。ゲッターは bool GetScalarParameterValue(FName ParameterName, float& OutParameterValue) const と、そのベクター版です。ForceReturnToDefaultValues() はインスタンスをリセットします。

Blueprint 対応ライブラリーは、ワールドの検索を代わりに行います（Kismet/KismetMaterialLibrary.h）。

static void SetScalarParameterValue(UObject* WorldContextObject, UMaterialParameterCollection* Collection, FName ParameterName, float ParameterValue);
static void SetVectorParameterValue(UObject* WorldContextObject, UMaterialParameterCollection* Collection, FName ParameterName, const FLinearColor& ParameterValue);
static float GetScalarParameterValue(UObject* WorldContextObject, UMaterialParameterCollection* Collection, FName ParameterName);
static FLinearColor GetVectorParameterValue(UObject* WorldContextObject, UMaterialParameterCollection* Collection, FName ParameterName);

コレクションにはテクスチャパラメーターを格納できません。多くのマテリアルで読み取る 1 つの値にはコレクションを、アクターごとの状態には MID を使用します。

レンダーターゲット

UKismetRenderingLibrary（Kismet/KismetRenderingLibrary.h）は、ランタイムのレンダーターゲットワークフローを管理します。

static UTextureRenderTarget2D* CreateRenderTarget2D(UObject* WorldContextObject, int32 Width = 256, int32 Height = 256, ETextureRenderTargetFormat Format = RTF_RGBA16f, FLinearColor ClearColor = FLinearColor::Black, bool bAutoGenerateMipMaps = false, bool bSupportUAVs = false);
static void ClearRenderTarget2D(UObject* WorldContextObject, UTextureRenderTarget2D* TextureRenderTarget, FLinearColor ClearColor = FLinearColor(0, 0, 0, 1));
static void ResizeRenderTarget2D(UTextureRenderTarget2D* TextureRenderTarget, int32 Width = 256, int32 Height = 256);
static void ReleaseRenderTarget2D(UTextureRenderTarget2D* TextureRenderTarget);
static void DrawMaterialToRenderTarget(UObject* WorldContextObject, UTextureRenderTarget2D* TextureRenderTarget, UMaterialInterface* Material);
static void ExportRenderTarget(UObject* WorldContextObject, UTextureRenderTarget2D* TextureRenderTarget, const FString& FilePath, const FString& FileName);
static FColor ReadRenderTargetPixel(UObject* WorldContextObject, UTextureRenderTarget2D* TextureRenderTarget, int32 X, int32 Y);

ETextureRenderTargetFormat（Engine/TextureRenderTarget2D.h）：RTF_R8、RTF_RG8、RTF_RGBA8、RTF_RGBA8_SRGB、RTF_R16f、RTF_RG16f、RTF_RGBA16f、RTF_R32f、RTF_RG32f、RTF_RGBA32f、RTF_RGB10A2。データを保持できる最小のフォーマットを選びます。LDR/UI には RTF_RGBA8、HDR には RTF_RGBA16f、単一チャンネルには RTF_R16f を使用します。

正確なピクセルフォーマットが必要な場合の手動作成：

UTextureRenderTarget2D* RT = NewObject<UTextureRenderTarget2D>(this);
RT->InitCustomFormat(512, 512, PF_FloatRGBA, /*bInForceLinearGamma=*/true);
RT->UpdateResourceImmediate(/*bClearRenderTarget=*/true);

キャンバス描画では、複数の描画を1回のレンダーターゲット遷移にまとめます。

UCanvas* Canvas = nullptr;
FVector2D CanvasSize = FVector2D::ZeroVector;
FDrawToRenderTargetContext Context;

UKismetRenderingLibrary::BeginDrawCanvasToRenderTarget(this, RT, Canvas, CanvasSize, Context);
Canvas->K2_DrawMaterial(IconMaterial, FVector2D::ZeroVector, CanvasSize, FVector2D::ZeroVector);
UKismetRenderingLibrary::EndDrawCanvasToRenderTarget(this, Context);

UCanvasRenderTarget2D（Engine/CanvasRenderTarget2D.h）はこのループをラップします。CreateCanvasRenderTarget2D(WorldContextObject, CanvasRenderTarget2DClass, Width, Height) で作成し、OnCanvasRenderTargetUpdate をバインドして、コンテンツを再描画する必要があるときに UpdateResource() を呼び出します。

ReadRenderTargetPixel などは GPU を停止させます。エディタツールや単発のキャプチャで使用し、毎フレームは使用しないでください。ストリーミング読み出しには FRHIGPUTextureReadback を使用します。

シーンキャプチャ

USceneCaptureComponent2D はワールドを UTextureRenderTarget2D にレンダリングします。このクラス独自のフィールド：TextureTarget、FOVAngle、PostProcessSettings、PostProcessBlendWeight、bMainViewResolution、CaptureScene()、CaptureSceneDeferred()。USceneCaptureComponent から継承されるもの：CaptureSource、bCaptureEveryFrame、bCaptureOnMovement、PrimitiveRenderMode、ShowOnlyActors、HiddenActors、ShowFlags、ShowOnlyComponent()、ShowOnlyActorComponents()。

#include "Components/SceneCaptureComponent2D.h"

SceneCapture = CreateDefaultSubobject<USceneCaptureComponent2D>(TEXT("SceneCapture"));
SceneCapture->SetupAttachment(RootComponent);
SceneCapture->FOVAngle = 90.f;
SceneCapture->CaptureSource = ESceneCaptureSource::SCS_FinalColorLDR;
SceneCapture->bCaptureEveryFrame = false;   // drive it manually
SceneCapture->bCaptureOnMovement = false;
SceneCapture->PrimitiveRenderMode = ESceneCapturePrimitiveRenderMode::PRM_UseShowOnlyList;
SceneCapture->ShowFlags.SetFog(false);
SceneCapture->ShowFlags.SetMotionBlur(false);

ESceneCaptureSource（Engine/EngineTypes.h）：SCS_SceneColorHDR、SCS_SceneColorHDRNoAlpha、SCS_FinalColorLDR、SCS_SceneColorSceneDepth、SCS_SceneDepth、SCS_DeviceDepth、SCS_Normal、SCS_BaseColor、SCS_FinalColorHDR、SCS_FinalToneCurveHDR。SCS_Normal と SCS_BaseColor はディファードレンダラーでのみ使用できます。

bCaptureEveryFrame = false と bCaptureOnMovement = false に設定し、ビューを更新する必要があるときに SceneCapture->CaptureScene() を呼び出します。シーンキャプチャでは、シーン全体が追加でレンダリングされます。

ポストプロセス

FPostProcessSettings（Engine/Scene.h）は、APostProcessVolume::Settings、UPostProcessComponent::Settings、UCameraComponent::PostProcessSettings、USceneCaptureComponent2D::PostProcessSettings に保持されます。各値フィールドには、対応する bOverride_<Field> ビットがあります。オーバーライドビットが true でない場合、その値は無視されます。

#include "Engine/PostProcessVolume.h"
#include "Engine/Scene.h"

void AMyMoodDirector::ApplyDangerMood(APostProcessVolume* Volume)
{
    Volume->bEnabled = true;
    Volume->bUnbound = true;
    Volume->Priority = 10.f;
    Volume->BlendWeight = 1.f;

    FPostProcessSettings& S = Volume->Settings;
    S.bOverride_BloomIntensity = true;
    S.BloomIntensity = 0.35f;
    S.bOverride_VignetteIntensity = true;
    S.VignetteIntensity = 0.8f;
    S.bOverride_ColorSaturation = true;
    S.ColorSaturation = FVector4(0.6f, 0.6f, 0.6f, 1.f);
}

APostProcessVolume と UPostProcessComponent はどちらも、Settings、Priority、BlendRadius、BlendWeight、bEnabled、bUnbound、AddOrUpdateBlendable(TScriptInterface<IBlendableInterface> InBlendableObject, float InWeight = 1.0f) を公開します。ボリュームが重なる場合は、Priority の値が大きい方が優先されます。bUnbound を設定すると、ボリュームがすべての場所に適用されます。

カメラごとのポストプロセス：PostProcessBlendWeight とともに UCameraComponent::PostProcessSettings を使用し、AddOrUpdateBlendable／RemoveBlendable も使用できます。（AddExtraPostProcessBlend は設定を保存するだけです。設定を読み戻すのはエディタービューポートのみです。Camera/CameraComponent.h:323。）カメラモディファイアーまたはカメラマネージャーから、一時的なブレンドを APlayerCameraManager::AddCachedPPBlend(FPostProcessSettings& PPSettings, float BlendWeight, EViewTargetBlendOrder BlendOrder = VTBlendOrder_Base) で追加し、GetCachedPostProcessBlends で読み戻します。キャッシュは ApplyCameraModifiers の開始時に毎フレームクリアされるため（PlayerCameraManager.cpp:289）、ブレンドは毎フレーム追加し直してください。ClearCachedPPBlends と PostProcessBlendCache 配列はどちらも保護されています（Camera/PlayerCameraManager.h:371,391）。

フィールド別の表（ブルーム、露出、DOF、カラーグレーディング、フィルムグレイン、AO、Lumen、SSR、モーションブラー、レンズ）は、ポストプロセス設定を参照してください。

ポストプロセスマテリアル

ポストプロセスマテリアルは、MaterialDomain が MD_PostProcess（MaterialDomain.h）である UMaterial です。関連する UMaterial のフィールドは、BlendableLocation、BlendablePriority、bIsBlendable、UserSceneTexture です。

EBlendableLocation（Engine/BlendableInterface.h）：BL_SceneColorBeforeDOF、BL_SceneColorAfterDOF、BL_TranslucencyAfterDOF、BL_SSRInput、BL_SceneColorBeforeBloom、BL_ReplacingTonemapper、BL_SceneColorAfterTonemapping。

// Weight 0 = invisible, 1 = full. Calling it again with the same object updates the weight.
Volume->AddOrUpdateBlendable(OutlineMaterial, 1.0f);

// A MID works as a blendable too, so the effect can be parameterised at runtime.
UMaterialInstanceDynamic* OutlineMID = UMaterialInstanceDynamic::Create(OutlineMaterial, this);
OutlineMID->SetScalarParameterValue(TEXT("Thickness"), 2.f);
Volume->AddOrUpdateBlendable(OutlineMID, 1.0f);

FPostProcessSettings::AddBlendable(TScriptInterface<IBlendableInterface> InBlendableObject, float InWeight) と RemoveBlendable は、ボリュームではなく設定構造体を保持している場合、WeightedBlendables 配列を直接操作します。

デカール

UDecalComponent（Components/DecalComponent.h）は、そのボックスと重なる対象にマテリアルを投影します。

void SetDecalMaterial(class UMaterialInterface* NewDecalMaterial);
class UMaterialInterface* GetDecalMaterial() const;
virtual class UMaterialInstanceDynamic* CreateDynamicMaterialInstance();
void SetFadeOut(float StartDelay, float Duration, bool DestroyOwnerAfterFade = true);
void SetFadeIn(float StartDelay, float Duration);
void SetFadeScreenSize(float NewFadeScreenSize);
void SetSortOrder(int32 Value);
void SetDecalColor(const FLinearColor& Color);

フィールド：DecalSize（ローカル空間での範囲。投影ボックスのスケールを設定します）、SortOrder、FadeScreenSize、FadeStartDelay、FadeDuration、DecalColor。

実行時には UGameplayStatics（Kismet/GameplayStatics.h）を使ってスポーンします。

UDecalComponent* Decal = UGameplayStatics::SpawnDecalAtLocation(
    this, BulletHoleMaterial, FVector(16.f, 16.f, 16.f), Hit.ImpactPoint, Hit.ImpactNormal.Rotation(), 10.f);

if (Decal)
{
    UMaterialInstanceDynamic* DecalMID = Decal->CreateDynamicMaterialInstance();
    DecalMID->SetScalarParameterValue(TEXT("Wear"), 0.25f);
}

SpawnDecalAttached(DecalMaterial, DecalSize, AttachToComponent, AttachPointName, Location, Rotation, LocationType, LifeSpan) は、動くコンポーネントに追従します。LifeSpan = 0 の場合、デカールは残り続けます。後から変更するには、UDecalComponent::SetLifeSpan(float)（Components/DecalComponent.h:153。UFUNCTION ではありません）を呼び出すか、SetFadeOut でフェードを制御します。

DBuffer デカールはベースパスの前にバッファへ蓄積されるため、ライトマップとスカイライティングに正しく影響します。これを有効にするには、再起動が必要なプロジェクト設定 r.DBuffer（URendererSettings::bDBuffer、Engine/RendererSettings.h:942）が必要です。これを有効にしない場合、通常のディファードデカールは引き続き GBuffer に書き込みますが、ベイク済みライティングやスカイライティングには正しく影響しません。

Nanite

UStaticMesh::HasValidNaniteData() は、メッシュに Nanite のレンダーデータがあるかどうかを返します（IsNaniteEnabled() は WITH_EDITORONLY_DATA であり、エディタービルドのみで使用できます。Engine/StaticMesh.h:1049）。設定には生のフィールドではなく、アクセサーを使用します：GetNaniteSettings() ／ SetNaniteSettings(const FMeshNaniteSettings&) ／ NotifyNaniteSettingsChanged()。

const UStaticMesh* Mesh = MeshComponent->GetStaticMesh();
const bool bIsNanite = Mesh && Mesh->HasValidNaniteData();

コードを書く前に知っておくとよい、マテリアルのルールは次のとおりです。

マテリアルプロパティNanite
不透明、両面サポートされています
マスクサポートされています。r.Nanite.AllowMaskedMaterials によって制御されます
World Position Offsetサポートされています。UStaticMeshComponent のコンポーネントごとの SetEvaluateWorldPositionOffset(bool) と SetWorldPositionOffsetDisableDistance(int32) を使用します
透過Nanite ではレンダリングされません。メッシュはフォールバックします
マテリアル使用フラグMATUSAGE_Nanite。スキン付き Nanite では MATUSAGE_SkeletalMesh も必要です（NaniteResources.cpp:2648）

マテリアルには、Nanite 専用の置き換えマテリアルを FMaterialOverrideNanite（Materials/MaterialOverrideNanite.h、GetOverrideMaterial() ／ SetOverrideMaterial(UMaterialInterface*, bool)）を使って設定できます。MID では同等の機能として SetNaniteOverride(UMaterialInterface* InMaterial) を使用します。

Nanite アセンブリは、複数のパーツからひとつの Nanite メッシュを構成します：FNaniteAssemblyData、FNaniteAssemblyPart、FNaniteAssemblyNode、FNaniteAssemblyBoneInfluence（Engine/NaniteAssemblyData.h）。スキン付き Nanite の状態は、コンポーネントごとに USkinnedMeshComponent::HasValidNaniteData() ／ GetNaniteResources() で取得でき、bDisallowNanite でコンポーネントごとに無効化できます。

Lumen と MegaLights

Lumen の品質は FPostProcessSettings で設定します。LumenSceneDetail、LumenSceneLightingQuality、LumenSceneLightingUpdateSpeed、LumenFinalGatherQuality、LumenFinalGatherLightingUpdateSpeed、LumenMaxTraceDistance、LumenReflectionQuality、LumenRayLightingMode があり、それぞれに対応する bOverride_* ビットがあります。ELumenRayLightingModeOverride の値は Default、SurfaceCache、HitLightingForReflections、HitLighting です。レンダラーのパス自体は、同じ構造体の DynamicGlobalIlluminationMethod と ReflectionMethod で選択します。

ボリュームごとのオーバーライドよりも、スケーラビリティ設定を使うほうが低コストです。sg.GlobalIlluminationQuality は BaseScalability.ini の [GlobalIlluminationQuality@N] ブロックを選択します。レベル 1（「Lumen Lite」）では、r.Lumen.FinalGatherMethod=0 を使った放射照度ボリュームのファイナルギャザーに Lumen を切り替え、サーフェスキャッシュを縮小します。レベル 2 以上ではスクリーンプローブギャザーを使います。C++ では、Scalability.h の Scalability::SetQualityLevels(const FQualityLevels& QualityLevels, bool bForce = false) を使用します。

MegaLights は、確率的サンプリングを使って多数のシャドウキャストライトをレンダリングします。プロジェクト全体では URendererSettings::bEnableMegaLights（コンソール変数 r.MegaLights.EnableForProject）で設定します。ボリュームごとの設定では FPostProcessSettings::bMegaLights と bOverride_bMegaLights を使います。実行時の CVar には r.MegaLights.Allowed と r.MegaLights.HardwareRayTracing があります。レイトレーシングデータが必要です。ハードウェアレイトレーシング、またはフォールバックとしてのソフトウェア（Lumen）トレーシング（MegaLights::HasRequiredTracingData、Renderer/Private/MegaLights/MegaLights.cpp:541）を使います。MegaLights が処理するライトについては、ほかの直接照明およびシャドウイングのパスを置き換えます。また、r.MegaLights.DirectionalLights=1（デフォルトは 0、MegaLights.cpp:239）でない限り、ディレクショナルライトはスキップします。

FPostProcessSettings& S = Volume->Settings;
S.bOverride_bMegaLights = true;
S.bMegaLights = true;

Substrate

Substrate はレイヤー型マテリアルシステムです。プロジェクトごとに URendererSettings::bEnableSubstrate（r.Substrate）で有効にし、r.Substrate.ProjectGBufferFormat と r.Substrate.ProjectClosuresPerPixel でメモリとクロージャの予算を制御します。Substrate マテリアルノードは Materials/MaterialExpressionSubstrate.h にあります。

カスタム Substrate 式はトポロジーツリーを構築します。5.8 でオーバーライドする仮想関数（エディター専用で、Materials/MaterialExpression.h:481 の #if WITH_EDITOR 内）は次のとおりです。

virtual FSubstrateOperator* SubstrateGenerateMaterialTopologyTree(struct FSubstrateTranslatorDataInterface& SubstrateTranslatorData, class UMaterialExpression* Parent, int32 OutputIndex) override;

静的ヘルパーは SubstrateGenerateMaterialTopologyTreeCommon で、最初の引数として FSubstrateTranslatorDataInterface& も受け取ります。FMaterialCompiler* を受け取っていた古いオーバーロードは非推奨です。

シャドウ、アンチエイリアシング、カスタムデプス

バーチャルシャドウマップはデフォルトのシャドウイングパスです。r.Shadow.Virtual.Enable で有効・無効を切り替えます。ワールド位置オフセットを使うマテリアルでは、シャドウを一致させるため、コンポーネントで WPO 評価を有効にする必要があります（SetEvaluateWorldPositionOffset）。

アンチエイリアシングは URendererSettings::DefaultFeatureAntiAliasing（EAntiAliasingMethod、SceneUtils.h）で設定します。AAM_TSR は Temporal Super-Resolution です。実行時のオーバーライドには r.AntiAliasingMethod を使います。

カスタムデプス／ステンシルは、輪郭、X 線、ハイライト用のポストプロセスマテリアルに入力されます。プロジェクト設定は URendererSettings::CustomDepthStencil（ECustomDepthStencil）、コンソール変数は r.CustomDepth です。コンポーネントごとの設定は次のとおりです。

MeshComponent->SetRenderCustomDepth(true);
MeshComponent->SetCustomDepthStencilValue(1);   // 0-255, read as CustomStencil in a post-process material

機能レベルとシェーダープラットフォーム

マテリアルのクエリ API が受け取るのは ERHIFeatureLevel::Type（RHIFeatureLevel.h）ではなく、EShaderPlatform（RHIShaderPlatform.h）です。RHIGlobals.h の GetFeatureLevelShaderPlatform で変換します。

#include "RHIGlobals.h"

const ERHIFeatureLevel::Type FeatureLevel = GetWorld()->GetFeatureLevel();
const EShaderPlatform ShaderPlatform = GetFeatureLevelShaderPlatform(FeatureLevel);

if (MyMaterial->IsCompilingOrHadCompileError(ShaderPlatform))   // UMaterial* -- not on UMaterialInterface
{
    // hide the object until its shaders are ready
}

使用フラグは UMaterialInterface の GetUsageByFlag(EMaterialUsage Usage) で読み取ります。bUsedWith* フィールドに直接アクセスしてはいけません。

if (!MyMaterial->GetUsageByFlag(MATUSAGE_Nanite))
{
    // not authorised for Nanite meshes
}

CheckMaterialUsage(EMaterialUsage) と CheckMaterialUsage_Concurrent(EMaterialUsage) const は、フラグを設定し、フラグがない場合は再コンパイルを実行します。SetMaterialUsage(EMaterialUsage Usage) は仮想関数です。

グローバルシェーダーとレンダーグラフ

実際の HLSL パスでは、DECLARE_GLOBAL_SHADER、SHADER_USE_PARAMETER_STRUCT、BEGIN_SHADER_PARAMETER_STRUCT ブロックを使用して FGlobalShader のサブクラスを宣言し、IMPLEMENT_GLOBAL_SHADER で .usf にバインドします。次に GraphBuilder.AddPass(...) で FRDGBuilder にパスを追加し、GraphBuilder.Execute() で実行します。Build.cs には "RenderCore"、"RHI"、"Projects" が必要です。

ほとんどの失敗は、次の 2 つのルールが原因です。StartupModule で AddShaderSourceDirectoryMapping を使ってシェーダーの仮想パスを登録してください。このモジュールの "LoadingPhase": "PostConfigInit" を設定してください。通常の Default フェーズでは、グローバルシェーダー型の登録が遅すぎて、"Shader type was loaded too late" の checkf（Shader.cpp:315）が発生します。コンピュートシェーダー宣言の全体、AddPass の形式、モジュールの起動コードについては、references/global-shaders-rdg.md を参照してください。

非推奨 — 使用しないでください

出力しないもの5.8 で使用するもの出典
Material->bUsedWithNanite（すべての bUsedWith* フィールド）Material->GetUsageByFlag(MATUSAGE_Nanite)Materials/Material.h の UE_DEPRECATED(5.8)（27 個のフラグ）
UMaterial::bEnableExecWireなし — 実験機能は削除されましたMaterials/Material.h の UE_DEPRECATED(5.8)
SetMaterialUsage(bool& bNeedsRecompile, EMaterialUsage, UMaterialInterface*)SetMaterialUsage(EMaterialUsage Usage)Materials/Material.h の UE_DEPRECATED(5.8)
IsCompilingOrHadCompileError(ERHIFeatureLevel::Type)IsCompilingOrHadCompileError(EShaderPlatform)Materials/Material.h の UE_DEPRECATED(5.7)
GetMaterialResource(ERHIFeatureLevel::Type, ...)GetMaterialResource(EShaderPlatform, ...)Materials/MaterialInterface.h の UE_DEPRECATED(5.7)
GetUsedTexturesAndIndices(..., ERHIFeatureLevel::Type)EShaderPlatform オーバーロードMaterials/MaterialInterface.h の UE_DEPRECATED(5.7)
CopyScalarAndVectorParameters(Source, ERHIFeatureLevel::Type)CopyScalarAndVectorParameters(Source, EShaderPlatform)Materials/MaterialInstanceDynamic.h の UE_DEPRECATED(5.7)
GetUsedMaterialPropertyDesc(ERHIFeatureLevel::Type)GetUsedMaterialPropertyDesc(EShaderPlatform)Components/PrimitiveComponent.h の UE_DEPRECATED(5.7)
UMaterialInstance::Resource（公開されているレンダープロキシ）GetRenderProxy() または GetInstanceRenderProxy()Materials/MaterialInstance.h の UE_DEPRECATED(5.8)
UMaterialExpressionTextureBase::GetSamplerTypeForTextureMaterialExpressionUtils::GetSamplerTypeForTextureMaterials/MaterialExpressionTextureBase.h の UE_DEPRECATED(5.8)
UMaterialExpressionTextureBase::VerifySamplerTypeMaterialExpressionUtils::VerifySamplerTypeMaterials/MaterialExpressionTextureBase.h の UE_DEPRECATED(5.8)
SubstrateGenerateMaterialTopologyTreeCommon(FMaterialCompiler*, ...)FSubstrateTranslatorDataInterface& オーバーロードMaterials/MaterialExpressionSubstrate.h の UE_DEPRECATED(5.8)
FTextureSamplingInfo CalculateTexturesSamplingInfo(UTexture*)出力パラメーターを持つ const bool 形式Materials/MaterialInterface.h の UE_DEPRECATED(5.8)
IsUsingNewTranslatorPrototype()IsUsingNewHLSLGenerator()Materials/MaterialInterface.h の UE_DEPRECATED(5.8)
CreateMIDForElement / CreateMIDForElementFromMaterialCreateDynamicMaterialInstance(ElementIndex, SourceMaterial, OptionalName)Components/PrimitiveComponent.h の DeprecatedFunction
StaticMesh->NaniteSettings（フィールドへの直接アクセス）GetNaniteSettings() / SetNaniteSettings()Engine/StaticMesh.h の UE_DEPRECATED(5.7)
BL_BeforeTranslucency、BL_BeforeTonemapping、BL_AfterTonemappingBL_SceneColorBeforeDOF、BL_SceneColorAfterDOF、BL_SceneColorAfterTonemappingEngine/BlendableInterface.h の UE_DEPRECATED(5.4)

よくある間違い

毎フレーム MID を作成する： CreateDynamicMaterialInstance は呼び出すたびに新しいインスタンスとレンダープロキシを割り当てます。BeginPlay で一度だけ作成して保存し、その後はセッターのみを呼び出してください。

MID を生ポインターで保持する： MID は UObject であり、参照されなくなるとガベージコレクションの対象になります。UPROPERTY() TObjectPtr<UMaterialInstanceDynamic> に保存し、UMaterialInstanceDynamic* のメンバーや静的変数にそのまま保持しないでください。

オーバーライドビットを設定せずにポストプロセス値を設定する： S.BloomIntensity = 2.f; だけでは、何も起きずに処理されます。値を代入するたびに、その隣で S.bOverride_BloomIntensity = true; を設定する必要があります。

シェーダープラットフォームが必要な場所にフィーチャーレベルを渡す： GetMaterialResource、IsCompilingOrHadCompileError、CopyScalarAndVectorParameters、GetUsedMaterialPropertyDesc の ERHIFeatureLevel::Type オーバーロードは非推奨です。GetFeatureLevelShaderPlatform(GetWorld()->GetFeatureLevel()) で一度変換してください。

bUsedWith* フィールドを読み取る： これらのメンバーは非推奨です。読み取りには GetUsageByFlag(EMaterialUsage) のみがサポートされ、書き込みには SetMaterialUsage(EMaterialUsage) のみがサポートされています。

SetVectorParameterValue で倍精度が使われると想定する： FVector／FVector4 オーバーロードは、FLinearColor（float）に変換するインラインの簡易関数です（Materials/MaterialInstanceDynamic.h:112-113）。マテリアルが倍精度のベクトルを読み取る場合は、SetDoubleVectorParameterValue(FName, FVector4) を使用してください。

MID をレプリケートする： MID はクライアントローカルのオブジェクトです。スカラー値とベクトル値をレプリケートし、各クライアントで OnRep を使って MID の状態を再構築してください。

スタティックスイッチが実行時に変更されると想定する： スタティックパラメーターはシェーダーパーミュテーションに焼き込まれます。パーミュテーションごとに UMaterialInstanceConstant を作成し、適切なインスタンスを MID の親にしてください。

Tick で ReadRenderTargetPixel を呼び出す： レンダリングコマンドをフラッシュし、パイプラインを停止させます。読み戻しはエディターツールに限定するか、FRHIGPUTextureReadback を使用してください。

bCaptureEveryFrame を有効にしたままにする： 毎フレームキャプチャする USceneCaptureComponent2D は、シーンをもう一度レンダリングします。これをオフにし、ターゲットが実際に変化したときに CaptureScene() を呼び出してください。

関連するスキル

  • ue-niagara-effects — Niagara システム、エミッターパラメーター、およびパーティクルに必要なマテリアル使用フラグ
  • ue-procedural-generation — これらのマテリアルを割り当てる PCG と実行時メッシュ生成
  • ue-actor-component-architecture — ここで使用するコンポーネントのセットアップ、アタッチ、ライフタイム
  • ue-ui-umg-slate — MD_UI マテリアル、ウィジェットブラシ、およびレンダーターゲットへの UMG のレンダリング
  • ue-sequencer-cinematics — シーケンスからのマテリアルパラメーターとポストプロセス設定のアニメーション
  • ue-testing-debugging — プロファイリング、stat コマンド、Insights、および GPU キャプチャのワークフロー
  • ue-data-assets-tables — マテリアルとレンダリング設定を制御するデータアセットとテーブル
  • ue-cpp-foundations — UObject のライフタイム、UPROPERTY、TObjectPtr、およびガベージコレクション

コメント

Markdown 対応