Struct wgpu_profiler::GpuProfiler
source · pub struct GpuProfiler { /* private fields */ }
Expand description
Profiler instance.
You can have an arbitrary number of independent profiler instances per application/adapter.
Manages all the necessary wgpu::QuerySet
and wgpu::Buffer
behind the scenes.
Any query creation method may allocate a new wgpu::QuerySet
and wgpu::Buffer
internally if necessary.
After the first call that passes wgpu::Device
, the same device must be used with all subsequent
calls to GpuProfiler
and all passed references to wgpu objects must originate from that device.
Implementations§
source§impl GpuProfiler
impl GpuProfiler
sourcepub const ALL_WGPU_TIMER_FEATURES: Features = _
pub const ALL_WGPU_TIMER_FEATURES: Features = _
Combination of all timer query features GpuProfiler
can leverage.
sourcepub const REQUIRED_WGPU_FEATURES: Features = GpuProfiler::ALL_WGPU_TIMER_FEATURES
👎Deprecated since 0.9.0: Use ALL_WGPU_TIMER_FEATURES instead
pub const REQUIRED_WGPU_FEATURES: Features = GpuProfiler::ALL_WGPU_TIMER_FEATURES
Combination of all timer query features GpuProfiler
can leverage.
sourcepub fn new(settings: GpuProfilerSettings) -> Result<Self, CreationError>
pub fn new(settings: GpuProfilerSettings) -> Result<Self, CreationError>
Creates a new Profiler object.
There is nothing preventing the use of several independent profiler objects.
sourcepub fn change_settings(
&mut self,
settings: GpuProfilerSettings
) -> Result<(), SettingsError>
pub fn change_settings( &mut self, settings: GpuProfilerSettings ) -> Result<(), SettingsError>
Changes the settings of an existing profiler.
If timer scopes are disabled by setting GpuProfilerSettings::enable_timer_queries to false,
any timer queries that are in flight will still be processed,
but unused query sets and buffers will be deallocated during Self::process_finished_frame
.
Similarly, any opened debugging scope will still be closed if debug groups are disabled by setting
GpuProfilerSettings::enable_debug_groups to false.
sourcepub fn scope<'a, Recorder: ProfilerCommandRecorder>(
&'a self,
label: impl Into<String>,
encoder_or_pass: &'a mut Recorder,
device: &Device
) -> Scope<'a, Recorder>
pub fn scope<'a, Recorder: ProfilerCommandRecorder>( &'a self, label: impl Into<String>, encoder_or_pass: &'a mut Recorder, device: &Device ) -> Scope<'a, Recorder>
Starts a new auto-closing profiler scope.
To nest scopes inside this scope, call Scope::scope
on the returned scope.
If an wgpu::CommandEncoder
is passed but the wgpu::Device
does not support wgpu::Features::TIMESTAMP_QUERY
, no gpu timer will be queried and the scope will
not show up in the final results.
If an wgpu::ComputePass
or wgpu::RenderPass
is passed but the wgpu::Device
does not support wgpu::Features::TIMESTAMP_QUERY_INSIDE_PASSES
, no scope will be opened.
If GpuProfilerSettings::enable_debug_groups
is true, a debug group will be pushed on the encoder or pass.
Scope is automatically closed on drop.
sourcepub fn owning_scope<'a, Recorder: ProfilerCommandRecorder>(
&'a self,
label: impl Into<String>,
encoder_or_pass: Recorder,
device: &Device
) -> OwningScope<'a, Recorder>
pub fn owning_scope<'a, Recorder: ProfilerCommandRecorder>( &'a self, label: impl Into<String>, encoder_or_pass: Recorder, device: &Device ) -> OwningScope<'a, Recorder>
Starts a new auto-closing profiler scope that takes ownership of the passed encoder or rendering/compute pass.
To nest scopes inside this scope, call OwningScope::scope
on the returned scope.
If an wgpu::CommandEncoder
is passed but the wgpu::Device
does not support wgpu::Features::TIMESTAMP_QUERY
, no gpu timer will be queried and the scope will
not show up in the final results.
If an wgpu::ComputePass
or wgpu::RenderPass
is passed but the wgpu::Device
does not support wgpu::Features::TIMESTAMP_QUERY_INSIDE_PASSES
, no scope will be opened.
If GpuProfilerSettings::enable_debug_groups
is true, a debug group will be pushed on the encoder or pass.
Scope is automatically closed on drop.
sourcepub fn manual_owning_scope<'a, Recorder: ProfilerCommandRecorder>(
&'a self,
label: impl Into<String>,
encoder_or_pass: Recorder,
device: &Device
) -> ManualOwningScope<'a, Recorder>
pub fn manual_owning_scope<'a, Recorder: ProfilerCommandRecorder>( &'a self, label: impl Into<String>, encoder_or_pass: Recorder, device: &Device ) -> ManualOwningScope<'a, Recorder>
Starts a new manually closed profiler scope that takes ownership of the passed encoder or rendering/compute pass.
Does NOT call GpuProfiler::end_query()
on drop.
This construct is just for completeness in cases where working with scopes is preferred but one can’t rely on the Drop call in the right place.
This is useful when the owned value needs to be recovered after the end of the scope.
In particular, to submit a wgpu::CommandEncoder
to a queue, ownership of the encoder is necessary.
To nest scopes inside this scope, call ManualOwningScope::scope
on the returned scope.
If an wgpu::CommandEncoder
is passed but the wgpu::Device
does not support wgpu::Features::TIMESTAMP_QUERY
, no gpu timer will be queried and the scope will
not show up in the final results.
If an wgpu::ComputePass
or wgpu::RenderPass
is passed but the wgpu::Device
does not support wgpu::Features::TIMESTAMP_QUERY_INSIDE_PASSES
, no scope will be opened.
If GpuProfilerSettings::enable_debug_groups
is true, a debug group will be pushed on the encoder or pass.
sourcepub fn begin_query<Recorder: ProfilerCommandRecorder>(
&self,
label: impl Into<String>,
encoder_or_pass: &mut Recorder,
device: &Device
) -> GpuProfilerQuery
pub fn begin_query<Recorder: ProfilerCommandRecorder>( &self, label: impl Into<String>, encoder_or_pass: &mut Recorder, device: &Device ) -> GpuProfilerQuery
Starts a new profiler query on the given encoder or rendering/compute pass (if enabled).
The returned query must be closed by calling GpuProfiler::end_query
with the same encoder/pass,
even if timer queries are disabled.
To do this automatically, use GpuProfiler::scope
/GpuProfiler::owning_scope
instead.
If an wgpu::CommandEncoder
is passed but the wgpu::Device
does not support wgpu::Features::TIMESTAMP_QUERY
, no gpu timer will be queried and the scope will
not show up in the final results.
If an wgpu::ComputePass
or wgpu::RenderPass
is passed but the wgpu::Device
does not support wgpu::Features::TIMESTAMP_QUERY_INSIDE_PASSES
, no timer queries will be allocated.
If GpuProfilerSettings::enable_debug_groups
is true, a debug group will be pushed on the encoder or pass.
sourcepub fn begin_pass_query(
&self,
label: impl Into<String>,
encoder: &mut CommandEncoder,
device: &Device
) -> GpuProfilerQuery
pub fn begin_pass_query( &self, label: impl Into<String>, encoder: &mut CommandEncoder, device: &Device ) -> GpuProfilerQuery
Starts a new profiler query to be used for render/compute pass timestamp writes.
The returned query must be closed by calling GpuProfiler::end_query
, even if timer queries are disabled.
To do this automatically, use Scope::scoped_render_pass
/Scope::scoped_compute_pass
instead.
Call GpuProfilerQuery::render_pass_timestamp_writes
or GpuProfilerQuery::compute_pass_timestamp_writes
to acquire the corresponding wgpu::RenderPassTimestampWrites
/wgpu::ComputePassTimestampWrites
object.
If the wgpu::Device
does not support wgpu::Features::TIMESTAMP_QUERY
, no gpu timer will be reserved.
Unlike GpuProfiler::begin_query
this will not create a debug scope,
in order to not force passing of the same encoder/pass to GpuProfiler::end_query
.
(this is needed to relax resource tracking requirements a bit, making it easier to implement the automatic scopes)
sourcepub fn end_query<Recorder: ProfilerCommandRecorder>(
&self,
encoder_or_pass: &mut Recorder,
query: GpuProfilerQuery
)
pub fn end_query<Recorder: ProfilerCommandRecorder>( &self, encoder_or_pass: &mut Recorder, query: GpuProfilerQuery )
Ends passed query.
If the passed query was opened with GpuProfiler::begin_query
, the passed encoder or pass must be the same
as when the query was opened.
sourcepub fn resolve_queries(&mut self, encoder: &mut CommandEncoder)
pub fn resolve_queries(&mut self, encoder: &mut CommandEncoder)
Puts query resolve commands in the encoder for all unresolved, pending queries of the active profiler frame.
Note that you do not need to do this for every encoder, it is sufficient do do this once per frame as long as you submit the corresponding command buffer after all others that may have opened queries in the same frame. (It does not matter if the passed encoder itself has previously opened queries or not.) If you were to make this part of a command buffer that is enqueued before any other that has opened queries in the same profiling frame, no failure will occur but some timing results may be invalid.
It is advised to call this only once at the end of a profiling frame, but it is safe to do so several times.
Implementation note:
This method could be made &self
, taking the internal lock on the query pools.
However, the intended use is to call this once at the end of a frame, so we instead
encourage this explicit sync point and avoid the lock.
sourcepub fn end_frame(&mut self) -> Result<(), EndFrameError>
pub fn end_frame(&mut self) -> Result<(), EndFrameError>
Marks the end of a frame.
Needs to be called after submitting any encoder used in the current profiler frame.
Fails if there are still open queries or unresolved queries.
sourcepub fn process_finished_frame(
&mut self,
timestamp_period: f32
) -> Option<Vec<GpuTimerQueryResult>>
pub fn process_finished_frame( &mut self, timestamp_period: f32 ) -> Option<Vec<GpuTimerQueryResult>>
Checks if all timer queries for the oldest pending finished frame are done and returns that snapshot if any.
timestamp_period:
The timestamp period of the device. Pass the result of wgpu::Queue::get_timestamp_period()
.
Note that some implementations (Chrome as of writing) may converge to a timestamp period while the application is running,
so caching this value is usually not recommended.