After Dark modules

Graphics Module Parameters

When a graphics module is called,. is passed three parameters. The first two are simple data types, but the third, "params", is a pointer to a data structure that holds useful information about the Macintosh that After Dark is running on. This includes information about monitors, Color QuickDraw, and any controls your module may have created. The structure "params" points to is defined as:
	GMParamBlock = record
		controlValues:  array[0..3] of integer;
		monitors:       MonitorsInfoPtr;
		colorQDAvail:   Boolean;
		systemConfig:   integer;
		qdGlobalsCopy:  QDGlobalsPtr;
		brightness:     integer;
		demoRect:       Rect;
		errorMessage:   StringPtr;
		sndChannel:     SndChannelPtr;
		adVersion:      integer;
	GMParamBlockPtr = ^GMParamBlock;
This array contains the current value of any slider, menu, text string, or check box control created by the graphics module (slider, menu, text strings, and check box controls are resources and are described later in "Control Resources"). Slider values can range from 0 to 100 and can be interpreted however the programmer wishes. Menu values range from 1 to the number of items in the menu with the value representing the item currently selected. Text strings values range from 0 to the number of strings defined. Check box values are either 0 or 1.

These values can be changed at any time by your module and will be reflected in the Control Panel. To avoid confusion on the user's part, do not change these values unless the user requests it (an exception are text strings which may need to be changed to provide new information to the user).

This field is a pointer to a structure that contains the number of monitors attached and an array of structures with information about the monitors. The structures are defined as:
	MonitorsInfo = record
		monitorCount:      integer;
		monitorList[0..0]: MonitorData;
	MonitorsInfoPtr = ^MonitorsInfo;
	MonitorData = packed record
		bounds:     Rect;
		synchFlag:  Boolean;
		curDepth:   Byte;
	MonitorData = ^MonitorsInfo;
In the MonitorsInfo structure, the "monitorCount" field is the number of monitors attached to the Macintosh. The "monitorList" field is an array of MonitorData structures which contains information about each monitor attached. The first monitor in the list is always the monitor with the menu bar (also called the "main" monitor).

In the MonitorData structure, the "bounds" field is the monitor's rectangle in global coordinates. The "synchFlag" field is used to help create smoother animation when drawing on the screen. The flag is set to true by After Dark when a vertical blanking ("VBL") interrupt occurs. Sufficiently rapid drawing begun immediately after this flag goes "true" should be flicker-free. For more information about VBL interrupts, see the Vertical Retrace Manager in Inside Macintosh Volume 2. The "curDepth" field is set to the pixel depth of the monitor.

If more information about a monitor is needed, the routines in Inside Macintosh can be used.

This field indicates whether or not Color QuickDraw is present on the Macintosh. This does not mean the Macintosh is running in color or has a color monitor. It only means the Color QuickDraw routines can be called. On a Macintosh SE/30 "colorQDAvail" is true.

This 16 bit value is a set of flags holding information about the configuration of the Macintosh. The flags are defined as:

Note: For more information about CLUT devices, see the Color Manager in Inside Macintosh Volume 5.

A bit is set to 1 if the corresponding statement is true. Bit 0 is the rightmost (least-significant) bit.

If a module requires more information about the Macintosh than "hasColorQD" and "systemConfig" provide, use the SysEnvirons() or Gestalt() routines documented in Inside Macintosh.

A code resource cannot directly access the QuickDraw global variables. Because they are quite useful, a read-only copy of them has been provided. The field "qdGlobalsCopy" is a pointer to the structure QDGlobals. This structure is defined as:
	QDGlobals = record 
		qdThePort:    GrafPtr; 
		qdWhite:      Pattern;
		qdBlack:      Pattern; 
		qdGray:       Pattern; 
		qdLtGray:     Pattern;
		qdDkGray:     Pattern; 
		qdArrow:      Cursor; 
		qdScreenBits: BitMap;
		qdRandSeed:   Longint; 
	QDGlobalsPtr = ^QDGlobals; 

If you are unfamiliar with any of these values or QuickDraw Globals in general, see Inside Macintosh Volume 1.

This field is used by a graphics module to tell After Dark to dim the monitors to a certain level. The values range from 0 (black) to 255 (normal). A module need only place a value in this field and After Dark will dim all of the monitors to the specified level. This only works if the "allCanDim" or "mainMonCanDim" bit in the systemConfig field is set.

When After Dark is in "Demo Mode", this field contains the global coordinates of the controls area. When After Dark is not in "Demo Mode" it contains an empty rectangle. This field is useful if a graphics module does something special when After Dark is in "Demo Mode."

If your module returns an error code to After Dark, a short message can be displayed explaining the problem. Before your module returns, copy a message into the Str255 string pointed at by 'errorMessage'. This can be done with the Macintosh routine BlockMove(). After Dark will display this message on the screen and will take over animation.

If a module wants to use sound, it needs a sound channel. By adding a resource of type 'Chnl' (described in the section "Sound Resources") to your module, After Dark will allocate a sound channel and place a pointer to it in the 'sndChannel' field. To add sound to your module, see the next section "Using Sound".

This field contains the version of After Dark in Binary Coded Decimal (BCD) format. For After Dark 2.0, this field contains the value 0x0200 hexadecimal, 512 decimal.

Begin | Introduction | Getting Started | main() | Advanced | Parameters | Sound | Resources | Hints & Tips | Further Info