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:
Examine and change display modes
Configure a set of displays in a single operation
Capture one or more displays for exclusive use
Perform fade effects
Activate display mirroring
Configure gamma color correction tables and color palettes
Receive notification of screen update operations
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:
Choose a different display resolution
Change the bits per pixel of a display, which determines how many colors can be displayed
Set the refresh rate of a CRT monitor
On a system with two or more attached monitors, the Arrangement pane shown in Figure 2 contains controls that allow the user to:
Rearrange the displays on the extended desktop
Change the main display by moving the menu bar from one display to another
Create a display mirroring set
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:
A display is active if it is awake and available for drawing.
A display is mirroring another display if the same content is drawn to both displays simultaneously. You cannot draw on the mirroring display.
A display is sleeping when its frame buffer and the attached monitor are in reduced power mode. A sleeping display is still considered to be a part of global display space, but you cannot draw on it.
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:
CGGetDisplaysWithPointobtains the display IDs for online displays whose bounds include a specified point.CGGetDisplaysWithRectobtains the display IDs for online displays whose bounds include a specified rectangle.CGGetDisplaysWithOpenGLDisplayMaskobtains the display IDs for online displays that correspond to the bits set in an OpenGL display mask.
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.
© 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-06-28)