Edit

Share via

EngCreatePalette function (winddi.h)

  • Article

The EngCreatePalette function sends a request to GDI to create an RGB palette.

Syntax

ENGAPI HPALETTE EngCreatePalette(
  [in] ULONG iMode,
  [in] ULONG cColors,
  [in] ULONG *pulColors,
  [in] FLONG flRed,
  [in] FLONG flGreen,
  [in] FLONG flBlue
);

Parameters

[in] iMode

Specifies how the palette will be defined. This parameter can be one of the following values:

Value Meaning
PAL_BITFIELDS The palette is defined by the flRed, flGreen, and flBlue parameters.
PAL_BGR The device accepts RGB colors directly, with B (blue) as the least significant byte.
PAL_CMYK The device accepts CMYK colors directly, with C (cyan) as the least significant byte.
PAL_INDEXED An array of RGB colors is provided with cColors and pulColors.
PAL_RGB The device accepts RGB colors directly, with R (red) as the least significant byte.

[in] cColors

If the iMode parameter is PAL_INDEXED, cColors specifies the number of colors provided in the array pointed to by pulColors. Otherwise, this parameter should be zero.

[in] pulColors

Pointer to the beginning of an array of ULONG values if iMode is PAL_INDEXED. The low-order 3 bytes of each ULONG define the RGB colors in the palette.

[in] flRed

If the iMode parameter is PAL_BITFIELDS, the flRed, flGreen and flBlue parameters are masks that show which bits correspond to red, green, and blue. Each mask must consist of contiguous bits and should not overlap other masks. All combinations of bitfields are supported by GDI.

[in] flGreen

If the iMode parameter is PAL_BITFIELDS, the flRed, flGreen and flBlue parameters are masks that show which bits correspond to red, green, and blue. Each mask must consist of contiguous bits and should not overlap other masks. All combinations of bitfields are supported by GDI.

[in] flBlue

If the iMode parameter is PAL_BITFIELDS, the flRed, flGreen and flBlue parameters are masks that show which bits correspond to red, green, and blue. Each mask must consist of contiguous bits and should not overlap other masks. All combinations of bitfields are supported by GDI.

Return value

The return value is a handle to the new palette if the function is successful. Otherwise, it is zero, and an error code is logged.

Remarks

The driver can associate the new palette with a device by returning a pointer to the palette in the DEVINFO structure.

A PAL_INDEXED palette associated with the device must have its first index entry set to black (red = 0, green = 0, blue = 0) and its last entry set to white (255, 255, 255). All other entries should be set so that entries whose indexes are one's complements of each other have colors that contrast greatly. For example, if entry 0x9 of a 16 entry palette is set to pure green (0,255,0), entry 0x6 (=~0x9) should be set to a color that contrasts well with green, such as dark purple (128,0,128). Setting entries in this way allows XOR raster operations to behave reasonably. You should delete the palette when you no longer need it by using EngDeletePalette.

Requirements

Requirement Value
Minimum supported client Available in Windows 2000 and later versions of the Windows operating systems.
Target Platform Universal
Header winddi.h (include Winddi.h)
Library Win32k.lib
DLL Win32k.sys

See also

DEVINFO

DrvSetPalette

EngDeletePalette