| ?/TD> |
| Microsoft DirectX 9.0 |
There are number of interesting queries on a driver that an application can make if there is no performance cost. In Microsoft?DirectX?7.0 and DirectX 8.x, a synchronous query mechanism, GetInfo, worked well for things like statistics, but no performance-critical queries were added. There are other things (like fences) that are inherently asynchronous. This is a simple application programming interface (API) to make both synchronous and asynchronous queries. GetInfo will be retired in DirectX 9.0.
Create a query using IDirect3DDevice9::CreateQuery. This method takes a D3DQUERYTYPE, which defines what kind of query to make and returns a pointer to an IDirect3DQuery9 object. If the query type is not supported, the call returns an error D3DERR_NOTAVAILABLE. Using the query object, the application submits the query to the runtime using IDirect3DQuery9::Issue, and polls the query status using IDirect3DQuery9::GetData. If the query result is available, S_OK is returned; otherwise, S_FALSE is returned. The application is expected to pass an appropriately sized buffer for the query results.
The application has an option to force the runtime to flush the query down to the driver by using D3DGETDATA_FLUSH with IDirect3DQuery9::GetData. It causes a flush, forcing the driver to see the query. In this case, D3DERR_DEVICELOST is returned if the device becomes lost.
All queries are lost when the device is lost, the application has to re-create them. If the device does not support the query and the pQueryID is NULL, the query creation will fail with D3DERR_INVALIDCALL.
The following table summaries important information about each query type.
| QuertyType | Valid issue flag | GetData buffer | Runtime | Implicit beginning of query |
|---|---|---|---|---|
| D3DQUERYTYPE_VCACHE | D3DISSUE_END | D3DDEVINFO_VCACHE | Retail/Debug | CreateDevice |
| D3DQUERYTYPE_RESOURCEMANAGER | D3DISSUE_END | D3DDEVINFO_RESOURCEMANAGER | Debug only | Present |
| D3DQUERYTYPE_VERTEXSTATS | D3DISSUE_END | D3DDEVINFO_D3DVERTEXSTATS | Debug only | Present |
| D3DQUERYTYPE_EVENT | D3DISSUE_END | BOOL | Retail/Debug | CreateDevice |
| D3DQUERYTYPE_OCCLUSION | D3DISSUE_BEGIN,D3DISSUE_END | DWORD | Retail/Debug | N/A |
Flags field for IDirect3DQuery9::Issue:
#define D3DISSUE_END (1 << 0) // Tells the runtime to issue the end of a query, changing its state to // "non-signaled"
#define D3DISSUE_BEGIN (1 << 1) // Tells the runtime to issue the // beginng of a query.
Flags field for IDirect3DQuery9::GetData:
#define D3DGETDATA_FLUSH (1 << 0) // Tells the runtime to flush // if the query is outstanding.