Platform SDK: DirectX

IDirectDrawSurface7::SetPalette

The IDirectDrawSurface7::SetPalette method attaches a palette object to (or detaches one from) a surface. The surface uses this palette for all subsequent operations. The palette change takes place immediately, without regard to refresh timing.

HRESULT SetPalette(
  LPDIRECTDRAWPALETTE lpDDPalette  
);

Parameters

lpDDPalette
Address of the IDirectDrawPalette interface for the palette object to be used with this surface. If NULL, the current palette is detached.

Return Values

If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDPIXELFORMAT
DDERR_INVALIDSURFACETYPE
DDERR_NOEXCLUSIVEMODE
DDERR_NOPALETTEATTACHED
DDERR_NOPALETTEHW
DDERR_NOT8BITCOLOR
DDERR_SURFACELOST
DDERR_UNSUPPORTED

Remarks

When setting a palette to a surface for the first time, this method increments the palette's reference count; subsequent calls do not affect the palette's reference count. If you pass NULL as the lpDDPalette parameter, the palette is removed from the surface, and the palette's reference count is decremented. If you do not delete the palette, the surface automatically releases its reference to the palette when the surface itself is released. According to COM rules, your application is responsible for releasing any references that it holds to the palette when the object is no longer needed.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 98.
  Header: Declared in ddraw.h.

See Also

IDirectDrawSurface7::GetPalette, IDirectDraw7::CreatePalette