Deprecated Quartz Display Services Functions

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

Deprecated in Mac OS X v10.6

CGConfigureDisplayMode

Configures the display mode of a display. (Deprecated in Mac OS X v10.6.)

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

Parameters

configRef

A display configuration, acquired by calling CGBeginDisplayConfiguration.

display

The display being configured.

mode

A display mode dictionary (see the discussion below).

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:

• A dictionary returned by one of the CGDisplayBestMode functions, such as CGDisplayBestModeForParameters.

• A dictionary in the array returned by CGDisplayAvailableModes.

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.

CGDisplayAddressForPosition

Returns the address in frame buffer memory that corresponds to a position on an online display. (Deprecated in Mac OS X v10.6.)

void * CGDisplayAddressForPosition (
   CGDirectDisplayID display,
   CGDisplayCoord x,
   CGDisplayCoord y
);

Parameters

display

The display to access.

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.

Discussion

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

CGDisplayAvailableModes

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

CFArrayRef CGDisplayAvailableModes (
   CGDirectDisplayID display
);

Parameters

display

The display to access.

Related Sample Code

• GLUT
• VBL

CGDisplayBaseAddress

Returns the base address in frame buffer memory of an online display. (Deprecated in Mac OS X v10.6.)

void * CGDisplayBaseAddress (
   CGDirectDisplayID display
);

Parameters

display

The display to access.

Discussion

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

CGDisplayBestModeForParameters

Returns information about the display mode closest to a specified depth and screen size. (Deprecated in Mac OS X v10.6.)

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

Parameters

display

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.

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.

CGDisplayBestModeForParametersAndRefreshRate

Returns information about the display mode closest to a specified depth, screen size, and refresh rate. (Deprecated in Mac OS X v10.6.)

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

Parameters

display

The display to access.

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.

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.

Related Sample Code

• GLUT
• VBL

CGDisplayBestModeForParametersAndRefreshRateWithProperty

Returns information about the display mode closest to a specified depth, screen size, and refresh rate, with a required property. (Deprecated in Mac OS X v10.6.)

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

Parameters

display

The display to access.

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.

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.

CGDisplayBitsPerPixel

Returns the number of bits used to represent a pixel in the frame buffer. (Deprecated in Mac OS X v10.6.)

size_t CGDisplayBitsPerPixel (
   CGDirectDisplayID display
);

Parameters

display

The display to access.

CGDisplayBitsPerSample

Returns the number of bits used to represent a pixel component in the frame buffer. (Deprecated in Mac OS X v10.6.)

size_t CGDisplayBitsPerSample (
   CGDirectDisplayID display
);

Parameters

display

The display to access.

CGDisplayBytesPerRow

Returns the number of bytes per row in a display. (Deprecated in Mac OS X v10.6.)

size_t CGDisplayBytesPerRow (
   CGDirectDisplayID display
);

Parameters

display

The display to access.

CGDisplayCurrentMode

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

CFDictionaryRef CGDisplayCurrentMode (
   CGDirectDisplayID display
);

Parameters

display

The display to access.

Related Sample Code

• Cocoa OpenGL
• GLUT
• OpenGL Screensaver
• VBL

CGDisplaySamplesPerPixel

Returns the number of color components used to represent a pixel. (Deprecated in Mac OS X v10.6.)

size_t CGDisplaySamplesPerPixel (
   CGDirectDisplayID display
);

Parameters

display

The display to access.

CGDisplaySwitchToMode

Switches a display to a different mode. (Deprecated in Mac OS X v10.6.)

CGDisplayErr CGDisplaySwitchToMode (
   CGDirectDisplayID display,
   CFDictionaryRef mode
);

Parameters

display

The display to access.

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.

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: call CGBeginDisplayConfiguration, call CGConfigureDisplayMode for each display to explicitly set the mode, and finally call CGCompleteDisplayConfiguration.

Related Sample Code

• GLUT
• VBL

---