Quartz Display Services Reference

Framework
ApplicationServices/ApplicationServices.h
Companion guide
Declared in
CGDirectDisplay.h
CGDisplayConfiguration.h
CGDisplayFade.h
CGDisplayStream.h
CGRemoteOperation.h
CGSession.h
CGWindowLevel.h

Overview

Quartz Display Services provides direct access to certain low-level features in the OS X window server related to the configuration and control of display hardware. For example, you can use Quartz Display Services to:

Functions by Task

Finding Displays

Capturing and Releasing Displays

Creating Images from the Display

Configuring Displays

Getting the Display Configuration

Registering for Notification of Display Configuration Changes

These functions are used to register and unregister a callback function for notification of display configuration changes.

Retrieving Display Parameters

Creating and Managing Display Modes

Getting Information About a Display Mode

Adjusting the Display Gamma

Display Fade Effects

Controlling the Mouse Cursor

Getting Window Server Information

Getting Information About Refresh and Move Operations

You can use these functions to find out what areas on local displays are changing their appearance as the result of operations such as drawing, window movement or scrolling, and display reconfiguration.

Streaming the Contents of a Display

Functions

CGAcquireDisplayFadeReservation

Reserves the fade hardware for a specified time interval.

CGError CGAcquireDisplayFadeReservation (
   CGDisplayReservationInterval seconds,
   CGDisplayFadeReservationToken *pNewToken
);
Parameters
seconds

The desired number of seconds to reserve the fade hardware. An application can specify any value in the interval (0, kCGMaxDisplayReservationInterval].

pNewToken

A pointer to storage (provided by the caller) for a fade reservation token. On return, the storage contains a new token.

Return Value

Returns kCGErrorNoneAvailable if another fade reservation is in effect. Otherwise, returns kCGErrorSuccess.

Discussion

Before performing a fade operation, an application must reserve the fade hardware for a specified period of time. Quartz returns a token that represents a new fade reservation. The application uses this token as an argument in subsequent calls to other display fade functions.

During the fade reservation interval, the application has exclusive rights to use the fade hardware. At the end of the interval, the token becomes invalid and the hardware automatically returns to a normal state. Typically, the application calls CGReleaseDisplayFadeReservation to release the fade reservation before it expires.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGDisplayFade.h

CGAssociateMouseAndMouseCursorPosition

Connects or disconnects the mouse and cursor while an application is in the foreground.

CGError CGAssociateMouseAndMouseCursorPosition (
   boolean_t connected
);
Parameters
connected

Pass true if the mouse and cursor should be connected; otherwise, pass false.

Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Discussion

When you call this function to disconnect the cursor and mouse, all events received by your application have a constant absolute location but contain mouse delta (change in X and Y) data. You may hide the cursor or change it into something appropriate for your application. You can reposition the cursor by using the function CGDisplayMoveCursorToPoint or the function CGWarpMouseCursorPosition.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGRemoteOperation.h

CGBeginDisplayConfiguration

Begins a new set of display configuration changes.

CGError CGBeginDisplayConfiguration (
   CGDisplayConfigRef *pConfigRef
);
Parameters
pConfigRef

A pointer to storage you provide for a display configuration. On return, your storage contains a new display configuration.

Return Value

A result code. If the object is successfully created, the result is kCGErrorSuccess. For other possible values, see Core Graphics Data Types and Constants Reference.

Discussion

This function creates a display configuration object that provides a context for a set of display configuration changes. After you specify the desired changes, you use CGCompleteDisplayConfiguration to apply them in a single transaction.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGDisplayConfiguration.h

CGCancelDisplayConfiguration

Cancels a set of display configuration changes.

CGError CGCancelDisplayConfiguration (
   CGDisplayConfigRef configRef
);
Parameters
configRef

The display configuration to cancel. On return, the configuration is canceled and is no longer valid.

Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Discussion

This function is used to abandon a display configuration. As a side effect, the display configuration object is released.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGDisplayConfiguration.h

CGCaptureAllDisplays

Captures all attached displays.

CGError CGCaptureAllDisplays (
   void
);
Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Discussion

This function captures all attached displays in a single operation. This operation provides an immersive environment for your application, and it prevents other applications from trying to adjust to display changes.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
CGDirectDisplay.h

CGCaptureAllDisplaysWithOptions

Captures all attached displays, using the specified options.

CGError CGCaptureAllDisplaysWithOptions (
   CGCaptureOptions options
);
Parameters
options

The options to use. See “Display Capture Options.”

Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Discussion

This function allows you to specify one or more options to use during capture of all attached displays.

Availability
  • Available in OS X v10.3 and later.
Declared In
CGDirectDisplay.h

CGCompleteDisplayConfiguration

Completes a set of display configuration changes.

CGError CGCompleteDisplayConfiguration (
   CGDisplayConfigRef configRef,
   CGConfigureOption option
);
Parameters
configRef

The display configuration with the desired changes. On return, this configuration is no longer valid.

option

The scope of the display configuration changes. Pass one of the constants listed in “Display Configuration Scopes.”

Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Discussion

This function applies a set of display configuration changes as a single atomic transaction. The duration or scope of the changes depends on the value of the option parameter. The possible scopes are fully described in “Display Configuration Scopes.”

A configuration change may fail if an unsupported display mode is requested or if another application is running in full-screen mode.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGDisplayConfiguration.h

CGConfigureDisplayFadeEffect

Modifies the settings of the built-in fade effect that occurs during a display configuration.

CGError CGConfigureDisplayFadeEffect (
   CGDisplayConfigRef configRef,
   CGDisplayFadeInterval fadeOutSeconds,
   CGDisplayFadeInterval fadeInSeconds,
   float fadeRed,
   float fadeGreen,
   float fadeBlue
);
Parameters
configRef

A display configuration, acquired by calling CGBeginDisplayConfiguration.

fadeOutSeconds

The time, in seconds, to fade from the normal display to the specified fade color. The fade out is completed before the display configuration is changed. If the interval is 0, Quartz applies the color immediately.

fadeInSeconds

The time, in seconds, to return from the specified fade color to the normal display. The fade-in is run asynchronously after the display configuration is changed.

fadeRed

An intensity value in the interval [0, 1] that represents the red component of the desired blend color.

fadeGreen

An intensity value in the interval [0, 1] that represents the green component of the desired blend color.

fadeBlue

An intensity value in the interval [0, 1] that represents the blue component of the desired blend color.

Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Discussion

This function provides a way to customize the built-in fade effect that Quartz performs when displays are reconfigured. The default time settings for this fade effect are 0.3 seconds to fade out, and 0.5 seconds to fade back in. The default fade color is French Blue for a normal desktop, and black for a captured display.

Before using this function, you need to call CGBeginDisplayConfiguration to acquire the display configuration token for the desired display. No fade reservation is needed—when you call CGCompleteDisplayConfiguration, Quartz reserves the fade hardware (assuming it is available) and performs the fade.

Calling this function modifies the fade behavior for a single display configuration and has no permanent effect.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGDisplayFade.h

CGConfigureDisplayMirrorOfDisplay

Changes the configuration of a mirroring set.

CGError CGConfigureDisplayMirrorOfDisplay (
   CGDisplayConfigRef configRef,
   CGDirectDisplayID display,
   CGDirectDisplayID masterDisplay
);
Parameters
configRef

A display configuration, acquired by calling CGBeginDisplayConfiguration.

display

The identifier of the display to add to a mirroring set.

masterDisplay

A display in a mirroring set, or kCGNullDirectDisplay to disable mirroring. To specify the main display, use CGMainDisplayID.

Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Discussion

Display mirroring and display matte generation are implemented either in hardware (preferred) or software, at the discretion of the device driver.

  • Hardware mirroring

    With hardware mirroring enabled, all drawing is directed to the primary display—see CGDisplayPrimaryDisplay.

    If the device driver selects hardware matte generation, the display bounds and row-bytes values are adjusted to reflect the active drawable area.

  • Software mirroring

    In this form of mirroring, identical content is drawn into each display in the mirroring set. Applications that use the window system need not be concerned about mirroring, as the window system takes care of all flushing of window content to the appropriate displays.

    Applications that draw directly to the display, as with display capture, must make sure to draw the same content to all mirrored displays in a software mirror set. When drawing to software mirrored displays using a full screen OpenGL context (not drawing through a window), you should create shared OpenGL contexts for each display and rerender for each display.

You can use the function CGGetActiveDisplayList to determine which displays are active, or drawable. This automatically gives your application the correct view of the current displays.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGDisplayConfiguration.h

CGConfigureDisplayOrigin

Configures the origin of a display in the global display coordinate space.

CGError CGConfigureDisplayOrigin (
   CGDisplayConfigRef configRef,
   CGDirectDisplayID display,
   int32_t x,
   int32_t y
);
Parameters
configRef

A display configuration, acquired by calling CGBeginDisplayConfiguration.

display

The identifier of the display being configured.

x

The desired x-coordinate for the upper-left corner of the display.

y

The desired y-coordinate for the upper-left corner of the display.

Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Discussion

In Quartz, the upper-left corner of a display is called the origin. The origin of a display is always specified in the global display coordinate space. The origin of the main or primary display is (0,0).

The new origin is placed as close as possible to the requested location, without overlapping or leaving a gap between displays.

If you use this function to change the origin of a mirrored display, the display may be removed from the mirroring set.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGDisplayConfiguration.h

CGConfigureDisplayStereoOperation

Enables or disables stereo operation for a display, as part of a display configuration.

CGError CGConfigureDisplayStereoOperation (
   CGDisplayConfigRef configRef,
   CGDirectDisplayID display,
   boolean_t stereo,
   boolean_t forceBlueLine
);
Parameters
configRef

A display configuration, acquired by calling CGBeginDisplayConfiguration.

display

The identifier of the display being configured.

stereo

Pass true if you want to enable stereo operation. To disable it, pass false.

forceBlueLine

When in stereo operation, a display may need to generate a special stereo sync signal as part of the video output. The sync signal consists of a blue line which occupies the first 25% of the last scan line for the left eye view, and the first 75% of the last scan line for the right eye view. The remainder of the scan line is black. To force the display to generate this sync signal, pass true; otherwise, pass false.

Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Discussion

The system normally detects the presence of a stereo window and automatically switches a display containing a stereo window to stereo operation. This function provides a mechanism to force a display to stereo operation, and to set options (blue line sync signal) when in stereo operation.

On success, the display resolution, mirroring mode, and available display modes may change due to hardware-specific capabilities and limitations. You should check these settings to verify that they are appropriate for your application.

Availability
  • Available in OS X v10.4 and later.
Declared In
CGDisplayConfiguration.h

CGConfigureDisplayWithDisplayMode

Configures the display mode of a display.

CGError CGConfigureDisplayWithDisplayMode(
   CGDisplayConfigRef config,
   CGDirectDisplayID display,
   CGDisplayModeRef mode,
   CFDictionaryRef options
);
Parameters
config

A display configuration, acquired by calling CGBeginDisplayConfiguration.

display

The identifier of the display being configured.

mode

A display mode to configure.

options

Reserved for future expansion. Pass NULL for now.

Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Discussion

This function is called to specify a display mode with which to configure the display using a transaction. Before using this function, call CGBeginDisplayConfiguration to acquire the display configuration token for the desired display. When the transaction is prepared, call CGCompleteDisplayConfiguration to execute it.

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.

Availability
  • Available in OS X v10.6 and later.
Declared In
CGDisplayConfiguration.h

CGDisplayBounds

Returns the bounds of a display in the global display coordinate space.

CGRect CGDisplayBounds (
   CGDirectDisplayID display
);
Parameters
display

The identifier of the display to be accessed.

Return Value

The bounds of the display, expressed as a rectangle in the global display coordinate space (relative to the upper-left corner of the main display).

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
CGDirectDisplay.h

CGDisplayCapture

Captures a display for exclusive use by an application.

CGError CGDisplayCapture (
   CGDirectDisplayID display
);
Parameters
display

The identifier of the display to be captured.

Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Discussion

When an application captures a display, Quartz does not allow other applications and system services to use the display or change its configuration.

If hardware or software mirroring is in effect, the easiest way to capture the primary display and all mirrored displays is to use the function CGCaptureAllDisplays. In case of software mirroring, applications that draw directly to the display must make sure to draw the same content to all displays in the mirror set.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGDirectDisplay.h

CGDisplayCaptureWithOptions

Captures a display for exclusive use by an application, using the specified options.

CGError CGDisplayCaptureWithOptions (
   CGDirectDisplayID display,
   CGCaptureOptions options
);
Parameters
display

The identifier of the display to be captured.

options

The options to use. See “Display Capture Options.”

Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Discussion

This function allows you to specify one or more options to use during capture of a display.

Availability
  • Available in OS X v10.3 and later.
Declared In
CGDirectDisplay.h

CGDisplayCopyAllDisplayModes

Returns information about the currently available display modes.

CFArrayRef CGDisplayCopyAllDisplayModes(
   CGDirectDisplayID display,
   CFDictionaryRef options
);
Parameters
display

The identifier of the display to be accessed.

options

Reserved for future expansion. Pass NULL for now.

Return Value

An array of display modes that the display supports, or NULL if the display is invalid. The caller is responsible for releasing the array. For more information on accessing the properties of a display mode, see “Getting Information About a Display Mode.”

Availability
  • Available in OS X v10.6 and later.
Declared In
CGDirectDisplay.h

CGDisplayCopyColorSpace

Returns the color space for a display.

CGColorSpaceRef CGDisplayCopyColorSpace (
   CGDirectDisplayID display
);
Parameters
display

The identifier of the display whose color space you want to obtain.

Return Value

The current color space for the specified display. The caller is responsible for releasing the color space with the CGColorSpaceRelease function.

Discussion

This function returns a display-dependent ICC-based color space. You can use this function when rendering content for a specific display in order to produce color-matched output for that display.

Availability
  • Available in OS X v10.5 and later.
Related Sample Code
Declared In
CGDisplayConfiguration.h

CGDisplayCopyDisplayMode

Returns information about a display’s current configuration.

CGDisplayModeRef CGDisplayCopyDisplayMode(
   CGDirectDisplayID display
);
Parameters
display

The identifier of the display to be accessed.

Return Value

A display-mode opaque-type reference, or NULL if the display is invalid. The caller is responsible for releasing the display mode using CGDisplayModeRelease.

Availability
  • Available in OS X v10.6 and later.
Declared In
CGDirectDisplay.h

CGDisplayCreateImage

Returns an image containing the contents of the specified display.

CGImageRef CGDisplayCreateImage(
   CGDirectDisplayID displayID
);
Parameters
display

The identifier of the display for which an image is being created.

Return Value

An image containing the contents of the specified display. If the display ID is invalid, the return value is NULL. The caller is responsible for releasing the image created by calling CGImageRelease.

Availability
  • Available in OS X v10.6 and later.
Related Sample Code
Declared In
CGDirectDisplay.h

CGDisplayCreateImageForRect

Returns an image containing the contents of a portion of the specified display.

CGImageRef CGDisplayCreateImageForRect(
   CGDirectDisplayID displayID
   CGRect rect
);
Parameters
display

The identifier of the display to be accessed.

rect

The rectangle, specified in display space, for the portion of the display being copied into the image.

Return Value

An image containing the contents of the specified rectangle. If the display ID is invalid, the return value is NULL. The caller is responsible for releasing the image created by calling CGImageRelease.

Discussion

The actual rectangle used is the rectangle returned by CGRectIntegral with rect as a parameter.

Availability
  • Available in OS X v10.6 and later.
Declared In
CGDirectDisplay.h

CGDisplayFade

Performs a single fade operation.

CGError CGDisplayFade (
   CGDisplayFadeReservationToken myToken,
   CGDisplayFadeInterval seconds,
   CGDisplayBlendFraction startBlend,
   CGDisplayBlendFraction endBlend,
   float redBlend,
   float greenBlend,
   float blueBlend,
   boolean_t synchronous
);
Parameters
myToken

A reservation token for the fade hardware, acquired by calling CGAcquireDisplayFadeReservation.

seconds

The desired number of seconds for the fade operation. You should use a value in the interval [0, kCGMaxDisplayReservationInterval]. If the value is 0, the ending blend color is applied immediately.

startBlend

An intensity value in the interval [0, 1] that specifies the alpha component of the desired blend color at the beginning of the fade operation. See “Display Fade Blend Fractions.”

endBlend

An intensity value in the interval [0, 1] that specifies the alpha component of the desired blend color at the end of the fade operation. See “Display Fade Blend Fractions.”

redBlend

An intensity value in the interval [0, 1] that specifies the red component of the desired blend color.

greenBlend

An intensity value in the interval [0, 1] that specifies the green component of the desired blend color.

blueBlend

An intensity value in the interval [0, 1] that specifies the blue component of the desired blend color.

synchronous

Pass true if you want the fade operation to be synchronous; otherwise, pass false. If a fade operation is synchronous, the function does not return until the operation is complete.

Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Discussion

Over the fade operation time interval, Quartz interpolates a blending coefficient between the starting and ending values given, applying a nonlinear (sine-based) bias term. Using this coefficient, the video output is blended with the specified color.

The following example shows how to perform a 2-second synchronous fade-out to black:

CGDisplayFade (
    myToken,
    2.0,                        // 2 seconds
    kCGDisplayBlendNormal,      // starting state
    kCGDisplayBlendSolidColor,  // ending state
    0.0, 0.0, 0.0,              // black
    true                        // wait for completion
);

To perform a 2-second asynchronous fade-in from black:

CGDisplayFade (
    myToken,
    2.0,                        // 2 seconds
    kCGDisplayBlendSolidColor,  // starting state
    kCGDisplayBlendNormal,      // ending state
    0.0, 0.0, 0.0,              // black
    false                       // don't wait for completion
);

If you specify an asynchronous fade operation, it’s safe to call CGReleaseDisplayFadeReservation immediately after this function returns.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGDisplayFade.h

CGDisplayGammaTableCapacity

Returns the capacity, or number of entries, in the gamma table for a display.

uint32_t CGDisplayGammaTableCapacity (
   CGDirectDisplayID display
);
Parameters
display

The identifier of the display to be accessed.

Return Value

The number of entries in the gamma table for a display.

Availability
  • Available in OS X v10.3 and later.
Declared In
CGDirectDisplay.h

CGDisplayGetDrawingContext

Returns a graphics context suitable for drawing to a captured display.

CGContextRef CGDisplayGetDrawingContext (
   CGDirectDisplayID display
);
Parameters
display

The identifier of the display to be accessed.

Return Value

A Quartz graphics context suitable for drawing to a captured display, or NULL if the display has not been captured. The context is owned by the system and you should not release it.

Discussion

After capturing a display or changing the configuration of a captured display, you can use this function to obtain the current graphics context for the display. The graphics context remains valid while the display is captured and the display configuration is unchanged. Releasing the captured display or reconfiguring the display invalidates the context. To determine when the display configuration is changing, you can use the function CGDisplayRegisterReconfigurationCallback to register a display reconfiguration callback.

Availability
  • Available in OS X v10.3 and later.
Declared In
CGDirectDisplay.h

CGDisplayHideCursor

Hides the mouse cursor, and increments the hide cursor count.

CGError CGDisplayHideCursor (
   CGDirectDisplayID display
);
Parameters
display

This parameter is not used. By default, you may pass kCGDirectMainDisplay.

Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Discussion

This function hides the cursor regardless of its current location; the display parameter is ignored. In most cases, the caller must be the foreground application to affect the cursor.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGDirectDisplay.h

CGDisplayIDToOpenGLDisplayMask

Maps a display ID to an OpenGL display mask.

CGOpenGLDisplayMask CGDisplayIDToOpenGLDisplayMask (
   CGDirectDisplayID display
);
Parameters
display

The display ID to be converted.

Return Value

The OpenGL display mask that corresponds to the specified display.

Discussion

OpenGL sometimes identifies a display using a bitmask with one bit set. This function maps a display ID to the corresponding OpenGL display mask.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGDirectDisplay.h

CGDisplayIsActive

Returns a Boolean value indicating whether a display is active.

boolean_t CGDisplayIsActive (
   CGDirectDisplayID display
);
Parameters
display

The identifier of the display to be accessed.

Return Value

If true, the specified display is active; otherwise, false.

Discussion

An active display is connected, awake, and available for drawing. In a hardware mirroring set, only the primary display is active.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGDisplayConfiguration.h

CGDisplayIsAlwaysInMirrorSet

Returns a Boolean value indicating whether a display is always in a mirroring set.

boolean_t CGDisplayIsAlwaysInMirrorSet (
   CGDirectDisplayID display
);
Parameters
display

The identifier of the display to be accessed.

Return Value

If true, the specified display is in a mirroring set and cannot be removed from this set.

Discussion

Some hardware configurations support the connection of auxiliary displays that always mirror the main display and therefore cannot be removed from the mirroring set to which they belong.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGDisplayConfiguration.h

CGDisplayIsAsleep

Returns a Boolean value indicating whether a display is sleeping (and is therefore not drawable.)

boolean_t CGDisplayIsAsleep (
   CGDirectDisplayID display
);
Parameters
display

The identifier of the display to be accessed.

Return Value

If true, the specified display is in sleep mode; otherwise, false.

Discussion

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 (desktop) space, but it is not drawable.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGDisplayConfiguration.h

CGDisplayIsBuiltin

Returns a Boolean value indicating whether a display is built-in, such as the internal display in portable systems.

boolean_t CGDisplayIsBuiltin (
   CGDirectDisplayID display
);
Parameters
display

The identifier of the display to be accessed.

Return Value

If true, the specified display is considered to be a built-in display; otherwise, false.

Discussion

Portable systems typically identify the internal LCD panel as a built-in display.

Note that it is possible and reasonable for a system to have no displays marked as built-in. For example, a portable system running with the lid closed may report no built-in displays.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGDisplayConfiguration.h

CGDisplayIsInHWMirrorSet

Returns a Boolean value indicating whether a display is in a hardware mirroring set.

boolean_t CGDisplayIsInHWMirrorSet (
   CGDirectDisplayID display
);
Parameters
display

The identifier of the display to be accessed.

Return Value

If true, the specified display is a member of a hardware mirroring set; otherwise, false.

Discussion

When hardware mirroring is enabled, the contents of a single framebuffer are rendered in all displays in the hardware mirroring set. All drawing operations are directed to the primary display in the set—see CGDisplayPrimaryDisplay.

For more information about display mirroring, see CGConfigureDisplayMirrorOfDisplay.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGDisplayConfiguration.h

CGDisplayIsInMirrorSet

Returns a Boolean value indicating whether a display is in a mirroring set.

boolean_t CGDisplayIsInMirrorSet (
   CGDirectDisplayID display
);
Parameters
display

The identifier of the display to be accessed.

Return Value

If true, the specified display is a member of a software or hardware mirroring set; otherwise, false.

Discussion

For more information about display mirroring, see CGConfigureDisplayMirrorOfDisplay.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGDisplayConfiguration.h

CGDisplayIsMain

Returns a Boolean value indicating whether a display is the main display.

boolean_t CGDisplayIsMain (
   CGDirectDisplayID display
);
Parameters
display

The identifier of the display to be accessed.

Return Value

If true, the specified display is currently the main display; otherwise, false.

Discussion

For information about the characteristics of a main display, see CGMainDisplayID.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGDisplayConfiguration.h

CGDisplayIsOnline

Returns a Boolean value indicating whether a display is connected or online.

boolean_t CGDisplayIsOnline (
   CGDirectDisplayID display
);
Parameters
display

The identifier of the display to be accessed.

Return Value

If true, the specified display is connected; otherwise, false.

Discussion

A display is considered connected or online when the framebuffer hardware is connected to a monitor.

You can use this function to determine whether someone has plugged a display into the system while the main power was on. This hardware feature, called hot-plugging, may not be present on all displays.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGDisplayConfiguration.h

CGDisplayIsStereo

Returns a Boolean value indicating whether a display is running in a stereo graphics mode.

boolean_t CGDisplayIsStereo (
   CGDirectDisplayID display
);
Parameters
display

The identifier of the display to be accessed.

Return Value

If true, the specified display is running in a stereo graphics mode; otherwise, false.

Availability
  • Available in OS X v10.4 and later.
Declared In
CGDisplayConfiguration.h

CGDisplayMirrorsDisplay

For a secondary display in a mirroring set, returns the primary display.

CGDirectDisplayID CGDisplayMirrorsDisplay (
   CGDirectDisplayID display
);
Parameters
display

The identifier of a secondary display in a mirroring set.

Return Value

Returns the primary display in the mirroring set. Returns kCGNullDirectDisplay if the specified display is actually the primary display or is not in a mirroring set.

Discussion

For more information about display mirroring, see CGConfigureDisplayMirrorOfDisplay.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGDisplayConfiguration.h

CGDisplayModeCopyPixelEncoding

Returns the pixel encoding of the specified display mode.

CFStringRef CGDisplayModeCopyPixelEncoding(
   CGDisplayModeRef mode
);
Parameters
mode

A display mode for which to find the associated pixel encoding.

Return Value

A string representing the pixel encoding of the specified display mode. This string is expressed as a CFString type containing an I/O Kit graphics mode. The caller is responsible for releasing the string.

Discussion

The returned string can be used to determine various aspects of the pixel encoding, such as bits per pixel and bits per sample. For more information, see the header file IOKit/IOGraphicsTypes.h in I/O Kit Framework Reference.

Availability
  • Available in OS X v10.6 and later.
Declared In
CGDirectDisplay.h

CGDisplayModeGetHeight

Returns the height of the specified display mode.

size_t CGDisplayModeGetHeight(
   CGDisplayModeRef mode
);
Parameters
mode

A display mode.

Return Value

The height, in pixels, of the specified display mode.

Availability
  • Available in OS X v10.6 and later.
Declared In
CGDirectDisplay.h

CGDisplayModeGetIODisplayModeID

Returns the I/O Kit display mode ID of the specified display mode.

int32_t CGDisplayModeGetIODisplayModeID(
   CGDisplayModeRef mode
);
Parameters
mode

A display mode for which to find the associated display mode ID.

Return Value

The I/O Kit display mode ID of the specified display mode.

Availability
  • Available in OS X v10.6 and later.
Declared In
CGDirectDisplay.h

CGDisplayModeGetIOFlags

Returns the I/O Kit flags of the specified display mode.

uint32_t CGDisplayModeGetIOFlags(
   CGDisplayModeRef mode
);
Parameters
mode

A display mode for which to find the associated flags.

Return Value

The I/O Kit flags of the specified display mode. For more information, see the header file IOKit/IOGraphicsTypes.h.

Availability
  • Available in OS X v10.6 and later.
Declared In
CGDirectDisplay.h

CGDisplayModeGetRefreshRate

Returns the refresh rate of the specified display mode.

double CGDisplayModeGetRefreshRate(
   CGDisplayModeRef mode
);
Parameters
mode

A display mode for which to find the associated refresh rate.

Return Value

The refresh rate, in hertz, of the specified display mode for a CRT display. Some displays may not use conventional video vertical and horizontal sweep in painting the screen; for these displays, the return value is 0.

Availability
  • Available in OS X v10.6 and later.
Declared In
CGDirectDisplay.h

CGDisplayModeGetTypeID

Returns the type identifier of Quartz display modes.

CFTypeID CGDisplayModeGetTypeID(
   void
);
Return Value

The type identifier of the CGDisplayMode opaque type.

Availability
  • Available in OS X v10.6 and later.
Declared In
CGDirectDisplay.h

CGDisplayModeGetWidth

Returns the width of the specified display mode.

size_t CGDisplayModeGetWidth(
   CGDisplayModeRef mode
);
Parameters
mode

A display mode.

Return Value

The width, in pixels, of the specified display mode.

Availability
  • Available in OS X v10.6 and later.
Declared In
CGDirectDisplay.h

CGDisplayModeIsUsableForDesktopGUI

Returns a Boolean value indicating whether the specified display mode is usable for a desktop graphical user interface.

bool CGDisplayModeIsUsableForDesktopGUI(
   CGDisplayModeRef mode
);
Parameters
mode

A display mode to be checked for usability.

Return Value

If true, the specified display mode is usable for a desktop graphical user interface; otherwise, false.

Discussion

This function’s criteria include factors such as sufficient width and height and adequate pixel depth.

Availability
  • Available in OS X v10.6 and later.
Declared In
CGDirectDisplay.h

CGDisplayModelNumber

Returns the model number of a display monitor.

uint32_t CGDisplayModelNumber (
   CGDirectDisplayID display
);
Parameters
display

The identifier of the display to be accessed.

Return Value

A model number for the monitor associated with the specified display, or a constant to indicate an exception—see the discussion below.

Discussion

This function uses I/O Kit to identify the monitor associated with the specified display. The return value depends on the following:

  • If I/O Kit can identify the monitor, the product ID code for the monitor is returned.

  • If I/O Kit can’t identify the monitor, kDisplayProductIDGeneric is returned.

  • If no monitor is connected, a value of 0xFFFFFFFF is returned.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGDisplayConfiguration.h

CGDisplayModeRelease

Releases a Core Graphics display mode.

void CGDisplayModeRelease(
   CGDisplayModeRef mode
);
Parameters
mode

A display mode to be released.

Discussion

This function is equivalent to CFRelease, except that it does not cause an error if the mode parameter is NULL.

Availability
  • Available in OS X v10.6 and later.
Declared In
CGDirectDisplay.h

CGDisplayModeRetain

Retains a Core Graphics display mode.

CGDisplayModeRef CGDisplayModeRetain(
   CGDisplayModeRef mode
);
Parameters
mode

A display mode to be retained.

Return Value

The input value mode.

Discussion

This function is equivalent to CFRetain, except that it does not cause an error if the mode parameter is NULL.

Availability
  • Available in OS X v10.6 and later.
Declared In
CGDirectDisplay.h

CGDisplayMoveCursorToPoint

Moves the mouse cursor to a specified point relative to the display origin (the upper-left corner of the display).

CGError CGDisplayMoveCursorToPoint (
   CGDirectDisplayID display,
   CGPoint point
);
Parameters
display

The identifier of the display to be accessed.

point

The coordinates of a point in local display space. The origin is the upper-left corner of the specified display.

Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Discussion

No events are generated as a result of this move. Points that lie outside the desktop are clipped to the desktop.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGDirectDisplay.h

CGDisplayPixelsHigh

Returns the display height in pixel units.

size_t CGDisplayPixelsHigh (
   CGDirectDisplayID display
);
Parameters
display

The identifier of the display to be accessed.

Return Value

The display height in pixel units.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGDirectDisplay.h

CGDisplayPixelsWide

Returns the display width in pixel units.

size_t CGDisplayPixelsWide (
   CGDirectDisplayID display
);
Parameters
display

The identifier of the display to be accessed.

Return Value

The display width in pixel units.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
CGDirectDisplay.h

CGDisplayPrimaryDisplay

Returns the primary display in a hardware mirroring set.

CGDirectDisplayID CGDisplayPrimaryDisplay (
   CGDirectDisplayID display
);
Parameters
display

The identifier of a display in a hardware mirror set.

Return Value

The primary display in the mirror set. If display is not hardware-mirrored, this function simply returns display.

Discussion

In hardware mirroring, the contents of a single framebuffer are rendered in two or more displays simultaneously. The mirrored displays are said to be in a hardware mirroring set.

At the discretion of the device driver, one of the displays in a hardware mirroring set is designated as the primary display. The device driver binds the drawing engine, hardware accelerator, and 3D engine to the primary display and directs all drawing operations to this display.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGDisplayConfiguration.h

CGDisplayRegisterReconfigurationCallback

Registers a callback function to be invoked whenever a local display is reconfigured.

CGError CGDisplayRegisterReconfigurationCallback (
   CGDisplayReconfigurationCallBack proc,
   void *userInfo
);
Parameters
proc

A pointer to the callback function to be registered.

userInfo

A pointer to user-defined data, or NULL. The userInfo argument is passed back to the callback function each time it’s invoked.

Discussion

Whenever local displays are reconfigured, the callback function you register is invoked twice for each display that’s added, removed, or currently online—once before the reconfiguration, and once after the reconfiguration. For more information, see the callback type CGDisplayReconfigurationCallBack.

A callback function may be registered multiple times with different user-defined data pointers, resulting in multiple registration entries. For each registration, when notification is no longer needed you should remove the registration by calling the function CGDisplayRemoveReconfigurationCallback.

Availability
  • Available in OS X v10.3 and later.
Declared In
CGDisplayConfiguration.h

CGDisplayRelease

Releases a captured display.

CGError CGDisplayRelease (
   CGDirectDisplayID display
);
Parameters
display

The identifier of the display to be released.

Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGDirectDisplay.h

CGDisplayRemoveReconfigurationCallback

Removes the registration of a callback function that’s invoked whenever a local display is reconfigured.

CGError CGDisplayRemoveReconfigurationCallback (
   CGDisplayReconfigurationCallBack proc,
   void *userInfo
);
Parameters
proc

A pointer to the callback function associated with the registration to be removed.

userInfo

A pointer to user-defined data associated with the registration to be removed, or NULL. This is the same pointer that’s passed to the function CGDisplayRegisterReconfigurationCallback when registering the callback.

Discussion

When you call this function, the two arguments must match the registered entry to be removed.

Availability
  • Available in OS X v10.3 and later.
Declared In
CGDisplayConfiguration.h

CGDisplayRestoreColorSyncSettings

Restores the gamma tables to the values in the user’s ColorSync display profile.

void CGDisplayRestoreColorSyncSettings (
   void
);
Availability
  • Available in OS X v10.0 and later.
Declared In
CGDirectDisplay.h

CGDisplayRotation

Returns the rotation angle of a display in degrees.

double CGDisplayRotation (
   CGDirectDisplayID display
);
Parameters
display

The identifier of the display to be accessed.

Return Value

The rotation angle of the display in degrees, or 0 if the display is not valid.

Discussion

This function returns the rotation angle of a display in a clockwise direction. For example, if the specified display is rotated clockwise 90 degrees, then this function returns 90.0. After a 90-degree clockwise rotation, the physical bottom of the display is on the left side and the physical top is on the right side.

Availability
  • Available in OS X v10.5 and later.
Declared In
CGDisplayConfiguration.h

CGDisplayScreenSize

Returns the width and height of a display in millimeters.

CGSize CGDisplayScreenSize (
   CGDirectDisplayID display
);
Parameters
display

The identifier of the display to be accessed.

Return Value

The size of the specified display in millimeters, or 0 if the display is not valid.

Discussion

If Extended Display Identification Data (EDID) for the display device is not available, the size is estimated based on the device width and height in pixels from CGDisplayBounds, with an assumed resolution of 2.835 pixels/mm or 72 dpi, a reasonable guess for displays predating EDID support.

Availability
  • Available in OS X v10.3 and later.
Declared In
CGDisplayConfiguration.h

CGDisplaySerialNumber

Returns the serial number of a display monitor.

uint32_t CGDisplaySerialNumber (
   CGDirectDisplayID display
);
Parameters
display

The identifier of the display to be accessed.

Return Value

A serial number for the monitor associated with the specified display, or a constant to indicate an exception—see the discussion below.

Discussion

This function uses I/O Kit to identify the monitor associated with the specified display.

If I/O Kit can identify the monitor:

  • If the manufacturer has encoded a serial number for the monitor, the number is returned.

  • If there is no encoded serial number, 0x00000000 is returned.

If I/O Kit cannot identify the monitor:

  • If a monitor is connected to the display, 0x00000000 is returned.

  • If no monitor is connected to the display hardware, 0xFFFFFFFF is returned.

Note that a serial number is meaningful only in conjunction with a specific vendor and product or model.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGDisplayConfiguration.h

CGDisplaySetDisplayMode

Switches a display to a different mode.

CGError CGDisplaySetDisplayMode(
   CGDirectDisplayID display,
   CGDisplayModeRef mode,
   CFDictionaryRef options
);
Parameters
display

The identifier of the display to be accessed.

mode

A display mode that contains information about the display mode to set. For information on the display-mode opaque-type properties, see“Getting Information About a Display Mode”.

options

Reserved for future expansion. Pass NULL for now.

Return Value

A result code. See Core Graphics Data Types and Constants 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 you change the display mode of a display in a mirroring set, other displays in the mirroring set are 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 CGConfigureDisplayWithDisplayMode for each display to explicitly set the mode, and finally call CGCompleteDisplayConfiguration.

Availability
  • Available in OS X v10.6 and later.
Declared In
CGDirectDisplay.h

CGDisplaySetStereoOperation

Immediately enables or disables stereo operation for a display.

CGError CGDisplaySetStereoOperation (
   CGDirectDisplayID display,
   boolean_t stereo,
   boolean_t forceBlueLine,
   CGConfigureOption option
);
Parameters
display

The identifier of the display being configured.

stereo

Pass true if you want to enable stereo operation. To disable it, pass false.

forceBlueLine

When in stereo operation, a display may need to generate a special stereo sync signal as part of the video output. The sync signal consists of a blue line that occupies the first 25% of the last scan line (for the left eye view), and the first 75% of the last scan line (for the right eye view). The remainder of the scan line is black. To force the display to generate this sync signal, pass true; otherwise pass false.

option

A constant that specifies the scope of the display configuration changes. For more information, see “Display Configuration Scopes.”

Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Discussion

The system normally detects the presence of a stereo window and automatically switches a display containing a stereo window to stereo operation. This function forces a display to stereo operation immediately, and sets options (blue line sync signal) when in stereo operation.

On success, the display resolution, mirroring mode, and available display modes may change due to hardware-specific capabilities and limitations. You should check these settings to verify that they are appropriate for your application.

Availability
  • Available in OS X v10.4 and later.
Declared In
CGDisplayConfiguration.h

CGDisplayShowCursor

Decrements the hide cursor count, and shows the mouse cursor if the count is 0.

CGError CGDisplayShowCursor (
   CGDirectDisplayID display
);
Parameters
display

This parameter is not used. By default, you may pass kCGDirectMainDisplay.

Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Discussion

If the hide cursor count is 0, this function shows the cursor regardless of its current location; the display parameter is ignored. In most cases, the caller must be the foreground application to affect the cursor.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGDirectDisplay.h

CGDisplayStreamCreate

Creates a new display stream to be used with a CFRunloop.

CGDisplayStreamRef CGDisplayStreamCreate(
   CGDirectDisplayID display,
   size_t outputWidth,
   size_t outputHeight,
   int32_t pixelFormat,
   CFDictionaryRef properties,
   CGDisplayStreamFrameAvailableHandler handler
);
Parameters
display

The identifier of the display to be streamed.

outputWidth

The width of the output frames in pixels. The width must not be zero.

outputHeight

The height of the output frames in pixels. The height must not be zero.

pixelFormat

The desired Core Media pixel format of the output frame data. The value must be one of the following:

  • 'BGRA': Packed Little Endian ARGB8888

  • 'l10r': Packed Little Endian ARGB2101010

  • '420v': 2-plane "video" range YCbCr 4:2:0

  • '420f': 2-plane "full" range YCbCr 4:2:0

properties

A dictionary of optional properties for the display stream. See “Display Stream Optional Property Keys” for the possible keys and values that can be provided in the options dictionary.

handler

A block to be called when new frames are ready.

Return Value

A new CGDisplayStream object.

Discussion

Before the stream can be started, it must be added to a run loop. Use the CGDisplayStreamGetRunLoopSource function to get an event source to add to the run loop.

Availability
  • Available in OS X v10.8 and later.
Declared In
CGDisplayStream.h

CGDisplayStreamCreateWithDispatchQueue

Creates a new display stream whose updates are delivered to a dispatch queue.

CGDisplayStreamRef CGDisplayStreamCreateWithDispatchQueue(
   CGDirectDisplayID display,
   size_t outputWidth,
   size_t outputHeight,
   int32_t pixelFormat,
   CFDictionaryRef properties,
   dispatch_queue_t queue,
   CGDisplayStreamFrameAvailableHandler handler
);
Parameters
display

The identifier of the display to be streamed.

outputWidth

The width of the output frames in pixels. The width must not be zero.

outputHeight

The height of the output frames in pixels. The height must not be zero.

pixelFormat

The desired Core Media pixel format of the output frame data. The value must be one of the following:

  • 'BGRA': Packed Little Endian ARGB8888

  • 'l10r': Packed Little Endian ARGB2101010

  • '420v': 2-plane "video" range YCbCr 4:2:0

  • '420f': 2-plane "full" range YCbCr 4:2:0

properties

A dictionary of optional properties for the display stream. See “Display Stream Optional Property Keys” for the possible keys and values that can be provided in the options dictionary.

queue

The GCD dispatch queue used when calling the update handler.

handler

A block to be called when new frames are ready.

Return Value

A new CGDisplayStream object.

Availability
  • Available in OS X v10.8 and later.
Declared In
CGDisplayStream.h

CGDisplayStreamGetRunLoopSource

Gets the run loop source for a display stream.

CFRunLoopSourceRef CGDisplayStreamGetRunLoopSource(
   CGDisplayStreamRef displayStream
);
Parameters
displayStream

A display stream reference created using the CGDisplayStreamCreate function.

Return Value

An event source for the display stream. This function returns NULL if you pass in a display stream that was created by calling the CGDisplayStreamCreateWithDispatchQueue function.

Availability
  • Available in OS X v10.8 and later.
Declared In
CGDisplayStream.h

CGDisplayStreamGetTypeID

Returns the type identifier of a Quartz display stream.

CFTypeID CGDisplayStreamGetTypeID(void);
Return Value

The type identifier of the CGDisplayStream opaque type.

Availability
  • Available in OS X v10.8 and later.
Declared In
CGDisplayStream.h

CGDisplayStreamStart

Tells a stream to start sending updates.

CGError CGDisplayStreamStart(
   CGDisplayStreamRef displayStream
);
Parameters
displayStream

The display stream that should start streaming data.

Return Value

kCGErrorSuccess if the stream started, otherwise an appropriate error code.

Availability
  • Available in OS X v10.8 and later.
Declared In
CGDisplayStream.h

CGDisplayStreamStop

Tells a stream to stop sending updates.

CGError CGDisplayStreamStop(
   CGDisplayStreamRef displayStream
);
Parameters
displayStream

The display stream that should stop streaming data.

Return Value

kCGErrorSuccess if the stream started, otherwise an appropriate error code.

Discussion

After this call returns, the stream is stopped. When the stream stops, its callback is called with a status of kCGDisplayStreamFrameStatusStopped. You must wait until this callback is received before releasing the display stream object.

It is safe to call this function from within the handler block.

Availability
  • Available in OS X v10.8 and later.
Declared In
CGDisplayStream.h

CGDisplayStreamUpdateCreateMergedUpdate

Combines two updates into a new update that includes the metadata for both source updates.

CGDisplayStreamUpdateRef CGDisplayStreamUpdateCreateMergedUpdate(
   CGDisplayStreamUpdateRef firstUpdate,
   CGDisplayStreamUpdateRef secondUpdate
);
Parameters
firstUpdate

A CGDisplayStreamUpdate reference. This must be the earlier of the two update references.

secondUpdate

A CGDisplayStreamUpdate reference. This must be the later of the two update references.

Return Value

A new update that contains the union of the information stored in the two source updates.

Discussion

If your app needs to drop a frame without processing it, use this function to merge that frame’s update data with the data provided for a later frame update.

Availability
  • Available in OS X v10.8 and later.
Declared In
CGDisplayStream.h

CGDisplayStreamUpdateGetDropCount

Returns the number of frames that have been dropped since the last call to your update handler.

size_t CGDisplayStreamUpdateGetDropCount(
   CGDisplayStreamUpdateRef updateRef
);
Parameters
updateRef

A CGDisplayStreamUpdate reference.

Return Value

The number of dropped frames.

Discussion

Use this call when measuring your client’s performance to ensure that it is keeping up with window server updates.

Availability
  • Available in OS X v10.8 and later.
Declared In
CGDisplayStream.h

CGDisplayStreamUpdateGetMovedRectsDelta

Return the movement delta values for a single update.

void CGDisplayStreamUpdateGetMovedRectsDelta(
   CGDisplayStreamUpdateRef updateRef,
   CGFloat *dx,
   CGFloat *dy
);
Parameters
updateRef

A CGDisplayStreamUpdate reference.

dx

A pointer to a CGFloat to store the x component of the movement delta

dy

A pointer to a CGFloat to store the y component of the movement delta

Discussion

The delta values describe the offset from the moved rectangles back to the source location.

Availability
  • Available in OS X v10.8 and later.
Declared In
CGDisplayStream.h

CGDisplayStreamUpdateGetRects

Returns an array of rectangles that describe where the frame has changed since the previous frame.

const CGRect *CGDisplayStreamUpdateGetRects(
   CGDisplayStreamUpdateRef updateRef,
   CGDisplayStreamUpdateRectType rectType,
   size_t *rectCount
);
Parameters
updateRef

A CGDisplayStreamUpdate reference for a frame update.

rectType

The rectangles you are interested in. See “Display Stream Update Rect Types.”

rectCount

A pointer to a size_t. This value must not be NULL. On return, this location is updated to contain the number of rectangles in the returned array.

Return Value

An array of CGRect structures.

Discussion

Do not free the array. It is managed automatically by the update and disposed of when the update object is destroyed.

Availability
  • Available in OS X v10.8 and later.
Declared In
CGDisplayStream.h

CGDisplayStreamUpdateGetTypeID

Returns the type identifier of a Quartz display stream update.

CFTypeID CGDisplayStreamUpdateGetTypeID(void)
Return Value

The type identifier of the CGDisplayStreamUpdate opaque type.

Availability
  • Available in OS X v10.8 and later.
Declared In
CGDisplayStream.h

CGDisplayUnitNumber

Returns the logical unit number of a display.

uint32_t CGDisplayUnitNumber (
   CGDirectDisplayID display
);
Parameters
display

The identifier of the display to be accessed.

Return Value

A logical unit number for the specified display.

Discussion

The logical unit number represents a particular node in the I/O Kit device tree associated with the display’s framebuffer.

For a particular hardware configuration, this value will not change when the attached monitor is changed. The number will change, though, if the I/O Kit device tree changes, for example, when hardware is reconfigured, drivers are replaced, or significant changes occur to I/O Kit. Therefore keep in mind that this number may vary across login sessions.

For more information about I/O Kit, see I/O Kit Fundamentals.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGDisplayConfiguration.h

CGDisplayUsesOpenGLAcceleration

Returns a Boolean value indicating whether Quartz is using OpenGL-based window acceleration (Quartz Extreme) to render in a display.

boolean_t CGDisplayUsesOpenGLAcceleration (
   CGDirectDisplayID display
);
Parameters
display

The identifier of the display to be accessed.

Return Value

If true, Quartz Extreme is used to render in the specified display; otherwise, false.

Discussion

Quartz Extreme is an OpenGL-based, hardware-accelerated window compositor available in OS X version 10.2 and later. Quartz Extreme requires a minimum hardware configuration to operate.

The information this function provides is typically used to adjust the demands of drawing operations to the capabilities of the display hardware. For example, an application running on an unaccelerated system could disable live window-resizing.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGDisplayConfiguration.h

CGDisplayVendorNumber

Returns the vendor number of the specified display's monitor.

uint32_t CGDisplayVendorNumber (
   CGDirectDisplayID display
);
Parameters
display

The identifier of the display to be accessed.

Return Value

A vendor number for the monitor associated with the specified display, or a constant to indicate an exception—see the discussion below.

Discussion

This function uses I/O Kit to identify the monitor associated with the specified display.

There are three cases:

  • If I/O Kit can identify the monitor, the vendor ID is returned.

  • If I/O Kit cannot identify the monitor, kDisplayVendorIDUnknown is returned.

  • If there is no monitor associated with the display, 0xFFFFFFFF is returned.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGDisplayConfiguration.h

CGGetActiveDisplayList

Provides a list of displays that are active (or drawable).

CGError CGGetActiveDisplayList (
   uint32_t maxDisplays,
   CGDirectDisplayID *activeDspys,
   uint32_t *dspyCnt
);
Parameters
maxDisplays

The size of the activeDspys array. This value determines the maximum number of displays that can be returned.

activeDspys

A pointer to storage provided by the caller for an array of display IDs. On return, the array contains a list of active displays. If you pass NULL, on return the display count contains the total number of active displays.

dspyCnt

A pointer to a display count variable provided by the caller. On return, the display count contains the actual number of displays returned in the activeDspys array. This value is at most maxDisplays.

Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Discussion

The first entry in the list of active displays is the main display. In case of mirroring, the first entry is the largest drawable display or, if all are the same size, the display with the greatest pixel depth.

Note that when hardware mirroring is being used between displays, only the primary display is active and appears in the list. When software mirroring is being used, all the mirrored displays are active and appear in the list. For more information about mirroring, see CGConfigureDisplayMirrorOfDisplay.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
CGDirectDisplay.h

CGGetDisplaysWithOpenGLDisplayMask

Provides a list of displays that corresponds to the bits set in an OpenGL display mask.

CGError CGGetDisplaysWithOpenGLDisplayMask (
   CGOpenGLDisplayMask mask,
   uint32_t maxDisplays,
   CGDirectDisplayID *dspys,
   uint32_t *dspyCnt
);
Parameters
mask

An OpenGL display mask that identifies one or more displays.

maxDisplays

The size of the dspys array. This value determines the maximum number of displays that can be returned.

dspys

A pointer to storage provided by the caller for an array of display IDs. On return, the array contains a list of displays that corresponds to the bits set in the mask. If you pass NULL, on return the display count contains the total number of displays specified in the mask.

dspyCnt

A pointer to a display count variable provided by the caller. On return, the display count contains the actual number of displays returned in the dspys array. This value is at most maxDisplays.

Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGDirectDisplay.h

CGGetDisplaysWithPoint

Provides a list of online displays with bounds that include the specified point.

CGError CGGetDisplaysWithPoint (
   CGPoint point,
   uint32_t maxDisplays,
   CGDirectDisplayID *dspys,
   uint32_t *dspyCnt
);
Parameters
point

The coordinates of a point in the global display coordinate space. The origin is the upper-left corner of the main display.

maxDisplays

The size of the dspys array. This value determines the maximum number of displays that can be returned.

dspys

A pointer to storage provided by the caller for an array of display IDs. On return, the array contains a list of displays with bounds that include the point. If you pass NULL, on return the display count contains the total number of displays with bounds that include the point.

dspyCnt

A pointer to a display count variable provided by the caller. On return, the display count contains the actual number of displays returned in the dspys array. This value is at most maxDisplays.

Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
CGDirectDisplay.h

CGGetDisplaysWithRect

Gets a list of online displays with bounds that intersect the specified rectangle.

CGError CGGetDisplaysWithRect (
   CGRect rect,
   uint32_t maxDisplays,
   CGDirectDisplayID *dspys,
   uint32_t *dspyCnt
);
Parameters
rect

The location and size of a rectangle in the global display coordinate space. The origin is the upper-left corner of the main display.

maxDisplays

The size of the dspys array. This value determines the maximum number of displays that can be returned in the dspys parameter. Generally, you should specify a number greater than 0 for this parameter. If you specify 0, the value returned in dspyCnt is undefined and this function sets the dspys parameter to NULL.

dspys

A pointer to storage provided by the caller for an array of display IDs. On return, the array contains a list of displays whose bounds intersect the specified rectangle.

dspyCnt

A pointer to a display count variable provided by the caller. On return, this variable contains the number of displays that were returned in the dspys parameter. You must provide a non-NULL value for this parameter.

Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGDirectDisplay.h

CGGetDisplayTransferByFormula

Gets the coefficients of the gamma transfer formula for a display.

CGError CGGetDisplayTransferByFormula (
   CGDirectDisplayID display,
   CGGammaValue *redMin,
   CGGammaValue *redMax,
   CGGammaValue *redGamma,
   CGGammaValue *greenMin,
   CGGammaValue *greenMax,
   CGGammaValue *greenGamma,
   CGGammaValue *blueMin,
   CGGammaValue *blueMax,
   CGGammaValue *blueGamma
);
Parameters
display

The identifier of the display to be accessed.

redMin

The minimum value of the red channel in the gamma table. The value is a number in the interval [0, redMax).

redMax

The maximum value of the red channel in the gamma table. The value is a number in the interval (redMin, 1].

redGamma

A positive value used to compute the red channel in the gamma table.

greenMin

The minimum value of the green channel in the gamma table. The value is a number in the interval [0, greenMax).

greenMax

The maximum value of the green channel in the gamma table. The value is a number in the interval (greenMin, 1].

greenGamma

A positive value used to compute the green channel in the gamma table.

blueMin

The minimum value of the blue channel in the gamma table. The value is a number in the interval [0, blueMax).

blueMax

The maximum value of the blue channel in the gamma table. The value is a number in the interval (blueMin, 1].

blueGamma

A positive value used to compute the blue channel in the gamma table.

Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Discussion

For information about the gamma transfer formula, see the description of the function CGSetDisplayTransferByFormula.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGDirectDisplay.h

CGGetDisplayTransferByTable

Gets the values in the RGB gamma tables for a display.

CGError CGGetDisplayTransferByTable (
   CGDirectDisplayID display,
   uint32_t capacity,
   CGGammaValue *redTable,
   CGGammaValue *greenTable,
   CGGammaValue *blueTable,
   uint32_t *sampleCount
);
Parameters
display

The identifier of the display to be accessed.

capacity

The number of entries each table can hold.

redTable

A pointer to an array of type CGGammaValue with size capacity. On return, the array contains the values of the red channel in the display’s gamma table.

greenTable

A pointer to an array of type CGGammaValue with size capacity. On return, the array contains the values of the green channel in the display’s gamma table.

blueTable

A pointer to an array of type CGGammaValue with size capacity. On return, the array contains the values of the blue channel in the display’s gamma table.

sampleCount

The number of samples actually copied into each array.

Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGDirectDisplay.h

CGGetLastMouseDelta

Reports the change in mouse position since the last mouse movement event received by the application.

void CGGetLastMouseDelta (
   int32_t *deltaX,
   int32_t *deltaY
);
Parameters
deltaX

A pointer to a int32_t variable. On return, this variable contains the horizontal change in the mouse position since the last mouse movement event.

deltaY

A pointer to a int32_t variable. On return, this variable contains the vertical change in the mouse position since the last mouse movement event.

Discussion

This function is not recommended for general use. Instead, you should use the mouse-tracking functions provided by the NSEvent class.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGDirectDisplay.h

CGGetOnlineDisplayList

Provides a list of displays that are online (active, mirrored, or sleeping).

CGError CGGetOnlineDisplayList (
   uint32_t maxDisplays,
   CGDirectDisplayID *onlineDspys,
   uint32_t *dspyCnt
);
Parameters
maxDisplays

The size of the onlineDspys array. This value determines the maximum number of display IDs that can be returned.

onlineDspys

A pointer to storage provided by the caller for an array of display IDs. On return, the array contains a list of the online displays. If you pass NULL, on return the display count contains the total number of online displays.

dspyCnt

A pointer to a display count variable provided by the caller. On return, the display count contains the actual number of displays returned in the onlineDspys array. This value is at most maxDisplays.

Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Discussion

If the framebuffer hardware is connected, a display is considered connected or online.

When hardware mirroring is used, a display can be online but not active or drawable. Programs that manipulate display settings (such as gamma tables) need access to all displays, including hardware mirrors, which are not drawable.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGDirectDisplay.h

CGMainDisplayID

Returns the display ID of the main display.

CGDirectDisplayID CGMainDisplayID (
   void
);
Return Value

The display ID assigned to the main display.

Discussion

The main display is the display with its screen location at (0,0) in the global display coordinate space. In a system without display mirroring, the display with the menu bar is typically the main display.

If mirroring is enabled and the menu bar appears on more than one display, this function provides a reliable way to find the main display.

In case of hardware mirroring, the drawable display becomes the main display. In case of software mirroring, the display with the highest resolution and deepest pixel depth typically becomes the main display.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGDirectDisplay.h

CGOpenGLDisplayMaskToDisplayID

Maps an OpenGL display mask to a display ID.

CGDirectDisplayID CGOpenGLDisplayMaskToDisplayID (
   CGOpenGLDisplayMask mask
);
Parameters
mask

The OpenGL display mask to be converted.

Return Value

The display ID assigned to the specified display mask, or kCGNullDirectDisplay if no display matches the mask.

Discussion

OpenGL sometimes identifies a display using a bitmask with one bit set. This function maps such a display mask to the corresponding display ID. If you pass in a mask with multiple bits set, this function returns a display ID matching one of these bits.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGDirectDisplay.h

CGReleaseAllDisplays

Releases all captured displays.

CGError CGReleaseAllDisplays (
   void
);
Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Discussion

This function releases all captured displays and restores the display modes to the user's preferences. It may be used in conjunction with any of the functions that capture displays, such as CGCaptureAllDisplays.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
CGDirectDisplay.h

CGReleaseDisplayFadeReservation

Releases a display fade reservation, and unfades the display if needed.

CGError CGReleaseDisplayFadeReservation (
   CGDisplayFadeReservationToken myToken
);
Parameters
myToken

The current fade reservation token to be released. On return, the reservation token is no longer valid and should be discarded.

Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Discussion

If you call this function while an asynchronous fade operation is running, there are two possible outcomes:

  • If the ending blend value is kCGDisplayBlendNormal, the fade operation is allowed to run to completion.

  • If the ending blend value is not kCGDisplayBlendNormal, the fade operation is terminated immediately and the display is returned to normal.

In both cases, the reservation is actually released when the fade operation completes.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGDisplayFade.h

CGRestorePermanentDisplayConfiguration

Restores the permanent display configuration settings for the current user.

void CGRestorePermanentDisplayConfiguration (
   void
);
Discussion

This function provides a convenient way to restore the permanent display configuration.

Applications that temporarily change the display configuration—such as applications and games that switch to full-screen display mode—can use this function to undo the changes.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGDisplayConfiguration.h

CGSessionCopyCurrentDictionary

Returns information about the caller’s window server session.

CFDictionaryRef CGSessionCopyCurrentDictionary (
   void
);
Return Value

A window server session dictionary, or NULL if the caller is not running within a Quartz GUI session or the window server is disabled. You should release the dictionary when you are finished using it. For information about the key-value pairs in this dictionary, see “Window Server Session Properties.”

Availability
  • Available in OS X v10.3 and later.
Related Sample Code
Declared In
CGSession.h

CGSetDisplayTransferByByteTable

Sets the byte values in the 8-bit RGB gamma tables for a display.

CGError CGSetDisplayTransferByByteTable (
   CGDirectDisplayID display,
   uint32_t tableSize,
   const uint8_t *redTable,
   const uint8_t *greenTable,
   const uint8_t *blueTable
);
Parameters
display

The identifier of the display to be accessed.

tableSize

The number of entries in each table.

redTable

An array of size tableSize containing the byte values of the red channel in the display’s gamma table.

greenTable

An array of size tableSize containing the byte values of the green channel in the display’s gamma table.

blueTable

An array of size tableSize containing the byte values of the blue channel in the display’s gamma table.

Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Discussion

The same table may be passed in for the red, green, and blue channels. The tables are interpolated as needed to generate the number of samples required by the graphics hardware.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGDirectDisplay.h

CGSetDisplayTransferByFormula

Sets the gamma function for a display by specifying the coefficients of the gamma transfer formula.

CGError CGSetDisplayTransferByFormula (
   CGDirectDisplayID display,
   CGGammaValue redMin,
   CGGammaValue redMax,
   CGGammaValue redGamma,
   CGGammaValue greenMin,
   CGGammaValue greenMax,
   CGGammaValue greenGamma,
   CGGammaValue blueMin,
   CGGammaValue blueMax,
   CGGammaValue blueGamma
);
Parameters
display

The identifier of the display to be accessed.

redMin

The minimum value of the red channel in the gamma table. The value should be a number in the interval [0, redMax).

redMax

The maximum value of the red channel in the gamma table. The value should be a number in the interval (redMin, 1].

redGamma

A positive value used to compute the red channel in the gamma table.

greenMin

The minimum value of the green channel in the gamma table. The value should be a number in the interval [0, greenMax).

greenMax

The maximum value of the green channel in the gamma table. The value should be a number in the interval (greenMin, 1].

greenGamma

A positive value used to compute the green channel in the gamma table.

blueMin

The minimum value of the blue channel in the gamma table. The value should be a number in the interval [0, blueMax).

blueMax

The maximum value of the blue channel in the gamma table. The value should be a number in the interval (blueMin, 1].

blueGamma

A positive value used to compute the blue channel in the gamma table.

Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Discussion

This function uses the specified parameter values to compute a gamma correction table for the specified display. The values in the table are computed by sampling the following gamma transfer formula for a range of indices from 0 to 1:

value = Min + ((Max - Min) * pow(index, Gamma))

The resulting values are converted to a machine-specific format and loaded into display hardware.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGDirectDisplay.h

CGSetDisplayTransferByTable

Sets the color gamma function for a display by specifying the values in the RGB gamma tables.

CGError CGSetDisplayTransferByTable (
   CGDirectDisplayID display,
   uint32_t tableSize,
   const CGGammaValue *redTable,
   const CGGammaValue *greenTable,
   const CGGammaValue *blueTable
);
Parameters
display

The identifier of the display to be accessed.

tableSize

The number of entries in each table.

redTable

An array of size tableSize containing the values of the red channel in the display’s gamma table. The values should be in the range 0.0 to 1.0.

greenTable

An array of size tableSize containing the values of the green channel in the display’s gamma table. The values should be in the range 0.0 to 1.0.

blueTable

An array of size tableSize containing the values of the blue channel in the display’s gamma table. The values should be in the range 0.0 to 1.0.

Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Discussion

The same table may be passed in for the red, green, and blue channels. The tables are interpolated as needed to generate the number of samples required by the graphics hardware.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGDirectDisplay.h

CGShieldingWindowID

Returns the window ID of the shield window for a captured display.

uint32_t CGShieldingWindowID (
   CGDirectDisplayID display
);
Parameters
display

The identifier of the display to be accessed.

Return Value

The window ID of the shield window for the specified display, or NULL if the display is not shielded.

Discussion

To prevent updates by direct-to-screen programs, Quartz draws a shield window that fills the entire screen of a captured display.

This function is not recommended for use in applications. Note that the graphics context associated with this window is not a full-featured drawing context. To get a full-featured drawing context for a captured display, you should use the function CGDisplayGetDrawingContext.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGDirectDisplay.h

CGShieldingWindowLevel

Returns the window level of the shield window for a captured display.

int32_t CGShieldingWindowLevel (
   void
);
Return Value

The window level of the shield window for a captured display.

Discussion

This function returns a value that is sometimes used to position a window over the shield window for a captured display. Attempting to position a window over a captured display may be unsuccessful—or it may present undesirable results such as illegible or invisible content—because of interactions between full-screen graphics (such as OpenGL full-screen drawing contexts) and the graphics hardware. Because of these limitations, this technique is not recommended.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGDirectDisplay.h

CGWarpMouseCursorPosition

Moves the mouse cursor without generating events.

CGError CGWarpMouseCursorPosition (
   CGPoint newCursorPosition
);
Parameters
newCursorPosition

The new mouse cursor position in the global display coordinate space.

Return Value

A result code. See Core Graphics Data Types and Constants Reference.

Discussion

You can use this function to “warp” or alter the cursor position without generating or posting an event. For example, this function is often used to move the cursor position back to the center of the screen by games that do not want the cursor pinned by display edges.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
CGRemoteOperation.h

CGWindowLevelForKey

Returns the window level that corresponds to one of the standard window types.

CGWindowLevel CGWindowLevelForKey (
   CGWindowLevelKey key
);
Parameters
key

A window level key constant that represents one of the standard window types. See “Window Level Keys.”

Return Value

The window level that corresponds to the specified key.

Discussion

This function is not recommended for use in applications. (This function is provided for application frameworks that create and manage windows, like Cocoa.)

Availability
  • Available in OS X v10.0 and later.
Declared In
CGWindowLevel.h

Callbacks

CGDisplayReconfigurationCallBack

A client-supplied callback function that’s invoked whenever the configuration of a local display is changed.

typedef void (*CGDisplayReconfigurationCallBack) (
   CGDirectDisplayID display,
   CGDisplayChangeSummaryFlags flags,
   void *userInfo
);

If you named your function MyDisplayReconfigurationCallBack, you would declare it like this:

void MyDisplayReconfigurationCallBack (
   CGDirectDisplayID display,
   CGDisplayChangeSummaryFlags flags,
   void *userInfo
);

Parameters
display

The display being reconfigured.

flags

Flags that indicate which display configuration parameters are changing.

userInfo

The userInfo argument passed to the function CGDisplayRegisterReconfigurationCallback when the callback function is registered.

Discussion

To register a display reconfiguration callback function, you call the function CGDisplayRegisterReconfigurationCallback. Quartz invokes your callback function when:

  • Your application calls a function to reconfigure a local display.

  • Your application is listening for events in the event-processing thread, and another application calls a function to reconfigure a local display.

  • The user changes the display hardware configuration—for example, by disconnecting a display or changing a system preferences setting.

Before display reconfiguration, Quartz invokes your callback function once for each online display to indicate a pending configuration change. The flags argument is always set to kCGDisplayBeginConfigurationFlag. The only display-specific information contained by this callback is the display ID number.The reason is that details of how a reconfiguration affects a particular device rely on device-specific behaviors which may not be available to a device driver.

After display reconfiguration, Quartz invokes your callback function once for each added, removed, and online display. At this time, all display state reported by Core Graphics and QuickDraw will be up to date. The flags argument indicates how the display configuration has changed. Note that in the case of removed displays, calls into Quartz with the removed display ID will fail.

The following code example illustrates how to test for specific conditions:

void MyDisplayReconfigurationCallBack (
   CGDirectDisplayID display,
   CGDisplayChangeSummaryFlags flags,
   void *userInfo)
{
    if (flags & kCGDisplayAddFlag) {
        // display has been added
    }
    else if (flags & kCGDisplayRemoveFlag) {
        // display has been removed
    }
}

Your callback function should avoid attempting to change display configurations and should not raise exceptions or perform a nonlocal return such as calling longjmp. When you are finished using a callback registration, you should call the function CGDisplayRemoveReconfigurationCallback to remove it.

Availability
  • Available in OS X v10.3 and later.
Declared In
CGDisplayConfiguration.h

CGScreenRefreshCallback

A client-supplied callback function that’s invoked when an area of the display is modified or refreshed.

typedef void (*CGScreenRefreshCallback) (
   CGRectCount count,
   const CGRect * rectArray,
   void * userParameter
);

If you name your function MyScreenRefreshCallback, you would declare it like this:

void MyScreenRefreshCallback (
   CGRectCount count,
   const CGRect * rectArray,
   void * userParameter
);

Parameters
count

The number of rectangles in the rectArray parameter.

rectArray

A list of the rectangles in the refreshed areas, specified in the global display coordinate space. The origin is the upper-left corner of the main display. You should not modify or deallocate memory pointed to by rectArray.

userParameter

The user data you specify when you register this callback.

Discussion

To register a screen-refresh callback function, you call the function CGRegisterScreenRefreshCallback. Quartz invokes your callback function when operations such as drawing, window movement, scrolling, or display reconfiguration occur on local displays. When you are finished using a callback registration, you should call the function CGUnregisterScreenRefreshCallback to remove it.

Note that a single rectangle may occupy multiple displays, either by overlapping the displays or by residing on coincident displays when mirroring is active. You can use the function CGGetDisplaysWithRect to determine the displays a rectangle occupies.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGRemoteOperation.h

CGScreenUpdateMoveCallback

A client-supplied callback function invoked when an area of the display is moved.

typedef void (*CGScreenUpdateMoveCallback) (
   CGScreenUpdateMoveDelta delta,
   CGRectCount count,
   const CGRect * rectArray,
   void * userParameter
);

If you name your function MyScreenUpdateMoveCallback, you would declare it like this:

void MyScreenUpdateMoveCallback (
   CGScreenUpdateMoveDelta delta,
   CGRectCount count,
   const CGRect * rectArray,
   void * userParameter
);

Parameters
delta

The distance, in pixel unites, that the display area has moved.

count

The number of rectangles in the rectArray parameter.

rectArray

A list of the rectangles in the moved areas, specified in the global display coordinate space. The origin is the upper-left corner of the main display. The rectangles describe the area prior to the move operation. You should not modify or deallocate memory pointed to by rectArray.

userParameter

The user data you specify when you register this callback.

Discussion

To register a screen-move callback function, you call the function CGScreenRegisterMoveCallback. Quartz invokes your callback function when operations such as window movement or scrolling occur on local displays. When you are finished using a callback registration, you should call the function CGScreenUnregisterMoveCallback to remove it.

Note that a single rectangle may occupy multiple displays, either by overlapping the displays or by residing on coincident displays when mirroring is active. You can use the function CGGetDisplaysWithRect to determine the displays a rectangle occupies.

Availability
  • Available in OS X v10.3 and later.
Declared In
CGRemoteOperation.h

Data Types

CGDirectDisplayID

A unique identifier for an attached display.

typedef uint32_t CGDirectDisplayID;
Discussion

In Quartz, the term display refers to a graphics hardware system consisting of a framebuffer, a color correction (gamma) table, and possibly an attached monitor. If no monitor is attached, a display is characterized as offline.

When a monitor is attached, Quartz assigns a unique display identifier (ID). A display ID can persist across processes and typically remains constant until the machine is restarted.

When assigning a display ID, Quartz considers the following parameters:

  • Vendor

  • Model

  • Serial number

  • Position in the I/O Kit registry

For information about how to obtain a display ID, see “Finding Displays.”

Availability
  • Available in OS X v10.0 and later.
Declared In
CGDirectDisplay.h

CGDisplayBlendFraction

The percentage of blend color used in a fade operation.

typedef float CGDisplayBlendFraction;
Discussion

The blend fraction ranges from 0 (no color) to 1 (full intensity). If you specify 0, the blend color is not applied. If you specify 1, the user sees only the blend color on the screen.

In a fade operation, Quartz blends a color specified by the application with the current contents of the framebuffer. The blend color can be applied both at the beginning and at the end of a fade operation.

Color blending during a fade operation is analogous to alpha blending in Quartz 2D, and the appearance is similar. However, the implementation is quite different. In a fade operation, the blend color is applied at the very end of the graphics pipeline, when the framebuffer is transferred to video output.

For example, the Universal Access preference panel in OS X allows you to select a flashing screen effect (sometimes called a visual bell) to accompany the system alert sound. When you select this option, the system uses a Quartz fade operation to produce the flash. The blend color is applied using a blend fraction of 0.5 or 50%.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGDisplayFade.h

CGDisplayConfigRef

A reference to a display configuration transaction.

typedef struct _CGDisplayConfigRef * CGDisplayConfigRef;
Discussion

This data type makes it possible to:

There are no restrictions on the order in which you accumulate configuration changes in a transaction.

Configuration changes sometimes conflict with each other. For example, a new origin might be rendered invalid by a subsequent configuration change.

If possible, Quartz uses a “best fit” strategy to resolve conflicts between configuration changes. For example, when you change the resolution of a single display in a two-display system, Quartz automatically retiles the displays to prevent separation or overlap of the adjoining edges.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGDisplayConfiguration.h

CGDisplayCount

The number of displays in various lists. (Deprecated. Use uint32_t instead.)

typedef uint32_t CGDisplayCount;
Discussion

Quartz uses CGDisplayCount to represent a count of either the current or the maximum number of displays in a display list. For example, see the function CGGetActiveDisplayList.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGDirectDisplay.h

CGDisplayErr

A uniform type for result codes returned by functions in Quartz Display Services. (Deprecated. Use CGError instead.)

typedef CGError CGDisplayErr;
Availability
  • Available in OS X v10.0 and later.
Declared In
CGDirectDisplay.h

CGDisplayFadeInterval

The duration in seconds of a fade operation or a fade hardware reservation.

typedef float CGDisplayFadeInterval;
Discussion

Quartz uses this data type to specify the duration of both fade-out and fade-in operations. Values may range from 0 to kCGMaxDisplayReservationInterval seconds. A 0 value means fade immediately—see CGDisplayFade.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGDisplayFade.h

CGDisplayFadeReservationToken

A token issued by Quartz when reserving one or more displays for a fade operation during a specified interval.

typedef uint32_t CGDisplayFadeReservationToken;
Discussion

Quartz lets you reserve the display hardware to perform a fade operation. Fade reservations are valid for up to 15 seconds. Only one token is needed for both fade-out and fade-in.

You should release a fade reservation immediately when you no longer need it. If the reservation expires, releasing it is safe but not necessary.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGDisplayFade.h

CGDisplayModeRef

A reference to a display mode object.

typedef struct CGDisplayMode *CGDisplayModeRef
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). For more information see “Creating and Managing Display Modes” or “Getting Information About a Display Mode.”

Availability
  • Available in OS X v10.6 and later.
Declared In
CGDirectDisplay.h

CGDisplayReservationInterval

The time interval for a fade reservation.

typedef float CGDisplayReservationInterval;
Discussion

A fade reservation interval is a period of time during which a specific display is reserved for a fade operation. Fade reservation intervals range from 1 to kCGMaxDisplayReservationInterval seconds.

For more information about fade reservations, see the function CGAcquireDisplayFadeReservation. Fade reservation tokens are discussed in CGDisplayFadeReservationToken.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGDisplayFade.h

CGGammaValue

A value used to map a color generated in software to a color supported by the display hardware.

typedef float CGGammaValue;
Discussion

In OS X, the Display panel in System Preferences is used to set the default gamma for a display. Quartz also allows an application to provide its own custom gamma information, using functions such as CGSetDisplayTransferByTable and CGSetDisplayTransferByFormula.

These functions take CGGammaValue arguments that specify:

  • A set of gamma table entries ranging from 0 to 1

  • The positive real coefficients in a gamma equation

Availability
  • Available in OS X v10.0 and later.
Declared In
CGDirectDisplay.h

CGOpenGLDisplayMask

A bitmask used in OpenGL to specify a set of attached displays.

typedef uint32_t CGOpenGLDisplayMask;
Discussion

In OS X, OpenGL can provide information about the capabilities of the hardware renderers driving a specified set of displays. A 32-bit mask is used to specify the displays—each bit in the mask represents a single display.

To learn how to find the mask bit that corresponds to a given display, see the function CGDisplayIDToOpenGLDisplayMask.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGDirectDisplay.h

CGRectCount

The size of an array of Quartz rectangles.

typedef uint32_t CGRectCount;
Discussion

For example, see the function CGWaitForScreenRefreshRects.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGRemoteOperation.h

CGRefreshRate

A display’s refresh rate in frames per second.

typedef double CGRefreshRate;
Discussion

When requesting a new display mode, you can specify a desired refresh rate as a hint to Quartz. For example, see the function CGDisplayBestModeForParametersAndRefreshRate.

Special Considerations

Most applications should never need this data type. Starting in OS X v10.6, the CGDisplayBestMode functions are deprecated and the new display mode API does not use this type.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGDirectDisplay.h

CGScreenUpdateMoveDelta

The distance, in pixel units, that an onscreen region moves.

struct CGScreenUpdateMoveDelta {
   int32_t dX, dY;
};
typedef struct CGScreenUpdateMoveDelta CGScreenUpdateMoveDelta;
Discussion

Move operation notifications are restricted to changes that move a region by an integer number of pixels. The fields dX and dY describe the direction of movement:

  • Positive values of dX indicate movement to the right.

  • Negative values of dX indicate movement to the left.

  • Positive values of dY indicate movement downward.

  • Negative values of dY indicate movement upward.

Availability
  • Available in OS X v10.3 and later.
Declared In
CGRemoteOperation.h

CGWindowLevel

A level assigned to a window by an application framework.

typedef int32_t CGWindowLevel;
Discussion

In OS X, application frameworks support the concept of multiple window levels (or layers). Window levels are assigned and managed by each individual framework.

Note that in an Aqua-compliant application, each document window exists in its own layer. As a result, windows created by different applications can be interleaved.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGWindowLevel.h

CGDisplayStreamRef

A reference to a display stream object.

typedef struct CGDisplayStream *CGDisplayStreamRef;
Discussion

This data type streams the contents of a display to your app. The contents can be scaled or converted to a different color space. You can also choose to capture only a portion of a display. Your update handler can be called either from a traditionalCFRunLoop or on a dispatch queue.

Availability
  • Available in OS X v10.8 and later.
Declared In
CGDisplayStream.h

CGDisplayStreamUpdate

A reference to frame update’s metadata.

typedef const struct CGDisplayStreamUpdate *CGDisplayStreamUpdateRef;
Discussion

This data type encapsulates information about how the frame changed since the previous frame delivered by a display stream. The metadata about the frame describes the portions of the screen that were redrawn and the portions of the screen that were moved from one place to another. You can merge multiple updates into a single update.

Availability
  • Available in OS X v10.8 and later.
Declared In
CGDisplayStream.h

CGDisplayStreamFrameAvailableHandler

A block called when a data stream has a new frame event to process.

typedef void (^CGDisplayStreamFrameAvailableHandler)(
   CGDisplayStreamFrameStatus status,
   uint64_t displayTime,
   IOSurfaceRef frameSurface,
   CGDisplayStreamUpdateRef updateRef
);
Discussion

The handler is called whenever the display stream has updated content to process as well as when other events occur. Each time a new frame is generated, the block receives an IOSurface object that contains the pixel data as well as an update object that describes the frame update.

The handler receives the following parameters:

status

Describes the kind of update being passed to the handler. See “Display Stream Update Status.”

displayTime

The mach absolute time when the event occurred. For a frame event, this is when the frame was displayed by the window server.

frameSurface

An IOSurface object that contains the pixel data. May be NULL in some cases.

If you need to maintain a reference to the surface beyond the lifetime of the handler call, you must call the CFRetain function to retain the surface and the IOSurfaceIncrementUseCount function to let the display stream know that the frame is not ready for re-use. Once you are finished using the surface you must call the IOSurfaceDecrementUseCount function and then call the CFRelease function. If you are maintaining a cache of information about the surface (such as a GL texture object created from the surface’s contents), you must not call release it until after you remove it from your cache.

You can not depend on the set of surfaces being used by the display stream as being static, so you should remove surfaces from the cache when they haven’t been re-used in a while.

updateRef

A CGDisplayStreamUpdate reference that holds the update metadata for the current frame.

If you need to hold onto the metadata beyond the lifetime of the handler call, you must call the CFRetain function on the update reference before the end of the handler. When you are finished with the update, call the call the CFRelease function.

This parameter holds NULL when the status parameter’s has any value other than kCGDisplayStreamFrameStatusFrameComplete.

Availability
  • Available in OS X v10.8 and later.
Declared In
CGDisplayStream.h

Constants

Display Capture Options

Configuration parameters that are used when capturing displays.

enum {
   kCGCaptureNoOptions = 0,
   kCGCaptureNoFill = (1 << 0)
};
typedef uint32_t CGCaptureOptions;
Constants
kCGCaptureNoOptions

The system should use the default fill behavior, which is fill with black.

Available in OS X v10.3 and later.

Declared in CGDirectDisplay.h.

kCGCaptureNoFill

Disables fill with black.

Available in OS X v10.3 and later.

Declared in CGDirectDisplay.h.

Discussion

For information about how these constants are used, see the functions CGDisplayCaptureWithOptions and CGCaptureAllDisplaysWithOptions.

Display Configuration Change Flags

The configuration parameters that are passed to a display reconfiguration callback function.

enum {
   kCGDisplayBeginConfigurationFlag = (1 << 0),
   kCGDisplayMovedFlag              = (1 << 1),
   kCGDisplaySetMainFlag            = (1 << 2),
   kCGDisplaySetModeFlag            = (1 << 3),
   kCGDisplayAddFlag                = (1 << 4),
   kCGDisplayRemoveFlag             = (1 << 5),
   kCGDisplayEnabledFlag            = (1 << 8),
   kCGDisplayDisabledFlag           = (1 << 9),
   kCGDisplayMirrorFlag             = (1 << 10),
   kCGDisplayUnMirrorFlag           = (1 << 11),
   kCGDisplayDesktopShapeChangedFlag = (1 << 12)
};
typedef u_int32_t CGDisplayChangeSummaryFlags;
Constants
kCGDisplayBeginConfigurationFlag

The display configuration is about to change.

Available in OS X v10.3 and later.

Declared in CGDisplayConfiguration.h.

kCGDisplayMovedFlag

The location of the upper-left corner of the display in the global display coordinate space has changed.

Available in OS X v10.3 and later.

Declared in CGDisplayConfiguration.h.

kCGDisplaySetMainFlag

The display is now the main display.

Available in OS X v10.3 and later.

Declared in CGDisplayConfiguration.h.

kCGDisplaySetModeFlag

The display mode has changed.

Available in OS X v10.3 and later.

Declared in CGDisplayConfiguration.h.

kCGDisplayAddFlag

The display has been added to the active display list.

Available in OS X v10.3 and later.

Declared in CGDisplayConfiguration.h.

kCGDisplayRemoveFlag

The display has been removed from the active display list.

Available in OS X v10.3 and later.

Declared in CGDisplayConfiguration.h.

kCGDisplayEnabledFlag

The display has been enabled.

Available in OS X v10.3 and later.

Declared in CGDisplayConfiguration.h.

kCGDisplayDisabledFlag

The display has been disabled.

Available in OS X v10.3 and later.

Declared in CGDisplayConfiguration.h.

kCGDisplayMirrorFlag

The display is now mirroring another display.

Available in OS X v10.3 and later.

Declared in CGDisplayConfiguration.h.

kCGDisplayUnMirrorFlag

The display is no longer mirroring another display.

Available in OS X v10.3 and later.

Declared in CGDisplayConfiguration.h.

kCGDisplayDesktopShapeChangedFlag

The shape of the desktop (the union of display areas) has changed.

Available in OS X v10.5 and later.

Declared in CGDisplayConfiguration.h.

Discussion

For information about how these constants are used, see the callback CGDisplayReconfigurationCallBack.

Display Configuration Scopes

The scope of the changes in a display configuration transaction.

enum {
   kCGConfigureForAppOnly = 0,
   kCGConfigureForSession = 1,
   kCGConfigurePermanently = 2
};
Constants
kCGConfigureForAppOnly

Changes persist for the lifetime of the current application. After the application terminates, the display configuration settings revert to the current login session.

Available in OS X v10.2 and later.

Declared in CGDisplayConfiguration.h.

kCGConfigureForSession

Changes persist for the lifetime of the current login session. After the current session terminates, the displays revert to the last saved permanent configuration.

Available in OS X v10.2 and later.

Declared in CGDisplayConfiguration.h.

kCGConfigurePermanently

Changes persist in future login sessions by the same user. If the requested changes cannot be supported by the Aqua UI (resolution and pixel depth constraints apply), the settings for the current login session are used instead, and any changes have session scope.

Available in OS X v10.2 and later.

Declared in CGDisplayConfiguration.h.

Discussion

For information about how these constants are used, see the function CGCompleteDisplayConfiguration.

Display Fade Blend Fractions

The lower and upper bounds for blend color fractions during a display fade operation.

#define kCGDisplayBlendNormal (0.0)
#define kCGDisplayBlendSolidColor (1.0)
Constants
kCGDisplayBlendNormal

The blend color is not applied at the start or end of a fade operation.

Available in OS X v10.2 and later.

Declared in CGDisplayFade.h.

kCGDisplayBlendSolidColor

The user sees only the blend color at the start or end of a fade operation.

Available in OS X v10.2 and later.

Declared in CGDisplayFade.h.

Discussion

For general information about blend fractions, see the data type CGDisplayBlendFraction. For information about how these constants are used, see the function CGDisplayFade.

Display Fade Constants

Values relating to fade operations.

#define kCGMaxDisplayReservationInterval (15.0)
#define kCGDisplayFadeReservationInvalidToken (0)
Constants
kCGMaxDisplayReservationInterval

The maximum number of seconds for fade hardware reservations and display fade operations. For general information about fade intervals, see the data type CGDisplayFadeInterval.

Available in OS X v10.2 and later.

Declared in CGDisplayFade.h.

kCGDisplayFadeReservationInvalidToken

An invalid fade reservation token. For general information about fade reservation tokens, see the data type CGDisplayFadeReservationToken.

Available in OS X v10.2 and later.

Declared in CGDisplayFade.h.

Display ID Defaults

Default values for a display ID.

#define kCGDirectMainDisplay (CGMainDisplayID())
#define kCGNullDirectDisplay ((CGDirectDisplayID)0)
Constants
kCGDirectMainDisplay

The current main display ID.

Available in OS X v10.0 and later.

Declared in CGDirectDisplay.h.

kCGNullDirectDisplay

A value that will never correspond to actual hardware.

Available in OS X v10.2 and later.

Declared in CGDirectDisplay.h.

Display Mode Standard Properties

Keys for the standard properties in a display mode dictionary. (Deprecated. There is no replacement; as display mode dictionaries are deprecated in OS X v10.6, these properties are not needed.)

#define kCGDisplayWidth CFSTR("Width")
#define kCGDisplayHeight CFSTR("Height")
#define kCGDisplayMode CFSTR("Mode")
#define kCGDisplayBitsPerPixel CFSTR("BitsPerPixel")
#define kCGDisplayBitsPerSample CFSTR("BitsPerSample")
#define kCGDisplaySamplesPerPixel CFSTR("SamplesPerPixel")
#define kCGDisplayRefreshRate CFSTR("RefreshRate")
#define kCGDisplayModeUsableForDesktopGUICFSTR("UsableForDesktopGUI")
#define kCGDisplayIOFlags CFSTR("IOFlags")
#define kCGDisplayBytesPerRow CFSTR("kCGDisplayBytesPerRow")
Constants
kCGDisplayWidth

Specifies a CFNumber integer value that represents the width of the display in pixels.

Available in OS X v10.2 and later.

Declared in CGDirectDisplay.h.

kCGDisplayHeight

Specifies a CFNumber integer value that represents the height of the display in pixels.

Available in OS X v10.2 and later.

Declared in CGDirectDisplay.h.

kCGDisplayMode

Specifies a CFNumber integer value that represents the I/O Kit display mode number.

Available in OS X v10.2 and later.

Declared in CGDirectDisplay.h.

kCGDisplayBitsPerPixel

Specifies a CFNumber integer value that represents the number of bits in a pixel.

Available in OS X v10.2 and later.

Declared in CGDirectDisplay.h.

kCGDisplayBitsPerSample

Specifies a CFNumber integer value that represents the number of bits in an individual sample (for example, a color value in an RGB pixel).

Available in OS X v10.2 and later.

Declared in CGDirectDisplay.h.

kCGDisplaySamplesPerPixel

Specifies a CFNumber integer value that represents the number of samples in a pixel.

Available in OS X v10.2 and later.

Declared in CGDirectDisplay.h.

kCGDisplayRefreshRate

Specifies a CFNumber double-precision floating point value that represents the refresh rate of a CRT display. Some displays may not use conventional video vertical and horizontal sweep in painting the screen; these displays report a refresh rate of 0.

Available in OS X v10.2 and later.

Declared in CGDirectDisplay.h.

kCGDisplayModeUsableForDesktopGUI

Specifies a CFBoolean value that indicates whether the display is suitable for use with the OS X graphical user interface. The criteria include factors such as sufficient width and height and adequate pixel depth.

Available in OS X v10.2 and later.

Declared in CGDirectDisplay.h.

kCGDisplayIOFlags

Specifies a CFNumber integer value that contains the I/O Kit display mode flags. For more information, see the header file IOKit/IOGraphicsTypes.h.

Available in OS X v10.2 and later.

Declared in CGDirectDisplay.h.

kCGDisplayBytesPerRow

Specifies a CFNumber integer value that represents the number of bytes in a row on the display.

Available in OS X v10.2 and later.

Declared in CGDirectDisplay.h.

Discussion

To learn how to use these keys to access the values in a display mode dictionary, see CFDictionary Reference.

Special Considerations

Starting in OS X v10.6, display mode dictionaries have been made obsolete by the display mode opaque type. For more information on display modes, see“Changing Display Modes (OS X v10.6 or later)” in Quartz Display Services Reference.

Display Mode Optional Properties

Keys for optional properties in a display mode dictionary. (Deprecated. There is no replacement; as display mode dictionaries are deprecated in OS X v10.6, these properties are not needed.)

#define kCGDisplayModeIsSafeForHardware CFSTR ("kCGDisplayModeIsSafeForHardware")
#define kCGDisplayModeIsInterlaced CFSTR("kCGDisplayModeIsInterlaced")
#define kCGDisplayModeIsStretched CFSTR("kCGDisplayModeIsStretched")
#define kCGDisplayModeIsTelevisionOutput CFSTR ("kCGDisplayModeIsTelevisionOutput")
Constants
kCGDisplayModeIsSafeForHardware

Specifies a CFBoolean value indicating that the display mode doesn't need a confirmation dialog to be set.

Available in OS X v10.2 and later.

Declared in CGDirectDisplay.h.

kCGDisplayModeIsInterlaced

Specifies a CFBoolean value indicating that the I/O Kit interlace mode flag is set.

Available in OS X v10.2 and later.

Declared in CGDirectDisplay.h.

kCGDisplayModeIsStretched

Specifies a CFBoolean value indicating that the I/O Kit stretched mode flag is set.

Available in OS X v10.2 and later.

Declared in CGDirectDisplay.h.

kCGDisplayModeIsTelevisionOutput

Specifies a CFBoolean value indicating that the I/O Kit television output mode flag is set.

Available in OS X v10.2 and later.

Declared in CGDirectDisplay.h.

Discussion

A given key is present in a display mode dictionary only if the property applies, and is always associated with a value of kCFBooleanTrue. Keys not relevant to a particular display mode will not appear in the mode dictionary.

Special Considerations

Starting in OS X v10.6, display mode dictionaries have been made obsolete by the display mode opaque type. For more information on display modes, see“Changing Display Modes (OS X v10.6 or later)” in Quartz Display Services Reference.

Reserved Window Levels

Window level constants.

#define kCGNumReservedWindowLevels      (16)
Constants
kCGNumReservedWindowLevels

The number of window levels reserved by Apple for internal use. Cocoa uses this constant during compilation.

Available in OS X v10.0 and later.

Declared in CGWindowLevel.h.

Screen Update Operations

Types of screen-update operations.

enum _CGScreenUpdateOperation {
   kCGScreenUpdateOperationRefresh = 0,
   kCGScreenUpdateOperationMove = (1 << 0),
   kCGScreenUpdateOperationReducedDirtyRectangleCount = (1 <<  31)
};
typedef uint32_t CGScreenUpdateOperation;
Constants
kCGScreenUpdateOperationRefresh

A screen-refresh operation.

Available in OS X v10.3 and later.

Declared in CGRemoteOperation.h.

kCGScreenUpdateOperationMove

A screen-move operation.

Available in OS X v10.3 and later.

Declared in CGRemoteOperation.h.

kCGScreenUpdateOperationReducedDirtyRectangleCount

When presented as part of the requested operations to the function CGWaitForScreenUpdateRects, specifies that the function should try to minimize the number of rectangles returned to represent the changed areas of the display. The function may combine adjacent rectangles within a larger bounding rectangle, which may include unmodified areas of the display.

Available in OS X v10.4 and later.

Declared in CGRemoteOperation.h.

Discussion

For information about how these constants are used, see the function CGWaitForScreenUpdateRects.

Window Level Keys

Keys that represent the standard window levels in OS X. Quartz includes these keys to support application frameworks like Cocoa. Applications do not need to use them directly.

enum _CGCommonWindowLevelKey {
   kCGBaseWindowLevelKey = 0,
   kCGMinimumWindowLevelKey,
   kCGDesktopWindowLevelKey,
   kCGBackstopMenuLevelKey,
   kCGNormalWindowLevelKey,
   kCGFloatingWindowLevelKey,
   kCGTornOffMenuWindowLevelKey,
   kCGDockWindowLevelKey,
   kCGMainMenuWindowLevelKey,
   kCGStatusWindowLevelKey,
   kCGModalPanelWindowLevelKey,
   kCGPopUpMenuWindowLevelKey,
   kCGDraggingWindowLevelKey,
   kCGScreenSaverWindowLevelKey,
   kCGMaximumWindowLevelKey,
   kCGOverlayWindowLevelKey,
   kCGHelpWindowLevelKey,
   kCGUtilityWindowLevelKey,
   kCGDesktopIconWindowLevelKey,
   kCGCursorWindowLevelKey,
   kCGAssistiveTechHighWindowLevelKey,
   kCGNumberOfWindowLevelKeys
};
typedef int32_t CGWindowLevelKey;
Constants
kCGBaseWindowLevelKey

The base key used to define window levels. Do not use.

Available in OS X v10.0 and later.

Declared in CGWindowLevel.h.

kCGMinimumWindowLevelKey

The lowest available window level.

Available in OS X v10.0 and later.

Declared in CGWindowLevel.h.

kCGDesktopWindowLevelKey

The level for the desktop.

Available in OS X v10.0 and later.

Declared in CGWindowLevel.h.

kCGBackstopMenuLevelKey

The level of the backstop menu.

Available in OS X v10.0 and later.

Declared in CGWindowLevel.h.

kCGNormalWindowLevelKey

The level for normal windows.

Available in OS X v10.0 and later.

Declared in CGWindowLevel.h.

kCGFloatingWindowLevelKey

The level for floating windows.

Available in OS X v10.0 and later.

Declared in CGWindowLevel.h.

kCGTornOffMenuWindowLevelKey

The level for torn-off menus.

Available in OS X v10.0 and later.

Declared in CGWindowLevel.h.

kCGDockWindowLevelKey

The level for the dock.

Available in OS X v10.0 and later.

Declared in CGWindowLevel.h.

kCGMainMenuWindowLevelKey

The level for the menus displayed in the menu bar.

Available in OS X v10.0 and later.

Declared in CGWindowLevel.h.

kCGStatusWindowLevelKey

The level for status windows.

Available in OS X v10.0 and later.

Declared in CGWindowLevel.h.

kCGModalPanelWindowLevelKey

The level for modal panels.

Available in OS X v10.0 and later.

Declared in CGWindowLevel.h.

kCGPopUpMenuWindowLevelKey

The level for pop-up menus.

Available in OS X v10.0 and later.

Declared in CGWindowLevel.h.

kCGDraggingWindowLevelKey

The level for a window being dragged.

Available in OS X v10.0 and later.

Declared in CGWindowLevel.h.

kCGScreenSaverWindowLevelKey

The level for screen savers.

Available in OS X v10.0 and later.

Declared in CGWindowLevel.h.

kCGMaximumWindowLevelKey

The highest allowed window level.

Available in OS X v10.0 and later.

Declared in CGWindowLevel.h.

kCGOverlayWindowLevelKey

The level for overlay windows.

Available in OS X v10.1 and later.

Declared in CGWindowLevel.h.

kCGHelpWindowLevelKey

The level for help windows.

Available in OS X v10.1 and later.

Declared in CGWindowLevel.h.

kCGUtilityWindowLevelKey

The level for utility windows.

Available in OS X v10.1 and later.

Declared in CGWindowLevel.h.

kCGDesktopIconWindowLevelKey

The level for desktop icons.

Available in OS X v10.1 and later.

Declared in CGWindowLevel.h.

kCGCursorWindowLevelKey

The level for the cursor.

Available in OS X v10.2 and later.

Declared in CGWindowLevel.h.

kCGAssistiveTechHighWindowLevelKey

The level for assistive technology.

Available in OS X v10.3 and later.

Declared in CGWindowLevel.h.

kCGNumberOfWindowLevelKeys

The total number of window levels.

Available in OS X v10.0 and later.

Declared in CGWindowLevel.h.

Window Server Session Properties

The keys for the standard properties in a window server session dictionary.

#define kCGSessionUserIDKey CFSTR("kCGSSessionUserIDKey")
#define kCGSessionUserNameKey CFSTR("kCGSSessionUserNameKey")
#define kCGSessionConsoleSetKey CFSTR("kCGSSessionConsoleSetKey")
#define kCGSessionOnConsoleKey CFSTR("kCGSSessionOnConsoleKey")
#define kCGSessionLoginDoneKey CFSTR("kCGSessionLoginDoneKey")
Constants
kCGSessionUserIDKey

A CFNumber 32-bit unsigned integer value that encodes a user ID for the session’s current user.

Available in OS X v10.3 and later.

Declared in CGSession.h.

kCGSessionUserNameKey

A CFString value that encodes the session’s short user name as set by the login operation.

Available in OS X v10.3 and later.

Declared in CGSession.h.

kCGSessionConsoleSetKey

A CFNumber 32-bit unsigned integer value that represents a set of hardware composing a console.

Available in OS X v10.3 and later.

Declared in CGSession.h.

kCGSessionOnConsoleKey

A CFBoolean value indicating whether the session is on a console.

Available in OS X v10.3 and later.

Declared in CGSession.h.

kCGSessionLoginDoneKey

A CFBoolean value indicating whether the login operation has been done.

Available in OS X v10.3 and later.

Declared in CGSession.h.

Discussion

To learn how to use these keys to access the values in a session dictionary, see CFDictionary Reference.

Display Stream Update Rect Types

Use these constants to determine which rectangles your app is interested in.

enum
{
   kCGDisplayStreamUpdateRefreshedRects,
   kCGDisplayStreamUpdateMovedRects,
   kCGDisplayStreamUpdateDirtyRects,
   kCGDisplayStreamUpdateReducedDirtyRects,
};
typedef int32_t CGDisplayStreamUpdateRectType;
Constants
kCGDisplayStreamUpdateRefreshedRects

The rectangles for the portions of the display that were redrawn.

Available in OS X v10.8 and later.

Declared in CGDisplayStream.h.

kCGDisplayStreamUpdateMovedRects

The rectangles for the portions of the display that were simply moved from one part of the display to another.

Available in OS X v10.8 and later.

Declared in CGDisplayStream.h.

kCGDisplayStreamUpdateDirtyRects

The union of both rectangles that were redrawn and rectangles that were moved.

Available in OS X v10.8 and later.

Declared in CGDisplayStream.h.

kCGDisplayStreamUpdateReducedDirtyRects

The union is calculated and then simplified. This reduces the number of rectangles returned to your app, but it may report some pixels that were not actually changed.

Available in OS X v10.8 and later.

Declared in CGDisplayStream.h.

Display Stream Update Status

Describes a frame update event.

enum
{
   kCGDisplayStreamFrameStatusFrameComplete,
   kCGDisplayStreamFrameStatusFrameIdle,
   kCGDisplayStreamFrameStatusFrameBlank,
   kCGDisplayStreamFrameStatusStopped,
};
typedef int32_t CGDisplayStreamFrameStatus;
Constants
kCGDisplayStreamFrameStatusFrameComplete

A new frame was generated.

Available in OS X v10.8 and later.

Declared in CGDisplayStream.h.

kCGDisplayStreamFrameStatusFrameIdle

A new frame was not generated because the display did not change.

Available in OS X v10.8 and later.

Declared in CGDisplayStream.h.

kCGDisplayStreamFrameStatusFrameBlank

A new frame was not generated because the display has gone blank.

Available in OS X v10.8 and later.

Declared in CGDisplayStream.h.

kCGDisplayStreamFrameStatusStopped

The display stream was stopped.

Available in OS X v10.8 and later.

Declared in CGDisplayStream.h.

Display Stream Optional Property Keys

These keys are used to populate the properties dictionary used when creating a new display stream.

const CFStringRef kCGDisplayStreamSourceRect;
const CFStringRef kCGDisplayStreamDestinationRect;
const CFStringRef kCGDisplayStreamPreserveAspectRatio;
const CFStringRef kCGDisplayStreamColorSpace;
const CFStringRef kCGDisplayStreamMinimumFrameTime;
const CFStringRef kCGDisplayStreamShowCursor;
const CFStringRef kCGDisplayStreamQueueDepth;
const CFStringRef kCGDisplayStreamYCbCrMatrix;
Constants
kCGDisplayStreamSourceRect

This key specifies that the display stream only samples a subset of the display’s framebuffer. If this key is not included in the dictionary, then the entire display is streamed. The value must be created using the CGRectCreateDictionaryRepresentation function. The rectangle is specified in points in the display’s logical coordinate system.

Available in OS X v10.8 and later.

Declared in CGDisplayStream.h.

kCGDisplayStreamDestinationRect

This key specifies that the display stream outputs the frame data into a subset of the output IOSurface object. If this key is not included in the dictionary, then the entire output surface is used. The value must be created using the CGRectCreateDictionaryRepresentation function. The rectangle is specified in pixels in the surface’s coordinate system.

Available in OS X v10.8 and later.

Declared in CGDisplayStream.h.

kCGDisplayStreamPreserveAspectRatio

This key specifies whether the display stream preserves the aspect ratio of the source pixel data. If this key is not included in the dictionary, then the aspect ratio is preserved. If the aspect ratio is preserved, then the display stream adds black bars to the output data. If the aspect ratio is not preserved, then the pixel data is stretched to fit the output buffer’s dimensions. The value associated with the key must be a CFBoolean.

Available in OS X v10.8 and later.

Declared in CGDisplayStream.h.

kCGDisplayStreamColorSpace

This key specifies the color space of the output buffer. If this key is not included in the dictionary, the output buffer uses the same color space as the display. The value associated with this key must be a CGColorSpaceRef for the desired color space.

Available in OS X v10.8 and later.

Declared in CGDisplayStream.h.

kCGDisplayStreamMinimumFrameTime

This key specifies the desired minimum time between frame updates, allowing you to throttle the rate at which updates are received. If this key is not included in the dictionary, the default value is 0, meaning that updates are not throttled. The value must be specified as a CFNumber.

Available in OS X v10.8 and later.

Declared in CGDisplayStream.h.

kCGDisplayStreamShowCursor

This key specifies whether the cursor should appear in the stream. If this key is not included in the dictionary, the cursor is visible. The value must be specified as a CFBoolean.

Available in OS X v10.8 and later.

Declared in CGDisplayStream.h.

kCGDisplayStreamQueueDepth

This key specifies the number of frames to keep in the queue. If this key is not included in the dictionary, the default value is 3 frames. Specifying more frames uses more memory, but may allow you to process frame data without stalling the display stream. The value associated with this key should be specified as a CFNumber, and should not exceed 8 frames.

Available in OS X v10.8 and later.

Declared in CGDisplayStream.h.

kCGDisplayStreamYCbCrMatrix

This key should only be included if you the display stream is creating output frames in either the 420v or 420f formats. It is used to specify the YCbCr matrix applied to the output surface. The value associated with this key must be one of the strings specified in “Display Stream YCbCr to RGB conversion Matrix Options.”

Available in OS X v10.8 and later.

Declared in CGDisplayStream.h.

Display Stream YCbCr to RGB conversion Matrix Options

These strings are used to specify a matrix for the kCGDisplayStreamYCbCrMatrix option.

CFStringRef kCGDisplayStreamYCbCrMatrix_ITU_R_709_2;
CFStringRef kCGDisplayStreamYCbCrMatrix_ITU_R_601_4;
CFStringRef kCGDisplayStreamYCbCrMatrix_SMPTE_240M_1995
Constants
kCGDisplayStreamYCbCrMatrix_ITU_R_709_2

Specifies the YCbCr to RGB conversion matrix for HDTV digital television (ITU R 709) images.

Available in OS X v10.8 and later.

Declared in CGDisplayStream.h.

kCGDisplayStreamYCbCrMatrix_ITU_R_601_4

Specifies the YCbCr to RGB conversion matrix for standard digital television ( ITU R 601) images.

Available in OS X v10.8 and later.

Declared in CGDisplayStream.h.

kCGDisplayStreamYCbCrMatrix_SMPTE_240M_1995

Specifies the YCbCR to RGB conversion matrix for 1920 x 1135 HDTV (SMPTE 240M 1995).

Available in OS X v10.8 and later.

Declared in CGDisplayStream.h.