< Previous PageNext Page > Hide TOC

Overview of Quartz Display Services

Quartz Display Services is a set of system software functions that support dynamic changes to the arrangement and display modes of the displays attached to a user’s computer, as well as other display-related operations. (In this document, the term display refers to a graphics hardware system consisting of a frame buffer, a gamma correction table or color palette, and possibly an attached monitor.)

For example, Mac OS X applications can use Quartz Display Services to:

Unlike the Carbon Display Manager, Quartz Display Services is a low-level API. User interface elements such as windows are not automatically repositioned when monitors are detached or display modes change. Instead, Quartz provides a notification mechanism for display state changes. High-level application frameworks such as Carbon and Cocoa can detect these state changes and make their own adjustments to the size, position, and layout of windows on the affected displays.

Mac OS X System Preferences uses Quartz Display Services to perform some of the actions in the Displays preferences pane. For example, the Display pane shown in Figure 1 contains controls that allow the user to switch display modes. The user can:


Figure 1  A Display pane

A Display pane

On a system with two or more attached monitors, the Arrangement pane shown in Figure 2 contains controls that allow the user to:


Figure 2  An Arrangement pane

An Arrangement pane

The next few sections introduce some basic features of displays, along with some of the more important functions in the Quartz Display Services API. The other articles in this document contain examples that show how to use this API to perform some common operations.

Contents:

Display States
Display IDs
Display Modes
Display Arrangement
Display Mirroring


Display States

A display is considered to be online when the frame buffer hardware is connected to a monitor. If no monitor is attached to the frame buffer, a display is characterized as offline.

When a display is online, the display is mapped into the global display (desktop) coordinate system. The upper-left corner of a display is called the origin. The origin of a display is always specified in global display (desktop) coordinates.

The display with the origin at (0,0) is called the main or primary display. In a system without display mirroring, the display with the menu bar is typically the main display. The user can change the main display by dragging the menu bar to a different display in Displays preferences.

An online display can be active, mirroring, or sleeping. These terms are defined as follows:

Display IDs

When a monitor is attached and a display is online, Quartz assigns a unique display identifier (ID) of type CGDirectDisplayID. A display ID can persist across processes and system reboot, and typically remains constant as long as certain display parameters do not change. You can obtain an array of display IDs that correspond to all online displays in the system with the function CGGetOnlineDisplayList.

Typically you're more interested in active displays because they're available for drawing. You can obtain an array of display IDs that correspond to all active displays in the system with the function CGGetActiveDisplayList. The first display in the list is always the main display. The main display is also represented by the constant kCGDirectMainDisplay, which is defined as a call to the function CGMainDisplayID.

These functions also obtain an array of display IDs:

Display Modes

Every display has a set of supported modes of operation. A display mode is a set of standard properties such as resolution (width and height in pixels), bits per pixel, and refresh rate, and optional properties such as pixel stretching to fill the screen.

Each display mode is represented by a display mode dictionary. To find out what modes a display supports, you use the function CGDisplayAvailableModes, which returns a list of mode dictionaries. To find out the current display mode for an online display, you use the function CGDisplayCurrentMode, which returns a single mode dictionary. A display mode dictionary contains a set of key-value pairs that you can query using Core Foundation CFDictionary functions.

To find the optimal mode for a selected set of properties, you can use the function CGDisplayBestModeForParameters. For example, if you request a supported mode for a display with a resolution of 750 x 550 pixels and 24 bits per pixel, this function may return a supported mode with resolution of 800 x 600 pixels and 32 bits per pixel.

Mode dictionaries are read-only. If you want to change a specific display property such as resolution, you need to find the appropriate mode dictionary and use it to change the mode of the display. You can use CGDisplaySwitchToMode, a convenience function for changing the mode of a single display. For more information, see “Changing Display Modes.”

Display Arrangement

On systems with multiple displays, your application can control the arrangement of the displays in the global display space. This is done by setting the origin of each display with the function CGConfigureDisplayOrigin. The new origins are placed as close as possible to the requested locations, without overlapping or leaving a gap between displays. You can also use this function to designate a display as the main display by setting its origin to (0,0). For more information about using this function, see “Configuring Displays Using a Transaction.”

When your application terminates, the display arrangement returns to the current settings in Displays preferences.

Display Mirroring

On systems with multiple displays, your application can draw the same content to two or more displays simultaneously. This is called mirroring, and the displays are said to be in a mirroring set. You can create or change the configuration of a mirroring set with the function CGConfigureDisplayMirrorOfDisplay. One display is designated the main or primary display in the mirroring set, and all drawing is directed to this display. For more information about using this function, see “Configuring Displays Using a Transaction.”

Display mirroring and display matte generation are implemented either in hardware (preferred) or software, at the discretion of the device driver. In hardware mirroring, the graphics hardware renders the contents of a single frame buffer in two or more displays simultaneously. In software mirroring, identical content is drawn into the frame buffer of each display in the mirroring set. The display with the highest resolution and deepest pixel depth typically becomes the main display.

Quartz makes sure that all window-based content is placed on all displays in a mirroring set. Applications that draw in windows need not be concerned about supporting mirroring. Applications drawing directly to the display may need to implement a traditional device loop to properly support mirroring.



< Previous PageNext Page > Hide TOC


© 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-06-28)


Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.