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 framebuffer, a gamma correction table or color palette, and possibly an attached monitor.)
For example, Mac apps 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
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. Cocoa automatically detects these state changes and makes adjustments to the size, position, and layout of windows on the affected displays.
OS X System Preferences uses Quartz Display Services to perform some of the actions in the Displays preferences pane. For example, the Display pane contains controls that allow the user to switch display modes to a different display resolution.
On a system with two or more attached monitors, the Arrangement pane shown in Figure 1 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.
Display States
A display is considered to be online when the framebuffer hardware is connected to a monitor. If no monitor is attached to the framebuffer, 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 framebuffer 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 typically remains constant until the machine is restarted. 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 (OS X v10.6 or later)
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 an instance of the CGDisplayMode opaque type. To find out what modes a display supports, you use the function CGDisplayCopyAllDisplayModes, which returns an array of display modes. To find out the current display mode for an online display, you use the function CGDisplayCopyDisplayMode, which returns a single display mode. A display mode contains a set of properties that you can query using Quartz Display Services CGDisplayMode functions. You are responsible for releasing the display mode when you are finished with it.
Display modes are read-only. If you want to change a specific display property such as resolution, you need to find the appropriate display mode and use it to change the mode of the display. You can use CGDisplaySetDisplayMode, a convenience function for changing the mode of a single display. For more information, see Changing Display Modes (OS X v10.6 or later).
Display Modes (OS X v10.5)
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 (OS X v10.5).
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 framebuffer in two or more displays simultaneously. In software mirroring, identical content is drawn into the framebuffer 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.
Copyright © 2013 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2013-12-16