Skip to content

README.md

Latest commit

 

History

History
97 lines (69 loc) · 3.62 KB

README.md

File metadata and controls

97 lines (69 loc) · 3.62 KB
Raw

PerfSDK Plugin

NVIDIA Nsight PerfSDK integration for Flax Engine with dual-mode architecture:

  • Mode 1 (Editor): Double-click a GPU profiler region in the editor to open live chip counter metrics
  • Mode 2 (Runtime): Press F1 in a cooked Debug/Development build to open a standalone GPU profiler with the same PerfSDK metrics on double-click

Features

  • Live throughput bars and counter values grouped by GPU subsystem (SM, caches, VRAM, raster, etc.)
  • + Add metric — browse and add any supported NVPerf counter at runtime
  • Custom metrics appear under a Custom group
  • Dual-mode: editor integration + standalone cooked build profiler
  • Zero impact on Release builds — completely stripped from shipping configurations

Requirements

  • Windows x64 or Linux x64
  • Flax 1.13+
  • NVIDIA GPU + Nsight Perf SDK installed
  • Environment variable NVPERF_SDK_PATH pointing at your Perf SDK root

Setup

  1. Set NVPERF_SDK_PATH in your user or system environment.
  2. On Linux, ensure the NvPerf host library directory is on the loader path.
  3. Reference the plugin from your game project:
"References": [
    { "Name": "$(EnginePath)/Flax.flaxproj" },
    { "Name": "$(EnginePath)/../PerfSDK/PerfSDK.flaxproj" }
]
  1. Open the project and Build & Run (or Tools → Recompile Scripts). Check the Output Log for Using PerfSDK v....
  2. See usage below for editor or cooked build profiling.

Mode 1: Editor Profiling

  1. Play the scene, open Profiler → GPU, enable live recording.
  2. Double-click a GPU region to open the Nvidia PerfSDK Metrics window.
  3. Click + Add metric to browse and add custom counters.

Mode 2: Cooked Build Profiling

  1. Cook your project as Debug or Development (never Release).
  2. Launch the cooked executable.
  3. Press F1 to toggle the standalone GPU profiler.
  4. Double-click any region in the timeline or table to open PerfSDK metrics.
  5. Same metrics window and + Add metric functionality as editor mode.

Supported Platforms

Platform Graphics APIs Editor Cooked Build
Windows x64 D3D11, D3D12, Vulkan Mode 1 Mode 2
Linux x64 Vulkan Mode 1 Mode 2

See WINDOWS_SETUP.md for Windows-specific setup.

Source Code Layout

Source/PerfSDK/
├── Shared/          ← NVPerf core + shared metrics UI (both modes)
│   ├── Native/      ← RenderPerfTools, PerfSdkHud
│   └── Managed/     ← PerfSdkChipMetricsTable, formatting helpers
├── Editor/          ← Mode 1: editor GPU profiler integration
├── Runtime/         ← Mode 2: standalone cooked build profiler (F1)
├── PerfSDK.cpp/h    ← Native GamePlugin entry
└── PerfSDK.Build.cs ← Build rules + Release gate

See /FlaxTesting/docs/ for full architecture documentation.

Release Build Guarantee

PerfSDK is completely absent from Release builds:

  • PerfSDK.ConditionalImport() returns false for Release non-editor
  • PerfSDKTarget.CanBuild() gates on ConditionalImport
  • All code wrapped in #if USE_PROFILER / #if COMPILE_WITH_RENDER_PERF_NVPERF
  • No DLL, no NVPerf libraries, no profiling hooks in Release

API (C# / C++ game code)

// Optional — only if calling RenderPerfTools from your game scripts
PerfSDK.ConditionalImport(options, options.PrivateDependencies);

Not required for editor metrics UI or runtime F1 profiler.

Vulkan Note

Set NVPERF_SDK_PATH before starting the editor or cooked build so Vulkan device creation enables NVPerf extensions. Fully restart after changing the env var.