Rename various things scope -> query, make timestamp writes api more …

…safe and better documented

examples/demo.rs

@@ -1,12 +1,12 @@
 use std::borrow::Cow;
-use wgpu_profiler::{GpuProfiler, GpuProfilerSettings, GpuTimerScopeResult};
+use wgpu_profiler::{GpuProfiler, GpuProfilerSettings, GpuTimerQueryResult};
 use winit::{
     event::{Event, VirtualKeyCode, WindowEvent},
     event_loop::{ControlFlow, EventLoop},
     window::Window,
 };
 
-fn scopes_to_console_recursive(results: &[GpuTimerScopeResult], indentation: u32) {
+fn scopes_to_console_recursive(results: &[GpuTimerQueryResult], indentation: u32) {
     for scope in results {
         if indentation > 0 {
             print!("{:<width$}", "|", width = 4);
@@ -18,13 +18,13 @@ fn scopes_to_console_recursive(results: &[GpuTimerScopeResult], indentation: u32
             scope.label
         );
 
-        if !scope.nested_scopes.is_empty() {
-            scopes_to_console_recursive(&scope.nested_scopes, indentation + 1);
+        if !scope.nested_queries.is_empty() {
+            scopes_to_console_recursive(&scope.nested_queries, indentation + 1);
         }
     }
 }
 
-fn console_output(results: &Option<Vec<GpuTimerScopeResult>>, enabled_features: wgpu::Features) {
+fn console_output(results: &Option<Vec<GpuTimerQueryResult>>, enabled_features: wgpu::Features) {
     profiling::scope!("console_output");
     print!("\x1B[2J\x1B[1;1H"); // Clear terminal and put cursor to first row first column
     println!("Welcome to wgpu_profiler demo!");
@@ -283,7 +283,7 @@ fn draw(
         // It's also possible to take timings by hand, manually calling `begin_scope` and `end_scope`.
         // This is generally not recommended as it's very easy to mess up by accident :)
         let pass_scope = profiler
-            .begin_pass_scope("render pass bottom", scope.recorder, device)
+            .begin_pass_query("render pass bottom", scope.recorder, device)
             .with_parent(scope.scope.as_ref());
         let mut rpass = scope
             .recorder
@@ -307,13 +307,13 @@ fn draw(
         // Similarly, you can manually manage nested scopes within a render pass.
         // Again, to do any actual timing, you need to enable wgpu::Features::TIMESTAMP_QUERY_INSIDE_PASSES.
         {
-            let scope = profiler
-                .begin_scope("fractal 2", &mut rpass, device)
+            let query = profiler
+                .begin_query("fractal 2", &mut rpass, device)
                 .with_parent(Some(&pass_scope));
             rpass.draw(0..6, 2..3);
 
-            // Don't forget to end the scope!
-            profiler.end_scope(&mut rpass, scope);
+            // Don't forget to end the query!
+            profiler.end_query(&mut rpass, query);
         }
         // TODO:
         // Another variant is to use `ManualOwningScope`, forming a middle ground between no scope helpers and fully automatic scope closing.
@@ -333,7 +333,7 @@ fn draw(
         // };
 
         // Don't forget to end the scope.
-        profiler.end_scope(&mut rpass, pass_scope);
+        profiler.end_query(&mut rpass, pass_scope);
     }
 }
 

src/chrometrace.rs

@@ -1,11 +1,11 @@
 use std::{fs::File, io::Write, path::Path};
 
-use crate::GpuTimerScopeResult;
+use crate::GpuTimerQueryResult;
 
 /// Writes a .json trace file that can be viewed as a flame graph in Chrome or Edge via <chrome://tracing>
 pub fn write_chrometrace(
     target: &Path,
-    profile_data: &[GpuTimerScopeResult],
+    profile_data: &[GpuTimerQueryResult],
 ) -> std::io::Result<()> {
     let mut file = File::create(target)?;
 
@@ -27,7 +27,7 @@ pub fn write_chrometrace(
 
 fn write_results_recursive(
     file: &mut File,
-    result: &GpuTimerScopeResult,
+    result: &GpuTimerQueryResult,
     last: bool,
 ) -> std::io::Result<()> {
     // note: ThreadIds are under the control of Rust’s standard library
@@ -52,24 +52,24 @@ fn write_results_recursive(
         result.time.start * 1000.0 * 1000.0,
         (result.time.end - result.time.start) * 1000.0 * 1000.0,
         result.label,
-        if last && result.nested_scopes.is_empty() {
+        if last && result.nested_queries.is_empty() {
             "\n"
         } else {
             ",\n"
         }
     )?;
-    if result.nested_scopes.is_empty() {
+    if result.nested_queries.is_empty() {
         return Ok(());
     }
 
     for child in result
-        .nested_scopes
+        .nested_queries
         .iter()
-        .take(result.nested_scopes.len() - 1)
+        .take(result.nested_queries.len() - 1)
     {
         write_results_recursive(file, child, false)?;
     }
-    write_results_recursive(file, result.nested_scopes.last().unwrap(), last)?;
+    write_results_recursive(file, result.nested_queries.last().unwrap(), last)?;
 
     Ok(())
     // { "pid":1, "tid":1, "ts":546867, "dur":121564, "ph":"X", "name":"DoThings"

src/errors.rs

@@ -49,12 +49,12 @@ pub enum SettingsError {
 /// Errors that can occur during [`crate::GpuProfiler::end_frame`].
 #[derive(thiserror::Error, Debug, PartialEq, Eq)]
 pub enum EndFrameError {
-    #[error("All profiling scopes need to be closed before ending a frame. There were still {0} open scopes.")]
-    UnclosedScopes(u32),
+    #[error("All profiling queries need to be closed before ending a frame. There were still {0} open queries.")]
+    UnclosedQueries(u32),
 
     #[error(
         "Not all queries were resolved before ending a frame.\n
-Call `GpuProfiler::resolve_queries` after all profiling scopes have been closed and before ending the frame.\n
+Call `GpuProfiler::resolve_queries` after all profiling queries have been closed and before ending the frame.\n
 There were still {0} queries unresolved."
     )]
     UnresolvedQueries(u32),