Next Previous

Getting Information About Displays

Quartz Display Services provides a number of functions to retrieve information about display state and display modes. This article briefly covers a few of these functions. For a complete list, see Quartz Display Services Reference.

Getting Display State Information (OS X v10.6 or later)

Quartz Display Services includes accessor functions that report current properties of the display hardware, properties that are also found in the current display mode. Because these functions do not rely on information from the current display mode, they provide the most accurate information available about the display (display mode properties are subject to change by the device driver). These functions, listed next, are straightforward to use:

Function	Description
`CGDisplayPixelsWide`	Returns the drawable width of a display in pixel units.
`CGDisplayPixelsHigh`	Returns the drawable height of a display in pixel units.

The API includes other accessor functions that report additional information about the current configuration and state of the display. The following table lists a representative sample of these functions:

Function	Description
`CGDisplayIsActive`	Returns a Boolean value indicating whether a display is active or drawable).
`CGDisplayIsBuiltin`	Returns a Boolean value indicating whether a display is built-in, such as the internal display in portable systems.
`CGDisplayIsMain`	Returns a Boolean value indicating whether a display is the main display.
`CGDisplayScreenSize`	Returns the width and height of a display in millimeters.
`CGDisplayUsesOpenGLAcceleration`	Returns a Boolean value indicating whether Quartz is using OpenGL-based window acceleration (Quartz Extreme) to render in a display.

Getting Display State Information (OS X v10.5)

Quartz Display Services includes several accessor functions that report current properties of the display hardware, properties that are also found in the current display mode dictionary. Because these functions do not rely on information from the current display mode, they provide the most accurate information available about the display (display mode properties are subject to change by the device driver). These functions, listed next, are straightforward to use:

Function	Description
`CGDisplayPixelsWide`	Returns the drawable width of a display in pixel units.
`CGDisplayPixelsHigh`	Returns the drawable height of a display in pixel units.
`CGDisplayBitsPerPixel`	Returns the number of bits used to represent a pixel in the frame buffer.
`CGDisplayBitsPerSample`	Returns the number of bits used to represent a pixel component in the frame buffer.
`CGDisplaySamplesPerPixel`	Returns the number of components used to represent a pixel in the frame buffer.
`CGDisplayBytesPerRow`	Returns the number of bytes per row in the frame buffer.

Function	Description
`CGDisplayIsActive`	Returns a Boolean value indicating whether a display is active or drawable).
`CGDisplayIsBuiltin`	Returns a Boolean value indicating whether a display is built-in, such as the internal display in portable systems.
`CGDisplayIsMain`	Returns a Boolean value indicating whether a display is the main display.
`CGDisplayScreenSize`	Returns the width and height of a display in millimeters.
`CGDisplayUsesOpenGLAcceleration`	Returns a Boolean value indicating whether Quartz is using OpenGL-based window acceleration (Quartz Extreme) to render in a display.

Getting Display Mode Information (OS X v10.6 or later)

Each online display has a current display mode and a set of available display modes. The device driver uses information in the current display mode to configure the display.

You can retrieve the values of the properties in a display mode with the appropriate CGDisplayMode function. Listing 1 shows how to retrieve several mode properties.

Listing 1 Getting display mode properties on OS X v10.6 or later

bool gui;

double refresh;

uint32_t ioflags;

CGDisplayModeRef currentMode = CGDisplayCopyDisplayMode(kCGDirectMainDisplay);

refresh = CGDisplayModeGetRefreshRate(currentMode);

gui = CGDisplayModeIsUsableForDesktopGUI(currentMode);

ioflags = CGDisplayModeGetIOFlags(currentMode);

CGDisplayModeRelease(currentMode);

Getting Display Mode Information (OS X v10.5)

Each online display has a current display mode and a set of available display modes. The device driver uses information in the current display mode to configure the display.

You can retrieve the values of the properties in a display mode dictionary with the CFDictionaryGetValue function. Then, you may need to cast the returned value to the appropriate data type. Listing 1 shows how to retrieve several mode properties and cast them to a base data type.

Listing 2 Getting display mode properties on OS X v10.5

CFNumberRef number;

CFBoolean booleanValue;

Boolean gui;

long mode, refresh, ioflags;

CFDictionaryRef currentMode = CGDisplayCurrentMode (kCGDirectMainDisplay);

number = CFDictionaryGetValue (currentMode, kCGDisplayMode);

CFNumberGetValue (number, kCFNumberLongType, &mode);

number = CFDictionaryGetValue (currentMode, kCGDisplayRefreshRate);

CFNumberGetValue (number, kCFNumberLongType, &refresh);

booleanValue = CFDictionaryGetValue (currentMode, kCGDisplayModeUsableForDesktopGUI);

gui = CFBooleanGetValue (booleanValue);

number = CFDictionaryGetValue (currentMode, kCGDisplayIOFlags);

CFNumberGetValue (number, kCFNumberLongType, &ioflags);

Next Previous