IDirect3DSurface9::GetDC method (d3d9helper.h)

Article
02/22/2024

Retrieves a device context.

Syntax

HRESULT GetDC(
  [out] HDC *phdc
);

Parameters

[out] phdc

Type: HDC*

Pointer to the device context for the surface.

Return value

Type: HRESULT

If the method succeeds, the return value is D3D_OK. D3DERR_INVALIDCALL is returned if the argument is invalid.

Remarks

The following restrictions apply.

IDirect3DSurface9::GetDC is valid on the following formats only: D3DFMT_R5G6B5, D3DFMT_X1R5G5B5, D3DFMT_R8G8B8, and D3DFMT_X8R8G8B8. Formats that contain Alpha are not supported because the GDI implementations don't have a well-defined behavior on the alpha channel. For more information about formats, see D3DFORMAT.
Only one device context per surface can be returned at a time.
IDirect3DSurface9::GetDC will fail if the surface is already locked. If the surface is a member of a mipmap or cubemap, IDirect3DSurface9::GetDC fails if any other mipmap or cubemap member is locked.
IDirect3DSurface9::GetDC fails on render targets unless they were created lockable (or, in the case of back buffers, with the D3DPRESENTFLAG_LOCKABLE_BACKBUFFER flag).
For surfaces not created with IDirect3DDevice9::CreateOffscreenPlainSurface, IDirect3DSurface9::GetDC will fail on default pool (D3DPOOL_DEFAULT) surfaces unless they are dynamic (D3DUSAGE_DYNAMIC) or are lockable render targets.
IDirect3DSurface9::GetDC will fail on D3DPOOL_SCRATCH surfaces.

When a device context is outstanding on a surface, the application may not call these methods:

IDirect3DCubeTexture9	IDirect3DCubeTexture9::LockRect
IDirect3DDevice9	IDirect3DDevice9::ColorFill
	IDirect3DDevice9::StretchRect
	IDirect3DDevice9::UpdateSurface
	IDirect3DDevice9::UpdateTexture
IDirect3DSurface9	IDirect3DSurface9::LockRect
IDirect3DSwapChain9	IDirect3DSwapChain9::Present *
IDirect3DTexture9	IDirect3DTexture9::LockRect

(on a swap chain that contains the surface)

IDirect3DSurface9::GetDC causes an implicit lock; do not retain the device context for later use. Call IDirect3DSurface9::ReleaseDC to release it.

It is valid to call IDirect3DSurface9::GetDC/IDirect3DSurface9::ReleaseDC on levels of a mipmap or cubemap, however, these calls will be slow to all miplevels except the topmost level, and GDI operations to these miplevels will not be accelerated.

The hdc provides access to Win32 and GDI functionality.

Requirements

Requirement	Value
Target Platform	Windows
Header	d3d9helper.h (include D3D9.h)
Library	D3D9.lib