Deprecated Quartz Display Services Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

Available in OS X v10.0 through OS X v10.6

CGDisplayAddressForPosition

Returns the address in framebuffer memory that corresponds to a position on an online display. (Available in OS X v10.0 through OS X v10.6. There is no replacement; because direct access to the raw framebuffer is not necessary, there is no need to retrieve its memory address.)

void * CGDisplayAddressForPosition (
   CGDirectDisplayID display,
   int32_t x,
   int32_t y
);
Parameters
display

The identifier of the display to be accessed.

x

The x-coordinate of a position in global display space. The origin is the upper-left corner of the main display.

y

The y-coordinate of a position in global display space. The origin is the upper-left corner of the main display, and the y-axis is oriented down.

Return Value

The address in framebuffer memory that corresponds to the specified position. If the display ID is invalid or the point lies outside the bounds of the display, the return value is NULL.

Discussion

If the display has not been captured, the returned address may refer to read-only memory.

Special Considerations

This deprecated function returned an address in framebuffer memory. Instead of using the raw framebuffer to draw to the screen, you should instead use a supported drawing engine such as Quartz or OpenGL. While accessing the framebuffer directly has been deprecated, it is possible to copy screen data using CGDisplayCreateImageForRect.

Availability
  • Available in OS X v10.0 through OS X v10.6.
  • Deprecated in OS X v10.6.
Declared In
CGDirectDisplay.h

CGDisplayBaseAddress

Returns the base address in framebuffer memory of an online display. (Available in OS X v10.0 through OS X v10.6. There is no replacement; because direct access to the raw framebuffer is not necessary, there is no need to retrieve its memory address.)

void * CGDisplayBaseAddress (
   CGDirectDisplayID display
);
Parameters
display

The identifier of the display to be accessed.

Return Value

The base address in framebuffer memory of the specified display. If the display ID is invalid, the return value is NULL.

Discussion

If the display has not been captured, the returned address may refer to read-only memory.

Special Considerations

This deprecated function returned an address in framebuffer memory. Instead of using the raw framebuffer to draw to the screen, you should instead use a supported drawing engine such as Quartz or OpenGL. While accessing the framebuffer directly has been deprecated, it is possible to copy screen data using CGDisplayCreateImage.

Availability
  • Available in OS X v10.0 through OS X v10.6.
  • Deprecated in OS X v10.6.
Declared In
CGDirectDisplay.h

CGDisplayBitsPerPixel

Returns the number of bits used to represent a pixel in the framebuffer. (Available in OS X v10.0 through OS X v10.6. Use CGDisplayModeCopyPixelEncoding instead.)

size_t CGDisplayBitsPerPixel (
   CGDirectDisplayID display
);
Parameters
display

The identifier of the display to be accessed.

Return Value

The number of bits used to represent a pixel in the framebuffer.

Special Considerations

This deprecated function allows an application to retrieve the number of bits used to represent a pixel in the framebuffer. Starting in OS X v10.6 the CGDisplayModeCopyPixelEncoding should be used because it returns to the user the I/O Kit Graphics Mode, which can be used to determine the bits per pixel, as well as their encoding. This can prevent treating display modes with different encodings, but a similar total number of bits per pixel, in the same way.

Availability
  • Available in OS X v10.0 through OS X v10.6.
  • Deprecated in OS X v10.6.
Declared In
CGDirectDisplay.h

CGDisplayBitsPerSample

Returns the number of bits used to represent a pixel component in the framebuffer. (Available in OS X v10.0 through OS X v10.6. Use CGDisplayModeCopyPixelEncoding instead.)

size_t CGDisplayBitsPerSample (
   CGDirectDisplayID display
);
Parameters
display

The identifier of the display to be accessed.

Return Value

The number of bits used to represent a pixel component such as a color value in the framebuffer.

Special Considerations

This deprecated function allows an application to retrieve the number of bits used to represent a pixel component in the framebuffer. Starting in OS X v10.6 the CGDisplayModeCopyPixelEncoding should be used because it returns to the user the I/O Kit Graphics Mode, which can be used to determine the bits per sample, as well as their encoding. This can prevent treating display modes with different encodings, but a similar total number of bits per sample, in the same way.

Availability
  • Available in OS X v10.0 through OS X v10.6.
  • Deprecated in OS X v10.6.
Declared In
CGDirectDisplay.h

CGDisplayBytesPerRow

Returns the number of bytes per row in a display. (Available in OS X v10.0 through OS X v10.6. Use CGDisplayCreateImage or CGDisplayCreateImageForRect instead.)

size_t CGDisplayBytesPerRow (
   CGDirectDisplayID display
);
Parameters
display

The identifier of the display to be accessed.

Return Value

The number of bytes per row in the display. This number also represents the stride between pixels in the same column of the display.

Special Considerations

This deprecated function required pixel data to be retrieved manually. Starting in OS X v10.6 one of the CGDisplayCreateImage functions should be used to create an image from the display. For more information, see CGImage Reference.

Availability
  • Available in OS X v10.0 through OS X v10.6.
  • Deprecated in OS X v10.6.
Declared In
CGDirectDisplay.h

CGDisplaySamplesPerPixel

Returns the number of color components used to represent a pixel. (Available in OS X v10.0 through OS X v10.6. Use CGDisplayModeCopyPixelEncoding instead.)

size_t CGDisplaySamplesPerPixel (
   CGDirectDisplayID display
);
Parameters
display

The identifier of the display to be accessed.

Return Value

The number of color components used to represent a pixel.

Special Considerations

This deprecated function allows an application to retrieve the number of color components used to represent a pixel in the framebuffer. Starting in OS X v10.6 the CGDisplayModeCopyPixelEncoding should be used because it returns to the user the I/O Kit Graphics Mode, which can be used to determine the samples per pixel, as well as their encoding. This can prevent treating display modes with different encodings, but a similar total number of samples per pixel, in the same way.

Availability
  • Available in OS X v10.0 through OS X v10.6.
  • Deprecated in OS X v10.6.
Declared In
CGDirectDisplay.h

Deprecated in OS X v10.6

CGConfigureDisplayMode

Configures the display mode of a display. (Deprecated in OS X v10.6. Use CGConfigureDisplayWithDisplayMode instead.)

CGError CGConfigureDisplayMode (
   CGDisplayConfigRef configRef,
   CGDirectDisplayID display,
   CFDictionaryRef mode
);
Parameters
configRef

A display configuration, acquired by calling CGBeginDisplayConfiguration.

display

The identifier of the display being configured.

mode

A display mode dictionary (see the discussion below).

Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Discussion

A display mode is a set of properties such as width, height, pixel depth, and refresh rate, and options such as stretched LCD panel filling.

The display mode you provide must be one of the following:

If you use this function to change the mode of a display in a mirroring set, Quartz may adjust the bounds, resolutions, and depth of the other displays in the set to a safe mode, with matching depth and the smallest enclosing size.

Special Considerations

This deprecated function takes as a parameter a display mode dictionary. Starting in OS X v10.6, display mode dictionaries have been replaced by the CGDisplayMode opaque type. For information on the CGDisplayMode opaque type, see “Getting Information About a Display Mode”.

Availability
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.6.
Declared In
CGDisplayConfiguration.h

CGDisplayAvailableModes

Returns information about the currently available display modes. (Deprecated in OS X v10.6. Use CGDisplayCopyAllDisplayModes instead.)

CFArrayRef CGDisplayAvailableModes (
   CGDirectDisplayID display
);
Parameters
display

The identifier of the display to be accessed.

Return Value

An array of dictionaries with display mode information, or NULL if the display is invalid. The array is owned by the system and you should not release it. Each dictionary in the array contains information about a mode that the display supports. For a list of the properties in a display mode dictionary, see “Display Mode Standard Properties” and “Display Mode Optional Properties.” For general information about using dictionaries, see CFDictionary Reference.

Special Considerations

This deprecated function returns an array of display mode dictionary. Starting in OS X v10.6, display mode dictionaries have been replaced by the CGDisplayMode opaque type. Whereas display mode dictionaries returned by CGDisplayAvailableModes are owned by the system and are not to be released, display mode opaque type references returned by CGDisplayCopyAllDisplayModes are owned by the caller and you must release them.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Related Sample Code
Declared In
CGDirectDisplay.h

CGDisplayBestModeForParameters

Returns information about the display mode closest to a specified depth and screen size. (Deprecated in OS X v10.6. Use the display mode query functions instead; see “Getting Information About a Display Mode”.)

CFDictionaryRef CGDisplayBestModeForParameters (
   CGDirectDisplayID display,
   size_t bitsPerPixel,
   size_t width,
   size_t height,
   boolean_t *exactMatch
);
Parameters
display

The identifier of the display to optimize.

bitsPerPixel

Optimal display depth in bits per pixel. Note that this value is not the same as pixel depth, which is the number of bits per channel or component.

width

Optimal display width in pixel units.

height

Optimal display height in pixel units.

exactMatch

A pointer to a Boolean variable. On return, its value is true if an exact match in display depth, width, and height is found; otherwise, false. If this information is not needed, pass NULL.

Return Value

A display mode dictionary, or NULL if the display is invalid. The dictionary is owned by the system and you should not release it. The dictionary contains information about the display mode closest to the specified depth and screen size. For a list of the properties in a display mode dictionary, see “Display Mode Standard Properties” and “Display Mode Optional Properties.” For general information about using dictionaries, see CFDictionary Reference.

Discussion

This function tries to find an optimal display mode for the specified display. The function first tries to find a mode with the specified pixel depth and dimensions equal to or greater than the specified width and height. If no depth match is found, it tries to find a mode with greater depth and the same or greater dimensions. If a suitable display mode is not found, this function simply returns the current display mode.

Special Considerations

This deprecated function selects a display mode closest to the specified parameters. Starting in OS X v10.6 new display mode APIs should be used to query display modes so that an application can tailor its definition of “best” to its graphics and memory needs.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
CGDirectDisplay.h

CGDisplayBestModeForParametersAndRefreshRate

Returns information about the display mode closest to a specified depth, screen size, and refresh rate. (Deprecated in OS X v10.6. Use the display mode query functions instead; see “Getting Information About a Display Mode”.)

CFDictionaryRef CGDisplayBestModeForParametersAndRefreshRate (
   CGDirectDisplayID display,
   size_t bitsPerPixel,
   size_t width,
   size_t height,
   CGRefreshRate refresh,
   boolean_t *exactMatch
);
Parameters
display

The identifier of the display to be accessed.

bitsPerPixel

Optimal display depth, in bits per pixel. Note that this value is not the same as pixel depth, which is the number of bits per channel or component.

width

Optimal display width, in pixel units.

height

Optimal display height, in pixel units.

refresh

Optimal display refresh rate, in frames per second.

exactMatch

A pointer to a Boolean variable. On return, its value is true if an exact match in display depth, width, height, and refresh rate is found; otherwise, false. If this information is not needed, pass NULL.

Return Value

A display mode dictionary, or NULL if the display is invalid. The dictionary is owned by the system and you should not release it. The dictionary contains information about the display mode closest to the specified depth, screen size, and refresh rate. For a list of the properties in a display mode dictionary, see “Display Mode Standard Properties” and “Display Mode Optional Properties.” For general information about using dictionaries, see CFDictionary Reference.

Discussion

This function searches the list of available display modes for a mode that comes closest to satisfying these criteria:

  • Has a pixel depth equal to or greater than the specified depth

  • Has dimensions equal to or greater than the specified height and width

  • Uses a refresh rate equal to or near the specified rate

If a suitable display mode is not found, this function simply returns the current display mode.

Special Considerations

This deprecated function selects a display mode closest to the specified parameters. Starting in OS X v10.6 new display mode APIs should be used to query display modes so that an application can taylor its definition of “best” to its graphics and memory needs.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Related Sample Code
Declared In
CGDirectDisplay.h

CGDisplayBestModeForParametersAndRefreshRateWithProperty

Returns information about the display mode closest to a specified depth, screen size, and refresh rate, with a required property. (Deprecated in OS X v10.6. Use the display mode query functions instead; see “Getting Information About a Display Mode”.)

CFDictionaryRef CGDisplayBestModeForParametersAndRefreshRateWithProperty (
   CGDirectDisplayID display,
   size_t bitsPerPixel,
   size_t width,
   size_t height,
   CGRefreshRate refresh,
   CFStringRef property,
   boolean_t *exactMatch
);
Parameters
display

The identifier of the display to be accessed.

bitsPerPixel

Optimal display depth, in bits per pixel. Note that this value is not the same as pixel depth, which is the number of bits per channel or component.

width

Optimal display width, in pixels.

height

Optimal display height, in pixels.

refresh

Optimal display refresh rate, in refreshes per second.

property

A required display mode property. For a list of the properties you can specify, see “Display Mode Optional Properties.”

exactMatch

A pointer to a Boolean variable. On return, its value is true if an exact match in display depth, width, height, refresh rate, and property is found; otherwise, false. If this information is not needed, pass NULL.

Return Value

A display mode dictionary, or NULL if the display is invalid. The dictionary is owned by the system and you should not release it. The dictionary contains information about the display mode with the specified property that comes closest to the specified depth, screen size, and refresh rate. For a list of the properties in a display mode dictionary, see “Display Mode Standard Properties” and “Display Mode Optional Properties.” For general information about using dictionaries, see CFDictionary Reference.

Discussion

This function searches the list of available display modes for a mode that includes the specified property and comes closest to satisfying these criteria:

  • Has a pixel depth equal to or greater than the specified depth

  • Has dimensions equal to or greater than the specified height and width

  • Uses a refresh rate equal to or near the specified rate

If no matching display mode is found, this function simply returns the current display mode.

Special Considerations

This deprecated function selects a display mode closest to the specified parameters. Starting in OS X v10.6 new display mode APIs should be used to query display modes so that an application can taylor its definition of “best” to its graphics and memory needs.

Availability
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.6.
Declared In
CGDirectDisplay.h

CGDisplayCurrentMode

Returns information about the current display mode. (Deprecated in OS X v10.6. Use CGDisplayCopyDisplayMode instead.)

CFDictionaryRef CGDisplayCurrentMode (
   CGDirectDisplayID display
);
Parameters
display

The identifier of the display to be accessed.

Return Value

A display mode dictionary, or NULL if the display is invalid. The dictionary is owned by the system and you should not release it. The dictionary contains information about the current display mode. For a list of the properties in a display mode dictionary, see “Display Mode Standard Properties” and “Display Mode Optional Properties.” For general information about using dictionaries, see CFDictionary Reference.

Special Considerations

This deprecated function returns a display mode dictionary. Starting in OS X v10.6, display mode dictionaries have been replaced by the CGDisplayMode opaque type. Whereas display mode dictionaries returned by CGDisplayCurrentModes are owned by the system and are not to be released, display mode opaque type references returned by CGDisplayCopyDisplayMode are owned by the caller and you must release them.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Related Sample Code
Declared In
CGDirectDisplay.h

CGDisplaySwitchToMode

Switches a display to a different mode. (Deprecated in OS X v10.6. Use CGDisplaySetDisplayMode instead.)

CGError CGDisplaySwitchToMode (
   CGDirectDisplayID display,
   CFDictionaryRef mode
);
Parameters
display

The identifier of the display to be accessed.

mode

A display mode dictionary that contains information about the display mode to set. The dictionary passed in must be a dictionary returned by another Quartz display function such as CGDisplayAvailableModes or CGDisplayBestModeForParameters. For a list of the properties in a display mode dictionary, see “Display Mode Standard Properties” and “Display Mode Optional Properties.” For general information about using dictionaries, see CFDictionary Reference.

Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Discussion

This function switches the display mode of the specified display. The operation is always synchronous; the function does not return until the mode switch is complete. Note that after switching, display parameters and addresses may change.

The selected display mode persists for the life of the calling program. When the program terminates, the display mode automatically reverts to the permanent setting in the Displays panel of System Preferences.

When changing the display mode of a display in a mirroring set, other displays in the mirroring set will be assigned a mode that's capable of mirroring the bounds of the display being adjusted. To avoid this automatic behavior, you can use the following procedure: callCGBeginDisplayConfiguration, call CGConfigureDisplayMode for each display to explicitly set the mode, and finally call CGCompleteDisplayConfiguration

Special Considerations

This deprecated function takes as a parameter a display mode dictionary. Starting in OS X v10.6, display mode dictionaries have been replaced by the CGDisplayMode opaque type.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Related Sample Code
Declared In
CGDirectDisplay.h

Deprecated in OS X v10.7

CGDisplayBeamPosition

Returns the current beam position on a display. (Deprecated in OS X v10.7.)

uint32_t CGDisplayBeamPosition (
   CGDirectDisplayID display
);
Parameters
display

The identifier of the display to be accessed.

Return Value

The current beam position on the specified display. If the display does not implement conventional video vertical and horizontal sweep in painting, or the driver does not implement this functionality, 0 is returned.

Discussion

This function returns the number of the scan line on which the beam is currently positioned, expressed as a nonnegative integer. The value increases as the beam moves lower on the display.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
CGDirectDisplay.h

CGDisplayCanSetPalette

Returns a Boolean value indicating whether the current display mode supports palettes. (Deprecated in OS X v10.7.)

boolean_t CGDisplayCanSetPalette (
   CGDirectDisplayID display
);
Parameters
display

The identifier of the display to be accessed.

Return Value

If true, the current display mode supports palettes; otherwise, false.

Discussion

Palettes are supported in any display selected to run in a 256-color display mode.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
CGDirectDisplay.h

CGDisplaySetPalette

Sets the palette for a display. (Deprecated in OS X v10.7.)

CGError CGDisplaySetPalette (
   CGDirectDisplayID display,
   const CGDirectPaletteRef palette
);
Parameters
display

The identifier of the display to be accessed.

palette

The display palette to be set.

Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
CGDirectDisplay.h

CGDisplayWaitForBeamPositionOutsideLines

Waits until the beam position moves outside a region in a display screen. (Deprecated in OS X v10.7.)

CGError CGDisplayWaitForBeamPositionOutsideLines (
   CGDirectDisplayID display,
   uint32_t upperScanLine,
   uint32_t lowerScanLine
);
Parameters
display

The identifier of the display to be accessed.

upperScanLine

The upper scan line number.

lowerScanLine

The lower scan line number.

Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Discussion

This function waits until the beam position is outside the range specified by the arguments upperScanLine and lowerScanLine. If the value of upperScanLine is greater than the value of lowerScanLine, or if upperScanLine and lowerScanLine encompass the entire display height, this function returns an error.

Some displays may not use conventional video vertical and horizontal sweep in painting. These displays report a refresh rate value of 0 in the display mode returned by CGDisplayCopyDisplayMode. Also, some display device drivers may not implement support for this mechanism. On such displays, this function returns at once.

This function is not designed for VBL drawing synchronization.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
CGDirectDisplay.h

CGPaletteCreateCopy

Returns a copy of a specified display palette. (Deprecated in OS X v10.7.)

CGDirectPaletteRef CGPaletteCreateCopy (
   CGDirectPaletteRef palette
);
Parameters
palette

The display palette to be copied.

Return Value

A new display palette object. When you no longer need the palette, you should release it using the function CGPaletteRelease.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
CGDirectPalette.h

CGPaletteCreateDefaultColorPalette

Returns a new display palette representing the default 8-bit color palette. (Deprecated in OS X v10.7.)

CGDirectPaletteRef CGPaletteCreateDefaultColorPalette (
   void
);
Return Value

A new display palette object. When you no longer need the palette, you should release it using the function CGPaletteRelease.

Discussion

Palettes are used with 256-color display modes. The default palette is the old default 8-bit Mac OS palette, with white at index 0 and black at index 255.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
CGDirectPalette.h

CGPaletteCreateFromPaletteBlendedWithColor

Returns a new tinted display palette. The new palette is derived from an existing palette blended with a solid color, at a specified level of intensity. (Deprecated in OS X v10.7.)

CGDirectPaletteRef CGPaletteCreateFromPaletteBlendedWithColor (
   CGDirectPaletteRef palette,
   CGPaletteBlendFraction fraction,
   CGDeviceColor color
);
Parameters
palette

The palette to be blended.

fraction

A value between 0 and 1 that represents the blend intensity. See CGPaletteBlendFraction.

color

The blend color. See CGDeviceColor.

Return Value

A new display palette object. When you no longer need the palette, you should release it using the function CGPaletteRelease.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
CGDirectPalette.h

CGPaletteCreateWithByteSamples

Returns a new display palette using 8-bit sample data. (Deprecated in OS X v10.7.)

CGDirectPaletteRef CGPaletteCreateWithByteSamples (
   CGDeviceByteColor *sampleTable,
   uint32_t sampleCount
);
Parameters
sampleTable

A color table with integer values that represent the intensity of the red, green, and blue components in each table entry. Each value ranges from 0 (no color) to 255 (full intensity). See CGDeviceByteColor.

sampleCount

The number of entries in the specified color table.

Return Value

A new display palette object. When you no longer need the palette, you should release it using the function CGPaletteRelease.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
CGDirectPalette.h

CGPaletteCreateWithCapacity

Returns a new display palette with a specified capacity. The new palette is initialized from the default color palette. (Deprecated in OS X v10.7.)

CGDirectPaletteRef CGPaletteCreateWithCapacity (
   uint32_t capacity
);
Parameters
capacity

The number of entries in the new palette.

Return Value

A new display palette object. When you no longer need the palette, you should release it using the function CGPaletteRelease.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
CGDirectPalette.h

CGPaletteCreateWithDisplay

Returns a copy of the current palette for a display. (Deprecated in OS X v10.7.)

CGDirectPaletteRef CGPaletteCreateWithDisplay (
   CGDirectDisplayID display
);
Parameters
display

The identifier of the display to be accessed.

Return Value

A new display palette object, or NULL if the current display mode does not support a palette. When you no longer need the palette, you should release it using the function CGPaletteRelease.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
CGDirectPalette.h

CGPaletteCreateWithSamples

Returns a new display palette using RGB sample data. (Deprecated in OS X v10.7.)

CGDirectPaletteRef CGPaletteCreateWithSamples (
   CGDeviceColor *sampleTable,
   uint32_t sampleCount
);
Parameters
sampleTable

A color table with floating-point values that represent the intensity of the red, green, and blue components in each table entry. Each value ranges from 0 (no color) to 1 (full intensity). See CGDeviceColor.

sampleCount

The number of entries in the specified color table.

Return Value

A new display palette object. When you no longer need the palette, you should release it using the function CGPaletteRelease.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
CGDirectPalette.h

CGPaletteGetColorAtIndex

Returns the color value at the specified index. (Deprecated in OS X v10.7.)

CGDeviceColor CGPaletteGetColorAtIndex (
   CGDirectPaletteRef palette,
   uint32_t index
);
Parameters
palette

The display palette to access.

index

The zero-based index of the desired palette entry.

Return Value

A color value. See CGDeviceColor.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
CGDirectPalette.h

CGPaletteGetIndexForColor

Returns the index of the display palette entry that most closely matches a specified color value. (Deprecated in OS X v10.7.)

uint32_t CGPaletteGetIndexForColor (
   CGDirectPaletteRef palette,
   CGDeviceColor color
);
Parameters
palette

The display palette to access.

color

The color value to match. See CGDeviceColor.

Return Value

The index of the display palette entry that most closely matches the specified color value.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
CGDirectPalette.h

CGPaletteGetNumberOfSamples

Returns the number of colors in a display palette. (Deprecated in OS X v10.7.)

uint32_t CGPaletteGetNumberOfSamples (
   CGDirectPaletteRef palette
);
Parameters
palette

The display palette to access.

Return Value

The number of colors in the specified display palette.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
CGDirectPalette.h

CGPaletteIsEqualToPalette

Returns a Boolean value indicating whether two display palettes are equal. (Deprecated in OS X v10.7.)

Boolean CGPaletteIsEqualToPalette (
   CGDirectPaletteRef palette1,
   CGDirectPaletteRef palette2
);
Parameters
palette1

The first display palette to be compared.

palette2

The second display palette to be compared.

Return Value

If true, the two specified display palettes are equal; otherwise, false.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
CGDirectPalette.h

CGPaletteRelease

Decrements the retain count of a display palette. (Deprecated in OS X v10.7.)

void CGPaletteRelease (
   CGDirectPaletteRef palette
);
Parameters
palette

The display palette to be released.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
CGDirectPalette.h

CGPaletteSetColorAtIndex

Updates the color value at the specified index in a display palette. (Deprecated in OS X v10.7.)

void CGPaletteSetColorAtIndex (
   CGDirectPaletteRef palette,
   CGDeviceColor color,
   uint32_t index
);
Parameters
palette

The display palette to be accessed.

color

The new color value.

index

The index of the palette entry to be updated.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
CGDirectPalette.h

Deprecated in OS X v10.8

CGRegisterScreenRefreshCallback

Registers a callback function to be invoked when local displays are refreshed or modified. (Deprecated in OS X v10.8.)

CGError CGRegisterScreenRefreshCallback (
   CGScreenRefreshCallback function,
   void *userParameter
);
Parameters
function

A pointer to the callback function to be registered.

userParameter

A pointer to user-defined data, or NULL. The userParameter argument is passed back to the callback function each time it’s invoked.

Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Discussion

A callback function may be registered multiple times with different user-defined data pointers, resulting in multiple registration entries. For each registration, when notification is no longer needed, you should call the function CGUnregisterScreenRefreshCallback to remove the registration.

The callback function you register is invoked only if your application has an active event loop. The callback is invoked in the same thread of execution that is processing events within your application.

Special Considerations

In OS X v10.4 and earlier, the result code returned by this function is a random value and should be ignored. In OS X v10.5 and later, the result code is valid.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
Declared In
CGRemoteOperation.h

CGReleaseScreenRefreshRects

Deallocates a list of rectangles that represent changed areas on local displays. (Deprecated in OS X v10.8.)

void CGReleaseScreenRefreshRects (
   CGRect *rectArray
);
Parameters
rectArray

A list of rectangles obtained by calling CGWaitForScreenRefreshRects or CGWaitForScreenUpdateRects.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
Declared In
CGRemoteOperation.h

CGScreenRegisterMoveCallback

Registers a callback function to be invoked when an area of the display is moved. (Deprecated in OS X v10.8.)

CGError CGScreenRegisterMoveCallback (
   CGScreenUpdateMoveCallback function,
   void *userParameter
);
Parameters
function

A pointer to the callback function to be registered.

userParameter

A pointer to user-defined data, or NULL. The userParameter argument is passed back to the callback function each time it’s invoked.

Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Discussion

A callback function may be registered multiple times with different user-defined data pointers, resulting in multiple registration entries. For each registration, when notification is no longer needed, you should remove the registration by calling the function CGScreenUnregisterMoveCallback.

The callback function you register is invoked only if your application has an active event loop. The callback is invoked in the same thread of execution that is processing events within your application.

Special Considerations

This function is implemented in OS X version 10.4.3 and later.

Availability
  • Available in OS X v10.3 and later.
  • Deprecated in OS X v10.8.
Declared In
CGRemoteOperation.h

CGScreenUnregisterMoveCallback

Removes a previously registered callback function invoked when an area of the display is moved. (Deprecated in OS X v10.8.)

void CGScreenUnregisterMoveCallback (
   CGScreenUpdateMoveCallback function,
   void *userParameter
);
Parameters
function

A pointer to the callback function to be unregistered.

userParameter

A pointer to user-defined data, or NULL. You should pass the same value you used when you registered the callback function.

Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Discussion

When you call this function, the two arguments must match the registered entry to be removed.

Availability
  • Available in OS X v10.3 and later.
  • Deprecated in OS X v10.8.
Declared In
CGRemoteOperation.h

CGUnregisterScreenRefreshCallback

Removes a previously registered callback function invoked when local displays are refreshed or modified. (Deprecated in OS X v10.8.)

void CGUnregisterScreenRefreshCallback (
   CGScreenRefreshCallback function,
   void *userParameter
);
Parameters
function

A pointer to the callback function to be unregistered.

userParameter

A pointer to user-defined data, or NULL. You should pass the same value you used when you registered the callback function.

Discussion

When you call this function, the two arguments must match the registered entry to be removed.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
Declared In
CGRemoteOperation.h

CGWaitForScreenRefreshRects

Waits for screen refresh operations. (Deprecated in OS X v10.8.)

CGError CGWaitForScreenRefreshRects (
   CGRect **pRectArray,
   CGRectCount *pCount
);
Parameters
pRectArray

A pointer to a CGRect* variable. On return, the variable contains an array of rectangles that bound the refreshed areas, specified in global coordinates. When you no longer need the array, you should deallocate it by calling CGReleaseScreenRefreshRects.

pCount

A pointer to a CGRectCount variable. On return, the variable contains the number of entries in the returned array of rectangles.

Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Discussion

In some applications it may be preferable to wait for screen-refresh data synchronously, using this function. You should call this function in a thread other than the main event-processing thread.

As an alternative, Quartz also supports asynchronous notification—see CGRegisterScreenRefreshCallback. If refresh callback functions are registered, this function should not be used.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
Declared In
CGRemoteOperation.h

CGWaitForScreenUpdateRects

Waits for screen update operations. (Deprecated in OS X v10.8.)

CGError CGWaitForScreenUpdateRects (
   CGScreenUpdateOperation requestedOperations,
   CGScreenUpdateOperation *currentOperation,
   CGRect **pRectArray,
   size_t *pCount,
   CGScreenUpdateMoveDelta *pDelta
);
Parameters
requestedOperations

The desired types of screen update operations. There are several possible choices:

  • Specify kCGScreenUpdateOperationRefresh if you want all move operations to be returned as refresh operations.

  • Specify (kCGScreenUpdateOperationRefresh | kCGScreenUpdateOperationMove) if you want to distinguish between move and refresh operations.

  • Add kCGScreenUpdateOperationReducedDirtyRectangleCount to the screen operations if you want to minimize the number of rectangles returned to represent changed areas of the display.

currentOperation

A pointer to a CGScreenUpdateOperation variable. On return, the variable indicates the type of update operation (refresh or move).

pRectArray

A pointer to a CGRect* variable. On return, the variable contains an array of rectangles that bound the updated areas, specified in global coordinates. When you no longer need the array, you should deallocate it by calling CGReleaseScreenRefreshRects.

pCount

A pointer to a size_t variable. On return, the variable contains the number of entries in the returned array of rectangles.

pDelta

A pointer to a CGScreenUpdateMoveDelta variable. On return, if the value of the currentOperation parameter is kCGScreenUpdateOperationMove, the variable contains the distance moved.

Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Discussion

In some applications it may be preferable to wait for screen-update data synchronously, using this function. You should call this function in a thread other than the main event-processing thread.

As an alternative, Quartz also supports asynchronous notification—see CGRegisterScreenRefreshCallback and CGScreenRegisterMoveCallback. If refresh or move callback functions are registered, this function should not be used.

Special Considerations

This function is implemented in OS X version 10.4.3 and later.

Availability
  • Available in OS X v10.3 and later.
  • Deprecated in OS X v10.8.
Declared In
CGRemoteOperation.h

CGWindowServerCFMachPort

Returns a Core Foundation Mach port (CFMachPort) that corresponds to the OS X window server. (Deprecated in OS X v10.8.)

CFMachPortRef CGWindowServerCFMachPort (
   void
);
Return Value

A Core Foundation Mach port, or NULL if the window server is not running. When you no longer need the port, you should release it using the function CFRelease.

Discussion

You can use this function to detect whether the window server process exits or is not running. If this function returns NULL, the window server is not running. This code example shows how to register a callback function to detect when the window server exits:

static void handleWindowServerDeath( CFMachPortRef port, void *info  )
{
    printf( "Window Server port death detected!\n" );
    CFRelease(port);
    exit(1);
}
 
static void watchForWindowServerDeath()
{
    CFMachPortRef port = CGWindowServerCFMachPort();
    CFMachPortSetInvalidationCallBack(port, handleWindowServerDeath);
}

Note that this callback only works if your program has an active run loop.

Availability
  • Available in OS X v10.1 and later.
  • Deprecated in OS X v10.8.
Declared In
CGRemoteOperation.h


© 2006, 2010 Apple Inc. All Rights Reserved. (Last updated: 2010-09-27)

Did this document help you? Yes It's good, but... Not helpful...