query< Target > Class Template Reference

Class encapsulating an OpenGL query object. More...

#include <query.hpp>

Public Member Functions
GLuint	name () const
	Retrieve the OpenGL name of this query. More...
template<typename T >
void	run (T callable)
	Run the query on the provided callable. More...
void	begin ()
	Mark the begin of the query block. More...
void	end ()
	Mark the end of the query block. More...
bool	poll_result (GLint &result)
	Poll the result of the query. More...
bool	poll_result (GLuint &result)
	Poll the result of the query. More...

Detailed Description

template<GLenum Target>
class gls::query< Target >

Class encapsulating an OpenGL query object.

A gls::query is an object that encapsulates an OpenGL query object.

Template Parameters

Target

The target established by this query when it is active

Like all objects in GLS, the underlying name is generated at object construction and deleted at destruction. This can be retrieved with name().

Query objects are used to query counters in the GL server. The counters are reset when the query begins and their value stored in the query object once the query ends. Common targets for a query are GL_SAMPLES_PASSED and GL_PRIMITIVES_GENERATED. If ARB_timer_query or OpenGL 3.3 is available, GL_TIME_ELAPSED is also common.

You can use a gls::query in 2 ways. The first method is closer to the way you would perform them yourself using OpenGL code directly, manually using begin() and end(). The second method using run() automatically takes care of calling end() for you once the callable has returned, thus it might be more convenient depending on the scenario. Either way, once end() has been called, either manually or automatically, you will need to periodically poll for the result. Once it is ready, you can start another query using this object.

Note that running 2 simultaneous queries with the same target will produce an OpenGL error. This will not happen if using run().

Example usage:

auto query = gls::query<GL_SAMPLES_PASSED>();
query.run( [&]() {

    ... some OpenGL code producing samples here ...

} );

...

auto result = GLuint( 0 );
if( query.poll_result( result ) ) {
    ... do something with the result ...
}

Member Function Documentation

GLuint name

(

)

const

Retrieve the OpenGL name of this query.

Returns

OpenGL name of this query

void run

(

T

callable

)

Run the query on the provided callable.

The callable should take no parameters, and its return value is ignored by run().

If a previous query is not pending begin() will be called, followed by the callable and then end(). Prefer using this method over begin() and end() when possible.

Parameters

callable

Callable to run between begin() and end()

void begin

(

)

Mark the begin of the query block.

If a previous query is still pending, calling this method will have no affect.

void end

(

)

Mark the end of the query block.

Calling this method if this query is not currently active will produce an OpenGL error.

bool poll_result

(

GLint &

result

)

Poll the result of the query.

After running run() or ending a block with end(), you can periodically poll the result of the query using this method. It will return true to signal the result passed in the result parameter is valid for use and false otherwise if the query is not yet ready.

Parameters

result

Variable to store the query result in

Returns

true if the result is ready and valid, false otherwise

bool poll_result

(

GLuint &

result

)

Poll the result of the query.

After running run() or ending a block with end(), you can periodically poll the result of the query using this method. It will return true to signal the result passed in the result parameter is valid for use and false otherwise if the query is not yet ready.

Parameters

result

Variable to store the query result in

Returns

true if the result is ready and valid, false otherwise