#graphics #wgpu #profiler #gpu

wgpu-profiler

Simple profiler scopes for wgpu using timer queries

22 releases (14 breaking)

0.16.1 Feb 9, 2024
0.15.0 Oct 26, 2023
0.13.0 Jul 24, 2023
0.11.0 Jan 26, 2023
0.3.1 Mar 6, 2021

#31 in Graphics APIs

Download history 240/week @ 2023-11-05 319/week @ 2023-11-12 205/week @ 2023-11-19 305/week @ 2023-11-26 204/week @ 2023-12-03 219/week @ 2023-12-10 338/week @ 2023-12-17 344/week @ 2023-12-24 341/week @ 2023-12-31 403/week @ 2024-01-07 434/week @ 2024-01-14 434/week @ 2024-01-21 487/week @ 2024-01-28 504/week @ 2024-02-04 853/week @ 2024-02-11 995/week @ 2024-02-18

2,860 downloads per month
Used in 10 crates (5 directly)

MIT/Apache

71KB
975 lines

wgpu-profiler

Crates.io

Simple profiler scopes for wgpu using timer queries

Features

  • Easy to use profiler scopes
    • Allows nesting!
    • Can be disabled by runtime flag
    • Additionally generates debug markers
    • Thread-safe - can profile several command encoder/buffers in parallel
  • Internally creates pools of timer queries automatically
    • Does not need to know in advance how many queries/profiling scopes are needed
    • Caches up profiler-frames until results are available
      • No stalling of the device at any time!
  • Many profiler instances can live side by side
  • chrome trace flamegraph json export
  • Tracy integration (behind tracy feature flag)

How to use

Create a new profiler object:

use wgpu_profiler::{wgpu_profiler, GpuProfiler, GpuProfilerSettings};
// ...
let mut profiler = GpuProfiler::new(GpuProfilerSettings::default());

Now you can start creating profiler scopes:

// You can now open profiling scopes on any encoder or pass:
let mut scope = profiler.scope("name of your scope", &mut encoder, &device);

// Scopes can be nested arbitrarily!
let mut nested_scope = scope.scope("nested!", &device);

// Scopes on encoders can be used to easily create profiled passes!
let mut compute_pass = nested_scope.scoped_compute_pass("profiled compute", &device);

// Scopes expose the underlying encoder or pass they wrap:
compute_pass.set_pipeline(&pipeline);
// ...

// Scopes created this way are automatically closed when dropped.

GpuProfiler reads the device features on first use: if your wgpu device doesn't have wgpu::Features::TIMESTAMP_QUERY enabled, it won't attempt to emit any timer queries. Similarly, if wgpu::Features::WRITE_TIMESTAMP_INSIDE_PASSES is not present, no queries will be issued from inside passes.

Wgpu-profiler needs to insert buffer copy commands, so when you're done with an encoder and won't do any more profiling scopes on it, you need to resolve the queries:

profiler.resolve_queries(&mut encoder);

And finally, to end a profiling frame, call end_frame. This does a few checks and will let you know if something is off!

profiler.end_frame().unwrap();

Retrieving the oldest available frame and writing it out to a chrome trace file.

if let Some(profiling_data) = profiler.process_finished_frame(queue.get_timestamp_period()) {
    wgpu_profiler::chrometrace::write_chrometrace(std::path::Path::new("mytrace.json"), &profiling_data);
}

To get a look of it in action, check out the example project!

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Changelog

  • 0.16.1
    • Fix building for wasm, by @davidster in #62
  • 0.16
    • update to wgpu 0.19
    • ⚠️ Includes many major breaking changes! ⚠️
      • GpuProfiler can now be used with several command buffers interleaved or in parallel!
        • Scope/OwningScope/ManualScope/ are now all top-level in the gpu_profiler module. GpuProfiler has utilities to create them directly.
      • GpuProfiler::begin_query returns a query and GpuProfiler::end_query consumes it again
      • nesting of profiling scopes is no longer done automatically: To manually associate a GpuProfilerQuery with a parent, use GpuProfilerQuery::with_parent
      • removed profiling macro (doesn't work well with the new nesting model)
      • GpuProfiler can now directly create scope structs using GpuProfiler::scope/owning_scope
  • 0.15
    • update to wgpu 0.18, by @Zoxc in #50
    • sample & doc fixes, by @waywardmonkeys in #41, #44
    • various methods return thiserror errors instead of internal unwrap/except on user errors, by @Wumpf in #45 and following PRs
    • overhauled GpuProfiler creation & configuration:
      • takes settings object that can be changed after the fact (allows disabling on the fly!)
      • adapter/queue/device no longer needed on creation unless tracy client is required.
      • separate creation method for tracy support
  • 0.14.2
    • Fix pointing to wrong tracy version, by @waywardmonkeys in #36
    • Doc fixes, by @waywardmonkeys in #38
  • 0.14.1
    • Tracy integration, by @cwfitzgerald in #35
  • 0.13.0
    • Upgrade to wgpu 0.17, by @waywardmonkeys in #31
  • 0.12.1
    • Fix wgpu validation error due to mapping of query resolve buffer, by @Davidster #28
  • 0.12.0
    • Upgrade to wgpu 0.16, by @davidster in #26
  • 0.11.0
    • Upgrade to wgpu 0.15
  • 0.10.0
    • Upgrade to wgpu 0.14 and switch to rust 2021 edition, by @Imberflur in #23
  • 0.9.1
    • Better docs #21
    • Fix crash on dropped frame #20, reported by @JCapucho in #19
    • Fix enable_pass_timer/enable_encoder_timer checking wrong features

Dependencies

~2–39MB
~560K SLoC