SetDeviceGammaRamp function (wingdi.h)

  • Article

The SetDeviceGammaRamp function sets the gamma ramp on direct color display boards having drivers that support downloadable gamma ramps in hardware.

Important

We strongly recommend that you don't use this API. Use of this API is subject to major limitations:

  • SetDeviceGammaRamp implements heuristics to check whether a provided ramp will result in an unreadable screen. If a ramp violates those heuristics, then the function fails silently (that is, it returns TRUE, but it doesn't set your ramp). For that reason, you can't expect to use this function to set just any arbitrary gamma ramp. In particular, the heuristics prevent ramps that would result in nearly all pixels approaching a single value (such as fullscreen black/white) as this may prevent a user from recovering the screen.

  • Because of the function's global nature, any other application on the system could, at any time, overwrite any ramp that you've set. In some cases the operating system itself may reserve the use of this function, causing any existing ramp to be overwritten. The gamma ramp is also reset on most display events (connecting/disconnecting a monitor, resolution changes, etc.). So you can't be certain that any ramp you set is in effect.

  • This API has undefined behavior in HDR modes.

  • This API has undefined interaction with both built-in and third-party color calibration solutions.

For color calibration, we recommend that you create an International Color Consortium (ICC) profile, and let the OS apply the profile. For advanced original equipment manufacturer (OEM) scenarios, there's a device driver model that you can use to customize color calibration more directly. See the Windows Color System for information on managing color profiles.

For blue light filtering, Windows now provides built-in support called Night Light. We recommend directing users to this feature.

For color adaptation (for example, adjusting color calibration based on ambient light sensors), Windows now provides built-in support, which we recommend for use by OEMs.

For custom filter effects, there are a variety of built-in accessibility color filters to help with a range of cases.

Syntax

BOOL SetDeviceGammaRamp(
  HDC    hdc,
  LPVOID lpRamp
);

Parameters

hdc

Specifies the device context of the direct color display board in question.

lpRamp

Pointer to a buffer containing the gamma ramp to be set. The gamma ramp is specified in three arrays of 256 WORD elements each, which contain the mapping between RGB values in the frame buffer and digital-analog-converter (DAC ) values. The sequence of the arrays is red, green, blue. The RGB values must be stored in the most significant bits of each WORD to increase DAC independence.

Return value

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE.

Remarks

Direct color display modes do not use color lookup tables and are usually 16, 24, or 32 bit. Not all direct color video boards support loadable gamma ramps. SetDeviceGammaRamp succeeds only for devices with drivers that support downloadable gamma ramps in hardware.

Note

This API can take a non-trivial amount of time to execute. It may take as long as 200ms to return on some hardware.

Requirements

Requirement Value
Minimum supported client Windows 2000 Professional [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only]
Target Platform Windows
Header wingdi.h
Library Gdi32.lib
DLL Gdi32.dll

See also