NtGdiDdQueryDirectDrawObject function

Article
02/15/2023

[This function is subject to change with each operating system revision. Instead, use the DirectDraw and Microsoft Direct3DAPIs; these APIs insulate applications from such operating system changes, and hide many other difficulties involved in interacting directly with display drivers.]

Queries a previously created kernel-mode representation of a Microsoft DirectDraw object for its capabilities.

Syntax

BOOL APIENTRY NtGdiDdQueryDirectDrawObject(
  _In_  HANDLE                      hDirectDrawLocal,
  _Out_ DD_HALINFO                  *pHalInfo,
        DWORD                       *pCallBackFlags,
  _Out_ LPD3DNTHAL_CALLBACKS        puD3dCallbacks,
  _Out_ LPD3DNTHAL_GLOBALDRIVERDATA puD3dDriverData,
  _Out_ PDD_D3DBUFCALLBACKS         puD3dBufferCallbacks,
  _Out_ LPDDSURFACEDESC             puD3dTextureFormats,
  _Out_ DWORD                       *puNumHeaps,
  _Out_ VIDEOMEMORY                 *puvmList,
  _Out_ DWORD                       *puNumFourCC,
  _Out_ DWORD                       *puFourCC
);

Parameters

hDirectDrawLocal [in]: Handle to the previously-created kernel-mode DirectDraw device.
pHalInfo [out]: Pointer to a DD_HALINFO structure that will be filled with the device's capabilities. See DDK documentation for details.
pCallBackFlags: Pointer to a caller-provided buffer that stores driver-reported callback flags. The buffer should be of size 3*sizeof(DWORD) and stores callback flags in the following order: pCallBackFlags[0] for flags in DD_CALLBACKS, pCallBackFlags[1] for flags in DD_SURFACECALLBACKS, and pCallBackFlags[2] for flags in DD_PALETTECALLBACKS. See DDK documentation for details.
puD3dCallbacks [out]: Pointer to a table of Direct3D callback pointers. The table is filled with pointers to functions within Gdi32.dll that imitate a Direct3D display driver. This callback table is identical to the D3DHAL_D3DCALLBACKS structure discussed in the DDK documentation.
puD3dDriverData [out]: Pointer to D3DHAL_GLOBALDRIVERDATA data, as described in the DDK documentation.
puD3dBufferCallbacks [out]: Pointer to a table of callback pointers. The table is filled with pointers to functions within Gdi32.dll that imitate a Direct3D display driver. This callback table is identical to the DDHAL_DDEXEBUFCALLBACKS structure, which maps to the DD_D3DBUFCALLBACKS structure discussed in the DDK documentation, except that members XxxD3DBuffer in DD_D3DBUFCALLBACKS are replaced with XxxExecuteBuffer in DDHAL_DDEXEBUFCALLBACKS.
puD3dTextureFormats [out]: Pointer to an array of DDSURFACEDESC structures that define the set of permissible texture formats.
puNumHeaps [out]: Pointer to the dwNumHeaps member of DD_HALINFO.vmiData. The dwNumHeaps member specifies the number of memory heaps in puvmList. See DDK documentation for details.
puvmList [out]: Pointer to a list of video memory heap descriptors. Can be NULL. This parameter is not used because video memory management is handled entirely within kernel mode.
puNumFourCC [out]: Pointer to the puNumFourCCCodes member of DD_HALINFO.ddCaps. The puNumFourCCCodes member specifies the number of Four-Character Codes (FOURCC) codes that the driver supports. See DDK documentation for details.
puFourCC [out]: Pointer to a list of supported Four-Character Codes (FOURCC) surface formats. Can be NULL.

Return value

If successful, this function returns TRUE; otherwise it returns FALSE.

Remarks

A call to this function is designed to be made in a two-step process. In the first step, puFourCC, puvmList and puD3dTextureFormats should be NULL, and DdQueryDirectDrawObject will fill in DD_HALINFO.ddCaps.dwNumFourCCCodes, DD_HALINFO.vmiData.dwNumHeaps, and D3DHAL_GLOBALDRIVERDATA.dwNumTextureFormats with the number of entries that are to be returned. In the second call, the caller should allocate arrays of the indicated size and pass those pointers instead of NULL values in the puFourCC, puvmList and puD3dTextureFormats parameters. The arrays will then be populated with appropriate data.

Applications are advised to use the DirectDraw and Direct3D APIs to create and manage graphics device objects. These constructs abstract the device creation process in a simplified and operating-system-independent way.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Header	Ntgdi.h