[UE4][ComputeShader][HLSL][C++]Unreal Engine 4で(RW)StructuredBufferを用いたComputeShaderを利用する（その２：C++側シェーダクラス）

その１：イントロでは文字通りイントロ（と愚痴…）だけになってしまいましたので、その２では具体的な実装を解説します。

1. C++経由で変数をHLSL側に渡す
2. C++側の変数にはFVectorも入れる
3. StructuredBufferを使う
4. RWStructuredBufferを使う
5. Unreal Engine 4が提供しているConstantBufferに該当するUniform Buffer Structを使う
6. そしてComputeShaderをC++側から呼び出す

という6つを確認できることを目標に以下のことをするComputeShaderを作ることにしました。先に断っておきますが、見た目的には微塵も面白くありません。

サンプルコード一式をGitHubに上げました。
https://github.com/HSeo/ComputeShaderUE419Test

実行してキーボードの1または2を押すと、Output Logに以下のように表示されます。

これだけです。これだけですが、プログラマ目線ではこれで十分かと思います。

では始めましょう。
実行環境はWindows 10, Visual Studio 2017, Unreal Engine 4.19になります。
他のOS環境などでの違いはわかりません。ごめんなさい。
GPU非搭載のマシンで何が起こるかもわかりません。ごめんなさい。

1. 下準備

◆HLSL Tools for Visual Studioのインストール
Unreal Engine 4 Rendering Part 1: Introductionにも書かれている通りです。
無くても構いませんが、インストールしておくと便利だと思います。

◆ConsoleVariables.iniの書き換え
Unreal Engine 4 Rendering Part 1: Introductionにも書かれているように、/Engine/Config/フォルダ内にあるConsoleVariables.iniを書き換えます。
r.ShaderDevelopmentMode=1
r.Shaders.Optimize=0
r.Shaders.KeepDebugInfo=1
に設定します（先頭の”;”を消して非コメント化します）。
コメントのままにしておくとどうなるのかはよくわかりません。ごめんなさい。何もしなくても大丈夫なのかもしれませんが、検証していません。

◆.build.csにモジュールを追加
PublicDependencyModuleNamesに
“ShaderCore”, “RenderCore”, “RHI”
の3つを追加して、一旦Visual Studioを閉じます。

◆Shadersフォルダの生成（UE 4.17以降）
シェーダーをプラグインとしてではなく用いる場合には、プロジェクトフォルダ直下にShadersフォルダを作り、さらにその直下にPrivateフォルダを作ります。
シェーダーファイルはこのPrivateフォルダ内に作ります。

なお、プラグインとして作る場合はPluginフォルダ内に同様にShaders→Privateフォルダを作ります。
詳しくはEpic Games Japan 岡田和也さんのスライドをご覧ください。

UE4.17で入る新機能を一気に紹介・解説！ from エピック・ゲームズ・ジャパン Epic Games Japan

4.16以前は、プラグインとして作る場合は同様にPluginフォルダ以下にフォルダを作れば大丈夫ですが、後述するC++での記述内容（パス指定方法）が若干変わるようです。
非プラグインとしてShadersフォルダを作って認識してくれるのかどうかはよくわかりません…。

◆.uprojectの書き換え
最初のハマりどころです。C++プロジェクトを作ると.uprojectファイル（テキストエディタで開けます）内に”Modules”という項目が追加されます。
この中の
“LoadingPhase”: “Default”,
を
“LoadingPhase”: “PostConfigInit“,
に書き換えます。
こうしないと、シェーダーコンパイルが通りません。
https://github.com/Temaran/UE4ShaderPluginDemo
にも”PostConfigInit”にしようね、とは書かれているのですが、具体的な場所がわからずに最初苦労しました。
LoadingPhaseの詳しい解説は
ELoadingPhase::Type | Unreal Engine
をご覧下さい。モジュールがどのタイミングで読み込まれるかを指定しています（たぶん）。

書き換えたらファイルを保存して、solutionファイルを作り直しましょう。.uprojectを右クリックして”Generate Visual Studio project files”を選択。

これで下準備完了です。

2. シェーダの記述（.usf）

プロジェクト名フォルダ（or Pluginフォルダ）→Shaders→Privateフォルダに.usfという拡張子のファイルを作ります。
グローバルシェーダとして記述することになります。
Unreal Engineのグローバルシェーダは（たぶんUE4.17から）.usfと.ushの2種類に分けられています。
シェーダーエントリーポイントが含まれる場合は.usf、それ以外は.ushになるそうです。

UE4.17で入る新機能を一気に紹介・解説！ from エピック・ゲームズ・ジャパン Epic Games Japan

ただ、このスライド、MainVS, MainPSを持つ場合に.usfということになっているのですが、ComputeShaderだったらどちらも持たないけど.usfだよなぁ、と思います。
.ushではなく.usfにして下さい。

.usfファイル内のシェーダの記述は、基本的にはHLSLと同じだと思います（…私はHLSLスーパー初心者ですので間違っていたらごめんなさい）。

今回書いたものはこれです。

// Copyright (c) 2018 Hirofumi Seo, M.D. at SCIEMENT, Inc.
// http://www.sciement.com
// https://www.sciement.com/tech-blog/

#pragma once

// Necessary to use UNIFORM_BUFFER_STRUCT
#include "/Engine/Private/Common.ush"

// UNIFORM_BUFFER_STRUCT is not available outside the fuction of IMPLEMENT_SHADER_TYPE's FunctionName.
// So, we can't use UNIFORM_BUFFER_STRUCT like global StructuredBuffer<UNIFORM_BUFFER_STRUCT>

/*
//TestComputeShader.h
BEGIN_UNIFORM_BUFFER_STRUCT(OffsetYZ, )
DECLARE_UNIFORM_BUFFER_STRUCT_MEMBER(float, y)
DECLARE_UNIFORM_BUFFER_STRUCT_MEMBER(float, z)
END_UNIFORM_BUFFER_STRUCT(OffsetYZ)

//TestComputeShader.cpp
IMPLEMENT_UNIFORM_BUFFER_STRUCT(OffsetYZ, TEXT("offset_yz"))
*/

StructuredBuffer<float3> test_input_position; // FVector in cpp
StructuredBuffer<float> test_input_scalar;
RWStructuredBuffer<float3> test_output;

float test_offset_x;
float test;

[numthreads(1, 1, 1)]
void CalculateOutput(int3 dispatch_id : SV_DispatchThreadID) {
  test_output[dispatch_id.x] = test_input_position[dispatch_id.x] * test_input_scalar[dispatch_id.x] + float3(test_offset_x, offset_yz.y, offset_yz.z);
}

// http://www.sciement.com

// https://www.sciement.com/tech-blog/

#pragma once

// Necessary to use UNIFORM_BUFFER_STRUCT

#include "/Engine/Private/Common.ush"

// UNIFORM_BUFFER_STRUCT is not available outside the fuction of IMPLEMENT_SHADER_TYPE's FunctionName.

// So, we can't use UNIFORM_BUFFER_STRUCT like global StructuredBuffer<UNIFORM_BUFFER_STRUCT>

//TestComputeShader.h

BEGIN_UNIFORM_BUFFER_STRUCT(OffsetYZ, )

DECLARE_UNIFORM_BUFFER_STRUCT_MEMBER(float, y)

DECLARE_UNIFORM_BUFFER_STRUCT_MEMBER(float, z)

END_UNIFORM_BUFFER_STRUCT(OffsetYZ)

//TestComputeShader.cpp

IMPLEMENT_UNIFORM_BUFFER_STRUCT(OffsetYZ, TEXT("offset_yz"))

StructuredBuffer<float3> test_input_position; // FVector in cpp

StructuredBuffer<float> test_input_scalar;

RWStructuredBuffer<float3> test_output;

float test_offset_x;

float test;

[numthreads(1, 1, 1)]

void CalculateOutput(int3 dispatch_id : SV_DispatchThreadID) {

test_output[dispatch_id.x] = test_input_position[dispatch_id.x] * test_input_scalar[dispatch_id.x] + float3(test_offset_x, offset_yz.y, offset_yz.z);

}

コメントなどで行数が多くなっていますが、やっていることは実質33行目の1行だけです。これが最初に示した数式です。
いくつかポイントを列挙します。

◆Uniform Buffer Structを使いたい場合
Unreal Engineが提供しているCommon.ushをincludeする必要があります。
このCommon.ushは、使用しているUnreal EngineのEngine→Shaders→Privateフォルダに入っています。このフォルダには他にもEpic Gamesによる貴重なシェーダーファイルがぎっしり詰まっており、ここを見るだけでも相当勉強になりそうです。

◆Engine→Shaders→Privateフォルダ内の.usf / .ushをincludeする際のファイルパス
落とし穴が1つあります。
/Engine/Shaders/Private/Common.ush
がEngine以下でファイルまでの正しいパスなのですが、コード上では

#include "/Engine/Private/Common.ush"

8	#include "/Engine/Private/Common.ush"

と書きます。/Shaders/がありません。
実はコードのビルド時のログをよーく眺めていると

LogShaders: Shader directory mapping /Engine -> ../../../Engine/Shaders

なるログを見つけることが出来ると思います。
HLSLコード内でパスに/Engineと書くと、それは自動的に/Engine/Shadersに置き換えられる仕様になっています。
何気にハマりやすいポイントの1つかと思いますので注意してください。

なお、Visual Studio側はこのパスを正しく認識できませんので、いつまで経ってもエラーを示す下線が付いたままになってしまうと思います。

◆Uniform Buffer Structを実際に使う
HLSLコードを見ていて、コード内に変数定義が無い変数を見つけたら、Uniform Buffer Structかもしれません。
このコードでは、CalculateOutput関数内でいきなりoffset_yz.y, offset_yz.zなる変数が登場しています。
これはコメントで記載したように、Uniform Buffer Structの定義は.h / .cpp内に記述されているためです。
Visual Studio内での自動補完も出来ず、ここもエラー表示のままになってしまいます。
可読性の点からも、むやみやたらにUnfirom Buffer Structを使うことはお勧めしません。

https://github.com/IntelSoftware/ue4-parallelのShaderFishPlugin.hのように、C++側で大量の変数をまとめて構造体として扱いたいとき、そしてその構造体の中身を丸ごとシェーダーでも使いたいときにはとても有用かと思います。

3. C++側からシェーダにアクセスするためのクラスの記述（.h）

シェーダとC++との接続のために、Unreal Engine側が用意しているFGlobalShaderクラスを継承したクラスを作ります。
ヘッダファイルは以下のようになります。

// Copyright (c) 2018 Hirofumi Seo, M.D. at SCIEMENT, Inc.
// http://www.sciement.com
// https://www.sciement.com/tech-blog/

#pragma once

#include "CoreMinimal.h"
#include "GlobalShader.h" //ShaderCore module
#include "UniformBuffer.h" // RenderCore module
#include "RHICommandList.h" // RHI module

// The first "F", like "FStruct" is not necessary for uniform buffer struct??
// The struct has to be implemented in .cpp using IMPLEMENT_UNIFORM_BUFFER_STRUCT
BEGIN_UNIFORM_BUFFER_STRUCT(OffsetYZ, )
DECLARE_UNIFORM_BUFFER_STRUCT_MEMBER(float, y)
DECLARE_UNIFORM_BUFFER_STRUCT_MEMBER(float, z)
END_UNIFORM_BUFFER_STRUCT(OffsetYZ)

class /*COMPUTESHADERTEST419_API*/ FTestComputeShader : public FGlobalShader {
  DECLARE_EXPORTED_SHADER_TYPE(FTestComputeShader, Global, );

public:
  /* Essential functions */

  FTestComputeShader() {}
  explicit FTestComputeShader(const ShaderMetaType::CompiledShaderInitializerType& initializer);

  static bool ShouldCache(EShaderPlatform platform) {
    return true;
    //// Could skip compiling if the platform does not support DirectX Shader Model 4, for example, like the following.
    //return IsFeatureLevelSupported(platform, ERHIFeatureLevel::SM4);
  }

  static void ModifyCompilationEnvironment(const FGlobalShaderPermutationParameters& PermutationParams, FShaderCompilerEnvironment& OutEnvironment) {
    FGlobalShader::ModifyCompilationEnvironment(PermutationParams, OutEnvironment);
    OutEnvironment.CompilerFlags.Add(CFLAG_StandardOptimization);
  }

  static bool ShouldCompilePermutation(const FGlobalShaderPermutationParameters& PermutationParams) {
    // Useful when adding a permutation of a particular shader
    return true;
  }

  virtual bool Serialize(FArchive& Ar) override;

  /* Custom functions */

  void SetOffsetX(FRHICommandList& rhi_command_list, const float offset_x);
  void SetOffsetYZ(FRHICommandList& rhi_command_list, const float offset_y, const float offset_z);

  // FShaderResourceViewRHIRef for StructuredBuffer, FUnorderedAccessViewRHIParamRef for RWStructuredBuffer.
  void SetInputPosition(FRHICommandList& rhi_command_list, FShaderResourceViewRHIRef input_position);
  void SetInputScalar(FRHICommandList& rhi_command_list, FShaderResourceViewRHIRef input_scalar);
  void SetOutput(FRHICommandList& rhi_command_list, FUnorderedAccessViewRHIParamRef output);
  void ClearParameters(FRHICommandList& rhi_command_list); // for StructuredBuffer.
  void ClearOutput(FRHICommandList& rhi_command_list); // for RWStructuredBuffer.

private:
  FShaderParameter offset_x_; // float test_offset_x;

  FShaderResourceParameter input_position_; // StructuredBuffer<float3> test_input_position;
  FShaderResourceParameter input_scalar_; // StructuredBuffer<float> test_input_scalar;
  FShaderResourceParameter output_; // RWStructuredBuffer<float3> test_output;
};

// http://www.sciement.com

// https://www.sciement.com/tech-blog/

#pragma once

#include "CoreMinimal.h"

#include "GlobalShader.h" //ShaderCore module

#include "UniformBuffer.h" // RenderCore module

#include "RHICommandList.h" // RHI module

// The first "F", like "FStruct" is not necessary for uniform buffer struct??

// The struct has to be implemented in .cpp using IMPLEMENT_UNIFORM_BUFFER_STRUCT

BEGIN_UNIFORM_BUFFER_STRUCT(OffsetYZ, )

DECLARE_UNIFORM_BUFFER_STRUCT_MEMBER(float, y)

DECLARE_UNIFORM_BUFFER_STRUCT_MEMBER(float, z)

END_UNIFORM_BUFFER_STRUCT(OffsetYZ)

class /*COMPUTESHADERTEST419_API*/ FTestComputeShader : public FGlobalShader {

DECLARE_EXPORTED_SHADER_TYPE(FTestComputeShader, Global, );

public:

/* Essential functions */

FTestComputeShader() {}

explicit FTestComputeShader(const ShaderMetaType::CompiledShaderInitializerType& initializer);

static bool ShouldCache(EShaderPlatform platform) {

return true;

//// Could skip compiling if the platform does not support DirectX Shader Model 4, for example, like the following.

//return IsFeatureLevelSupported(platform, ERHIFeatureLevel::SM4);

}

static void ModifyCompilationEnvironment(const FGlobalShaderPermutationParameters& PermutationParams, FShaderCompilerEnvironment& OutEnvironment) {

FGlobalShader::ModifyCompilationEnvironment(PermutationParams, OutEnvironment);

OutEnvironment.CompilerFlags.Add(CFLAG_StandardOptimization);

}

static bool ShouldCompilePermutation(const FGlobalShaderPermutationParameters& PermutationParams) {

// Useful when adding a permutation of a particular shader

return true;

}

virtual bool Serialize(FArchive& Ar) override;

/* Custom functions */

void SetOffsetX(FRHICommandList& rhi_command_list, const float offset_x);

void SetOffsetYZ(FRHICommandList& rhi_command_list, const float offset_y, const float offset_z);

// FShaderResourceViewRHIRef for StructuredBuffer, FUnorderedAccessViewRHIParamRef for RWStructuredBuffer.

void SetInputPosition(FRHICommandList& rhi_command_list, FShaderResourceViewRHIRef input_position);

void SetInputScalar(FRHICommandList& rhi_command_list, FShaderResourceViewRHIRef input_scalar);

void SetOutput(FRHICommandList& rhi_command_list, FUnorderedAccessViewRHIParamRef output);

void ClearParameters(FRHICommandList& rhi_command_list); // for StructuredBuffer.

void ClearOutput(FRHICommandList& rhi_command_list); // for RWStructuredBuffer.

private:

FShaderParameter offset_x_; // float test_offset_x;

FShaderResourceParameter input_position_; // StructuredBuffer<float3> test_input_position;

FShaderResourceParameter input_scalar_; // StructuredBuffer<float> test_input_scalar;

FShaderResourceParameter output_; // RWStructuredBuffer<float3> test_output;

};

大きく5つのブロックに分かれます。紐解いていけば、単純なことしかやっていません。

◆Uniform Buffer Structの定義

// The first "F", like "FStruct" is not necessary for uniform buffer struct??
// The struct has to be implemented in .cpp using IMPLEMENT_UNIFORM_BUFFER_STRUCT
BEGIN_UNIFORM_BUFFER_STRUCT(OffsetYZ, )
DECLARE_UNIFORM_BUFFER_STRUCT_MEMBER(float, y)
DECLARE_UNIFORM_BUFFER_STRUCT_MEMBER(float, z)
END_UNIFORM_BUFFER_STRUCT(OffsetYZ)

// The first "F", like "FStruct" is not necessary for uniform buffer struct??

// The struct has to be implemented in .cpp using IMPLEMENT_UNIFORM_BUFFER_STRUCT

BEGIN_UNIFORM_BUFFER_STRUCT(OffsetYZ, )

DECLARE_UNIFORM_BUFFER_STRUCT_MEMBER(float, y)

DECLARE_UNIFORM_BUFFER_STRUCT_MEMBER(float, z)

END_UNIFORM_BUFFER_STRUCT(OffsetYZ)

マクロが用意されているので、これに倣って書けば問題ないと思います。
（たぶん）シェーダー側で読める型である必要があるため、FVectorを使いたい場合は（たぶん）float変数3つに分解しておく必要があります。
また、この構造体はBluePrints上で用いるUSTRUCTS()とは別物であるため、構造体名の頭に”F”を付ける必要はありません。

◆DECLARE_EXPORTED_SHADER_TYPE

  DECLARE_EXPORTED_SHADER_TYPE(FTestComputeShader, Global, );

20	DECLARE_EXPORTED_SHADER_TYPE(FTestComputeShader, Global, );

イマイチよくわかりませんでした。ごめんなさい…。UE4 にグローバルシェーダーを追加してみようによると、

DECLARE_EXPORTED_SHADER_TYPE() マクロを使うと、シェーダーのタイプのシリアル化に必要なエクスポートが生成されます。3 番目のパラメータは、シェーダーのモジュールが存在することになるコードモジュールの外部リンケージのタイプです。

とのことです。
教えて、詳しい人！

◆必須のメンバ関数の定義

  FTestComputeShader() {}
  explicit FTestComputeShader(const ShaderMetaType::CompiledShaderInitializerType& initializer);

  static bool ShouldCache(EShaderPlatform platform) {
    return true;
    //// Could skip compiling if the platform does not support DirectX Shader Model 4, for example, like the following.
    //return IsFeatureLevelSupported(platform, ERHIFeatureLevel::SM4);
  }

  static void ModifyCompilationEnvironment(const FGlobalShaderPermutationParameters& PermutationParams, FShaderCompilerEnvironment& OutEnvironment) {
    FGlobalShader::ModifyCompilationEnvironment(PermutationParams, OutEnvironment);
    OutEnvironment.CompilerFlags.Add(CFLAG_StandardOptimization);
  }

  static bool ShouldCompilePermutation(const FGlobalShaderPermutationParameters& PermutationParams) {
    // Useful when adding a permutation of a particular shader
    return true;
  }

  virtual bool Serialize(FArchive& Ar) override;

FTestComputeShader() {}

explicit FTestComputeShader(const ShaderMetaType::CompiledShaderInitializerType& initializer);

static bool ShouldCache(EShaderPlatform platform) {

return true;

//// Could skip compiling if the platform does not support DirectX Shader Model 4, for example, like the following.

//return IsFeatureLevelSupported(platform, ERHIFeatureLevel::SM4);

}

static void ModifyCompilationEnvironment(const FGlobalShaderPermutationParameters& PermutationParams, FShaderCompilerEnvironment& OutEnvironment) {

FGlobalShader::ModifyCompilationEnvironment(PermutationParams, OutEnvironment);

OutEnvironment.CompilerFlags.Add(CFLAG_StandardOptimization);

}

static bool ShouldCompilePermutation(const FGlobalShaderPermutationParameters& PermutationParams) {

// Useful when adding a permutation of a particular shader

return true;

}

virtual bool Serialize(FArchive& Ar) override;

計6個のメンバ関数の定義が必須です。関数名、引数ともに上記の通りにする必要があります。

・コンストラクタは2種類用意します。引数無しコンストラクタは実装は空のもにします。const ShaderMetaType::CompiledShaderInitializerType&を引数に取るコンストラクタの実装は今回は.cppに書きましたので後述します。

・ShouldCache関数はイマイチよく分かりませんでした…。IsFeatureLevelSupported関数を用いて、実行環境によってシェーダーコンパイルを行わないように設定できるようです。ERHIFeatureLevel::Typeの定義を見てみると、DirectX11サポートの有無を調べたければSM5、MetalであればES3_1などを指定できるようです。この関数がfalseを返してコンパイルしない場合に何をどうすれば良いのかはよく分かりません…。
教えて、詳しい人！

・ModifyCompilationEnvironmentは全然分かりませんでした。Unreal Engine 4 Rendering Part 2: Shaders and Vertex Dataによると（一部省略）、

The second important concept is the ability to change preprocessor defines in the HLSL code before compilation. This functions is called before the shader is compiled and lets you modify the HLSL preprocessor defines.

とのことで、CFLAG_StandardOptimization以外にも様々なフラグ（ECompilerFlags）があり、指定することで色々変わる…のだとは思うのですがそれ以上は全然わからず…。基本的には上記のコピペで良いような気がします。
また、Yet another blog…: Adding Global shaders to UE4 v2.0には

The new ModifyCompilationEnvironment() function is used when the same C++ class defines different behaviors and be able to set up #define values in the shader.

と書かれており、異なるサンプル実装が書かれています。
教えて、詳しい人！

なお、（たぶん）UE4.18以上と未満とでは引数の型が異なっており、const FGlobalShaderPermutationParameters&が以前はEShaderPlatform Platformでした。Unreal Engineのバージョンを上げたときにシェーダーコンパイルが通らなくなってしまう原因の1つです。

・ShouldCompilePermutationはさらに全く分かりませんでした。
Yet another blog…: Adding Global shaders to UE4 v2.0によると

The ShouldCompilePermutation() function, needed when a permutation of a global shader is required. This is a slightly more advanced topic outside the scope of this post.

とのことで、単純にコピペして完了とします。
教えて、詳しい人！

・最後のSerializeはとても重要で、各種Shader Parameter（後述）を設定します。
やはりYet another blog…: Adding Global shaders to UE4 v2.0の説明を借りれば

The Serialize() method is required. This is where the compile/cook time information from the shader’s binding (matched during the serialization constructor) gets loaded and stored at runtime.

とのことです。今回は.cppで実装しました。

◆C++側で設定した値をシェーダ側と結びつけるための関数

  void SetOffsetX(FRHICommandList& rhi_command_list, const float offset_x);
  void SetOffsetYZ(FRHICommandList& rhi_command_list, const float offset_y, const float offset_z);

  // FShaderResourceViewRHIRef for StructuredBuffer, FUnorderedAccessViewRHIParamRef for RWStructuredBuffer.
  void SetInputPosition(FRHICommandList& rhi_command_list, FShaderResourceViewRHIRef input_position);
  void SetInputScalar(FRHICommandList& rhi_command_list, FShaderResourceViewRHIRef input_scalar);
  void SetOutput(FRHICommandList& rhi_command_list, FUnorderedAccessViewRHIParamRef output);
  void ClearParameters(FRHICommandList& rhi_command_list); // for StructuredBuffer.
  void ClearOutput(FRHICommandList& rhi_command_list); // for RWStructuredBuffer.