NtGdiDdCreateSurfaceObject function

Article
01/06/2021

[This function is subject to change with each operating system revision. Instead, use the Microsoft 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.]

Creates a kernel-mode surface object that represents the user-mode surface object referenced by puSurfaceLocal.

Syntax

HANDLE APIENTRY NtGdiDdCreateSurfaceObject(
  _In_ HANDLE             hDirectDrawLocal,
  _In_ HANDLE             hSurface,
  _In_ PDD_SURFACE_LOCAL  puSurfaceLocal,
  _In_ PDD_SURFACE_MORE   puSurfaceMore,
  _In_ PDD_SURFACE_GLOBAL puSurfaceGlobal,
  _In_ BOOL               bComplete
);

Parameters

hDirectDrawLocal [in]: Handle to the kernel-mode DirectDraw object.
hSurface [in]: Previous handle to the same surface. Used if the surface is being re-created after a mode switch.
puSurfaceLocal [in]: Pointer to the DD_SURFACE_LOCAL structure that represents the DirectDraw user-mode surface object with which to associate the allocated memory. See the DDK documentation for details.
puSurfaceMore [in]: Pointer to the DD_SURFACE_MORE structure that contains additional local data for each individual surface object. See the DDK documentation for details.
puSurfaceGlobal [in]: Pointer to the DD_SURFACE_GLOBAL structure that contains surface data shared globally with multiple surfaces. See the DDK documentation for details.
bComplete [in]: Kernel-mode object completion flag. Can be one of the following values.
(TRUE): Complete all processing concerning the kernel-mode representation.
(FALSE): Create the object, but do not set up internal data such as the memory pointer. Objects created using FALSE can be attached using NtGdiDdAttachSurface and are completed by a call to NtGdiDdCreateSurface.

Return value

If successful, this function returns a handle to the kernel-mode surface representation; otherwise it returns NULL.

Remarks

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