Quickdraw Offscreen GWorld Interfaces. More...

#include <MacErrors.h>
#include <Quickdraw.h>

Typedefs
typedef unsigned long	GWorldFlags

typedef CGrafPtr	GWorldPtr

Enumerations
enum	{ pixPurgeBit = 0 , noNewDeviceBit = 1 , useTempMemBit = 2 , keepLocalBit = 3 , useDistantHdwrMemBit = 4 , useLocalHdwrMemBit = 5 , pixelsPurgeableBit = 6 , pixelsLockedBit = 7 , mapPixBit = 16 , newDepthBit = 17 , alignPixBit = 18 , newRowBytesBit = 19 , reallocPixBit = 20 , clipPixBit = 28 , stretchPixBit = 29 , ditherPixBit = 30 , gwFlagErrBit = 31 }

enum	{ pixPurge = 1L << pixPurgeBit , noNewDevice = 1L << noNewDeviceBit , useTempMem = 1L << useTempMemBit , keepLocal = 1L << keepLocalBit , useDistantHdwrMem = 1L << useDistantHdwrMemBit , useLocalHdwrMem = 1L << useLocalHdwrMemBit , pixelsPurgeable = 1L << pixelsPurgeableBit , pixelsLocked = 1L << pixelsLockedBit , kAllocDirectDrawSurface = 1L << 14 , mapPix = 1L << mapPixBit , newDepth = 1L << newDepthBit , alignPix = 1L << alignPixBit , newRowBytes = 1L << newRowBytesBit , reallocPix = 1L << reallocPixBit , clipPix = 1L << clipPixBit , stretchPix = 1L << stretchPixBit , ditherPix = 1L << ditherPixBit , gwFlagErr = 1L << gwFlagErrBit }

enum	{ deviceIsIndirect = (1L << 0) , deviceNeedsLock = (1L << 1) , deviceIsStatic = (1L << 2) , deviceIsExternalBuffer = (1L << 3) , deviceIsDDSurface = (1L << 4) , deviceIsDCISurface = (1L << 5) , deviceIsGDISurface = (1L << 6) , deviceIsAScreen = (1L << 7) , deviceIsOverlaySurface = (1L << 8) }

Functions
QDErr	NewGWorld (GWorldPtr offscreenGWorld, short PixelDepth, const Rect boundsRect, CTabHandle cTable, GDHandle aGDevice, GWorldFlags flags)

QDErr	NewGWorldFromPtr (GWorldPtr offscreenGWorld, unsigned long PixelFormat, const Rect boundsRect, CTabHandle cTable, GDHandle aGDevice, GWorldFlags flags, Ptr newBuffer, long rowBytes)

Boolean	LockPixels (PixMapHandle pm)
	Lock the offscreen buffer in memory for duration of a draw. More...

void	UnlockPixels (PixMapHandle pm)
	Unlock the buffer used by an offscreen graphics world. More...

GWorldFlags	UpdateGWorld (GWorldPtr offscreenGWorld, short pixelDepth, const Rect boundsRect, CTabHandle cTable, GDHandle aGDevice, GWorldFlags flags)

void	DisposeGWorld (GWorldPtr offscreenGWorld)
	Dispose of a GDevice structure and substructures. More...

void	GetGWorld (CGrafPtr port, GDHandle gdh)
	Get the current graphics world. More...

void	SetGWorld (CGrafPtr port, GDHandle gdh)
	Set the current graphics world. More...

void	CTabChanged (CTabHandle ctab)
	Get a new seed (a unique identifier) for the color table. More...

void	PixPatChanged (PixPatHandle ppat)
	Set the patXValid flag to -1. More...

void	PortChanged (GrafPtr port)
	Notify QuickDraw of a change. More...

void	GDeviceChanged (GDHandle gdh)
	Notify QuickDraw of a graphics device record change. More...

void	AllowPurgePixels (PixMapHandle pm)
	AllowPurgePixels Mark the pixel map's offscreen buffer as purgeable. More...

void	NoPurgePixels (PixMapHandle pm)
	Mark the pixel map's offscreen buffer as unpurgeable. More...

GWorldFlags	GetPixelsState (PixMapHandle pm)
	Get state of the pixel map's offscreen buffer. More...

void	SetPixelsState (PixMapHandle pm, GWorldFlags state)
	Set state of the pixel map's offscreen buffer. More...

Ptr	GetPixBaseAddr (PixMapHandle pm)
	Get a pointer to the beginning of the pixel map's pixels. More...

long	GetPixRowBytes (PixMapHandle pm)

QDErr	NewScreenBuffer (const Rect globalRect, Boolean purgeable, GDHandle gdh, PixMapHandle *offscreenPixMap)

void	DisposeScreenBuffer (PixMapHandle offscreenPixMap)
	DisposeScreenBuffer Dispose of memory for offscreen buffer and color table. More...

GDHandle	GetGWorldDevice (GWorldPtr offscreenGWorld)
	Get a handle to the device attached to the offscreen world. More...

Boolean	QDDone (GrafPtr port)
	Ensure that all drawing is done. More...

long	OffscreenVersion (void)

QDErr	NewTempScreenBuffer (const Rect globalRect, Boolean purgeable, GDHandle gdh, PixMapHandle *offscreenPixMap)

Boolean	PixMap32Bit (PixMapHandle pmHandle)
	Determine if PixMap requires 32-bit addr mode to access its pixels. More...

PixMapHandle	GetGWorldPixMap (GWorldPtr offscreenGWorld)
	Get a handle to the pixel map for an offscreen graphics world. More...

Detailed Description

Quickdraw Offscreen GWorld Interfaces.

Introduced In: Mac OS 8

Avaliable From: Universal Interfaces 3.4.1

Copyright: � 1985-2001 by Apple Computer, Inc., all rights reserved

For bug reports, consult the following page on the World Wide Web:

http://developer.apple.com/bugreporter/

Function Documentation

◆ AllowPurgePixels()

void AllowPurgePixels ( PixMapHandle pm )

AllowPurgePixels Mark the pixel map's offscreen buffer as purgeable.

AllowPurgePixels marks the pixel map's offscreen buffer as purgeable.

Copyright: THINK Reference © 1991-1992 Symantec Corporation

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ CTabChanged()

void CTabChanged ( CTabHandle ctab )

Get a new seed (a unique identifier) for the color table.

Call CTabChanged after modifying the content of the color table specified by
the ctab parameter. CTabChanged calls GetCTSeed to get a new seed (a
unique identifier) for the color table and notifies QuickDraw of the change.
ctabthe color table handle

Returns

none

Copyright: THINK Reference © 1991-1992 Symantec Corporation

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ DisposeGWorld()

void DisposeGWorld ( GWorldPtr offscreenGWorld )

Dispose of a GDevice structure and substructures.

If an offscreen graphics device was created, DisposeGWorld disposes of its
GDevice structure and substructures.
Call DisposeGWorld only when the application no longer needs the offscreen
buffer. If the current device was the offscreen device attached to
offscreenGWorld, the current device is reset to the device stored in the global
variable MainDevice .

Copyright: THINK Reference © 1991-1992 Symantec Corporation

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ DisposeScreenBuffer()

void DisposeScreenBuffer ( PixMapHandle offscreenPixMap )

DisposeScreenBuffer Dispose of memory for offscreen buffer and color table.

DisposeScreenBuffer is called by DisposeGWorld . It disposes of the
memory allocated for the offscreen buffer, the offscreen pixel map, and the
color table.

Copyright: THINK Reference © 1991-1992 Symantec Corporation

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ GDeviceChanged()

void GDeviceChanged ( GDHandle gdh )

Notify QuickDraw of a graphics device record change.

Call GDeviceChanged after modifying the graphics device record specified
by the gdh parameter or any of its substructures. GDeviceChanged notifies
QuickDraw of the change.
gdhhandle to the graphics device record or any of its substructures.

Returns

none

Note

If your application changes the pmTable field of the graphics device's pixel
map, it should call GDeviceChanged . However, if your application changes
the content of the color table referenced by gdPMap, it should call
CTabChanged as well.

Copyright: THINK Reference © 1991-1992 Symantec Corporation

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ GetGWorld()

void GetGWorld	(	CGrafPtr *	port,
		GDHandle *	gdh
	)

Get the current graphics world.

GetGWorld returns the current graphics world in the port and gdh
parameters. The port parameter is set to the current port, which can be of
type GrafPtr, CGrafPtr or GWorldPtr . The gdh parameter is set to the current
device.

Copyright: THINK Reference © 1991-1992 Symantec Corporation

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ GetGWorldDevice()

GDHandle GetGWorldDevice ( GWorldPtr offscreenGWorld )

Get a handle to the device attached to the offscreen world.

GetGWorldDevice returns a handle to the device attached to the offscreen
world specified by the offscreenGWorld parameter. This device is generally the
offscreen device created by NewGWorld . If offscreenGWorld was created with
the noNewDevice flag set, the attached device is one of the screen devices or the
device was passed to NewGWorld or UpdateGWorld .
If the offscreenGWorld parameter points to a regular GrafPort or CGrafPort ,
GetGWorldDevice returns the current device.

Copyright: THINK Reference © 1991-1992 Symantec Corporation

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ GetGWorldPixMap()

PixMapHandle GetGWorldPixMap ( GWorldPtr offscreenGWorld )

Get a handle to the pixel map for an offscreen graphics world.

GetGWorldPixMap returns a handle to the pixel map created for an
offscreen graphics world. Use GetGWorldPixMap whenever you need to
address the pixel map record created for an offscreen graphics world, rather
than dereferencing the GWorldPtr , to ensure compatibility on systems that
have the offscreen graphics world routines but are running the original
QuickDraw (not Color QuickDraw).
For example, you should use this function before calling CopyBits when
copying from the pixel map of an offscreen graphics world:
pixBase = GetGWorldPixMap (offscreenGWorld );
CopyBits (*pixBase,myWindow->portBits,&aRect,&otherR,srcCopy,NULL);
Use the GetGWorldPixMap function with offscreen graphics world
routines, such as LockPixels , AllowPurgePixels and GetPixelsState ,
that use a handle to a pixel map.

Copyright: THINK Reference © 1991-1992 Symantec Corporation

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ GetPixBaseAddr()

Ptr GetPixBaseAddr ( PixMapHandle pm )

Get a pointer to the beginning of the pixel map's pixels.

GetPixBaseAddr returns a 32-bit pointer to the beginning of the pixel
map's pixels. Your application should always call GetPixBaseAddr before
accessing the pixels of an offscreen pixel map directly. Then your application
should switch to 32-bit mode, access the pixels, and switch back to 24-bit
mode (if that's the mode you were in). Your application should never access the
baseAddr field of the pixel map directly.
If the offscreen buffer has been purged, GetPixBaseAddr returns NULL.
If QuickDraw is called after GetPixBaseAddr , the contents of the offscreen
buffer are not guaranteed to be accurate.

Copyright: THINK Reference © 1991-1992 Symantec Corporation

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ GetPixelsState()

GWorldFlags GetPixelsState ( PixMapHandle pm )

Get state of the pixel map's offscreen buffer.

GetPixelsState returns the state of the pixel map's offscreen buffer. The
state can be a combination of the flags pixelsPurgeable , pixelsLocked and
keepLocal , which are members of GWorldFlags . Use GetPixelsState in
conjunction with SetPixelsState to save and restore the state of these flags.
You can save the flags, change any of them, and then restore their original state
by passing the result of GetPixelsState back to the SetPixelsState
procedure.

Copyright: THINK Reference © 1991-1992 Symantec Corporation

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ GetPixRowBytes()

long GetPixRowBytes ( PixMapHandle pm )

GetPixRowBytes()

Non-Carbon CFM: in InterfaceLib 8.5 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ LockPixels()

Boolean LockPixels ( PixMapHandle pm )

Lock the offscreen buffer in memory for duration of a draw.

LockPixels should be called before drawing to or from an offscreen graphics
world. In the pm parameter pass the pixel map handle returned from a
GetGWorldPixMap call. LockPixels locks the offscreen buffer in memory
for the duration of the drawing.
If the offscreen buffer is purgeable and has been purged, LockPixels
returns FALSE to signal that no drawing can be made to the buffer memory. At
that point, the application should either call UpdateGWorld to reallocate the
buffer or draw directly in the window it represents.
If the offscreen buffer hasn't been purged or is not purgeable, LockPixels
returns TRUE.
As soon as the drawing is completed, you should call UnlockPixels .

Returns

 a Boolean value; It will be one of:
TRUEbuffer is in memory (either not purged or not purgeable)
FALSEbuffer has been purged

Copyright: THINK Reference © 1991-1992 Symantec Corporation

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ NewGWorld()

QDErr NewGWorld	(	GWorldPtr *	offscreenGWorld,
		short	PixelDepth,
		const Rect *	boundsRect,
		CTabHandle	cTable,
		GDHandle	aGDevice,
		GWorldFlags	flags
	)

NewGWorld()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ NewGWorldFromPtr()

QDErr NewGWorldFromPtr	(	GWorldPtr *	offscreenGWorld,
		unsigned long	PixelFormat,
		const Rect *	boundsRect,
		CTabHandle	cTable,
		GDHandle	aGDevice,
		GWorldFlags	flags,
		Ptr	newBuffer,
		long	rowBytes
	)

NewGWorldFromPtr()

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.1 and later

Mac OS X: in version 10.0 and later

◆ NewScreenBuffer()

QDErr NewScreenBuffer	(	const Rect *	globalRect,
		Boolean	purgeable,
		GDHandle *	gdh,
		PixMapHandle *	offscreenPixMap
	)

NewScreenBuffer()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ NewTempScreenBuffer()

QDErr NewTempScreenBuffer	(	const Rect *	globalRect,
		Boolean	purgeable,
		GDHandle *	gdh,
		PixMapHandle *	offscreenPixMap
	)

NewTempScreenBuffer()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ NoPurgePixels()

void NoPurgePixels ( PixMapHandle pm )

Mark the pixel map's offscreen buffer as unpurgeable.

NoPurgePixels marks the pixel map's offscreen buffer as unpurgeable.

Copyright: THINK Reference © 1991-1992 Symantec Corporation

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ OffscreenVersion()

long OffscreenVersion ( void )

OffscreenVersion()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ PixMap32Bit()

Boolean PixMap32Bit ( PixMapHandle pmHandle )

Determine if PixMap requires 32-bit addr mode to access its pixels.

PixMap32Bit returns TRUE if the specified pixel map requires 32-bit
addressing mode for access to its pixels.

Copyright: THINK Reference © 1991-1992 Symantec Corporation

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ PixPatChanged()

void PixPatChanged ( PixPatHandle ppat )

Set the patXValid flag to -1.

Call PixPatChanged after modifying either the pixel pattern record
specified by the ppat parameter or any of its substructures (pattern map or
pattern data records). PixPatChanged sets the patXValid flag to -1 and
notifies QuickDraw of the change.
ppatthe pixel pattern record handle

Returns

none

Note

If your application changes the pmTable field of the pattern map's pixel
pattern, it should call PixPatChanged . However, if your application
changes the content of the color table referenced by the pixel map's pmTable
field, it should call CTabChanged as well.

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ PortChanged()

void PortChanged ( GrafPtr port )

Notify QuickDraw of a change.

Call PortChanged after modifying the content of a grafPort or any of its
substructures. PortChanged notifies QuickDraw of the change.
porta grafPort pointer

Returns

none

Note

You should not directly change any of the pixel pattern records pointed to
by a color grafPort record. Instead, use the PenPixPat and BackPixPat
procedures. However, if your application changes the content of one of the
pixel pattern records, it should call PixPatChanged .
If your application changes the pmTable field of the port's pixel map, it
should call PortChanged . However, if your application changes the content
of the color table referenced by pmTable, it should call CTabChanged as
well.

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ QDDone()

Boolean QDDone ( GrafPtr port )

Ensure that all drawing is done.

You can use the QDDone function to ensure that all drawing is done and avoid
the possibility that new drawing operations might be overlaid by previously
issued but unexecuted operations. This function is especially useful if a
graphics accelerator is present and operating asynchronously.
port the designated graphics port

Returns

a Boolean value. The QDDone function returns TRUE if drawing
operations have finished in the designated graphics port, FALSE if any
remain to be executed. If you pass NIL as the port parameter, then
QDDone returns TRUE only if drawing operations have completed in
all ports. (If a port has a clock or other continuously operating
process, QDDone may never return TRUE.)

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ SetGWorld()

void SetGWorld	(	CGrafPtr	port,
		GDHandle	gdh
	)

Set the current graphics world.

SetGWorld sets the current graphics world. SetGWorld can be used with a
port parameter of type GrafPtr. CGrafPtr , or GWorldPtr (with proper type
coercion).
If the port parameter is of type GrafPtr or CGrafPtr , the current port is set
to the port specified by the port parameter, and the current device is set to the
device specified by the gdh parameter.
If the port parameter is of type GWorldPtr , the current port is set to the port
specified by the port parameter, and the current device is set to the device
attatched to the given graphics world. The gdh parameter will be ignored.

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ SetPixelsState()

void SetPixelsState	(	PixMapHandle	pm,
		GWorldFlags	state
	)

Set state of the pixel map's offscreen buffer.

SetPixelsState sets the lock and purge states of the pixel map's offscreen
buffer to the given flags by calling LockPixels or UnlockPixels and
AllowPurgePixels or NoPurgePixels . Pass the pixel map handle
returned from a GetGWorldPixMap call, and a setting of 0 or 1 for the
GWorldFlags , pixelsPurgeable and pixelsLocked .
You can also use SetPixelsState to set the keepLocal flag: pass keepLocal as
a state parameter to specify that the offscreen graphics world stays in main
memory rather than being checked on an accelerator card. A graphics world that
has already been cached will be brought back to main memory. Clearing the flag
will again allow caching. Use this setting carefully, as keeping graphics world
local surrenders the benefits of graphics accelerators.

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ UnlockPixels()

void UnlockPixels ( PixMapHandle pm )

Unlock the buffer used by an offscreen graphics world.

UnlockPixels unlocks the offscreen buffer. Call UnlockPixels as soon as
the application finishes drawing to or from the offscreen pixel map. You don't
need to call UnlockPixels if LockPixels returned FALSE, because
LockPixels doesn't lock purged pixels. However, calling UnlockPixels on
purged pixels does no harm.

Returns

 an Error Code . It is one of:
noErr(0) No error
paramErr (-50) Illegal parameter

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ UpdateGWorld()

GWorldFlags UpdateGWorld	(	GWorldPtr *	offscreenGWorld,
		short	pixelDepth,
		const Rect *	boundsRect,
		CTabHandle	cTable,
		GDHandle	aGDevice,
		GWorldFlags	flags
	)

UpdateGWorld()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

Typedefs

Enumerations

Functions

Detailed Description

Function Documentation

◆ AllowPurgePixels()

◆ CTabChanged()

◆ DisposeGWorld()

◆ DisposeScreenBuffer()

◆ GDeviceChanged()

◆ GetGWorld()

◆ GetGWorldDevice()

◆ GetGWorldPixMap()

◆ GetPixBaseAddr()

◆ GetPixelsState()

◆ GetPixRowBytes()

◆ LockPixels()

◆ NewGWorld()

◆ NewGWorldFromPtr()

◆ NewScreenBuffer()

◆ NewTempScreenBuffer()

◆ NoPurgePixels()

◆ OffscreenVersion()

◆ PixMap32Bit()

◆ PixPatChanged()

◆ PortChanged()

◆ QDDone()

◆ SetGWorld()

◆ SetPixelsState()

◆ UnlockPixels()

◆ UpdateGWorld()