Magnum::GL::SampleQuery class
#include <Magnum/GL/SampleQuery.h>

Query for samples.

Queries count of samples passed from fragment shader or boolean value indicating whether any samples passed. Can be used for example for conditional rendering:

GL::SampleQuery q{GL::SampleQuery::Target::AnySamplesPassed};

q.begin();
/* Render simplified object to test whether it is visible at all */
// ...
q.end();

/* Render full version of the object only if it is visible */
if(q.result<bool>()) {
    // ...
}

This approach has some drawbacks, as the rendering is blocked until result is available for the CPU to decide. This can be improved by using conditional rendering on GPU itself. The drawing commands will be sent to the GPU and processed or discarded later, so CPU can continue executing the code without waiting for the result.

GL::SampleQuery q{GL::SampleQuery::Target::AnySamplesPassed};

q.begin();
/* Render simplified object to test whether it is visible at all */
// ...
q.end();

q.beginConditionalRender(GL::SampleQuery::ConditionalRenderMode::Wait);
/* Render full version of the object only if the query returns nonzero result */
// ...
q.endConditionalRender();

Base classes

class AbstractQuery
Base class for queries.

Public types

enum class Target: GLenum { SamplesPassed = GL_SAMPLES_PASSED, AnySamplesPassed = GL_ANY_SAMPLES_PASSED, AnySamplesPassedConservative = GL_ANY_SAMPLES_PASSED_CONSERVATIVE }
Query target.
enum class ConditionalRenderMode: GLenum { Wait = GL_QUERY_WAIT, WaitInverted = GL_QUERY_WAIT_INVERTED, NoWait = GL_QUERY_NO_WAIT, NoWaitInverted = GL_QUERY_NO_WAIT_INVERTED, ByRegionWait = GL_QUERY_BY_REGION_WAIT, ByRegionWaitInverted = GL_QUERY_BY_REGION_WAIT_INVERTED, ByRegionNoWait = GL_QUERY_BY_REGION_NO_WAIT, ByRegionNoWaitInverted = GL_QUERY_BY_REGION_NO_WAIT_INVERTED }
Conditional render mode.

Public static functions

static auto wrap(GLuint id, Target target, ObjectFlags flags = {}) -> SampleQuery
Wrap existing OpenGL sample query object.

Constructors, destructors, conversion operators

SampleQuery(Target target) explicit
Constructor.
SampleQuery(NoCreateT) explicit noexcept
Construct without creating the underlying OpenGL object.
SampleQuery(const SampleQuery&) deleted
Copying is not allowed.
SampleQuery(SampleQuery&&) defaulted noexcept
Move constructor.

Public functions

auto operator=(const SampleQuery&) -> SampleQuery& deleted
Copying is not allowed.
auto operator=(SampleQuery&&) -> SampleQuery& defaulted noexcept
Move assignment.
void beginConditionalRender(ConditionalRenderMode mode)
Begin conditional rendering based on result value.
void endConditionalRender()
End conditional render.

Enum documentation

enum class Magnum::GL::SampleQuery::Target: GLenum

Query target.

Enumerators
SamplesPassed

Count of samples passed from fragment shader. Use result<UnsignedInt>() or result<Int>() to retrieve the result.
AnySamplesPassed

Whether any samples passed from fragment shader. Use result<bool>() to retrieve the result.
AnySamplesPassedConservative

Whether any samples passed from fragment shader (conservative). An implementation may choose a less precise version of the test at the expense of some false positives. Use result<bool>() to retrieve the result.

enum class Magnum::GL::SampleQuery::ConditionalRenderMode: GLenum

Conditional render mode.

Enumerators
Wait

If query result is not yet available, waits for it and then begins rendering only if result is nonzero.
WaitInverted

If query result is not yet available, waits for it and then begins rendering only if result is zero.
NoWait

If query result is not yet available, begins rendering like if the result was nonzero.
NoWaitInverted

If query result is not yet available, begins rendering like if the result was zero.
ByRegionWait

The same as ConditionalRenderMode::Wait, but regions untouched by the sample query may not be rendered at all.
ByRegionWaitInverted

The same as ConditionalRenderMode::WaitInverted, but regions untouched by the sample query may not be rendered at all.
ByRegionNoWait

The same as ConditionalRenderMode::NoWait, but regions untouched by the sample query may not be rendered at all.
ByRegionNoWaitInverted

The same as ConditionalRenderMode::NoWaitInverted, but regions untouched by the sample query may not be rendered at all.

Function documentation

static SampleQuery Magnum::GL::SampleQuery::wrap(GLuint id, Target target, ObjectFlags flags = {})

Wrap existing OpenGL sample query object.

Parameters
id OpenGL sample query ID
target Query target
flags Object creation flags

The id is expected to be of an existing OpenGL query object. Unlike query created using constructor, the OpenGL object is by default not deleted on destruction, use flags for different behavior.

Magnum::GL::SampleQuery::SampleQuery(Target target) explicit

Constructor.

Creates new OpenGL query object. If ARB_direct_state_access (part of OpenGL 4.5) is not available, the query is created on first use.

Magnum::GL::SampleQuery::SampleQuery(NoCreateT) explicit noexcept

Construct without creating the underlying OpenGL object.

The constructed instance is equivalent to moved-from state. Useful in cases where you will overwrite the instance later anyway. Move another object over it to make it useful.

This function can be safely used for constructing (and later destructing) objects even without any OpenGL context being active. However note that this is a low-level and a potentially dangerous API, see the documentation of NoCreate for alternatives.

void Magnum::GL::SampleQuery::beginConditionalRender(ConditionalRenderMode mode)

Begin conditional rendering based on result value.

void Magnum::GL::SampleQuery::endConditionalRender()

End conditional render.