Class ARBOcclusionQuery
- java.lang.Object
-
- org.lwjgl.opengl.ARBOcclusionQuery
-
public class ARBOcclusionQuery extends java.lang.Object
Native bindings to the ARB_occlusion_query extension.This extension defines a mechanism whereby an application can query the number of pixels (or, more precisely, samples) drawn by a primitive or group of primitives.
The primary purpose of such a query (hereafter referred to as an "occlusion query") is to determine the visibility of an object. Typically, the application will render the major occluders in the scene, then perform an occlusion query for the bounding box of each detail object in the scene. Only if said bounding box is visible, i.e., if at least one sample is drawn, should the corresponding object be drawn.
The earlier HP_occlusion_test extension defined a similar mechanism, but it had two major shortcomings.
- It returned the result as a simple
TRUE
/FALSE
result, when in fact it is often useful to know exactly how many samples were drawn. - It provided only a simple "stop-and-wait" model for using multiple queries. The application begins an occlusion test and ends it; then, at some later point, it asks for the result, at which point the driver must stop and wait until the result from the previous test is back before the application can even begin the next one. This is a very simple model, but its performance is mediocre when an application wishes to perform many queries, and it eliminates most of the opportunities for parallelism between the CPU and GPU.
This extension solves both of those problems. It returns as its result the number of samples that pass the depth and stencil tests, and it encapsulates occlusion queries in "query objects" that allow applications to issue many queries before asking for the result of any one. As a result, they can overlap the time it takes for the occlusion query results to be returned with other, more useful work, such as rendering other parts of the scene or performing other computations on the CPU.
There are many situations where a pixel/sample count, rather than a boolean result, is useful.
- Objects that are visible but cover only a very small number of pixels can be skipped at a minimal reduction of image quality.
- Knowing exactly how many pixels an object might cover may help the application decide which level-of-detail model should be used. If only a few pixels are visible, a low-detail model may be acceptable.
- "Depth peeling" techniques, such as order-independent transparency, need to know when to stop rendering more layers; it is difficult to determine a priori how many layers are needed. A boolean result allows applications to stop when more layers will not affect the image at all, but this will likely result in unacceptable performance. Instead, it makes more sense to stop rendering when the number of pixels in each layer falls below a given threshold.
- Occlusion queries can replace glReadPixels of the depth buffer to determine whether (for example) a light source is visible for the purposes of a lens flare effect or a halo to simulate glare. Pixel counts allow you to compute the percentage of the light source that is visible, and the brightness of these effects can be modulated accordingly.
Promoted to core in
OpenGL 1.5
. - It returned the result as a simple
-
-
Field Summary
Fields Modifier and Type Field and Description static int
GL_CURRENT_QUERY_ARB
GL_QUERY_COUNTER_BITS_ARBAccepted by thepname
parameter of GetQueryivARB.static int
GL_QUERY_RESULT_ARB
GL_QUERY_RESULT_AVAILABLE_ARBAccepted by thepname
parameter of GetQueryObjectivARB and GetQueryObjectuivARB.static int
GL_SAMPLES_PASSED_ARB
Accepted by thetarget
parameter of BeginQueryARB, EndQueryARB, and GetQueryivARB.
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method and Description static void
glBeginQueryARB(int target, int id)
Creates a query object and makes it active.static void
glDeleteQueriesARB(int id)
Deletes named query objects.static void
glDeleteQueriesARB(int[] ids)
Array version of:DeleteQueriesARB
static void
glDeleteQueriesARB(java.nio.IntBuffer ids)
Deletes named query objects.static void
glEndQueryARB(int target)
Marks the end of the sequence of commands to be tracked for the active query specified bytarget
.static int
glGenQueriesARB()
Generates query object names.static void
glGenQueriesARB(int[] ids)
Array version of:GenQueriesARB
static void
glGenQueriesARB(java.nio.IntBuffer ids)
Generates query object names.static int
glGetQueryiARB(int target, int pname)
Returns parameters of a query object target.static void
glGetQueryivARB(int target, int pname, int[] params)
Array version of:GetQueryivARB
static void
glGetQueryivARB(int target, int pname, java.nio.IntBuffer params)
Returns parameters of a query object target.static int
glGetQueryObjectiARB(int id, int pname)
Returns the integer value of a query object parameter.static void
glGetQueryObjectivARB(int id, int pname, int[] params)
Array version of:GetQueryObjectivARB
static void
glGetQueryObjectivARB(int id, int pname, java.nio.IntBuffer params)
Returns the integer value of a query object parameter.static int
glGetQueryObjectuiARB(int id, int pname)
Unsigned version ofGetQueryObjectivARB
.static void
glGetQueryObjectuivARB(int id, int pname, int[] params)
Array version of:GetQueryObjectuivARB
static void
glGetQueryObjectuivARB(int id, int pname, java.nio.IntBuffer params)
Unsigned version ofGetQueryObjectivARB
.static boolean
glIsQueryARB(int id)
Determine if a name corresponds to a query object.
-
-
-
Field Detail
-
GL_SAMPLES_PASSED_ARB
Accepted by thetarget
parameter of BeginQueryARB, EndQueryARB, and GetQueryivARB.
-
GL_QUERY_COUNTER_BITS_ARB, GL_CURRENT_QUERY_ARB
Accepted by thepname
parameter of GetQueryivARB.
-
GL_QUERY_RESULT_ARB, GL_QUERY_RESULT_AVAILABLE_ARB
Accepted by thepname
parameter of GetQueryObjectivARB and GetQueryObjectuivARB.
-
-
Method Detail
-
glGenQueriesARB
public static void glGenQueriesARB(java.nio.IntBuffer ids)
Generates query object names.- Parameters:
ids
- a buffer in which the generated query object names are stored
-
glGenQueriesARB
public static int glGenQueriesARB()
Generates query object names.
-
glDeleteQueriesARB
public static void glDeleteQueriesARB(java.nio.IntBuffer ids)
Deletes named query objects.- Parameters:
ids
- an array of query objects to be deleted
-
glDeleteQueriesARB
public static void glDeleteQueriesARB(int id)
Deletes named query objects.
-
glIsQueryARB
public static boolean glIsQueryARB(int id)
Determine if a name corresponds to a query object.- Parameters:
id
- a value that may be the name of a query object
-
glBeginQueryARB
public static void glBeginQueryARB(int target, int id)
Creates a query object and makes it active.- Parameters:
target
- the target type of query object established. One of:SAMPLES_PASSED
PRIMITIVES_GENERATED
TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN
TIME_ELAPSED
TIMESTAMP
ANY_SAMPLES_PASSED
ANY_SAMPLES_PASSED_CONSERVATIVE
id
- the name of a query object
-
glEndQueryARB
public static void glEndQueryARB(int target)
Marks the end of the sequence of commands to be tracked for the active query specified bytarget
.- Parameters:
target
- the query object target. One of:SAMPLES_PASSED
PRIMITIVES_GENERATED
TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN
TIME_ELAPSED
TIMESTAMP
ANY_SAMPLES_PASSED
ANY_SAMPLES_PASSED_CONSERVATIVE
-
glGetQueryivARB
public static void glGetQueryivARB(int target, int pname, java.nio.IntBuffer params)
Returns parameters of a query object target.- Parameters:
target
- the query object target. One of:SAMPLES_PASSED
PRIMITIVES_GENERATED
TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN
TIME_ELAPSED
TIMESTAMP
ANY_SAMPLES_PASSED
ANY_SAMPLES_PASSED_CONSERVATIVE
pname
- the symbolic name of a query object target parameter. One of:QUERY_COUNTER_BITS_ARB
CURRENT_QUERY_ARB
params
- the requested data
-
glGetQueryiARB
public static int glGetQueryiARB(int target, int pname)
Returns parameters of a query object target.- Parameters:
target
- the query object target. One of:SAMPLES_PASSED
PRIMITIVES_GENERATED
TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN
TIME_ELAPSED
TIMESTAMP
ANY_SAMPLES_PASSED
ANY_SAMPLES_PASSED_CONSERVATIVE
pname
- the symbolic name of a query object target parameter. One of:QUERY_COUNTER_BITS_ARB
CURRENT_QUERY_ARB
-
glGetQueryObjectivARB
public static void glGetQueryObjectivARB(int id, int pname, java.nio.IntBuffer params)
Returns the integer value of a query object parameter.- Parameters:
id
- the name of a query objectpname
- the symbolic name of a query object parameter. One of:QUERY_RESULT_ARB
QUERY_RESULT_AVAILABLE_ARB
params
- the requested data
-
glGetQueryObjectiARB
public static int glGetQueryObjectiARB(int id, int pname)
Returns the integer value of a query object parameter.- Parameters:
id
- the name of a query objectpname
- the symbolic name of a query object parameter. One of:QUERY_RESULT_ARB
QUERY_RESULT_AVAILABLE_ARB
-
glGetQueryObjectuivARB
public static void glGetQueryObjectuivARB(int id, int pname, java.nio.IntBuffer params)
Unsigned version ofGetQueryObjectivARB
.- Parameters:
id
- the name of a query objectpname
- the symbolic name of a query object parameter. One of:QUERY_RESULT_ARB
QUERY_RESULT_AVAILABLE_ARB
params
- the requested data
-
glGetQueryObjectuiARB
public static int glGetQueryObjectuiARB(int id, int pname)
Unsigned version ofGetQueryObjectivARB
.- Parameters:
id
- the name of a query objectpname
- the symbolic name of a query object parameter. One of:QUERY_RESULT_ARB
QUERY_RESULT_AVAILABLE_ARB
-
glGenQueriesARB
public static void glGenQueriesARB(int[] ids)
Array version of:GenQueriesARB
-
glDeleteQueriesARB
public static void glDeleteQueriesARB(int[] ids)
Array version of:DeleteQueriesARB
-
glGetQueryivARB
public static void glGetQueryivARB(int target, int pname, int[] params)
Array version of:GetQueryivARB
-
glGetQueryObjectivARB
public static void glGetQueryObjectivARB(int id, int pname, int[] params)
Array version of:GetQueryObjectivARB
-
glGetQueryObjectuivARB
public static void glGetQueryObjectuivARB(int id, int pname, int[] params)
Array version of:GetQueryObjectuivARB
-
-