Legacy Document

Inside Macintosh: Imaging With QuickDraw /

Chapter 5 - Graphics Devices / Graphics Devices Reference

Routines for Graphics Devices / Creating, Setting, and Disposing of GDevice Records

NewGDevice

You can use the NewGDevice function to create a new GDevice record, although you generally don't need to, because Color QuickDraw uses this function to create GDevice records for your application automatically.

FUNCTION NewGDevice (refNum: Integer; mode: LongInt): GDHandle;

refNum

Reference number of the graphics device for which you are creating a GDevice record. For most video devices, this information is set at system startup.

mode

The device configuration mode. Used by the screen driver, this value sets the pixel depth and specifies color or black and white.

DESCRIPTION

For the graphics device whose driver is specified in the refNum parameter and whose mode is specified in the mode parameter, the NewGDevice function allocates a new GDevice record and all of its handles, and then calls the InitGDevice procedure to initialize the record. As its function result, NewGDevice returns a handle to the new GDevice record. If the request is unsuccessful, NewGDevice returns NIL.

The NewGDevice function allocates the new GDevice record and all of its handles in the system heap, and the NewGDevice function sets all attributes in the gdFlags field of the GDevice record to FALSE. If your application creates a GDevice record, it can use the SetDeviceAttribute procedure, described on page 5-21, to change the flag bits in the gdFlags field of the GDevice record to TRUE. Your application should never directly change the gdFlags field of the GDevice record; instead, your application should use only the SetDeviceAttribute procedure.

If your application creates a GDevice record without a driver, it should set the mode parameter to -1. In this case, InitGDevice cannot initialize the GDevice record, so your application must perform all initialization of the record. A GDevice record's default mode is defined as 128; this is assumed to be a black-and-white mode. If you specify a value other than 128 in the mode parameter, the record's gdDevType bit in the gdFlags field of the GDevice record is set to TRUE to indicate that the graphics device is capable of displaying color.

The NewGDevice function doesn't automatically insert the GDevice record into the device list. In general, your application shouldn't create GDevice records, and if it ever does, it should never add them to the device list.

SPECIAL CONSIDERATIONS

If your program uses NewGDevice to create a graphics device without a driver, InitGDevice does nothing; instead, your application must initialize all fields of the GDevice record. After your application initializes the color table for the GDevice record, your application should call the Color Manager procedure MakeITable to build the inverse table for the graphics device.

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

SEE ALSO

The GDevice record is described on page 5-14. See Designing Cards and Drivers for the Macintosh Family, third edition, for more information about the device modes that you can specify in the mode parameter. The Color Manager is described in Advanced Color Imaging on the Mac OS.