Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Inside Macintosh: Imaging With QuickDraw /: Chapter 6 - Offscreen Graphics Worlds

Summary of Offscreen Graphics Worlds

Pascal Summary

Constants

CONST
   cDepthErr            = -157;  {invalid pixel depth}
   pixPurgeBit          = 0;     {set to to make base address for  }
                                 { offscreen pixel image purgeable}
   noNewDeviceBit       = 1;     {set to not create a new GDevice }
                                 { record for offscreen world} 
   useTempMemBit        = 2;     {set to create base address for offscreen }
                                 { pixel image in temporary memory} 
   keepLocalBit         = 3;     {set to keep offscreen pixel image in }
                                 { main memory}
   pixelsPurgeableBit   = 6;     {set to make base address for pixel image }
                                 { purgeable}
   pixelsLockedBit      = 7;     {set to lock base address for offscreen }
                                 { pixel image}
   mapPixBit            = 16;    {set by UpdateGWorld if it remapped }
                                 { colors to a new color table}
   newDepthBit          = 17;    {set by UpdateGWorld if it translated }
                                 { pixel map to a different pixel depth}
   alignPixBit          = 18;    {set by UpdateGWorld if it realigned }
                                 { pixel image to onscreen window} 
   newRowBytesBit       = 19;    {set by UpdateGWorld if it changed }
                                 { rowBytes field of PixMap record}
   reallocPixBit        = 20;    {set by UpdateGWorld if it reallocated }
                                 { base address for offscreen pixel image}
   clipPixBit           = 28;    {set to clip pixel image} 
   stretchPixBit        = 29;    {set to stretch or shrink pixel image} 
   ditherPixBit         = 30;    {set to dither pixel image} 
   gwFlagErrBit         = 31;    {set by UpdateGWorld if it failed}

Data Types

TYPE GWorldPtr = CGrafPtr;
TYPE GWorldFlags = 
   SET OF (
      pixPurge,         {specify to NewGWorld to make base address for }
                        { offscreen pixel image purgeable}
      noNewDevice,      {specify to NewGWorld to not create a new GDevice }
                        { record for offscreen world}
      useTempMem,       {specify to NewGWorld to create base address for }
                        { offscreen pixel image in temporary memory}
      keepLocal,        {specify to NewGWorld to keep offscreen pixel image }
                        { in main memory}
      gWorldFlag4,      {reserved}
      gWorldFlag5,      {reserved}
      pixelsPurgeable,  {returned by GetPixelsState to indicate that base }
                        { address for offscreen pixel image is purgeable; }
                        { specify to SetPixelsState to make base address }
                        { for pixel image purgeable}
      pixelsLocked,     {returned by GetPixelsState to indicate that base }
                        { address for offscreen pixel image is locked; }
                        { specify to SetPixelsState to lock base address }
                        { for offscreen pixel image}
      gWorldFlag8,      {reserved}
      gWorldFlag9,      {reserved}
      gWorldFlag10,     {reserved}
      gWorldFlag11,     {reserved}
      gWorldFlag12,     {reserved}
      gWorldFlag13,     {reserved}
      gWorldFlag14,     {reserved}
      gWorldFlag15,     {reserved}
      mapPix,           {returned by UpdateGWorld if it remapped colors to }
                        { a new color table}
      newDepth,         {returned by UpdateGWorld if it translated pixel } 
                        { map to a different pixel depth}
      alignPix,         {returned by UpdateGWorld if it realigned pixel }
                        { image to onscreen window} 
      newRowBytes,      {returned by UpdateGWorld if it changed rowBytes } 
                        { field of PixMap record}
      reallocPix,       {returned by UpdateGWorld if it reallocated }
                        { base address for offscreen pixel image}
      gWorldFlag21,     {reserved}
      gWorldFlag22,     {reserved}
      gWorldFlag23,     {reserved}
      gWorldFlag24,     {reserved}
      gWorldFlag25,     {reserved}
      gWorldFlag26,     {reserved}
      gWorldFlag27,     {reserved}
      clipPix,          {specify to UpdateGWorld to update and clip pixel }
                        { image}
      stretchPix,       {specify to UpdateGWorld to update and stretch or }
                        { shrink pixel image}
      ditherPix,        {specify to UpdateGWorld to dither pixel image}
      gwFlagErr,        {returned by UpdateGWorld if it failed}
   );

Routines

Creating, Altering, and Disposing of Offscreen Graphics Worlds

FUNCTION NewGWorld       (VAR offscreenGWorld: GWorldPtr; 
                          pixelDepth: Integer; boundsRect: Rect; 
                          cTable: CTabHandle; aGDevice: GDHandle; 
                          flags: GWorldFlags): QDErr;
FUNCTION NewScreenBuffer (globalRect: Rect; 
                          purgeable: Boolean; VAR gdh: GDHandle; 
                          VAR offscreenPixMap: PixMapHandle): QDErr;
FUNCTION NewTempScreenBuffer 
                         (globalRect: Rect; 
                          purgeable: Boolean; 
                          VAR gdh: GDHandle; 
                          VAR offscreenPixMap: PixMapHandle): QDErr;
FUNCTION UpdateGWorld    (VAR offscreenGWorld: GWorldPtr; 
                          pixelDepth: Integer; boundsRect: Rect; 
                          cTable: CTabHandle; aGDevice: GDHandle; 
                          flags: GWorldFlags): GWorldFlags;
PROCEDURE DisposeGWorld  (offscreenGWorld: GWorldPtr);
PROCEDURE DisposeScreenBuffer 
                         (offscreenPixMap: PixMapHandle);

Saving and Restoring Graphics Ports and Offscreen Graphics Worlds

PROCEDURE GetGWorld      (VAR port: CGrafPtr; VAR gdh: GDHandle);
PROCEDURE SetGWorld      (port: CGrafPtr; gdh: GDHandle);
FUNCTION GetGWorldDevice (offscreenGWorld: GWorldPtr): GDHandle;

Managing an Offscreen Graphics World's Pixel Image

FUNCTION GetGWorldPixMap     (offscreenGWorld: GWorldPtr): PixMapHandle;
FUNCTION LockPixels          (pm: PixMapHandle): Boolean;
PROCEDURE UnlockPixels       (pm: PixMapHandle);
PROCEDURE AllowPurgePixels   (pm: PixMapHandle);
PROCEDURE NoPurgePixels      (pm: PixMapHandle);
FUNCTION GetPixelsState      (pm: PixMapHandle): GWorldFlags;
PROCEDURE SetPixelsState     (pm: PixMapHandle; state: GWorldFlags);
FUNCTION GetPixBaseAddr      (pm: PixMapHandle): Ptr;
FUNCTION PixMap32Bit         (pmHandle: PixMapHandle): Boolean;

C Summary

Constants

enum {                        /* bit assignments for GWorldFlags data type */
   pixPurgeBit          = 0,  /* set to to make base address for   
                                 offscreen pixel image purgeable */
   noNewDeviceBit       = 1,  /* set to not create a new GDevice 
                                 record for offscreen world */
   useTempMemBit        = 2,  /* set to create base address for offscreen
                                 pixel image in temporary memory */
   keepLocalBit         = 3,  /* set to keep offscreen pixel image in 
                                 main memory */
   pixelsPurgeableBit   = 6,  /* set to make base address for pixel image
                                 purgeable */
   pixelsLockedBit      = 7,  /* set to lock base address for offscreen
                                 pixel image */
   mapPixBit            = 16, /* set by UpdateGWorld if it remapped 
                                 colors to a new color table */
   newDepthBit          = 17, /* set by UpdateGWorld if it translated 
                                 pixel map to a different pixel depth */
   alignPixBit          = 18, /* set by UpdateGWorld if it realigned 
                                 pixel image to onscreen window */
   newRowBytesBit       = 19, /* set by UpdateGWorld if it changed 
                                 rowBytes field of PixMap record */
   reallocPixBit        = 20, /* set by UpdateGWorld if it reallocated 
                                 base address for offscreen pixel image */
   clipPixBit           = 28, /* set to update and clip pixel image */
   stretchPixBit        = 29, /* set to update and stretch or shrink pixel 
                                 image */
   ditherPixBit         = 30, /* set to dither pixel image */
   gwFlagErrBit         = 31  /* set by UpdateGWorld if it failed */
};
enum {                  /* constants for GWorldFlags data type */
   pixPurge          = 1 << pixPurgeBit,
   noNewDevice       = 1 << noNewDeviceBit,
   useTempMem        = 1 << useTempMemBit,
   keepLocal         = 1 << keepLocalBit,
   pixelsPurgeable   = 1 << pixelsPurgeableBit,
   pixelsLocked      = 1 << pixelsLockedBit,
   mapPix            = 1 << mapPixBit,
   newDepth          = 1 << newDepthBit,
   alignPix          = 1 << alignPixBit,
   newRowBytes       = 1 << newRowBytesBit,
   reallocPix        = 1 << reallocPixBit,
   clipPix           = 1 << clipPixBit,
   stretchPix        = 1 << stretchPixBit,
   ditherPix         = 1 << ditherPixBit,
   gwFlagErr         = 1 << gwFlagErrBit
};
enum {
   cDepthErr         = -157   /* invalid pixel depth */
};

Data Types

typedef CGrafPtr GWorldPtr;
typedef unsigned long GWorldFlags;

Functions

Creating, Altering, and Disposing of Offscreen Graphics Worlds

pascal QDErr NewGWorld        (GWorldPtr *offscreenGWorld, short PixelDepth, 
                               const Rect *boundsRect, CTabHandle cTable, 
                               GDHandle aGDevice, GWorldFlags flags); 
pascal QDErr NewScreenBuffer
                              (const Rect *globalRect, Boolean purgeable, GDHandle *gdh, PixMapHandle *offscreenPixMap); 
pascal QDErr NewTempScreenBuffer
                              (const Rect *globalRect, Boolean purgeable, GDHandle *gdh, PixMapHandle *offscreenPixMap); 
pascal GWorldFlags UpdateGWorld
                              (GWorldPtr *offscreenGWorld, short pixelDepth,  const Rect *boundsRect, CTabHandle cTable, GDHandle aGDevice, GWorldFlags flags); 
pascal void DisposeGWorld     (GWorldPtr offscreenGWorld); 
pascal void DisposeScreenBuffer
                              (PixMapHandle offscreenPixMap);

Saving and Restoring Graphics Ports and Offscreen Graphics Worlds

pascal void GetGWorld         (CGrafPtr *port, GDHandle *gdh); 
pascal void SetGWorld         (CGrafPtr port, GDHandle gdh); 
pascal GDHandle GetGWorldDevice
                              (GWorldPtr offscreenGWorld);

Managing an Offscreen Graphics World's Pixel Image

pascal PixMapHandle GetGWorldPixMap
                              (GWorldPtr offscreenGWorld); 
pascal Boolean LockPixels     (PixMapHandle pm); 
pascal void UnlockPixels      (PixMapHandle pm); 
pascal void AllowPurgePixels
                              (PixMapHandle pm); 
pascal void NoPurgePixels     (PixMapHandle pm); 
pascal GWorldFlags GetPixelsState
                              (PixMapHandle pm); 
pascal void SetPixelsState    (PixMapHandle pm, GWorldFlags state); 
pascal Ptr GetPixBaseAddr     (PixMapHandle pm); 
pascal Boolean PixMap32Bit    (PixMapHandle pmHandle);

Assembly-Language Summary

Trap Macros Requiring Routine Selectors

_QDExtensions

Selector	Routine
$00160000	NewGWorld
$00040001	LockPixels
$00040002	UnlockPixels
$00160003	UpdateGWorld
$00040004	DisposeGWorld
$00080005	GetGWorld
$00080006	SetGWorld
$0004000B	AllowPurgePixels
$0004000C	NoPurgePixels
$0004000D	GetPixelsState
$0008000E	SetPixelsState
$0004000F	GetPixBaseAddr
$000E0010	NewScreenBuffer
$00040011	DisposeScreenBuffer
$00040012	GetGWorldDevice
$000E0015	NewTempScreenBuffer
$00040016	PixMap32Bit
$00040017	GetGWorldPixMap

Result Codes

noErr	0	No error
paramErr	-50	Illegal parameter
cNoMemErr	-152	Failed to allocate memory for structures
cDepthErr	-157	Invalid pixel depth

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.