Inside Macintosh: Apple Game Sprockets Guide /

Chapter 2 - DrawSprocket / DrawSprocket Reference

DrawSprocket Functions / Drawing and Double Buffering

DSpContext_FadeGamma

You can use the DSpContext_FadeGamma function to manually fade the specified context either in or out to a color of your choice.

OSStatus DSpContext_FadeGamma (
DSpContextReference inContext,
SInt32 inPercentOfOriginalIntensity,
RGBColor *inZeroIntensityColor);

inContext

A reference to the context whose display is to be faded. If you pass NULL for this parameter, the fade operation applies simultaneously to all displays.

inPercentOfOriginalIntensity

The amount of fading to apply, expressed as the resultant percentage (0-100) of the display's full intensity that you want to achieve with this call. Values above 100 percent begin to converge on white. If you have specified an intensity color, values less than zero begin to converge on black.

inZeroIntensityColor

A pointer to the color that is to correspond to zero intensity (represented by a value of 0 in the inPercentOfOriginalIntensity parameter). If you pass NULL for this parameter, the zero-intensity color is black.

function result

A result code.

DESCRIPTION

The DSpContext_FadeGamma function fades the context specified in the inContext parameter by the percentage specified in the inPercentOfOriginalIntensity parameter. Fading the context is an aesthetically pleasing way to transition into and out of your game and between different sections of it. When performing a resolution-mode switch (as when activating and deactivating your context's play state), it is important to fade the display to hide the flash that occurs.

DSpContext_FadeGamma performs a gamma fade, which gives better results than a simple indexed fade. See "Gamma Fading" (page 2-9) for more information on this and other advantages of DrawSprocket's support for fading.

Fading is normally an incremental process. Over a period of time, you make repeated, timed calls to DSpContext_FadeGamma, each time passing it an incrementally different value for the inPercentOfOriginalIntensity parameter, until the final desired intensity is achieved. The intensity value you pass is usually an integer between 0 and 100. It can be greater than 100, if you want to use fading to create a high-intensity burst of light, or less than 100 if you have specified a zero-intensity color and want to fade the color toward black.

The zero-intensity value that you fade out to is by default black, but it can be any color that you specify in the inZeroIntensityColor parameter. You can achieve special effects by fading partially toward one zero-intensity color and then completing the fade to a different one. At the point when you actually switch resolution modes, the zero-intensity color must be black and your display must be completely faded if there is to be no visible flash.

To automatically accomplish a smooth fade all the way from full intensity to zero intensity, or vice versa, in a single operation use the DSpContext_FadeGammaIn function (page 2-48) and the DSpContext_FadeGammaOut (page 2-47) function.

CALLING RESTRICTIONS

Do not call this function during an interrupt.