/*

    File:       MacGamma.h

    Contains:   Functions to enable Mac OS device gamma adjustments using 3 channel 256 element 8 bit gamma ramps

    Written by: Geoff Stahl (ggs)

    Copyright:  Copyright © 1999 Apple Computer, Inc., All Rights Reserved

    Change History (most recent first):

         <7>     8/25/99    ggs     Added usage notes

         <6>     8/25/99    ggs     Added usage notes

         <5>     7/14/99    ggs     Added sample code notice

         <4>     5/20/99    ggs     Updated function names.

         <3>     5/20/99    ggs     Cleaned up and commented

         <2>     5/20/99    ggs     Added system wide get and restore gamma functions to enable

                                    restoration of original for all devices.  Modified functionality

                                    to return pointers vice squirreling away the memory.

         <1>     5/20/99    ggs     Initial Add

    Disclaimer: You may incorporate this sample code into your applications without

                restriction, though the sample code has been provided "AS IS" and the

                responsibility for its operation is 100% yours.  However, what you are

                not permitted to do is to redistribute the source as "DSC Sample Code"

                after having made changes. If you're going to re-distribute the source,

                we require that you make it clear in the source that the code was

                descended from Apple Sample Code, but that you've made changes.

*/

// Usage notes: 

// SetDeviceGammaRampXX may not return until the VBL following their call, depending on the display driver,

// this is due to the handling of the Control call by the driver.

// Startup and Shutdown:

// GetSystemGammas (...) must be called to save the system gammas prior to using MacGamma

// RestoreSystemGamms (...)  must be called before exiting to restore original gamma

// DisposeSystemGammas (...) can then be used to dispose of the system gammas

// Suspend and Resume:

// RestoreSystemGamms (...); DisposeSystemGammas (...); should also be called prior to suspend and

// GetSystemGammas (...) should be called when resuming

// this prevents users from saving display settings with your gammas

// include control --------------------------------------------------

#ifndef MacGamma_h

#define MacGamma_h

// includes ---------------------------------------------------------

#include <Quickdraw.h>

#include <QDOffscreen.h>

// public function declarations -------------------------------------

// 5/20/99: (ggs) added system wide gamma get and restore

Ptr GetSystemGammas (void);                                     // returns a pointer to a set of all current device gammas in native format

                                                                    // (returns NULL on failure, which means reseting gamma will not be possible)

void RestoreSystemGammas (Ptr pSystemGammas);                   // restores all system devices to saved gamma setting

void DisposeSystemGammas (Ptr* ppSystemGammas);                 // iterates through and deletes stored gamma settings

Boolean GetDeviceGammaRampGD (GDHandle hGD, Ptr pRamp);         // retrieves the gamma ramp from a graphics device (pRamp: 3 arrays of 256 elements each)

Boolean GetDeviceGammaRampGW (GWorldPtr pGW, Ptr pRamp);        // retrieves the gamma ramp from a graphics device associated with a GWorld pointer (pRamp: 3 arrays of 256 elements each)

Boolean GetDeviceGammaRampCGP (CGrafPtr pGraf, Ptr pRamp);      // retrieves the gamma ramp from a graphics device associated with a CGraf pointer (pRamp: 3 arrays of 256 elements each)

Boolean SetDeviceGammaRampGD (GDHandle hGD, Ptr pRamp);         // sets the gamma ramp for a graphics device (pRamp: 3 arrays of 256 elements each (R,G,B))

Boolean SetDeviceGammaRampGW (GWorldPtr pGW, Ptr pRamp);        // sets the gamma ramp for a graphics device associated with a GWorld pointer (pRamp: 3 arrays of 256 elements each (R,G,B))

Boolean SetDeviceGammaRampCGP (CGrafPtr pGraf, Ptr pRamp);      // sets the gamma ramp for a graphics device associated with a CGraf pointer (pRamp: 3 arrays of 256 elements each (R,G,B))

#endif // MacGamma_h