DOCSEARCHbyAlgolia
Submit Docs

PresentMon Capture Application

repository·main·Indexed 25 days ago

https://github.com/gametechdev/presentmon

A tool for trace capture and real-time performance overlaying for games and graphics-intensive applications. It leverages the PresentMon Service for data collection, provides detailed performance metrics via CSV output, and includes an Intel-PresentMon ETW provider for direct communication between applications, libraries, and drivers.

Tokens
20.3K
Snippets
37
Records
105
Agent score
81%

What's inside PresentMon

  2. Use the PresentMon Console Application

    main
    The PresentMon console application is a standalone tool that uses the PresentMon SDK to capture and analyze graphics application performance. It outputs data to the console and/or CSV files. You can download pre-built binaries from the project releases (e.g., PresentMon-2.3.1-x64.exe).

  3. What is the PresentMon Service?

    main
    The PresentMon Service is a backend component that aggregates ETW (Event Tracing for Windows) frame data from the PresentMon Analysis library with hardware telemetry (such as GPU temperature and power). It acts as a central provider that exposes this aggregated data to client applications through the PresentMon API.

  4. How Z-bands and uiAccess ensure overlay visibility

    main

    To ensure the performance monitoring overlay appears above target applications (including those in fullscreen exclusive mode), PresentMon utilizes Windows Z-bands and the uiAccess manifest option.

    Z-bands

    Windows uses Z-bands to create hierarchical layers of Z-order. Windows in a higher Z-band always appear above windows in lower Z-bands. While most applications reside in ZBID_DESKTOP, PresentMon uses the undocumented WinAPI function CreateWindowInBand to place the overlay in a higher band.

    uiAccess

    To gain the privileges required to use CreateWindowInBand, the application manifest must set uiAccess=true. This allows the application to bypass certain UI restrictions, similar to accessibility tools.

    Requirements for uiAccess applications:

    • The executable must be cryptographically signed.
    • The executable must be run from a trusted location (e.g., C:\Program Files).

    Capabilities enabled by uiAccess:

    • Setting the foreground window.
    • Driving application windows via SendInput.
    • Using low-level hooks, raw input, GetKeyState, GetAsyncKeyState, and GetKeyboardInput to read input across all integrity levels.
    • Setting journal hooks.
    • Using AttachThreadInput to attach to a higher integrity input queue.

  5. Understanding the CEF implementation in PresentMon

    main

    The PresentMon Capture Application uses the Chromium Embedded Framework (CEF) to implement its control UI. CEF is a C++ framework that integrates Chromium components (rendering, inputs, sockets, etc.) into the application.

    Key Implementation Details:

    • Customization: Behavior is customized by inheriting from base class interfaces and injecting them into the framework to hook callback functions.
    • JS/C++ Interop: Custom C++ objects can be injected into the global (window) namespace in V8, allowing JavaScript code to interact with C++ logic.
    • Multi-process Architecture: Developers must account for Chromium's multi-process nature. Code execution depends on the specific process and thread. Operations must be coordinated using thread task queues and IPC message queues to ensure they execute on the correct thread/process. V8 contexts must be explicitly captured and managed during interaction.

  6. Understand CSV file output and naming conventions

    main

    The PresentMon capture application generates two CSV files for every capture session. By default, these are stored in the user's appdata local directory under Intel\PresentMon\Capture.

    1. Raw Frame Data File: Records the raw frame data.

      • Pattern: pmcap-[executablename]-YYMMDD-HHMMSS.csv

    2. Stats Summary File: Includes capture duration, total frames captured, and FPS percentiles (average, minimum, maximum, 99th, 95th, and 90th).

      • Pattern: pmcap-[executablename]-YYMMDD-HHMMSS-stats.csv

  7. Understand the CSV data format and structure

    main

    The CSV output from PresentMon provides frame-level granularity for application performance analysis.

    • Row Definition: Each row in the CSV represents a single frame that an application rendered and presented to the system.
    • Column Definition: Each column contains a specific metric value associated with that frame.
    • Time Units: All time-based values in the columns are expressed in milliseconds (ms).

  8. Upgrade the locked CEF runtime

    main

    To intentionally upgrade the CEF version, use the upgrade-cef.ps1 script. This script downloads the provided archive, stages the new payload, updates IntelPresentMon\AppCef\cef-lock.json, and regenerates the installer CEF WiX fragments. You should review all generated changes after the upgrade.

    > IntelPresentMon\AppCef\Batch\upgrade-cef.ps1 https://example.com/path/to/cef_archive.tar.bz2

  9. Integrate with the PresentMon Service using the SDK

    main

    To communicate with the PresentMon Service, client applications should use the PresentMon SDK.

    Starting from version 2.3.1, the service installs PresentMonAPI2.dll alongside the service itself. You have two primary integration paths:

    1. Manual Dynamic Loading

    Include the C header PresentMonAPI.h in your project and dynamically load PresentMonAPI2.dll at runtime.

    Warning: If your application ships its own copy of PresentMonAPI2.dll instead of using the one provided by the service installation, binary compatibility with the service is not guaranteed.

    2. Using the Loader Library (Recommended)

    To simplify the process of manually loading the DLL and resolving endpoints, use the provided loader library.

    • Build time: Link against the PresentMonAPI2Loader.lib import library.
    • Runtime: Deploy PresentMonAPI2Loader.dll alongside your application.

    SDK Location

    If installed with the service, the SDK files (PresentMonAPI.h, PresentMonAPI2Loader.lib, and PresentMonAPI2Loader.dll) are located by default in: Program Files\Intel\PresentMon\SDK

  10. Install build tool dependencies for PresentMon

    main

    To build the full PresentMon application, you must install the following build tools:

    • Visual Studio 2022
    • vcpkg
    • CMake
    • Node.js / NPM
    • WiX toolset v3 (including the VS extension)

    Note: If you only need to build the PresentData library or the PresentMon Console application, you only require Visual Studio. In this case, you can ignore the other dependencies and build PresentData\PresentData.vcxproj or PresentMon\ConsoleApplication.sln directly.

  11. Bootstrap auxiliary test data

    main

    To set up the required auxiliary test data for the project, run the bootstrap script from the repository root. This script automates cloning the IPMAuxTestData repository, checking out the specific commit pinned in Tests\aux-data.lock.json, downloading ETL release assets, and verifying their hashes.

    .\bootstrap.ps1

  12. Run the PresentMon Capture Application

    main
    To start the application, execute PresentMon.exe. The application provides both trace capture capabilities and a real-time performance overlay for games and graphics-intensive applications. It relies on the PresentMon Service for data collection, uses a custom Direct3D 11 renderer for the overlay, and a CEF-based UI for configuration.
    PresentMon.exe