統計システムの概要

デベロッパーはゲームを最適化するために、統計システムを使用してパフォーマンス データを収集して表示できます。

Choose your operating system:

Windows

macOS

Linux

前提トピック

このページは以下のトピックへの知識があることを前提にしています。まず以下のトピックの内容についてご確認をお願いします。

ゲームの最適化に利用するために 統計システム を使用してパフォーマンス データを収集して表示できます。

Stat コマンドのヘルプを参照するには、コンソールに stat と入力するか PrintStatsHelpToOutputDevice(); メソッドを参照してください。

タイプ

統計システムは、次の統計のタイプをサポートしています。

統計のタイプ

説明

Cycle Counter

オブジェクトの存続期間中のサイクル数をカウントするために使用される汎用のサイクル カウンター。

Float/Dword Counter

フレームごとにクリアされるカウンター。

Float/Dword Accumulator

フレームごとにクリアされずに、永続的な統計を示すリセット可能なカウンター。

Memory

メモリ追跡用に最適化された特殊なカウンター。

統計項目をグループ化する

各統計項目はグループ化されている必要があります。これは、通常、指定された統計グループの表示と一致します。例えば stat statsystem は統計システムの関連データを表示します。

統計グループを定義するには、次のいずれかのメソッドを使用します。

メソッド

説明

DECLARE_STATS_GROUP(GroupDesc, GroupId, GroupCat)

デフォルトで有効な統計グループを宣言します。

DECLARE_STATS_GROUP_VERBOSE(GroupDesc, GroupId, GroupCat)

デフォルトで無効な統計グループを宣言します。

DECLARE_STATS_GROUP_MAYBE_COMPILED_OUT(GroupDesc, GroupId, GroupCat)

コンパイラによって削除される統計グループを宣言します。

ここでは、次のようになります。

  • GroupDesc はグループのテキスト記述です

  • GroupId はグループの UNIQUE ID です

  • GroupCat は将来の使用のために予約されています

  • CompileIn が true に設定されている場合、コンパイラによって削除される可能性があります

使用するスコープに応じて、ソース ファイルまたはヘッダ ファイルでグループ化を行うことができます。

使用例

DECLARE_STATS_GROUP(TEXT("Threading"), STATGROUP_Threading, STATCAT_Advanced);
DECLARE_STATS_GROUP_VERBOSE(TEXT("Linker Load"), STATGROUP_LinkerLoad, STATCAT_Advanced);

統計項目の宣言と定義を行う

統計項目を宣言して定義できますが、その前に、統計項目は次の範囲内で使用できることに注意してください。

  • 単一の cpp ファイルのみ

  • 関数スコープ

  • モジュール スコープ

  • プロジェクト全体

単一ファイルの場合

スコープが単一ファイルの場合、統計項目のタイプに応じて、次のいずれかのメソッドを使用する必要があります。

メソッド

説明

DECLARE_CYCLE_STAT(CounterName, StatId, GroupId)

Cycle Counter の統計項目を宣言します。

DECLARE_SCOPE_CYCLE_COUNTER(CounterName, StatId, GroupId)

Cycle Counter の統計項目を宣言し、それと同時に使用します。また、単一の関数スコープに制限されます。

QUICK_SCOPE_CYCLE_COUNTER(StatId)

「Quick」という統計グループに属する Cycle Counter の統計項目を宣言します。

RETURN_QUICK_DECLARE_CYCLE_STAT(StatId, GroupId)

Cycle Counter を返します。一部の特殊なクラスで使用されることがあります。

DECLARE_FLOAT_COUNTER_STAT(CounterName, StatId, GroupId)

Float Counter を宣言します。double 型 (8 バイト) がベースとなっています。

DECLARE_DWORD_COUNTER_STAT(CounterName, StatId, GroupId)

Dword Counter を宣言します。qword 型 (8 バイト) がベースとなっています。

DECLARE_FLOAT_ACCUMULATOR_STAT(CounterName, StatId, GroupId)

Float Accumulator を宣言します。

DECLARE_DWORD_ACCUMULATOR_STAT(CounterName, StatId, GroupId)

Dword Accumulator を宣言します。

DECLARE_MEMORY_STAT(CounterName, StatId, GroupId)

Dword Accumulator と同じメモリ カウンターを宣言します。メモリ固有の単位で表示されます。

DECLARE_MEMORY_STAT_POOL(CounterName, StatId, GroupId, Pool)

プールを使用するメモリ カウンターを宣言します。

複数のファイルの場合

プロジェクト全体 (またはより広範囲のファイル) から統計項目にアクセスできるようにするには、extern バージョンを使用する必要があります。 これらのメソッドは前に説明したのと同じものですが、次のように名前の終わりに _EXTERN が付いています。

DECLARE_CYCLE_STAT_EXTERN(CounterName, StatId, GroupId, API)
DECLARE_FLOAT_COUNTER_STAT_EXTERN(CounterName, StatId, GroupId, API)
DECLARE_DWORD_COUNTER_STAT_EXTERN(CounterName, StatId, GroupId, API)
DECLARE_FLOAT_ACCUMULATOR_STAT_EXTERN(CounterName, StatId, GroupId, API)
DECLARE_DWORD_ACCUMULATOR_STAT_EXTERN(CounterName, StatId, GroupId, API)
DECLARE_MEMORY_STAT_EXTERN(CounterName, StatId, GroupId, API)
DECLARE_MEMORY_STAT_POOL_EXTERN(CounterName, StatId, GroupId, Pool, API)

次に、ソースファイルで、次のパラメータを指定し、 _EXTERN 付きでこれらの統計項目を宣言して定義する必要があります。

ここでは、次のようになります。

  • CounterName は統計項目のテキスト記述です

  • StatId は統計項目の UNIQUE ID です

  • GroupId は統計項目が属するグループの ID です。 GroupId は、「DECLARE_STATS_GROUP*」で指定したものです

  • Pool はプラットフォーム固有のメモリ プールです

  • API はモジュールの 「*_API」です。統計項目がそのモジュールでのみ使用される場合は、空にすることができます

プールを使用するカスタムのメモリ統計

最初に、 enum EMemoryCounterRegion に新しいプールを追加する必要があります。これは、グローバルまたはプラットフォーム固有のものになります。

enum EMemoryCounterRegion
{
    MCR_Invalid,        // not memory
    MCR_Physical,       // main system memory
    MCR_GPU,            // memory directly a GPU (graphics card)
    MCR_GPUSystem,      // system memory directly accessible by a GPU
    MCR_TexturePool,    // pre-sized texture pools
    MCR_MAX
};

次の例では、どこからでもプールを使用できます ( を参照)。

プール名は MCR_ で始める必要があります。

ヘッダ ファイルの例

DECLARE_MEMORY_STAT_POOL_EXTERN(TEXT("Physical Memory Pool [Physical]"), MCR_Physical, STATGROUP_Memory, FPlatformMemory::MCR_Physical, CORE_API);
DECLARE_MEMORY_STAT_POOL_EXTERN(TEXT("GPU Memory Pool [GPU]"), MCR_GPU,STATGROUP_Memory, FPlatformMemory::MCR_GPU, CORE_API);
DECLARE_MEMORY_STAT_POOL_EXTERN(TEXT("Texture Memory Pool [Texture]"), MCR_TexturePool, STATGROUP_Memory, FPlatformMemory::MCR_TexturePool,CORE_API);

ソース ファイルの例

DEFINE_STAT(MCR_Physical);
DEFINE_STAT(MCR_GPU);
DEFINE_STAT(MCR_TexturePool);

// これはプールです。そのため、通常は、F*PlatformMemory::Init() で初期化する必要があります。
SET_MEMORY_STAT(MCR_Physical, PhysicalPoolLimit);
SET_MEMORY_STAT(MCR_GPU, GPUPoolLimit);
SET_MEMORY_STAT(MCR_TexturePool, TexturePoolLimit);

// プールが作成できたら、プールのメモリ統計を設定できます。

// 以下は、どこからでもアクセス可能です。
DECLARE_MEMORY_STAT_POOL_EXTERN(TEXT("Index buffer memory"), STAT_IndexBufferMemory, STATGROUP_RHI, FPlatformMemory::MCR_GPU, RHI_API);
DECLARE_MEMORY_STAT_POOL_EXTERN(TEXT("Vertex buffer memory"), STAT_VertexBufferMemory, STATGROUP_RHI, FPlatformMemory::MCR_GPU, RHI_API);
DECLARE_MEMORY_STAT_POOL_EXTERN(TEXT("Structured buffer memory"), STAT_StructuredBufferMemory,STATGROUP_RHI, FPlatformMemory::MCR_GPU, RHI_API);
DECLARE_MEMORY_STAT_POOL_EXTERN(TEXT("Pixel buffer memory"), STAT_PixelBufferMemory, STATGROUP_RHI, FPlatformMemory::MCR_GPU, RHI_API);

// 以下は、定義されたモジュール内でのみアクセス可能です。
DECLARE_MEMORY_STAT_POOL_EXTERN(TEXT("Pool Memory Size"), STAT_TexturePoolSize, STATGROUP_Streaming, FPlatformMemory::MCR_TexturePool, );
DECLARE_MEMORY_STAT_POOL_EXTERN(TEXT("Pool Memory Used"), STAT_TexturePoolAllocatedSize, STATGROUP_Streaming, FPlatformMemory::MCR_TexturePool, );

// 最後に、メモリ統計を更新する必要があります。

// 指定された値の分だけメモリ統計を増やします。
INC_MEMORY_STAT_BY(STAT_PixelBufferMemory,NumBytes);
// 指定された値の分だけメモリ統計を減らします。
DEC_MEMORY_STAT_BY(STAT_PixelBufferMemory,NumBytes);
// 指定された値でメモリ統計を設定します。
SET_MEMORY_STAT(STAT_PixelBufferMemory,NumBytes);

プールを使用しない通常のメモリ統計

DECLARE_MEMORY_STAT(TEXT("Total Physical"), STAT_TotalPhysical, STATGROUP_MemoryPlatform);
DECLARE_MEMORY_STAT(TEXT("Total Virtual"), STAT_TotalVirtual, STATGROUP_MemoryPlatform);
DECLARE_MEMORY_STAT(TEXT("Page Size"), STAT_PageSize, STATGROUP_MemoryPlatform);
DECLARE_MEMORY_STAT(TEXT("Total Physical GB"), STAT_TotalPhysicalGB, STATGROUP_MemoryPlatform);

または、必要に応じて、ヘッダ ファイルに DECLARE_MEMORY_STAT_EXTERN 、ソース ファイルに DEFINE_STAT を記述することができます。

メモリ統計の更新は、プールを使用したバージョンと同じ方法で行われます。

Cycle Counter を使用したパフォーマンス データ

最初に、Cycle Counter を追加する必要があります。

DECLARE_CYCLE_STAT(TEXT("Broadcast"), STAT_StatsBroadcast, STATGROUP_StatSystem);
DECLARE_CYCLE_STAT(TEXT("Condense"), STAT_StatsCondense, STATGROUP_StatSystem);

または、必要に応じて、ヘッダ ファイルに DECLARE_CYCLE_STAT_EXTERN 、ソース ファイルに DEFINE_STAT を記述することができます。

これで、以下のようにパフォーマンス データを取得できます。

Stats::Broadcast()
{
    SCOPE_CYCLE_COUNTER(STAT_StatsBroadcast);
    // ...
    // コードの一部
    // ...
}

関数が呼び出されるたびに統計情報を取得したくない場合は、条件付き Cycle Counter を使用できます。それほど一般的な方法ではありませんが、役に立つ場合があります。

Stats::Broadcast(bool bSomeCondition)
{

    CONDITIONAL_SCOPE_CYCLE_COUNTER(STAT_StatsBroadcast,bSomeCondition);
    // ...
    // コードの一部
    // ...
}

単一の関数からパフォーマンス データを取得する場合は、次の構文を使用できます。

Stats::Broadcast(bool bSomeCondition)
{
    DECLARE_SCOPE_CYCLE_COUNTER(TEXT("Broadcast"), STAT_StatsBroadcast, STATGROUP_StatSystem);
    // ...
    // コードの一部
    // ...
}

次のようにすることもできます。

Stats::Broadcast(bool bSomeCondition)
{
    QUICK_SCOPE_CYCLE_COUNTER(TEXT("Stats::Broadcast"));
    // ...
    // コードの一部
    // ...
}

これは主に一時的な統計に使用されます。

前述のすべての Cycle Counter は使用すると、パフォーマンス データに関する詳細な情報を取得するために、階層が生成されます。ただし、フラットな Cycle Counter を設定するオプションもあります。

Stats::Broadcast(bool bSomeCondition)
{
    const uint32 BroadcastBeginTime = FPlatformTime::Cycles();
    // ...
    // コードの一部
    // ...
    const uint32 BroadcastEndTime = FPlatformTime::Cycles();
    SET_CYCLE_COUNTER(STAT_StatsBroadcast, BroadcastEndTime-BroadcastBeginTime);
}

GetStatId を使用したパフォーマンス データ

Unreal Engine に実装されているいくつかのタスクは、パフォーマンス データの取得に関して異なるアプローチを使用します。これらは、 GetStatId() メソッドを実装します。 GetStatId() が存在しない場合、コードはコンパイルされません。

次に例を示します。

class FParallelAnimationCompletionTask
{
    // ...
    // コードの一部
    // ...
    FORCEINLINE TStatId GetStatId() const
    {
        RETURN_QUICK_DECLARE_CYCLE_STAT(FParallelAnimationCompletionTask, STATGROUP_TaskGraphTasks);
    }
    // ...
    // コードの一部
    // ...
};

パフォーマンス データをログに記録する

単にパフォーマンス データをログに記録する場合は、次の機能を使用できます。

メソッド

次のメソッドは、時間 (秒単位で渡される) を取得し、渡された変数にデルタ時間を追加します。

SCOPE_SECONDS_COUNTER(double& Seconds)

コードの例

Stats::Broadcast()
{
    double ThisTime = 0;
    {
       SCOPE_SECONDS_COUNTER(ThisTime);
        // ...
        // コードの一部
        // ...
    }
    UE_LOG(LogTemp, Log, TEXT("Stats::Broadcast %.2f"), ThisTime);  
}

ユーティリティ クラスとメソッド

クラス

説明

FScopeLogTime

時間 (秒単位で渡される) をログに記録し、渡された変数に累積統計を追加し、デストラクタのログにパフォーマンス データを出力するユーティリティ クラス。

メソッド

説明

SCOPE_LOG_TIME(Name, CumulativePtr)

指定された名前を使用して、パフォーマンス データを出力し、累積統計を収集します。

SCOPE_LOG_TIME_IN_SECONDS(Name, CumulativePtr)

SCOPE_LOG_TIME と同じ機能ですが、すぐに出力されます。

SCOPE_LOG_TIME_FUNC()

関数名を使用して、パフォーマンス データを出力します。ネストすることはできません。

SCOPE_LOG_TIME_FUNC_WITH_GLOBAL(CumulativePtr)

SCOPE_LOG_TIME_FUNC と同じ機能ですが、累積統計を収集します。

コードの例

double GMyBroadcastTime = 0.0;
Stats::Broadcast()
{
    SCOPE_LOG_TIME("Stats::Broadcast", &GMyBroadcastTime);
    SCOPE_LOG_TIME_IN_SECONDS("Stats::Broadcast (sec)", &GMyBroadcastTime);
    // ...
    // コードの一部
    // ...
}

Stats::Condense()
{
    // 名前は「Stats::Condense()」にする必要があります。ただし、コンパイラによって異なる場合があります。
    SCOPE_LOG_TIME_FUNC_WITH_GLOBAL(&GMyBroadcastTime);
    // ...
    // コードの一部
    // ...
}

FLOAT Counter または DWORD Counter を使用した汎用データ

通常、最初に行う必要があるのは、次のようなカウンターを追加することです。

DECLARE_FLOAT_COUNTER_STAT_EXTERN(STAT_FloatCounter,StatId,STATGROUP_TestGroup, CORE_API);
DECLARE_DWORD_COUNTER_STAT_EXTERN(STAT_DwordCounter,StatId,STATGROUP_TestGroup, CORE_API);
DECLARE_FLOAT_ACCUMULATOR_STAT_EXTERN(STAT_FloatAccumulator,StatId,STATGROUP_TestGroup, CORE_API);
DECLARE_DWORD_ACCUMULATOR_STAT_EXTERN(STAT_DwordAccumulator,StatId,STATGROUP_TestGroup, CORE_API);

次に、カウンターを更新および管理するには、次のメソッドを使用できます。

カウンターの更新メソッド

メソッド

説明

INC_DWORD_STAT(StatId)

Increases a dword stat by 1.

DEC_DWORD_STAT(StatId)

Decreases a dword stat by 1.

INC_DWORD_STAT_BY(StatId, Amount)

Increases a dword stat by the specified value.

DEC_DWORD_STAT_BY(StatId, Amount)

Decreases a dword stat by the specified value.

SET_DWORD_STAT(StatId, Value)

Sets a dword stat to the specified value.

INC_FLOAT_STAT_BY(StatId, Amount)

Increases a float stat by the specified value.

DEC_FLOAT_STAT_BY(StatId, Amount)

Decreases a float stat by the specified value.

SET_FLOAT_STAT(StatId, Value)

Sets a float stat to the specified value.

カウンターを管理するヘルパー メソッド

メソッド

説明

GET_STATID(StatId)

統計の TStatId のインスタンスを返します。

これは上級者向けです。

GET_STATDESCRIPTION(StatId)

統計の説明テキストを返します。

Unreal Engine のドキュメントを改善するために協力をお願いします!どのような改善を望んでいるかご意見をお聞かせください。
調査に参加する
閉じる