Platform SDK: DirectX

Setting and Retrieving Gamma Ramp Levels

[C++]

Gamma ramp levels are effectively look-up tables that DirectDraw uses to map the frame buffer color components to new levels that will be displayed. For more information, see About Gamma Ramp Levels. You set and retrieve ramp levels for the primary surface by calling the IDirectDrawGammaControl::SetGammaRamp and IDirectDrawGammaControl::GetGammaRamp methods. Both methods accept two parameters, but the first parameter is reserved for future use, and should be set to zero. The second parameter, lpRampData, is the address of a DDGAMMARAMP structure. The DDGAMMARAMP structure contains three 256-element arrays of WORDs, one array each to contain the red, green, and blue gamma ramps.

You can include the DDSGR_CALIBRATE value when calling the IDirectDrawGammaControl::SetGammaRamp to invoke the calibrator when setting new gamma levels. Calibrating gamma ramps incurs some processing overhead, and should not be used frequently. Setting a calibrated gamma ramp will provide a consistent and absolute gamma value for the viewer, regardless of the display adapter and monitor.

Not all systems support gamma calibration. To determine if gamma calibration is supported, call IDirectDraw7::GetCaps, and examine the dwCaps2 member of the associated DDCAPS structure after the method returns. If the DDCAPS2_CANCALIBRATEGAMMA capability flag is present, then gamma calibration is supported.

When setting new ramp levels, keep in mind that that the levels you set in the arrays are only used when your application is in full-screen, exclusive mode. Whenever your application changes to normal mode, the ramp levels are set aside, taking effect again when the application reinstates full-screen mode. In addition, remember that you cannot set ramp levels for any surface other than the primary.

Note  Those very familiar with the Win32® API might wonder why DirectDraw exposes an interface like IDirectDrawGammaControl, when Win32 offers the GetDeviceGammaRamp and SetDeviceGammaRamp functions for the same surfaces. Although the Win32 API includes these functions, they do not always succeed on all Windows platforms like the methods of the IDirectDrawGammaControl interface.

[Visual Basic]

Gamma ramp levels are effectively look-up tables that DirectDraw uses to map the frame buffer color components to new levels that will be displayed. For more information, see About Gamma Ramp Levels. You set and retrieve ramp levels for the primary surface by calling the DirectDrawGammaControl.SetGammaRamp and DirectDrawGammaControl.GetGammaRamp methods. Both methods accept two parameters, the first parameter is used to specify calibration. The second parameter, gammaRamp, is a DDGAMMARAMP type. The DDGAMMARAMP type contains three 256-element arrays of Integers, one array each to contain the red, green, and blue gamma ramps.

You can include the DDSGR_CALIBRATE value in the flags parameter when calling the DirectDrawGammaControl.SetGammaRamp to invoke the calibrator when setting new gamma levels. Calibrating gamma ramps incurs some processing overhead, and should not be used frequently. Setting a calibrated gamma ramp will provide a consistent and absolute gamma value for the viewer, regardless of the display adapter and monitor.

Not all systems support gamma calibration. To determine if gamma calibration is supported, call DirectDraw7.GetCaps, and examine the lCaps2 member of the associated DDCAPS type after the method returns. If the DDCAPS2_CANCALIBRATEGAMMA capability flag is present, then gamma calibration is supported.

When setting new ramp levels, keep in mind that that the levels you set in the arrays are only used when your application is in full-screen, exclusive mode. Whenever your application changes to normal mode, the ramp levels are set aside, taking effect again when the application reinstates full-screen mode. In addition, remember that you cannot set ramp levels for any surface other than the primary.

Note  Those very familiar with the Win32® API might wonder why DirectDraw creates an object like DirectDrawGammaControl, when Win32 offers the GetDeviceGammaRamp and SetDeviceGammaRamp functions for the same surfaces. Although the Win32 API includes these functions, they do not always succeed on all Windows platforms like the methods of the DirectDrawGammaControl object.