IDirect3DSurface9::GetDC Method

Retrieves a device context.

Syntax

HRESULT GetDC(      

    HDC* phdc
);

Parameters

phdc

[out] Pointer to the device context for the surface.

Return Value

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 Microsoft?Windows?Graphics Device Interface (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 handle to a device context (HDC) provides access to Microsoft Win32?and GDI functionality.

See Also

IDirect3DSurface9::ReleaseDC, D3DUSAGE, D3DPOOL, D3DPRESENT_PARAMETERS