IDirect3DQuery9::GetData

Polls a queried resource to get the query state or a query result. For more information about queries, see Queries.

HRESULT GetData(
  void* pData,
  DWORD dwSize,
  DWORD dwGetDataFlags
);

Parameters

pData

[in, out] Pointer to a buffer containing the query data. The user is responsible for allocating this. pData may be NULL only if dwSize is 0.

dwSize

[in] Number of bytes of data in pData. If you set dwSize to zero, you can use this method to poll the resource for the query status. See remarks.

dwGetDataFlags

[in] Data flags specifying the query type. Valid values are either 0 or D3DGETDATA_FLUSH. Use 0 to avoid flushing batched queries to the driver and use D3DGETDATA_FLUSH to go ahead and flush them. For applications writing their own version of waiting, a query result is not realized until the driver receives a flush.

Return Values

The return type identifies the query state (see Queries). The method returns S_OK if the query data is available and S_FALSE if it is not. These are considered successful return values. If the method fails when D3DGETDATA_FLUSH is used, the return value can be D3DERR_DEVICELOST.

Remarks

It is possible to lose the device while polling for query status. When D3DGETDATA_FLUSH is specified, this method will return D3DERR_DEVICELOST in response to a lost device. This allows an application to prevent threads from endlessly polling due to a lost device (which cannot respond to the query).

An application must never write code that only invokes GetData ( ... , 0 ), expecting that GetData will eventually return S_OK by itself over time. This is true, even if the application has used the FLUSH flag with GetData in the past. For example:

// Enables an infinite loop:
while( pQuery->GetData( ... , 0 ) == S_FALSE ) ;

// Still enables an infinite loop:
pQuery->GetData( ... , D3DGETDATA_FLUSH );
while( pQuery->GetData( ... , 0 ) == S_FALSE ) ;

// Does not enable an infinate loop because eventually the command
// buffer will fill up and that will cause a flush to occur.
while( pQuery->GetData( ..., 0 ) == S_FALSE ) {
	pDevice->SetTexture(...);
	pDevice->Draw(...);
}

Requirements

Header: Declared in D3d9.h.