Demonstration Program PreQuickDraw

// *******************************************************************************************
// PreQuickDraw.c                                                          CLASSIC EVENT MODEL
// *******************************************************************************************
// 
// This program opens a window in which is displayed some information retrieved from the
// GDevice structure for the main video device, from the graphics port's pixel map, and from
// the graphics port object using QuickDraw functions.  
//
// A Demonstration menu allows the user to set the monitor to various pixel depths and to 
// restore the original pixel depth.  Setting the monitor to a pixel depth of 8 (256 colours)
// or less causes the colours in the colour table to be displayed.
//
// The program utilises 'plst', 'MBAR', 'MENU', 'WIND', and 'STR#' resources, and a 'SIZE'
// resource with the acceptSuspendResumeEvents, canBackground, doesActivateOnFGSwitch, and 
// isHighLevelEventAware flags set.
//
// *******************************************************************************************

// .................................................................................. includes

#include <Carbon.h>

// ................................................................................... defines

#define rMenubar              128
#define rWindow               128
#define mAppleApplication     128
#define  iAbout               1
#define mFile                 129
#define  iQuit                12
#define mDemonstration        131
#define  iSetDepth8           1
#define  iSetDepth16          2
#define  iSetDepth32          3
#define  iRestoreStartDepth   5
#define rIndexedStrings       128
#define  sMonitorInadequate   1
#define  sMonitorAtThatDepth  2  
#define  sMonitorAtStartDepth 3 
#define  sRestoringMonitor    4
#define MAX_UINT32            0xFFFFFFFF

// .......................................................................... global variables

Boolean gDone;
SInt16  gStartupPixelDepth;

// ....................................................................... function prototypes

void    main                       (void);
void    doPreliminaries            (void);
OSErr   quitAppEventHandler        (AppleEvent *,AppleEvent *,SInt32);
void    doEvents                   (EventRecord *);
void    doDisplayInformation       (WindowRef);
Boolean doCheckMonitor             (void);
void    doSetMonitorPixelDepth     (SInt16);
void    doRestoreMonitorPixelDepth (void);
void    doMonitorAlert             (Str255);

// ************************************************************************************** main

void  main(void)
{
  MenuBarHandle menubarHdl;
  SInt32        response;
  MenuRef       menuRef;
  WindowRef     windowRef;
  SInt16        entries = 0;
  Str255        theString;
  EventRecord   EventStructure;

  // ........................................................................ do preliminaries

  doPreliminaries();
  
  // ............................................................... set up menu bar and menus
  
  menubarHdl = GetNewMBar(rMenubar);
  if(menubarHdl == NULL)
    ExitToShell();
  SetMenuBar(menubarHdl);
  DrawMenuBar();

  Gestalt(gestaltMenuMgrAttr,&response);
  if(response & gestaltMenuMgrAquaLayoutMask)
  {
    menuRef = GetMenuRef(mFile);
    if(menuRef != NULL)
    {
      DeleteMenuItem(menuRef,iQuit);
      DeleteMenuItem(menuRef,iQuit - 1);
      DisableMenuItem(menuRef,0);
    }
  }

  // ..................................... check if monitor can display at least 16-bit colour

  if(!doCheckMonitor())
  {
    GetIndString(theString,rIndexedStrings,sMonitorInadequate);
    doMonitorAlert(theString);
  }

  // ...................................... open windows, set font, show windows, move windows

  if(!(windowRef = GetNewCWindow(rWindow,NULL,(WindowRef)-1)))
    ExitToShell();

  SetPortWindowPort(windowRef);
  TextSize(10);

  // ......................................................................... enter eventLoop

  gDone = false;

  while(!gDone)
  {
    if(WaitNextEvent(everyEvent,&EventStructure,MAX_UINT32,NULL))
      doEvents(&EventStructure);
  }
}

// *************************************************************************** doPreliminaries

void  doPreliminaries(void)
{
  OSErr osError;

  MoreMasterPointers(32);
  InitCursor();
  FlushEvents(everyEvent,0);

  osError = AEInstallEventHandler(kCoreEventClass,kAEQuitApplication,
                            NewAEEventHandlerUPP((AEEventHandlerProcPtr) quitAppEventHandler),
                            0L,false);
  if(osError != noErr)
    ExitToShell();
}

// **************************************************************************** doQuitAppEvent

OSErr  quitAppEventHandler(AppleEvent *appEvent,AppleEvent *reply,SInt32 handlerRefcon)
{
  OSErr    osError;
  DescType returnedType;
  Size     actualSize;

  osError = AEGetAttributePtr(appEvent,keyMissedKeywordAttr,typeWildCard,&returnedType,NULL,0,
                              &actualSize);

  if(osError == errAEDescNotFound)
  {
    gDone = true;
    osError = noErr;
  } 
  else if(osError == noErr)
    osError = errAEParamMissed;

  return osError;
}

// ********************************************************************************** doEvents

void  doEvents(EventRecord *eventStrucPtr)
{
  SInt32         menuChoice;
  MenuID         menuID;
  MenuItemIndex  menuItem;
  WindowPartCode partCode;
  WindowRef      windowRef;
  Rect           portRect;
    
  switch(eventStrucPtr->what)
  {
    case kHighLevelEvent:
      AEProcessAppleEvent(eventStrucPtr);
      break;

    case keyDown:
      if((eventStrucPtr->modifiers & cmdKey) != 0)
      {
        menuChoice = MenuEvent(eventStrucPtr);
        menuID = HiWord(menuChoice);
        menuItem = LoWord(menuChoice);
        if(menuID == mFile && menuItem  == iQuit)
          gDone = true;
      }
      break;

    case mouseDown:
      if(partCode = FindWindow(eventStrucPtr->where,&windowRef))
      {
        switch(partCode)
        {
          case inMenuBar:
            menuChoice = MenuSelect(eventStrucPtr->where);
            menuID = HiWord(menuChoice);
            menuItem = LoWord(menuChoice);

            if(menuID == 0)
              return;

            switch(menuID)
            {
              case mAppleApplication:
                if(menuItem == iAbout)
                  SysBeep(10);
                break;

              case mFile:
                if(menuItem == iQuit)
                  gDone = true;
                break;
  
              case mDemonstration:
                if(menuItem == iSetDepth8)
                  doSetMonitorPixelDepth(8);
                else if(menuItem == iSetDepth16)
                  doSetMonitorPixelDepth(16);
                else if(menuItem == iSetDepth32)
                  doSetMonitorPixelDepth(32);
                else if(menuItem == iRestoreStartDepth)
                  doRestoreMonitorPixelDepth();
                break;
            }
            HiliteMenu(0);
            break;
          
          case inDrag:
            DragWindow(windowRef,eventStrucPtr->where,NULL);
            GetWindowPortBounds(windowRef,&portRect);
            InvalWindowRect(windowRef,&portRect);
            break;
        }
      }
      break;

    case updateEvt:
      windowRef = (WindowRef) eventStrucPtr->message;
      BeginUpdate(windowRef);
      SetPortWindowPort(windowRef);
      doDisplayInformation(windowRef);
      EndUpdate(windowRef);
      break;
  }
}

// ********************************************************************** doDisplayInformation

void  doDisplayInformation(WindowRef windowRef)
{
  RGBColor     whiteColour = { 0xFFFF, 0xFFFF, 0xFFFF };
  RGBColor     blueColour  = { 0x3333, 0x3333, 0x9999 };
  Rect         portRect;
  GDHandle     deviceHdl;
  SInt16       videoDeviceCount = 0;  
  Str255       theString;
  SInt16       deviceType, pixelDepth, bytesPerRow;
  Rect         theRect;
  GrafPtr      grafPort;
  PixMapHandle pixMapHdl;
  CTabHandle   colorTableHdl;
  SInt16       entries = 0, vert = 28, horiz = 250, index = 0;
  RGBColor     getPixelColour,colourTableColour;

  RGBForeColor(&whiteColour);
  RGBBackColor(&blueColour);
  GetWindowPortBounds(windowRef,&portRect);
  EraseRect(&portRect);
  QDFlushPortBuffer(GetWindowPort(FrontWindow()),NULL);

  // ......................................................................... Get Device List

  deviceHdl = GetDeviceList();

  // ...................................................... count video devices in device list

  while(deviceHdl != NULL)
  {
    if(TestDeviceAttribute(deviceHdl,screenDevice))
      videoDeviceCount ++;

    deviceHdl = GetNextDevice(deviceHdl);
  }

  NumToString(videoDeviceCount,theString);
  MoveTo(10,20);
  DrawString(theString);
  if(videoDeviceCount < 2)
    DrawString("\p video device in the device list.");
  else
    DrawString("\p video devices in the device list.");

  // ......................................................................... Get Main Device

  deviceHdl = GetMainDevice();

  // ................................................................... determine device type

  MoveTo(10,35);

  if(((1 << gdDevType) & (*deviceHdl)->gdFlags) != 0)
    DrawString("\pThe main video device is a colour device.");
  else
    DrawString("\pThe main video device is a monochrome device.");

  MoveTo(10,50);
  deviceType = (*deviceHdl)->gdType;
  switch(deviceType)
  {
    case clutType:
      DrawString("\pIt is an indexed device with variable CLUT.");
      break;

    case fixedType:
      DrawString("\pIt is is an indexed device with fixed CLUT.");
      break;

    case directType:
      DrawString("\pIt is a direct device.");
      break;
  }

  // ................................................................. Get Handle to Pixel Map

  grafPort = GetWindowPort(windowRef);
  pixMapHdl = GetPortPixMap(grafPort);
  // pixMapHdl = (*deviceHdl)->gdPMap; // alternative method

  // ............................................................. get and display pixel depth

  MoveTo(10,70);
  DrawString("\pPixel depth = ");

  pixelDepth = GetPixDepth(pixMapHdl);
  // pixelDepth = (*(*deviceHdl)->gdPMap)->pixelSize;  // alternative method

  NumToString(pixelDepth,theString);
  DrawString(theString);

  // ........................................................... get and display bytes per row 

  MoveTo(10,90);
  bytesPerRow = (*pixMapHdl)->rowBytes & 0x7FFF;
  DrawString("\pBytes per row = ");
  NumToString(bytesPerRow,theString);
  DrawString(theString);

  // .................................................. Get Device's Global Boundary Rectangle

  theRect = (*deviceHdl)->gdRect;

  // ........................................... calculate and display total pixel image bytes

  MoveTo(10,105);
  DrawString("\pTotal pixel image bytes = ");
  NumToString(bytesPerRow * theRect.bottom,theString);
  DrawString(theString);

  // ..................................................... display device's boundary rectangle

  MoveTo(10,130);
  TextFace(bold);
  DrawString("\pGraphics Device's Boundary Rectangle");
  TextFace(normal);
  MoveTo(10,145);
  DrawString("\p(gdRect field of GDevice structure)");

  MoveTo(10,160);
  DrawString("\pBoundary rectangle top = ");
  NumToString(theRect.top,theString);
  DrawString(theString);

  MoveTo(10,175);
  DrawString("\pBoundary rectangle left = ");
  NumToString(theRect.left,theString);
  DrawString(theString);

  MoveTo(10,190);
  DrawString("\pBoundary rectangle bottom = ");
  NumToString(theRect.bottom,theString);
  DrawString(theString);

  MoveTo(10,205);
  DrawString("\pBoundary rectangle right = ");
  NumToString(theRect.right,theString);
  DrawString(theString);

  // .......................................... Get and Display Pixel Map's Boundary Rectangle

  GetPixBounds(pixMapHdl,&theRect);

  MoveTo(10,225);
  TextFace(bold);
  DrawString("\pPixel Map's Boundary Rectangle");
  TextFace(normal);
  MoveTo(10,240);
  DrawString("\p(bounds field of PixMap structure)");

  MoveTo(10,255);
  DrawString("\pBoundary rectangle top = ");
  NumToString(theRect.top,theString);
  DrawString(theString);

  MoveTo(10,270);
  DrawString("\pBoundary rectangle left = ");
  NumToString(theRect.left,theString);
  DrawString(theString);

  MoveTo(10,285);
  DrawString("\pBoundary rectangle bottom = ");
  NumToString(theRect.bottom,theString);
  DrawString(theString);

  MoveTo(10,300);
  DrawString("\pBoundary rectangle right = ");
  NumToString(theRect.right,theString);
  DrawString(theString);

  MoveTo(10,320);
  DrawString("\pOn Mac OS X, drag window after pixel depth and screen resolution changes to");
  DrawString("\p ensure that");
  MoveTo(10,333);
  DrawString("\pbytes per row, pixel image bytes, and colour values are updated.");

  // ........................... Get and Display RGB Components of Requested Background Colour

  MoveTo(250,255);
  GetBackColor(&blueColour);
  DrawString("\pRequested background colour (rgb) = ");
  MoveTo(250,270);
  NumToString(blueColour.red,theString);
  DrawString(theString);
  DrawString("\p  ");
  NumToString(blueColour.green,theString);
  DrawString(theString);
  DrawString("\p  ");
  NumToString(blueColour.blue,theString);
  DrawString(theString);

  // ........ If Direct Device, Get and Display RGB Components of Colour Returned by GetCPixel

  if(deviceType == directType)
  {
    MoveTo(250,285);
    GetCPixel(10,10,&getPixelColour);
    DrawString("\pColour returned by CetCPixel (rgb) = ");
    MoveTo(250,300);
    NumToString(getPixelColour.red,theString);
    DrawString(theString);
    DrawString("\p  ");
    NumToString(getPixelColour.green,theString);
    DrawString(theString);
    DrawString("\p  ");
    NumToString(getPixelColour.blue,theString);
    DrawString(theString);
  }

  // .............................................. else prepare to display colour table index

  else
  {
    MoveTo(250,285);
    DrawString("\pBackground colour (colour table index):");
  }

  // .............................................................. Get Handle to Colour Table

  colorTableHdl = (*pixMapHdl)->pmTable;

  // ........................................ if any entries in colour table, draw the colours

  MoveTo(250,20);
  DrawString("\pColour table:");

  entries = (*colorTableHdl)->ctSize;

  if(entries < 2)
  {
    MoveTo(260,100);
    DrawString("\pOnly one (dummy) entry in the colour");
    MoveTo(260,115);
    DrawString("\ptable.  To cause the colour table to be");
    MoveTo(260,130);
    DrawString("\pbuilt, set the monitor to bit depth 8");
    MoveTo(260,145);
    DrawString("\p(256 colours), causing it to act like ");
    MoveTo(260,160);
    DrawString("\pan indexed device.");
    SetRect(&theRect,250,28,458,236);
    FrameRect(&theRect);
  }

  for(index = 0;index <= entries;index++)
  {
    SetRect(&theRect,horiz,vert,horiz+12,vert+12);
    colourTableColour = (*colorTableHdl)->ctTable[index].rgb;
    RGBForeColor(&colourTableColour);
    PaintRect(&theRect);

    // .... also, if device is not a  direct device, and current colour matches background ...

    if(deviceType == clutType || deviceType == fixedType)
    {
      if(colourTableColour.red == blueColour.red && 
         colourTableColour.green == blueColour.green && 
         colourTableColour.blue == blueColour.blue)
      {

        // ....................... outline the drawn colour and display the colour table index

        RGBForeColor(&whiteColour);
        InsetRect(&theRect,-1,-1);
        FrameRect(&theRect);
        MoveTo(250,300);
        NumToString(index,theString);
        DrawString(theString);
      }
    }

    horiz += 13;
    if(horiz > 445)
    {
      horiz = 250;
      vert += 13;
    }
  }

  QDFlushPortBuffer(GetWindowPort(FrontWindow()),NULL);
}

// **************************************************************************** doCheckMonitor

Boolean doCheckMonitor(void)
{
  GDHandle  mainDeviceHdl;

  mainDeviceHdl = GetMainDevice();

  if(!(HasDepth(mainDeviceHdl,16,gdDevType,1)))
  {
    DisableMenuItem(GetMenuRef(mDemonstration),0);
    return false;
  }
  else
  {
    gStartupPixelDepth = (**((**mainDeviceHdl).gdPMap)).pixelSize;
    return true;
  }
}

// ******************************************************************** doSetMonitorPixelDepth

void  doSetMonitorPixelDepth(SInt16 requiredDepth)
{
  GDHandle mainDeviceHdl;
  Str255   alertString;  
  SInt16   currentPixelDepth;

  mainDeviceHdl = GetMainDevice();
  currentPixelDepth = (**((**mainDeviceHdl).gdPMap)).pixelSize;

  if(currentPixelDepth != requiredDepth)
  {
    SetDepth(mainDeviceHdl,requiredDepth,gdDevType,1);
  }
  else
  {
    GetIndString(alertString,rIndexedStrings,sMonitorAtThatDepth);
    doMonitorAlert(alertString);
  }
}

// **************************************************************** doRestoreMonitorPixelDepth

void  doRestoreMonitorPixelDepth(void)
{
  GDHandle mainDeviceHdl;
  Str255   alertString;  
  SInt16   pixelDepth;

  mainDeviceHdl = GetMainDevice();
  pixelDepth = (**((**mainDeviceHdl).gdPMap)).pixelSize;

  if(pixelDepth != gStartupPixelDepth)
  {
    GetIndString(alertString,rIndexedStrings,sRestoringMonitor);
    doMonitorAlert(alertString);
    SetDepth(mainDeviceHdl,gStartupPixelDepth,gdDevType,1);
  }
  else
  {
    GetIndString(alertString,rIndexedStrings,sMonitorAtStartDepth);
    doMonitorAlert(alertString);
  }
}

// **************************************************************************** doMonitorAlert

void  doMonitorAlert(Str255 labelText)
{
  SInt16 itemHit;

  StandardAlert(kAlertNoteAlert,labelText,NULL,NULL,&itemHit);
}

// *******************************************************************************************

Demonstration Program PreQuickDraw Comments

When this program is run, the user should:

o Drag the window to various positions on the main screen, noting, on Mac OS 8/9 only, the
  changes to the coordinates of the pixel map's boundary rectangle.  (On Mac OS X these
  coordinates represent the bounds of the Core Graphics window that backs the Carbon window, 
  not the screen.)

o Change between the available monitor resolutions, noting the changes in the bytes per row and
  total pixel image bytes figures displayed in the window.

o Using the Demonstration menu, change between the available pixel depths, noting the changes
  to the pixel depth and total pixel image bytes figures, and the background colour values,
  displayed in the window.

o Note that, when a pixel depth of 8 is set on a direct device, the device creates a CLUT and
  operates like a direct device.  In this case, the background colour value is the colour table
  entry (index), and the relevant colour in the colour table display is framed in white.

On Mac OS 8/9, if the user's monitor is set to thousands or millions of colours when the
program is run for the first time, the colour table will not be built.  It will be built when
the user first sets the pixel depth to 8 (256 colours).

main

The call to doCheckMonitor determines whether the monitor can support a pixel depth of at least
16.  If it cannot, the Demonstration menu is disabled, false is returned, and an alert is
displayed advising the user that the Demonstration menu will be unavailable.  If the monitor
can support a pixel depth of at least 16, the current pixel depth is assigned to the global
variable gStartupPixelDepth.

doEvents

In the case of a mouse-down event, in the inDrag case, when the user releases the mouse button,
the window is invalidated, causing it to be redrawn.

doDisplayInformation

At the first two lines, RGB colours are assigned to the window's graphics port's rgbFgColor and
rgbBkColor fields.  The call to EraseRect causes the content region to be filled with the
background colour.

Get Device List

The call to GetDeviceList gets a handle to the first GDevice structure in the device list.  The
device list is then "walked" in the while loop.  For every video device found in the list, the
variable videoDeviceCount is incremented.  GetNextDevice gets a handle to the next device in
the device list.

Get Main Device

GetMainDevice gets a handle to the startup device, that is, the device on which the menu bar
appears.

Following the call to MoveTo, the gdDevType bit is tested to determine whether the main
(startup) device is a colour or black-and-white device.

In the next block, the gdType field of the GDevice structure is examined to determine whether
the device is an indexed device with a variable CLUT, an indexed device with a fixed CLUT, or a
direct device (or a direct device set to display 256 colours or less and, as a consequence,
acting like an indexed device).

Get Handle to Pixel Map

The call to GetWindowPort gets the reference to the window's graphics port required by the call
to GetPortPixMap. GetPortPixMap gets a handle to the pixel map. (The following line shows an
alternative method of obtaining a handle to a pixel map, in this case from the GDevice
structure.)

In the next block, GetPixDepth is called to get the pixel depth. (The following line shows an
alternative method of obtaining the pixel depth, in this case from the GDevice structure.) 

At the next block, the number of bytes in each row in the pixel map is determined.  (The high
bit in the rowBytes field of the PixMap structure is a flag which indicates whether the data
structure is a PixMap structure or a BitMap structure.)

Get Device's Boundary Rectangle

At the first line of this block, the device's boundary rectangle is extracted from the GDevice
structure's gdRect field.  

At the next block, the bytes per row value is multiplied by the height of the boundary
rectangle to arrive at the total number of bytes in the pixel image.

The boundary rectangle's top, left, bottom, and right coordinates are then drawn in the window.

Get and Display Pixel Map's Boundary Rectangle

The call to GetPixBounds gets the pixel map's bounding rectangle.  The rectangle's top, left,
bottom, and right coordinates are then drawn in the window.

Get and Display RGB Components of Requested Background Colour

The second line of this block calls GetBackColor to get the graphics port's background colour. 
The red, green, and blue values are then printed in the window.
If Direct Device, Get and Display RGB Components of Colour Returned by GetCPixel
If the device is a direct device, GetCPixel is called to get the colour of a pixel in the
window drawn with the background colour.  The red, green and blue values are then printed in
the window.

If the device is not a direct device, some preparatory text is drawn in the window.

Get Handle To Colour Table

The first and fourth lines get a handle to the colour table in the GDevice structure's pixel
map and the number of entries in that table.  (Note that the ctSize field of the ColorTable
structure contains the number of table entries minus one.)

On Mac OS 8/9, QuickDraw only calls the Color Manager to build the colour table if the device
is an indexed device (or a direct device acting as an indexed device).  Thus, on Mac OS 8/9,
there will only be a dummy entry in the colour table unless the monitor is an indexed device or
a direct divice set to display 256 colours or less.

The final block paints small coloured rectangles for each entry in the colour table.  If the
main device is an indexed device (or if it is a direct device set to display 256 colours or
less), the colour table entry being used as the best match for the requested background colour
is outlined in white and the index value is drawn.

doCheckMonitor

doCheckMonitor is called at program start to determine whether the main device supports at
least 16-bit colour and, if it does, to assign the main device's pixel depth at startup to the
global variable gStartupPixelDepth.

The call to GetMainDevice gets a handle to the main device's GDevice structure.  The function
HasDepth is used to determine whether the device supports at least 16-bit colour.  If it does
not, the Demonstration menu is disabled and false is returned.  If it does, the pixel depth is
extracted from the pixelSize field of the PixMap structure in the GDevice structure and
assigned to the global variable gStartupPixelDepth.

doSetMonitorPixelDepth

doSetMonitorPixelDepth is called when one of the the first three items in the Demonstration
menu is chosen.
  
If the current pixel depth determined at the first two lines is not equal to the required new
depth, SetDepth is called to set the main device's pixel depth to the required depth.  
If the current pixel depth is equal to the required pixel depth, an alert is displayed advising
the user that the device is currently set to that pixel depth.

doRestoreMonitorPixelDepth

doRestoreMonitorPixelDepth is called, when the last item in the Demonstration menu is chosen,
to reset the main device's pixel depth to the startup pixel depth.
  
If the current pixel depth determined at the first two lines is not equal to the startup pixel
depth, a string is retrieved from a 'STR#' resource and passed to the function doMonitorAlert,
which displays a movable modal alert box advising the user that the monitor's bit depth is
about to be changed to the startup pixel depth.  When the user dismisses the alert box,
SetDepth sets the main device's pixel depth to the startup pixel depth. 
 
If the current pixel depth is the startup pixel depth, the last two lines display an alert box
advising the user that the device is currently set to that pixel depth.