| Name |
| |
| ARB_occlusion_query |
| |
| Name Strings |
| |
| GL_ARB_occlusion_query |
| |
| Contributors |
| |
| Ross Cunniff |
| Matt Craighead |
| Daniel Ginsburg |
| Kevin Lefebvre |
| Bill Licea-Kane |
| Nick Triantos |
| |
| Contact |
| |
| Matt Craighead, NVIDIA Corporation (mcraighead 'at' nvidia.com) |
| Daniel Ginsburg, AMD (dan.ginsburg 'at' amd.com) |
| |
| Notice |
| |
| Copyright (c) 2003-2013 The Khronos Group Inc. Copyright terms at |
| http://www.khronos.org/registry/speccopyright.html |
| |
| IP Status |
| |
| HP has claimed that they hold IP around use of this extension. HP |
| has committed to releasing rights to this IP to the ARB if the |
| functionality is included in OpenGL (April 10, 2003). |
| |
| Status |
| |
| Approved by the ARB (version 1.0), June 10, 2003, pending further minor |
| revisions |
| |
| Version |
| |
| Date: April 21, 2007 |
| Revision: 7 |
| $Id$ |
| |
| Number |
| |
| ARB Extension #29 |
| |
| Dependencies |
| |
| Written based on the wording of the OpenGL 1.4 specification. |
| |
| HP_occlusion_test affects the definition of this extension. |
| |
| Overview |
| |
| 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 GL_TRUE/GL_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. |
| |
| Issues |
| |
| How is this extension different from NV_occlusion_query? |
| |
| The following changes have been made. |
| - A "target" parameter has been added. Only one target exists at |
| present, SAMPLES_PASSED_ARB, but future extensions could add |
| additional types of queries. |
| - Terminology changed slightly. "Pixel" was being used |
| incorrectly, where "fragment" or "sample" would be more |
| accurate. |
| - Various NVIDIA-specific references have been removed. |
| - Interactions with multisample have been changed slightly to |
| allow implementations based on either a sample count or a |
| fragment count. The result is returned in units of samples. |
| - Clarified that using an id of zero is illegal. |
| - Added missing spec language for IsQuery entry point. |
| - General language, issues, etc. cleanup. |
| - HP_occlusion_test is no longer required. |
| - Modified the minimum required counter bits to be dependent on |
| the implementation's maximum viewport or the value 0 |
| - Clarified that active query state is per target server state. |
| This implies that a loop of QUERY_RESULT_AVAILABLE_ARB will |
| return TRUE in finite time. NV_occlusion_query asked |
| that the application flush to prevent an infinite loop. |
| - Clarified the behavior of the async QUERY_RESULT_AVAILABLE_ARB |
| command. |
| - When the count of samples that pass the occlusion query overflows, |
| the value should saturate. |
| |
| Should we use an object-based interface? |
| |
| RESOLVED: Yes, this makes the interface much simpler, and it is |
| friendly for indirect rendering. |
| |
| What is the difference between a "query object" and an "occlusion |
| query"? |
| |
| "Occlusion query" is a synonym for "query object used with target |
| SAMPLES_PASSED". |
| |
| Should we offer a way to poll whether an occlusion query has |
| completed and its result is available? |
| |
| RESOLVED. Yes, this allows applications to use CPU time that might |
| have been spent spinning more usefully. However, the polling |
| method introduced in the NV_occlusion_query spec allowed for a |
| potential infinite loop if the application does not do a flush. |
| This version of the spec clarifies the behavior which now makes such |
| a flush unnecessary. |
| |
| Is GetQueryObjectuivARB necessary? |
| |
| RESOLVED: Yes, it makes using a 32-bit count less painful. |
| |
| Should there be a limit on how many queries can be outstanding? |
| |
| RESOLVED: No. This would make the extension much more |
| difficult to spec and use. Allowing this does not add any |
| significant implementation burden; and even if drivers have some |
| internal limit on the number of outstanding queries, it is not |
| expected that applications will need to know this to achieve |
| optimal or near-optimal performance. |
| |
| What happens if BeginQueryARB is called when a query is already |
| outstanding for a different object on the same target? |
| |
| RESOLVED: This is an INVALID_OPERATION error. |
| |
| What happens if BeginQueryARB is called with an ID of a query that is |
| already in progress? |
| |
| RESOLVED: This is also an INVALID_OPERATION error. |
| |
| What parameters should EndQueryARB have? |
| |
| RESOLVED: Just a target. It doesn't need to take an "id" |
| argument, since this would be redundant -- only one query can be |
| active for any given target at a given time. |
| |
| How many bits should we require the samples-passed count to be, at |
| minimum? |
| |
| RESOLVED. The largest minimum that can be required of a GL |
| implementation is 32, the minimum bit width of an int or uint. |
| |
| The minimum number of bits required for the samples-passed |
| count will be dependent on the implementation's maximum viewport size. |
| In order to allow for two overdraws in the case of only one sample |
| buffer, the minimum counter precision (n) will be determined by: |
| |
| n = min (32 , ceil (log2 (maxViewportWidth x maxViewportHeight x |
| 1 sample x 2 overdraws) ) ) |
| |
| An implementation can either set QUERY_COUNTER_BITS_ARB to the |
| value 0, or to some number greater than or equal to n. If an |
| implementation returns 0 for QUERY_COUNTER_BITS_ARB, then the |
| occlusion queries will always return that zero samples passed the |
| occlusion test, and so an application should not use occlusion queries |
| on that implementation. |
| |
| Note that other targets may come along in the future that require more |
| or fewer bits. |
| |
| What should we do about overflows? |
| |
| RESOLVED: Overflows are required to saturate, though it is expected |
| that several current implementations will not conform to this |
| requirement. |
| |
| The ideal behavior is to saturate. This ensures that you always |
| get a "large" result when you render many samples. It also |
| ensures that apps which want a boolean test can do this without |
| worrying about the rare case where the result ends up exactly at |
| zero after wrapping. |
| |
| Either way, it's unlikely that this matters much as long as a |
| sufficient number of bits are required. |
| |
| What is the interaction with multisample? |
| |
| RESOLVED: We count samples, not pixels -- even if MULTISAMPLE is |
| disabled but SAMPLE_BUFFERS is 1. |
| |
| A given fragment may have anywhere between zero and SAMPLES of |
| its samples covered. Ideally, the samples-passed count would be |
| incremented by the precise number of samples, but we permit |
| implementations to instead increment the samples-passed count by |
| SAMPLES if at least one sample in a given fragment is covered. |
| |
| Note that the depth/stencil test optimization whereby |
| implementations may choose to depth test at only one of the |
| samples when MULTISAMPLE is disabled does not cause this to |
| become ill-specified, because we are counting the number of |
| samples that are still alive _after_ the depth test stage. The |
| particular mechanism used to decide whether to kill or keep those |
| samples is not relevant. |
| |
| Exactly what stage in the pipeline are we counting samples at? |
| |
| RESOLVED: We are counting immediately after _both_ the depth and |
| stencil tests, i.e., samples that pass both. Note that the depth |
| test comes after the stencil test, so to say that it is the |
| number that pass the depth test is sufficient; though it is often |
| conceptually helpful to think of the depth and stencil tests as |
| being combined, because the depth test's result impacts the |
| stencil operation used. |
| |
| Is it guaranteed that occlusion queries return in order? |
| |
| RESOLVED: Yes. It makes sense to do this. If occlusion test X |
| occurred before occlusion query Y, and the driver informs the app |
| that occlusion query Y is done, the app can infer that occlusion |
| query X is also done. For applications that do poll, this allows |
| them to do so with less effort. |
| |
| Will polling a query without a Flush possibly cause an infinite loop? |
| |
| RESOLVED: No. An infinite loop was possible in the original |
| NV_occlusion_query spec if an application did not perform a |
| flush prior to polling. This behavior was removed in this version |
| of the spec as it violated language in the core GL spec. |
| |
| Instead of allowing for an infinite loop, performing a |
| QUERY_RESULT_AVAILABLE_ARB will perform a flush if the result |
| is not ready yet on the first time it is queried. This ensures |
| that the async query will return true in finite time. |
| |
| This behavior is not a significant performance loss over the original |
| version of the spec. A flush would need to be performed at some |
| point anyway and the flush performed when QUERY_RESULT_AVAILABLE_ARB |
| is requested will only occur *if the result is not back yet*. |
| |
| What should be the interaction between this spec and |
| HP_occlusion_test? |
| |
| RESOLVED: Whereas NV_occlusion_query required that you implement |
| HP_occlusion_test, and even went so far as to specify the precise |
| behavior of HP_occlusion_test (since the HP_occlusion_test spec |
| did not contain those details), this spec does not. This spec |
| explains the interaction with HP_occlusion_test, but does not |
| attempt to double as a spec for that extension. |
| |
| What happens if HP_occlusion_test and ARB_occlusion_query usage is |
| overlapped? |
| |
| RESOLVED: The two can be overlapped safely. Counting is enabled |
| if either an occlusion query is active *or* OCCLUSION_TEST_HP is |
| enabled. The alternative (producing an error) does not work -- |
| it would require that PopAttrib be capable of producing an error, |
| which would be rather problematic. |
| |
| Note that BeginQueryARB, not EndQueryARB, resets the sample |
| count (and therefore the occlusion test result). This can avoid |
| certain types of strange behavior where an occlusion query's |
| samples-passed count does not always correspond to the samples |
| rendered during the occlusion query. The spec would make sense |
| the other way, but the behavior would be strange. |
| |
| Should there be a "target" parameter to BeginQueryARB? |
| |
| RESOLVED: Yes. Whereas NV_occlusion_query wasn't trying to solve |
| a problem beyond simple occlusion queries, this extension creates |
| a framework useful for future queries. |
| |
| Does GenQueriesARB need a "target" parameter? |
| |
| RESOLVED: No. A query can be reused any number of times with any |
| targets. |
| |
| How can one ask for the currently active query? |
| |
| RESOLVED: A new entry point has been added to query information |
| about a given query target. This makes it unnecessary to add two |
| new enumerants (# of bits and current query ID) for each new |
| target that is introduced. |
| |
| Are query objects shareable between multiple contexts? |
| |
| RESOLVED: No. Query objects are lightweight and we normally share |
| large data across contexts. Also, being able to share query objects |
| across contexts is not particularly useful. In order to do the async |
| query across contexts, a query on one context would have to be finished |
| before the other context could query it. |
| |
| What happens when an app begins a query on a target, ends it, begins |
| a query on the same target with the same id, ends it, and then tries |
| to retrieve data about the query using GetQueryObjecti[u]vARB? Which |
| query does the GetQueryObjecti[u]vARB return results for? |
| |
| RESOLVED. In this case, the result retrieved from |
| GetQueryObjecti[u]vARB will be from the last query on that target and |
| id. The result returned from GetQueryObjecti[u]vARB will always be from |
| the last BeginQueryARB/EndQueryARB pair on that target and id. |
| |
| Is this extension useful for saving geometry, fill rate, or both? |
| |
| The answer to this question is to some extent implementation- |
| dependent, but it is expected that it is most useful for reducing |
| geometry workload, and less so for fill rate. |
| |
| For the cost of rendering a bounding box, you can potentially |
| save rendering a normal object. A bounding box consists of only |
| 12 triangles, whereas the original object might have contained |
| thousands or even millions of triangles. |
| |
| Using bounding box occlusion queries may either help or hurt in |
| fill-limited situations, because rendering the pixels of a |
| bounding box is not free. In most situations, a bounding box |
| will probably have more pixels than the original object. Those |
| pixels can probably be rendered more quickly, though, since they |
| involve only Z reads (no Z writes or color traffic), and they |
| need not be textured or otherwise shaded. |
| |
| In multipass rendering situations, however, occlusion queries can |
| almost always save fill rate, because wrapping an object with an |
| occlusion query is generally cheap. See "Usage Examples" for an |
| illustration. |
| |
| What can be said about guaranteeing correctness when using |
| occlusion queries, especially as it relates to invariance? |
| |
| Invariance is critical to guarantee the correctness of occlusion |
| queries. If occlusion queries go through a different code path |
| than standard rendering, the fragments rendered may be different. |
| |
| However, the invariance issues are difficult at best to solve. |
| Because of the vagaries of floating-point precision, it is |
| difficult to guarantee that rendering a bounding box will render |
| at least as many pixels with equal or smaller Z values than the |
| object itself would have rendered. |
| |
| Likewise, many other aspects of rendering state tend to be |
| different when performing an occlusion query. Color and depth |
| writes are typically disabled, as are texturing, vertex programs, |
| and any fancy per-fragment math. So unless all these features |
| have guarantees of invariance themselves (unlikely at best), |
| requiring invariance for ARB_occlusion_query would be futile. |
| |
| In general, implementations are recommended to be fully invariant |
| with respect to whether any given type of query is active, |
| insofar as it is possible. That is, having an occlusion query |
| active should not affect the operation of any other stage of the |
| pipeline. Following this rule is essential to numerous occlusion |
| query algorithms working correctly. However, to permit |
| implementations where this feature is implemented in software, |
| this rule is only a recommendation, not a requirement. |
| |
| Another unrelated problem that can threaten correctness is near |
| and far clipping. The bounding box of an object may penetrate |
| the near clip plane, even though the original object may not |
| have. In such a circumstance, a bounding box occlusion query may |
| produce an incorrect result. Whenever you design an algorithm |
| using occlusion queries, it is best to be careful about the near |
| and far clip planes. |
| |
| How can frame-to-frame coherency help applications using this |
| extension get even higher performance? |
| |
| Usually, if an object is visible one frame, it will be visible |
| the next frame, and if it is not visible, it will not be visible |
| the next frame. |
| |
| Of course, for most applications, "usually" isn't good enough. |
| It is undesirable, but acceptable, to render an object that |
| *isn't* visible, because that only costs performance. It is |
| generally unacceptable to *not* render an object that *is* |
| visible. |
| |
| The simplest approach is that visible objects should be checked |
| every N frames (where, say, N=5) to see if they have become |
| occluded, while objects that were occluded last frame must be |
| rechecked again in the current frame to guarantee that they are |
| still occluded. This will reduce the number of wasteful |
| occlusion queries by almost a factor of N. |
| |
| Other, more complicated techniques exist but are beyond the scope |
| of this extension document. |
| |
| Do occlusion queries make other visibility algorithms obsolete? |
| |
| No. |
| |
| Occlusion queries are helpful, but they are not a cure-all. They |
| should be only one of many items in your bag of tricks to decide |
| whether objects are visible or invisible. They are not an excuse |
| to skip frustum culling, or precomputing visibility using portals |
| for static environments, or other standard visibility techniques. |
| |
| New Procedures and Functions |
| |
| void GenQueriesARB(sizei n, uint *ids); |
| void DeleteQueriesARB(sizei n, const uint *ids); |
| boolean IsQueryARB(uint id); |
| void BeginQueryARB(enum target, uint id); |
| void EndQueryARB(enum target); |
| void GetQueryivARB(enum target, enum pname, int *params); |
| void GetQueryObjectivARB(uint id, enum pname, int *params); |
| void GetQueryObjectuivARB(uint id, enum pname, uint *params); |
| |
| New Tokens |
| |
| Accepted by the <target> parameter of BeginQueryARB, EndQueryARB, |
| and GetQueryivARB: |
| |
| SAMPLES_PASSED_ARB 0x8914 |
| |
| Accepted by the <pname> parameter of GetQueryivARB: |
| |
| QUERY_COUNTER_BITS_ARB 0x8864 |
| CURRENT_QUERY_ARB 0x8865 |
| |
| Accepted by the <pname> parameter of GetQueryObjectivARB and |
| GetQueryObjectuivARB: |
| |
| QUERY_RESULT_ARB 0x8866 |
| QUERY_RESULT_AVAILABLE_ARB 0x8867 |
| |
| Additions to Chapter 2 of the OpenGL 1.4 Specification (OpenGL Operation) |
| |
| Modify Section 2.1, OpenGL Fundamentals (p. 4) |
| |
| (modify fourth paragraph, p. 4) It also means that queries and |
| pixel read operations return state consistent with complete |
| execution of all previously invoked GL commands, except where |
| explicitly specified otherwise |
| |
| Additions to Chapter 3 of the OpenGL 1.4 Specification (Rasterization) |
| |
| None. |
| |
| Additions to Chapter 4 of the OpenGL 1.4 Specification (Per-Fragment |
| Operations and the Frame Buffer) |
| |
| Add a new section "Occlusion Queries" between sections 4.1.6 and |
| 4.1.7: |
| |
| "4.1.6A Occlusion Queries |
| |
| Occlusion queries can be used to track the number of fragments or |
| samples that pass the depth test. |
| |
| Occlusion queries are associated with query objects. The command |
| |
| void GenQueriesARB(sizei n, uint *ids); |
| |
| returns <n> previously unused query object names in <ids>. These |
| names are marked as used, but no object is associated with them until |
| the first time they are used by BeginQueryARB. Query objects contain |
| one piece of state, an integer result value. This result value is |
| initialized to zero when the object is created. Any positive integer |
| except for zero (which is reserved for the GL) is a valid query |
| object name. |
| |
| Query objects are deleted by calling |
| |
| void DeleteQueriesARB(sizei n, const uint *ids); |
| |
| <ids> contains <n> names of query objects to be deleted. After a |
| query object is deleted, its name is again unused. Unused names in |
| <ids> are silently ignored. |
| |
| An occlusion query can be started and finished by calling |
| |
| void BeginQueryARB(enum target, uint id); |
| void EndQueryARB(enum target); |
| |
| where <target> is SAMPLES_PASSED_ARB. If BeginQueryARB is called |
| with an unused <id>, that name is marked as used and associated with |
| a new query object. If BeginQueryARB is called while another query |
| is already in progress with the same target, an INVALID_OPERATION |
| error is generated. If EndQueryARB is called while no query with the |
| same target is in progress, an INVALID_OPERATION error is generated. |
| Calling either GenQueriesARB or DeleteQueriesARB while any query of |
| any target is active causes an INVALID_OPERATION error to be |
| generated. |
| |
| BeginQueryARB with a <target> of SAMPLES_PASSED_ARB resets the |
| current samples-passed count to zero and sets the query active |
| state to TRUE and the active query id to <id>. EndQueryARB with |
| a target of SAMPLES_PASSED_ARB initializes a copy of the current |
| samples-passed count into the active occlusion query object's results |
| value, sets the active occlusion query object's result available to |
| FALSE, sets the query active state to FALSE, and the active query |
| id to 0. |
| |
| If BeginQueryARB is called with an <id> of zero, or where <id> is the |
| name of a query currently in progress, an INVALID_OPERATION error is |
| generated. |
| |
| When an occlusion query is active, the samples-passed count increases |
| by a certain quantity for each fragment that passes the depth test. |
| If the value of SAMPLE_BUFFERS is 0, then the samples-passed count |
| increases by 1 for each fragment. If the value of SAMPLE_BUFFERS is |
| 1, then the samples-passed count increases by the number of samples |
| whose coverage bit is set. However, implementations, at their |
| discretion, are allowed to instead increase the samples-passed count |
| by the value of SAMPLES if any sample in the fragment is covered. |
| |
| If the samples-passed count overflows, i.e., exceeds the value 2^n-1 |
| (where n is the number of bits in the samples-passed count), its |
| value becomes undefined. It is recommended, but not required, that |
| implementations handle this overflow case by saturating at 2^n-1 and |
| incrementing no further. |
| |
| The necessary state is a single bit indicating whether an occlusion |
| query is active, the identifier of the currently active occlusion |
| query, and a counter keeping track of the number of samples that |
| have passed." |
| |
| Additions to Chapter 5 of the OpenGL 1.4 Specification (Special Functions) |
| |
| Add to the end of Section 5.4 "Display Lists": |
| |
| "DeleteQueriesARB, GenQueriesARB, IsQueryARB, GetQueryivARB, |
| GetQueryObjectivARB, and GetQueryObjectuivARB are not compiled into |
| display lists but are executed immediately." |
| |
| Additions to Chapter 6 of the OpenGL 1.4 Specification (State and |
| State Requests) |
| |
| Add a new section 6.1.13 "Occlusion Queries": |
| |
| "The command |
| |
| boolean IsQueryARB(uint id); |
| |
| returns TRUE if <id> is the name of a query object. If <id> is zero, |
| or if <id> is a non-zero value that is not the name of a query |
| object, IsQueryARB returns FALSE. |
| |
| Information about a query target can be queried with the command |
| |
| void GetQueryivARB(enum target, enum pname, int *params); |
| |
| If <pname> is CURRENT_QUERY_ARB, the name of the currently active |
| query for <target>, or zero if no query is active, will be placed in |
| <params>. |
| |
| If <pname> is QUERY_COUNTER_BITS_ARB, the number of bits in the counter for |
| <target> will be placed in <params>. The minimum number of query counter |
| bits allowed is a function of the implementation's maximum viewport |
| dimensions (MAX_VIEWPORT_DIMS). If the counter is non-zero, then the |
| counter must be able to represent at least two overdraws for every pixel |
| in the viewport using only one sample buffer. The formula to compute the |
| allowable minimum value is below (where n is the minimum number of bits): |
| |
| n = (min (32, ceil (log2 (maxViewportWidth x maxViewportHeight x 2) ) ) ) or |
| 0 |
| |
| If the value of n is 0, then the result from GetQueryiv(SAMPLES_PASSED_ARB) |
| will always return 0, |
| |
| The state of a query object can be queried with the commands |
| |
| void GetQueryObjectivARB(uint id, enum pname, int *params); |
| void GetQueryObjectuivARB(uint id, enum pname, uint *params); |
| |
| If <id> is not the name of a query object, or if the query object |
| named by <id> is currently active, then an INVALID_OPERATION error is |
| generated. |
| |
| If <pname> is QUERY_RESULT_ARB, then the query object's result value |
| is placed in <params>. |
| |
| Often, query object results will be returned asynchronously with |
| respect to the host processor's operation. As a result, sometimes, |
| if a result is queried, the host must wait until the result is back. |
| If <pname> is QUERY_RESULT_AVAILABLE_ARB, the value placed in |
| <params> indicates whether or not such a wait would occur if the |
| result of that query object were to be queried presently. A result |
| of TRUE means no wait would be required; a result of FALSE means that |
| some wait would occur. It must always be true that if the result for one |
| query is available, the result for all previous queries must also be |
| available at that point in time. |
| |
| Querying the state for a given occlusion query forces that occlusion |
| query to complete within a finite amount of time. |
| |
| If multiple queries are issued on the same target and id prior to |
| calling GetQueryObject[u]iVARB, the result returned will always be |
| from the last query issued. The results from any queries before the |
| last one will be lost if the results are not retrieved before starting |
| a new query on the same target and id." |
| |
| Dependencies on HP_occlusion_test |
| |
| When GetIntegerv is called with <pname> of OCCLUSION_TEST_RESULT_HP, |
| the current samples-passed count is reset to zero. The occlusion |
| test result is TRUE when the samples-passed count is nonzero, and |
| FALSE when it is zero. Sample counting is active (i.e. the samples- |
| passed count increases as fragments are drawn) whenever either an |
| occlusion query is active *or* OCCLUSION_TEST_HP is enabled. |
| |
| GLX Protocol |
| |
| Seven new GL commands are added. |
| |
| The following two rendering commands are sent to the server as part |
| of a glXRender request: |
| |
| BeginQueryARB |
| 2 12 rendering command length |
| 2 231 rendering command opcode |
| 4 ENUM target |
| 4 CARD32 id |
| |
| EndQueryARB |
| 2 8 rendering command length |
| 2 232 rendering command opcode |
| 4 ENUM target |
| |
| The remaining fivecommands are non-rendering commands. These |
| commands are sent separately (i.e., not as part of a glXRender or |
| glXRenderLarge request), using glx single requests: |
| |
| DeleteQueriesARB |
| 1 CARD8 opcode (X assigned) |
| 1 161 GLX opcode |
| 2 3+n request length |
| 4 GLX_CONTEXT_TAG context tag |
| 4 INT32 n |
| n*4 LISTofCARD32 ids |
| |
| GenQueriesARB |
| 1 CARD8 opcode (X assigned) |
| 1 162 GLX opcode |
| 2 3 request length |
| 4 GLX_CONTEXT_TAG context tag |
| 4 INT32 n |
| => |
| 1 1 reply |
| 1 unused |
| 2 CARD16 sequence number |
| 4 n reply length |
| 24 unused |
| n*4 LISTofCARD32 queries |
| |
| IsQueryARB |
| 1 CARD8 opcode (X assigned) |
| 1 163 GLX opcode |
| 2 3 request length |
| 4 GLX_CONTEXT_TAG context tag |
| 4 CARD32 id |
| => |
| 1 1 reply |
| 1 unused |
| 2 CARD16 sequence number |
| 4 0 reply length |
| 4 BOOL32 return value |
| 20 unused |
| |
| GetQueryivARB |
| 1 CARD8 opcode (X assigned) |
| 1 164 GLX opcode |
| 2 4 request length |
| 4 GLX_CONTEXT_TAG context tag |
| 4 ENUM target |
| 4 ENUM pname |
| => |
| 1 1 reply |
| 1 unused |
| 2 CARD16 sequence number |
| 4 m reply length, m=(n==1?0:n) |
| 4 unused |
| 4 CARD32 n |
| |
| if (n=1) this follows: |
| |
| 4 INT32 params |
| 12 unused |
| |
| otherwise this follows: |
| |
| 16 unused |
| n*4 LISTofINT32 params |
| |
| GetQueryObjectivARB |
| 1 CARD8 opcode (X assigned) |
| 1 165 GLX opcode |
| 2 4 request length |
| 4 GLX_CONTEXT_TAG context tag |
| 4 CARD32 id |
| 4 ENUM pname |
| => |
| 1 1 reply |
| 1 unused |
| 2 CARD16 sequence number |
| 4 m reply length, m=(n==1?0:n) |
| 4 unused |
| 4 CARD32 n |
| |
| if (n=1) this follows: |
| |
| 4 INT32 params |
| 12 unused |
| |
| otherwise this follows: |
| |
| 16 unused |
| n*4 LISTofINT32 params |
| |
| GetQueryObjectuivARB |
| 1 CARD8 opcode (X assigned) |
| 1 166 GLX opcode |
| 2 4 request length |
| 4 GLX_CONTEXT_TAG context tag |
| 4 CARD32 id |
| 4 ENUM pname |
| => |
| 1 1 reply |
| 1 unused |
| 2 CARD16 sequence number |
| 4 m reply length, m=(n==1?0:n) |
| 4 unused |
| 4 CARD32 n |
| |
| if (n=1) this follows: |
| |
| 4 CARD32 params |
| 12 unused |
| |
| otherwise this follows: |
| |
| 16 unused |
| n*4 LISTofCARD32 params |
| |
| Errors |
| |
| The error INVALID_VALUE is generated if GenQueriesARB is called where |
| <n> is negative. |
| |
| The error INVALID_VALUE is generated if DeleteQueriesARB is called |
| where <n> is negative. |
| |
| The error INVALID_OPERATION is generated if GenQueriesARB or |
| DeleteQueriesARB is called when a query of any target is active. |
| |
| The error INVALID_ENUM is generated if BeginQueryARB, EndQueryARB, or |
| GetQueryivARB is called where <target> is not SAMPLES_PASSED_ARB. |
| |
| The error INVALID_OPERATION is generated if BeginQueryARB is called |
| when a query of the given <target> is already active. |
| |
| The error INVALID_OPERATION is generated if EndQueryARB is called |
| when a query of the given <target> is not active. |
| |
| The error INVALID_OPERATION is generated if BeginQueryARB is called |
| where <id> is zero. |
| |
| The error INVALID_OPERATION is generated if BeginQueryARB is called |
| where <id> is is the name of a query currently in progress. |
| |
| The error INVALID_ENUM is generated if GetQueryivARB is called where |
| <pname> is not QUERY_COUNTER_BITS_ARB or CURRENT_QUERY_ARB. |
| |
| The error INVALID_OPERATION is generated if GetQueryObjectivARB or |
| GetQueryObjectuivARB is called where <id> is not the name of a query |
| object. |
| |
| The error INVALID_OPERATION is generated if GetQueryObjectivARB or |
| GetQueryObjectuivARB is called where <id> is the name of a currently |
| active query object. |
| |
| The error INVALID_ENUM is generated if GetQueryObjectivARB or |
| GetQueryObjectuivARB is called where <pname> is not QUERY_RESULT_ARB |
| or QUERY_RESULT_AVAILABLE_ARB. |
| |
| The error INVALID_OPERATION is generated if any of the commands |
| defined in this extension is executed between the execution of Begin |
| and the corresponding execution of End. |
| |
| New State |
| |
| (table 6.18, p. 233) |
| |
| Get Value Type Get Command Initial Value Description Sec Attribute |
| --------- ---- ----------- ------------- ----------- ------ --------- |
| - B - FALSE query active 4.1.6A - |
| CURRENT_QUERY_ARB Z+ GetQueryiv 0 active query ID 4.1.6A - |
| QUERY_RESULT_ARB Z+ GetQueryObjectuivARB 0 samples-passed count 4.1.6A - |
| QUERY_RESULT_AVAILABLE_ARB B GetQueryObjectivARB FALSE query result available 4.1.6A - |
| |
| New Implementation Dependent State |
| |
| (table 6.29, p. 224) Add the following entry: |
| |
| Get Value Type Get Command Minimum Value Description Sec Attribute |
| -------------------------- ---- ----------- ------------- ---------------- ------ -------------- |
| QUERY_COUNTER_BITS_ARB Z+ GetQueryiv see 6.1.13 Number of bits in 6.1.13 - |
| query counter |
| |
| Revision History |
| |
| Date: 4/21/2007 |
| Revision: 7 (Jon Leech) |
| - Added QUERY_RESULT_ARB and QUERY_RESULT_AVAILABLE to state table |
| 6.18 (also fixed in OpenGL 2.1 spec). |
| |
| Date: 11/4/2006 |
| Revision: 6 (Benj Lipchak, AMD) |
| - Updated contact info after ATI/AMD merger. |
| |
| Date: 10/27/2004 |
| Revision: 5? (James Jones, NVIDIA) |
| - Added GLX protocol. |
| |
| Usage Examples |
| |
| Here is some rough sample code that illustrates how this extension |
| can be used. |
| |
| GLuint queries[N]; |
| GLuint sampleCount; |
| GLint available; |
| GLuint bitsSupported; |
| |
| // check to make sure functionality is supported |
| glGetQueryiv(GL_QUERY_COUNTER_BITS_ARB, &bitsSupported); |
| if (bitsSupported == 0) { |
| // render scene without using occlusion queries |
| } |
| |
| glGenQueriesARB(N, queries); |
| ... |
| // before this point, render major occluders |
| glColorMask(GL_FALSE, GL_FALSE, GL_FALSE, GL_FALSE); |
| glDepthMask(GL_FALSE); |
| // also disable texturing and any fancy shaders |
| for (i = 0; i < N; i++) { |
| glBeginQueryARB(GL_SAMPLES_PASSED_ARB, queries[i]); |
| // render bounding box for object i |
| glEndQueryARB(GL_SAMPLES_PASSED_ARB); |
| } |
| |
| glFlush(); |
| |
| // Do other work until "most" of the queries are back, to avoid |
| // wasting time spinning |
| i = N*3/4; // instead of N-1, to prevent the GPU from going idle |
| do { |
| DoSomeStuff(); |
| glGetQueryObjectivARB(queries[i], |
| GL_QUERY_RESULT_AVAILABLE_ARB, |
| &available); |
| } while (!available); |
| |
| glColorMask(GL_TRUE, GL_TRUE, GL_TRUE, GL_TRUE); |
| glDepthMask(GL_TRUE); |
| // reenable other state, such as texturing |
| for (i = 0; i < N; i++) { |
| glGetQueryObjectuivARB(queries[i], GL_QUERY_RESULT_ARB, |
| &sampleCount); |
| if (sampleCount > 0) { |
| // render object i |
| } |
| } |
| |
| Here is some rough sample code for a simple multipass rendering |
| application that does not use occlusion queries. |
| |
| for (i = 0; i < N; i++) { |
| // First rendering pass |
| glDisable(GL_BLEND); |
| glDepthFunc(GL_LESS); |
| glDepthMask(GL_TRUE); |
| // configure shader 0 |
| // render object i |
| |
| // Second rendering pass |
| glEnable(GL_BLEND); |
| glBlendFunc(...); |
| glDepthFunc(GL_EQUAL); |
| glDepthMask(GL_FALSE); |
| // configure shader 1 |
| // render object i |
| } |
| |
| Here is the previous example, enhanced using occlusion queries. |
| |
| GLuint queries[N]; |
| GLuint sampleCount; |
| |
| glGenQueriesARB(N, queries); |
| ... |
| // First rendering pass plus almost-free visibility checks |
| glDisable(GL_BLEND); |
| glDepthFunc(GL_LESS); |
| glDepthMask(GL_TRUE); |
| // configure shader 0 |
| for (i = 0; i < N; i++) { |
| glBeginQueryARB(GL_SAMPLES_PASSED_ARB, queries[i]); |
| // render object i |
| glEndQueryARB(GL_SAMPLES_PASSED_ARB); |
| } |
| |
| // Second pass only on objects that were visible |
| glEnable(GL_BLEND); |
| glBlendFunc(...); |
| glDepthFunc(GL_EQUAL); |
| glDepthMask(GL_FALSE); |
| // configure shader 1 |
| for (i = 0; i < N; i++) { |
| glGetQueryObjectuivARB(queries[i], GL_QUERY_RESULT_ARB, |
| &sampleCount); |
| if (sampleCount > 0) { |
| // render object i |
| } |
| } |
