Legacy Document

Inside Macintosh: Imaging With QuickDraw /

Chapter 5 - Graphics Devices / Graphics Devices Reference

Routines for Graphics Devices / Changing the Pixel Depth for a Video Device

SetDepth

To change the pixel depth of a video device, use the SetDepth function.

FUNCTION SetDepth (aDevice: GDHandle; depth: Integer; 
                  whichFlags: Integer; flags: Integer): OSErr;

aDevice

A handle to the GDevice record of the video device whose pixel depth you wish to change.

depth

The mode ID returned by the HasDepth function (described in the previous section) indicating that the video device supports the desired pixel depth. Alternatively, you can pass the desired pixel depth directly in this parameter, although you should use the HasDepth function to ensure that the device supports this depth.

whichFlags

The gdDevType constant, which represents a bit in the gdFlags field of the GDevice record. (If this bit is set to 0 in the GDevice record, the video device is black and white; if the bit is set to 1, the device supports color.)

flags

The value 0 or 1. If you pass 0 in this parameter, the SetDepth function changes the video device to black and white; if you pass 1 in this parameter, SetDepth changes the video device to color.

DESCRIPTION

The SetDepth function sets the video device you specify in the aDevice parameter to the pixel depth you specify in the depth parameter, and it sets the device to either black and white or color as you specify in the flags parameter. You should use the HasDepth function to ensure that the video device supports the values you specify to SetDepth. The SetDepth returns zero if successful, or it returns a nonzero value if it cannot impose the desired depth and display mode on the requested device.

The SetDepth function does not change the 'scrn' resource; when the system is restarted, the original depth for this device is restored.

SPECIAL CONSIDERATIONS

Your application should use SetDepth only if your application can run on devices of a particular pixel depth and is unable to adapt to any other depth. Your application should display a dialog box that offers the user a choice between changing to that depth or canceling display of the image before your application uses SetDepth. Such a dialog box saves the user the trouble of going to the Monitors control panel before returning to your application.

The SetDepth function may move or purge blocks of memory in the application heap. Your application should not call this function at interrupt time.

SEE ALSO

See the chapter "Dialog Manager" in Inside Macintosh: Macintosh Toolbox Essentials for information about creating and using dialog boxes.