Struct ElapsedQuery

pub struct ElapsedQuery { /* private fields */ }

Available on crate feature dep_miniquad only.

ElapsedQuery is used to measure duration of GPU operations.

Usual timing/profiling methods are difficult apply to GPU workloads as draw calls are submitted asynchronously effectively hiding execution time of individual operations from the user. ElapsedQuery allows to measure duration of individual rendering operations, as though the time was measured on GPU rather than CPU side.

The query is created using ElapsedQuery::new() function.

use miniquad::graphics::ElapsedQuery;
// initialization
let mut query = ElapsedQuery::new();

Measurement is performed by calling ElapsedQuery::begin_query() and ElapsedQuery::end_query()

query.begin_query();
// one or multiple calls to miniquad::GraphicsContext::draw()
query.end_query();

Retreival of measured duration is only possible at a later point in time. Often a frame or couple frames later. Measurement latency can especially be high on WASM/WebGL target.

// couple frames later:
if query.is_available() {
  let duration_nanoseconds = query.get_result();
  // use/display duration_nanoseconds
}

And during finalization:

// clean-up
query.delete();

It is only possible to measure single query at once.

On OpenGL/WebGL platforms implementation relies on EXT_disjoint_timer_query extension.

Implementations

impl ElapsedQuery

pub fn new() -> ElapsedQuery

pub fn begin_query(&mut self)

Submit a beginning of elapsed-time query.

Only a single query can be measured at any moment in time.

Use ElapsedQuery::end_query() to finish the query and ElapsedQuery::get_result() to read the result when rendering is complete.

The query can be used again after retriving the result.

Implemented as glBeginQuery(GL_TIME_ELAPSED, ...) on OpenGL/WebGL platforms.

Use ElapsedQuery::is_supported() to check if functionality is available and the method can be called.

pub fn end_query(&mut self)

Submit an end of elapsed-time query that can be read later when rendering is complete.

This function is usd in conjunction with ElapsedQuery::begin_query() and ElapsedQuery::get_result().

Implemented as glEndQuery(GL_TIME_ELAPSED) on OpenGL/WebGL platforms.

pub fn get_result(&self) -> u64

Retreieve measured duration in nanonseconds.

Note that the result may be ready only couple frames later due to asynchronous nature of GPU command submission. Use ElapsedQuery::is_available() to check if the result is available for retrieval.

Use ElapsedQuery::is_supported() to check if functionality is available and the method can be called.

pub fn is_supported() -> bool

Reports whenever elapsed timer is supported and other methods can be invoked.

pub fn is_available(&self) -> bool

Reports whenever result of submitted query is available for retrieval with ElapsedQuery::get_result().

Note that the result may be ready only couple frames later due to asynchrnous nature of GPU command submission.

Use ElapsedQuery::is_supported() to check if functionality is available and the method can be called.

pub fn delete(&mut self)

Delete query.

Note that the query is not deleted automatically when dropped.

Implemented as glDeleteQueries(...) on OpenGL/WebGL platforms.

Trait Implementations

impl Clone for ElapsedQuery

fn clone(&self) -> ElapsedQuery

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for ElapsedQuery