Mac Developer Library

Developer

ApplicationServices Framework Reference Quartz Display Services Reference

Options
Deployment Target:

On This Page
Language:

Quartz Display Services Reference

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import CoreGraphics

Objective-C

@import CoreGraphics;

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:

  • Examine and change display mode properties such as width, height, and pixel depth

  • Configure a set of displays in a single operation

  • Capture one or more displays for exclusive use

  • Stream the contents of a display

  • Perform fade effects

  • Activate display mirroring

  • Configure gamma color correction tables

  • Receive notification of screen update operations

Functions

  • Returns the display ID of the main display.

    Declaration

    Swift

    func CGMainDisplayID() -> CGDirectDisplayID

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func CGGetOnlineDisplayList(_ maxDisplays: UInt32, _ onlineDspys: UnsafeMutablePointer<CGDirectDisplayID>, _ dspyCnt: UnsafeMutablePointer<UInt32>) -> CGError

    Objective-C

    CGError CGGetOnlineDisplayList ( uint32_t maxDisplays, CGDirectDisplayID *onlineDisplays, uint32_t *displayCount );

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func CGGetActiveDisplayList(_ maxDisplays: UInt32, _ activeDspys: UnsafeMutablePointer<CGDirectDisplayID>, _ dspyCnt: UnsafeMutablePointer<UInt32>) -> CGError

    Objective-C

    CGError CGGetActiveDisplayList ( uint32_t maxDisplays, CGDirectDisplayID *activeDisplays, uint32_t *displayCount );

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func CGGetDisplaysWithOpenGLDisplayMask(_ mask: CGOpenGLDisplayMask, _ maxDisplays: UInt32, _ dspys: UnsafeMutablePointer<CGDirectDisplayID>, _ dspyCnt: UnsafeMutablePointer<UInt32>) -> CGError

    Objective-C

    CGError CGGetDisplaysWithOpenGLDisplayMask ( CGOpenGLDisplayMask mask, uint32_t maxDisplays, CGDirectDisplayID *displays, uint32_t *matchingDisplayCount );

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func CGGetDisplaysWithPoint(_ point: CGPoint, _ maxDisplays: UInt32, _ dspys: UnsafeMutablePointer<CGDirectDisplayID>, _ dspyCnt: UnsafeMutablePointer<UInt32>) -> CGError

    Objective-C

    CGError CGGetDisplaysWithPoint ( CGPoint point, uint32_t maxDisplays, CGDirectDisplayID *displays, uint32_t *matchingDisplayCount );

    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.

    Discussion

    If the dspys array is NULL, this function ignores the maxDisplays parameter. If the maxDisplays parameter is 0, this function ignores the dspys array. In any case, this function fills in the dspyCnt pointer with the number of displays that contain the specified point.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func CGGetDisplaysWithRect(_ rect: CGRect, _ maxDisplays: UInt32, _ dspys: UnsafeMutablePointer<CGDirectDisplayID>, _ dspyCnt: UnsafeMutablePointer<UInt32>) -> CGError

    Objective-C

    CGError CGGetDisplaysWithRect ( CGRect rect, uint32_t maxDisplays, CGDirectDisplayID *displays, uint32_t *matchingDisplayCount );

    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.

    Discussion

    If the dspys array is NULL, this function ignores the maxDisplays parameter. If the maxDisplays parameter is 0, this function ignores the dspys array. In any case, this function fills in the dspyCnt pointer with the number of displays that intersect the specified rectangle.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

  • Maps an OpenGL display mask to a display ID.

    Declaration

    Swift

    func CGOpenGLDisplayMaskToDisplayID(_ mask: CGOpenGLDisplayMask) -> CGDirectDisplayID

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

  • Maps a display ID to an OpenGL display mask.

    Declaration

    Swift

    func CGDisplayIDToOpenGLDisplayMask(_ display: CGDirectDisplayID) -> CGOpenGLDisplayMask

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

  • Captures a display for exclusive use by an application.

    Declaration

    Swift

    func CGDisplayCapture(_ display: CGDirectDisplayID) -> CGError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func CGDisplayCaptureWithOptions(_ display: CGDirectDisplayID, _ options: CGCaptureOptions) -> CGError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.3 and later.

    See Also

    CGDisplayCapture

  • Releases a captured display.

    Declaration

    Swift

    func CGDisplayRelease(_ display: CGDirectDisplayID) -> CGError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

  • Returns a Boolean value indicating whether a display is captured.

    Deprecation Statement

    There is no replacement.

    Declaration

    Objective-C

    boolean_t CGDisplayIsCaptured ( CGDirectDisplayID display );

    Parameters

    display

    The identifier of the display to be accessed.

    Return Value

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

    Import Statement

    Objective-C

    @import CoreGraphics;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

  • Captures all attached displays.

    Declaration

    Swift

    func CGCaptureAllDisplays() -> CGError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

    See Also

    CGDisplayCapture

  • Captures all attached displays, using the specified options.

    Declaration

    Swift

    func CGCaptureAllDisplaysWithOptions(_ options: CGCaptureOptions) -> CGError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.3 and later.

  • Releases all captured displays.

    Declaration

    Swift

    func CGReleaseAllDisplays() -> CGError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func CGShieldingWindowID(_ display: CGDirectDisplayID) -> UInt32

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func CGShieldingWindowLevel() -> Int32

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

  • CGDisplayAddressForPosition CGDisplayAddressForPosition Available in OS X v10.0 through OS X v10.6

    Returns the address in framebuffer memory that corresponds to a position on an online display.

    Deprecation Statement

    There is no replacement; because direct access to the raw framebuffer is not necessary, there is no need to retrieve its memory address.

    Declaration

    Objective-C

    void * CGDisplayAddressForPosition ( CGDirectDisplayID display, int32_t x, int32_t y );

    Parameters

    display

    The identifier of the display to be accessed.

    x

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

    y

    The y-coordinate of a position in the global display coordinate space. The origin is the upper-left corner of the main display, and the y-axis is oriented down.

    Return Value

    The address in framebuffer memory that corresponds to the specified position. If the display ID is invalid or the point lies outside the bounds of the display, the return value is NULL.

    Discussion

    If the display has not been captured, the returned address may refer to read-only memory.

    Special Considerations

    This deprecated function returned an address in framebuffer memory. Instead of using the raw framebuffer to draw to the screen, you should instead use a supported drawing engine such as Quartz or OpenGL. While accessing the framebuffer directly has been deprecated, it is possible to copy screen data using CGDisplayCreateImageForRect.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.6.

    Deprecated in OS X v10.6.

  • CGDisplayBaseAddress CGDisplayBaseAddress Available in OS X v10.0 through OS X v10.6

    Returns the base address in framebuffer memory of an online display.

    Deprecation Statement

    There is no replacement; because direct access to the raw framebuffer is not necessary, there is no need to retrieve its memory address.

    Declaration

    Objective-C

    void * CGDisplayBaseAddress ( CGDirectDisplayID display );

    Parameters

    display

    The identifier of the display to be accessed.

    Return Value

    The base address in framebuffer memory of the specified display. If the display ID is invalid, the return value is NULL.

    Discussion

    If the display has not been captured, the returned address may refer to read-only memory.

    Special Considerations

    This deprecated function returned an address in framebuffer memory. Instead of using the raw framebuffer to draw to the screen, you should instead use a supported drawing engine such as Quartz or OpenGL. While accessing the framebuffer directly has been deprecated, it is possible to copy screen data using CGDisplayCreateImage.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.6.

    Deprecated in OS X v10.6.

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

    Declaration

    Swift

    func CGDisplayGetDrawingContext(_ display: CGDirectDisplayID) -> Unmanaged<CGContext>!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.3 and later.

  • Returns an image containing the contents of the specified display.

    Declaration

    Swift

    func CGDisplayCreateImage(_ display: CGDirectDisplayID) -> Unmanaged<CGImage>!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.6 and later.

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

    Declaration

    Swift

    func CGDisplayCreateImageForRect(_ display: CGDirectDisplayID, _ rect: CGRect) -> Unmanaged<CGImage>!

    Objective-C

    CGImageRef CGDisplayCreateImageForRect ( CGDirectDisplayID display, 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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.6 and later.

  • Begins a new set of display configuration changes.

    Declaration

    Swift

    func CGBeginDisplayConfiguration(_ pConfigRef: UnsafeMutablePointer<CGDisplayConfigRef>) -> CGError

    Objective-C

    CGError CGBeginDisplayConfiguration ( CGDisplayConfigRef *config );

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

  • Cancels a set of display configuration changes.

    Declaration

    Swift

    func CGCancelDisplayConfiguration(_ configRef: CGDisplayConfigRef) -> CGError

    Objective-C

    CGError CGCancelDisplayConfiguration ( CGDisplayConfigRef config );

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

  • Completes a set of display configuration changes.

    Declaration

    Swift

    func CGCompleteDisplayConfiguration(_ configRef: CGDisplayConfigRef, _ option: CGConfigureOption) -> CGError

    Objective-C

    CGError CGCompleteDisplayConfiguration ( CGDisplayConfigRef config, 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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

  • Changes the configuration of a mirroring set.

    Declaration

    Swift

    func CGConfigureDisplayMirrorOfDisplay(_ configRef: CGDisplayConfigRef, _ display: CGDirectDisplayID, _ masterDisplay: CGDirectDisplayID) -> CGError

    Objective-C

    CGError CGConfigureDisplayMirrorOfDisplay ( CGDisplayConfigRef config, CGDirectDisplayID display, CGDirectDisplayID master );

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

  • Configures the display mode of a display.

    Deprecation Statement

    Use CGConfigureDisplayWithDisplayMode instead.

    Declaration

    Objective-C

    CGError CGConfigureDisplayMode ( CGDisplayConfigRef config, CGDirectDisplayID display, CFDictionaryRef mode );

    Parameters

    configRef

    A display configuration, acquired by calling CGBeginDisplayConfiguration.

    display

    The identifier of the display being configured.

    mode

    A display mode dictionary (see the discussion below).

    Return Value

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

    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.

    The display mode you provide must be one of the following:

    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.

    Special Considerations

    This deprecated function takes as a parameter a display mode dictionary. Starting in OS X v10.6, display mode dictionaries have been replaced by the CGDisplayMode opaque type. For information on the CGDisplayMode opaque type, see “Getting Information About a Display Mode”.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

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

    Declaration

    Swift

    func CGConfigureDisplayOrigin(_ configRef: CGDisplayConfigRef, _ display: CGDirectDisplayID, _ x: Int32, _ y: Int32) -> CGError

    Objective-C

    CGError CGConfigureDisplayOrigin ( CGDisplayConfigRef config, 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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

  • Restores the permanent display configuration settings for the current user.

    Declaration

    Swift

    func CGRestorePermanentDisplayConfiguration()

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func CGConfigureDisplayStereoOperation(_ configRef: CGDisplayConfigRef, _ display: CGDirectDisplayID, _ stereo: boolean_t, _ forceBlueLine: boolean_t) -> CGError

    Objective-C

    CGError CGConfigureDisplayStereoOperation ( CGDisplayConfigRef config, 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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

  • Immediately enables or disables stereo operation for a display.

    Declaration

    Swift

    func CGDisplaySetStereoOperation(_ display: CGDirectDisplayID, _ stereo: boolean_t, _ forceBlueLine: boolean_t, _ option: CGConfigureOption) -> CGError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

  • Configures the display mode of a display.

    Declaration

    Swift

    func CGConfigureDisplayWithDisplayMode(_ config: CGDisplayConfigRef, _ display: CGDirectDisplayID, _ mode: CGDisplayMode!, _ options: CFDictionary!) -> CGError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.6 and later.

  • Returns the color space for a display.

    Declaration

    Swift

    func CGDisplayCopyColorSpace(_ display: CGDirectDisplayID) -> Unmanaged<CGColorSpace>!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.5 and later.

  • Returns the I/O Kit service port of the specified display.

    Deprecation Statement

    There is no replacement.

    Declaration

    Objective-C

    io_service_t CGDisplayIOServicePort ( CGDirectDisplayID display );

    Parameters

    display

    The identifier of the display to be accessed.

    Return Value

    The I/O Kit service port for the specified display.

    Discussion

    An I/O Kit service port can be passed to I/O Kit to obtain additional information about the display.

    The port is owned by the graphics system and should not be destroyed.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.9.

  • Returns a Boolean value indicating whether a display is active.

    Declaration

    Swift

    func CGDisplayIsActive(_ display: CGDirectDisplayID) -> boolean_t

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func CGDisplayIsAlwaysInMirrorSet(_ display: CGDirectDisplayID) -> boolean_t

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func CGDisplayIsAsleep(_ display: CGDirectDisplayID) -> boolean_t

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func CGDisplayIsBuiltin(_ display: CGDirectDisplayID) -> boolean_t

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func CGDisplayIsInHWMirrorSet(_ display: CGDirectDisplayID) -> boolean_t

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func CGDisplayIsInMirrorSet(_ display: CGDirectDisplayID) -> boolean_t

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func CGDisplayIsMain(_ display: CGDirectDisplayID) -> boolean_t

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func CGDisplayIsOnline(_ display: CGDirectDisplayID) -> boolean_t

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func CGDisplayIsStereo(_ display: CGDirectDisplayID) -> boolean_t

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func CGDisplayMirrorsDisplay(_ display: CGDirectDisplayID) -> CGDirectDisplayID

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

  • Returns the model number of a display monitor.

    Declaration

    Swift

    func CGDisplayModelNumber(_ display: CGDirectDisplayID) -> UInt32

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

  • Returns the primary display in a hardware mirroring set.

    Declaration

    Swift

    func CGDisplayPrimaryDisplay(_ display: CGDirectDisplayID) -> CGDirectDisplayID

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

  • Returns the rotation angle of a display in degrees.

    Declaration

    Swift

    func CGDisplayRotation(_ display: CGDirectDisplayID) -> Double

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.5 and later.

  • Returns the width and height of a display in millimeters.

    Declaration

    Swift

    func CGDisplayScreenSize(_ display: CGDirectDisplayID) -> CGSize

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.3 and later.

  • Returns the serial number of a display monitor.

    Declaration

    Swift

    func CGDisplaySerialNumber(_ display: CGDirectDisplayID) -> UInt32

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

  • Returns the logical unit number of a display.

    Declaration

    Swift

    func CGDisplayUnitNumber(_ display: CGDirectDisplayID) -> UInt32

    Objective-C

    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 IOKit Fundamentals.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func CGDisplayUsesOpenGLAcceleration(_ display: CGDirectDisplayID) -> boolean_t

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func CGDisplayVendorNumber(_ display: CGDirectDisplayID) -> UInt32

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

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

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

    Declaration

    Swift

    func CGDisplayRegisterReconfigurationCallback(_ proc: CGDisplayReconfigurationCallBack, _ userInfo: UnsafeMutablePointer<Void>) -> CGError

    Objective-C

    CGError CGDisplayRegisterReconfigurationCallback ( CGDisplayReconfigurationCallBack callback, 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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Swift

    func CGDisplayRemoveReconfigurationCallback(_ proc: CGDisplayReconfigurationCallBack, _ userInfo: UnsafeMutablePointer<Void>) -> CGError

    Objective-C

    CGError CGDisplayRemoveReconfigurationCallback ( CGDisplayReconfigurationCallBack callback, 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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Swift

    func CGDisplayBounds(_ display: CGDirectDisplayID) -> CGRect

    Objective-C

    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).

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

  • Returns the display height in pixel units.

    Declaration

    Swift

    func CGDisplayPixelsHigh(_ display: CGDirectDisplayID) -> Int

    Objective-C

    size_t CGDisplayPixelsHigh ( CGDirectDisplayID display );

    Parameters

    display

    The identifier of the display to be accessed.

    Return Value

    The display height in pixel units.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

  • Returns the display width in pixel units.

    Declaration

    Swift

    func CGDisplayPixelsWide(_ display: CGDirectDisplayID) -> Int

    Objective-C

    size_t CGDisplayPixelsWide ( CGDirectDisplayID display );

    Parameters

    display

    The identifier of the display to be accessed.

    Return Value

    The display width in pixel units.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

  • CGDisplayBitsPerPixel CGDisplayBitsPerPixel Available in OS X v10.0 through OS X v10.6

    Returns the number of bits used to represent a pixel in the framebuffer.

    Deprecation Statement

    Use CGDisplayModeCopyPixelEncoding instead.

    Declaration

    Objective-C

    size_t CGDisplayBitsPerPixel ( CGDirectDisplayID display );

    Parameters

    display

    The identifier of the display to be accessed.

    Return Value

    The number of bits used to represent a pixel in the framebuffer.

    Special Considerations

    This deprecated function allows an application to retrieve the number of bits used to represent a pixel in the framebuffer. Starting in OS X v10.6 the CGDisplayModeCopyPixelEncoding should be used because it returns to the user the I/O Kit Graphics Mode, which can be used to determine the bits per pixel, as well as their encoding. This can prevent treating display modes with different encodings, but a similar total number of bits per pixel, in the same way.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.6.

    Deprecated in OS X v10.6.

  • CGDisplayBitsPerSample CGDisplayBitsPerSample Available in OS X v10.0 through OS X v10.6

    Returns the number of bits used to represent a pixel component in the framebuffer.

    Deprecation Statement

    Use CGDisplayModeCopyPixelEncoding instead.

    Declaration

    Objective-C

    size_t CGDisplayBitsPerSample ( CGDirectDisplayID display );

    Parameters

    display

    The identifier of the display to be accessed.

    Return Value

    The number of bits used to represent a pixel component such as a color value in the framebuffer.

    Special Considerations

    This deprecated function allows an application to retrieve the number of bits used to represent a pixel component in the framebuffer. Starting in OS X v10.6 the CGDisplayModeCopyPixelEncoding should be used because it returns to the user the I/O Kit Graphics Mode, which can be used to determine the bits per sample, as well as their encoding. This can prevent treating display modes with different encodings, but a similar total number of bits per sample, in the same way.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.6.

    Deprecated in OS X v10.6.

  • CGDisplaySamplesPerPixel CGDisplaySamplesPerPixel Available in OS X v10.0 through OS X v10.6

    Returns the number of color components used to represent a pixel.

    Deprecation Statement

    Use CGDisplayModeCopyPixelEncoding instead.

    Declaration

    Objective-C

    size_t CGDisplaySamplesPerPixel ( CGDirectDisplayID display );

    Parameters

    display

    The identifier of the display to be accessed.

    Return Value

    The number of color components used to represent a pixel.

    Special Considerations

    This deprecated function allows an application to retrieve the number of color components used to represent a pixel in the framebuffer. Starting in OS X v10.6 the CGDisplayModeCopyPixelEncoding should be used because it returns to the user the I/O Kit Graphics Mode, which can be used to determine the samples per pixel, as well as their encoding. This can prevent treating display modes with different encodings, but a similar total number of samples per pixel, in the same way.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.6.

    Deprecated in OS X v10.6.

  • CGDisplayBytesPerRow CGDisplayBytesPerRow Available in OS X v10.0 through OS X v10.6

    Returns the number of bytes per row in a display.

    Deprecation Statement

    Use CGDisplayCreateImage or CGDisplayCreateImageForRect instead.

    Declaration

    Objective-C

    size_t CGDisplayBytesPerRow ( CGDirectDisplayID display );

    Parameters

    display

    The identifier of the display to be accessed.

    Return Value

    The number of bytes per row in the display. This number also represents the stride between pixels in the same column of the display.

    Special Considerations

    This deprecated function required pixel data to be retrieved manually. Starting in OS X v10.6 one of the CGDisplayCreateImage functions should be used to create an image from the display. For more information, see CGImage Reference.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 through OS X v10.6.

    Deprecated in OS X v10.6.

  • Returns information about the currently available display modes.

    Deprecation Statement

    Use CGDisplayCopyAllDisplayModes instead.

    Declaration

    Objective-C

    CFArrayRef CGDisplayAvailableModes ( CGDirectDisplayID display );

    Parameters

    display

    The identifier of the display to be accessed.

    Return Value

    An array of dictionaries with display mode information, or NULL if the display is invalid. The array is owned by the system and you should not release it. Each dictionary in the array contains information about a mode that the display supports. For a list of the properties in a display mode dictionary, see Display Mode Standard Properties and Display Mode Optional Properties. For general information about using dictionaries, see CFDictionary Reference.

    Special Considerations

    This deprecated function returns an array of display mode dictionary. Starting in OS X v10.6, display mode dictionaries have been replaced by the CGDisplayMode opaque type. Whereas display mode dictionaries returned by CGDisplayAvailableModes are owned by the system and are not to be released, display mode opaque type references returned by CGDisplayCopyAllDisplayModes are owned by the caller and you must release them.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Returns information about the display mode closest to a specified depth and screen size.

    Deprecation Statement

    Use the display mode query functions instead; see “Getting Information About a Display Mode”.

    Declaration

    Objective-C

    CFDictionaryRef CGDisplayBestModeForParameters ( CGDirectDisplayID display, size_t bitsPerPixel, size_t width, size_t height, boolean_t *exactMatch );

    Parameters

    display

    The identifier of the display to optimize.

    bitsPerPixel

    Optimal display depth in bits per pixel. Note that this value is not the same as pixel depth, which is the number of bits per channel or component.

    width

    Optimal display width in pixel units.

    height

    Optimal display height in pixel units.

    exactMatch

    A pointer to a Boolean variable. On return, its value is true if an exact match in display depth, width, and height is found; otherwise, false. If this information is not needed, pass NULL.

    Return Value

    A display mode dictionary, or NULL if the display is invalid. The dictionary is owned by the system and you should not release it. The dictionary contains information about the display mode closest to the specified depth and screen size. For a list of the properties in a display mode dictionary, see Display Mode Standard Properties and Display Mode Optional Properties. For general information about using dictionaries, see CFDictionary Reference.

    Discussion

    This function tries to find an optimal display mode for the specified display. The function first tries to find a mode with the specified pixel depth and dimensions equal to or greater than the specified width and height. If no depth match is found, it tries to find a mode with greater depth and the same or greater dimensions. If a suitable display mode is not found, this function simply returns the current display mode.

    Special Considerations

    This deprecated function selects a display mode closest to the specified parameters. Starting in OS X v10.6 new display mode APIs should be used to query display modes so that an application can tailor its definition of “best” to its graphics and memory needs.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Returns information about the display mode closest to a specified depth, screen size, and refresh rate.

    Deprecation Statement

    Use the display mode query functions instead; see “Getting Information About a Display Mode”.

    Declaration

    Objective-C

    CFDictionaryRef CGDisplayBestModeForParametersAndRefreshRate ( CGDirectDisplayID display, size_t bitsPerPixel, size_t width, size_t height, CGRefreshRate refreshRate, boolean_t *exactMatch );

    Parameters

    display

    The identifier of the display to be accessed.

    bitsPerPixel

    Optimal display depth, in bits per pixel. Note that this value is not the same as pixel depth, which is the number of bits per channel or component.

    width

    Optimal display width, in pixel units.

    height

    Optimal display height, in pixel units.

    refresh

    Optimal display refresh rate, in frames per second.

    exactMatch

    A pointer to a Boolean variable. On return, its value is true if an exact match in display depth, width, height, and refresh rate is found; otherwise, false. If this information is not needed, pass NULL.

    Return Value

    A display mode dictionary, or NULL if the display is invalid. The dictionary is owned by the system and you should not release it. The dictionary contains information about the display mode closest to the specified depth, screen size, and refresh rate. For a list of the properties in a display mode dictionary, see Display Mode Standard Properties and Display Mode Optional Properties. For general information about using dictionaries, see CFDictionary Reference.

    Discussion

    This function searches the list of available display modes for a mode that comes closest to satisfying these criteria:

    • Has a pixel depth equal to or greater than the specified depth

    • Has dimensions equal to or greater than the specified height and width

    • Uses a refresh rate equal to or near the specified rate

    If a suitable display mode is not found, this function simply returns the current display mode.

    Special Considerations

    This deprecated function selects a display mode closest to the specified parameters. Starting in OS X v10.6 new display mode APIs should be used to query display modes so that an app can tailor its definition of “best” to its graphics and memory needs.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Returns information about the current display mode.

    Deprecation Statement

    Use CGDisplayCopyDisplayMode instead.

    Declaration

    Objective-C

    CFDictionaryRef CGDisplayCurrentMode ( CGDirectDisplayID display );

    Parameters

    display

    The identifier of the display to be accessed.

    Return Value

    A display mode dictionary, or NULL if the display is invalid. The dictionary is owned by the system and you should not release it. The dictionary contains information about the current display mode. For a list of the properties in a display mode dictionary, see Display Mode Standard Properties and Display Mode Optional Properties. For general information about using dictionaries, see CFDictionary Reference.

    Special Considerations

    This deprecated function returns a display mode dictionary. Starting in OS X v10.6, display mode dictionaries have been replaced by the CGDisplayMode opaque type. Whereas display mode dictionaries returned by CGDisplayCurrentModes are owned by the system and are not to be released, display mode opaque type references returned by CGDisplayCopyDisplayMode are owned by the caller and you must release them.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Switches a display to a different mode.

    Deprecation Statement

    Use CGDisplaySetDisplayMode instead.

    Declaration

    Objective-C

    CGError CGDisplaySwitchToMode ( CGDirectDisplayID display, CFDictionaryRef mode );

    Parameters

    display

    The identifier of the display to be accessed.

    mode

    A display mode dictionary that contains information about the display mode to set. The dictionary passed in must be a dictionary returned by another Quartz display function such as CGDisplayAvailableModes or CGDisplayBestModeForParameters. For a list of the properties in a display mode dictionary, see Display Mode Standard Properties and Display Mode Optional Properties. For general information about using dictionaries, see CFDictionary Reference.

    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 changing the display mode of a display in a mirroring set, other displays in the mirroring set will be 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: callCGBeginDisplayConfiguration, call CGConfigureDisplayMode for each display to explicitly set the mode, and finally call CGCompleteDisplayConfiguration

    Special Considerations

    This deprecated function takes as a parameter a display mode dictionary. Starting in OS X v10.6, display mode dictionaries have been replaced by the CGDisplayMode opaque type.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Returns information about a display’s current configuration.

    Declaration

    Swift

    func CGDisplayCopyDisplayMode(_ display: CGDirectDisplayID) -> Unmanaged<CGDisplayMode>!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.6 and later.

  • Returns information about the currently available display modes.

    Declaration

    Swift

    func CGDisplayCopyAllDisplayModes(_ display: CGDirectDisplayID, _ options: CFDictionary!) -> Unmanaged<CFArray>!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.6 and later.

  • Switches a display to a different mode.

    Declaration

    Swift

    func CGDisplaySetDisplayMode(_ display: CGDirectDisplayID, _ mode: CGDisplayMode!, _ options: CFDictionary!) -> CGError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.6 and later.

  • Retains a Core Graphics display mode.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Availability

    Available in OS X v10.6 and later.

  • Releases a Core Graphics display mode.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Availability

    Available in OS X v10.6 and later.

  • Returns the width of the specified display mode.

    Declaration

    Swift

    func CGDisplayModeGetWidth(_ mode: CGDisplayMode!) -> Int

    Objective-C

    size_t CGDisplayModeGetWidth ( CGDisplayModeRef mode );

    Parameters

    mode

    A display mode.

    Return Value

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

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.6 and later.

  • Returns the height of the specified display mode.

    Declaration

    Swift

    func CGDisplayModeGetHeight(_ mode: CGDisplayMode!) -> Int

    Objective-C

    size_t CGDisplayModeGetHeight ( CGDisplayModeRef mode );

    Parameters

    mode

    A display mode.

    Return Value

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

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.6 and later.

  • Returns the pixel encoding of the specified display mode.

    Declaration

    Swift

    func CGDisplayModeCopyPixelEncoding(_ mode: CGDisplayMode!) -> Unmanaged<CFString>!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.6 and later.

  • Returns the refresh rate of the specified display mode.

    Declaration

    Swift

    func CGDisplayModeGetRefreshRate(_ mode: CGDisplayMode!) -> Double

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.6 and later.

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

    Declaration

    Swift

    func CGDisplayModeGetIOFlags(_ mode: CGDisplayMode!) -> UInt32

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.6 and later.

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

    Declaration

    Swift

    func CGDisplayModeGetIODisplayModeID(_ mode: CGDisplayMode!) -> Int32

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.6 and later.

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

    Declaration

    Swift

    func CGDisplayModeIsUsableForDesktopGUI(_ mode: CGDisplayMode!) -> Bool

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.6 and later.

  • Returns the type identifier of Quartz display modes.

    Declaration

    Swift

    func CGDisplayModeGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID CGDisplayModeGetTypeID ( void );

    Return Value

    The type identifier of the CGDisplayMode opaque type.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.6 and later.

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

    Declaration

    Swift

    func CGSetDisplayTransferByFormula(_ display: CGDirectDisplayID, _ redMin: CGGammaValue, _ redMax: CGGammaValue, _ redGamma: CGGammaValue, _ greenMin: CGGammaValue, _ greenMax: CGGammaValue, _ greenGamma: CGGammaValue, _ blueMin: CGGammaValue, _ blueMax: CGGammaValue, _ blueGamma: CGGammaValue) -> CGError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func CGGetDisplayTransferByFormula(_ display: CGDirectDisplayID, _ redMin: UnsafeMutablePointer<CGGammaValue>, _ redMax: UnsafeMutablePointer<CGGammaValue>, _ redGamma: UnsafeMutablePointer<CGGammaValue>, _ greenMin: UnsafeMutablePointer<CGGammaValue>, _ greenMax: UnsafeMutablePointer<CGGammaValue>, _ greenGamma: UnsafeMutablePointer<CGGammaValue>, _ blueMin: UnsafeMutablePointer<CGGammaValue>, _ blueMax: UnsafeMutablePointer<CGGammaValue>, _ blueGamma: UnsafeMutablePointer<CGGammaValue>) -> CGError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func CGSetDisplayTransferByTable(_ display: CGDirectDisplayID, _ tableSize: UInt32, _ redTable: UnsafePointer<CGGammaValue>, _ greenTable: UnsafePointer<CGGammaValue>, _ blueTable: UnsafePointer<CGGammaValue>) -> CGError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func CGGetDisplayTransferByTable(_ display: CGDirectDisplayID, _ capacity: UInt32, _ redTable: UnsafeMutablePointer<CGGammaValue>, _ greenTable: UnsafeMutablePointer<CGGammaValue>, _ blueTable: UnsafeMutablePointer<CGGammaValue>, _ sampleCount: UnsafeMutablePointer<UInt32>) -> CGError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func CGSetDisplayTransferByByteTable(_ display: CGDirectDisplayID, _ tableSize: UInt32, _ redTable: UnsafePointer<UInt8>, _ greenTable: UnsafePointer<UInt8>, _ blueTable: UnsafePointer<UInt8>) -> CGError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func CGDisplayRestoreColorSyncSettings()

    Objective-C

    void CGDisplayRestoreColorSyncSettings ( void );

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func CGDisplayGammaTableCapacity(_ display: CGDirectDisplayID) -> UInt32

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Swift

    func CGConfigureDisplayFadeEffect(_ configRef: CGDisplayConfigRef, _ fadeOutSeconds: CGDisplayFadeInterval, _ fadeInSeconds: CGDisplayFadeInterval, _ fadeRed: Float, _ fadeGreen: Float, _ fadeBlue: Float) -> CGError

    Objective-C

    CGError CGConfigureDisplayFadeEffect ( CGDisplayConfigRef config, 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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

  • Reserves the fade hardware for a specified time interval.

    Declaration

    Swift

    func CGAcquireDisplayFadeReservation(_ seconds: CGDisplayReservationInterval, _ pNewToken: UnsafeMutablePointer<CGDisplayFadeReservationToken>) -> CGError

    Objective-C

    CGError CGAcquireDisplayFadeReservation ( CGDisplayReservationInterval seconds, CGDisplayFadeReservationToken *token );

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

  • Performs a single fade operation.

    Declaration

    Swift

    func CGDisplayFade(_ myToken: CGDisplayFadeReservationToken, _ seconds: CGDisplayFadeInterval, _ startBlend: CGDisplayBlendFraction, _ endBlend: CGDisplayBlendFraction, _ redBlend: Float, _ greenBlend: Float, _ blueBlend: Float, _ synchronous: boolean_t) -> CGError

    Objective-C

    CGError CGDisplayFade ( CGDisplayFadeReservationToken token, CGDisplayFadeInterval duration, 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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

  • Returns a Boolean value indicating whether a fade operation is currently in progress.

    Deprecation Statement

    There is no replacement.

    Declaration

    Objective-C

    boolean_t CGDisplayFadeOperationInProgress ( void );

    Return Value

    If true, a fade operation is currently in progress; otherwise, false.

    Discussion

    You may call this function from any task running in the system. The calling task need not have a valid fade reservation.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.9.

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

    Declaration

    Swift

    func CGReleaseDisplayFadeReservation(_ myToken: CGDisplayFadeReservationToken) -> CGError

    Objective-C

    CGError CGReleaseDisplayFadeReservation ( CGDisplayFadeReservationToken token );

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func CGDisplayHideCursor(_ display: CGDirectDisplayID) -> CGError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func CGDisplayShowCursor(_ display: CGDirectDisplayID) -> CGError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func CGDisplayMoveCursorToPoint(_ display: CGDirectDisplayID, _ point: CGPoint) -> CGError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

  • Returns a Boolean value indicating whether the mouse cursor is visible.

    Deprecation Statement

    There is no replacement.

    Declaration

    Objective-C

    boolean_t CGCursorIsVisible ( void );

    Return Value

    If true, the cursor is visible on any display; otherwise, false.

    Discussion

    To hide or show the cursor, you can use the functions CGDisplayHideCursor and CGDisplayShowCursor.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Availability

    Available in OS X v10.3 and later.

    Deprecated in OS X v10.9.

  • Returns a Boolean value indicating whether the mouse cursor is drawn in framebuffer memory.

    Deprecation Statement

    There is no replacement.

    Declaration

    Objective-C

    boolean_t CGCursorIsDrawnInFramebuffer ( void );

    Return Value

    If true, the cursor is drawn in framebuffer memory; otherwise, false.

    Discussion

    This function returns a Boolean value that indicates whether or not the cursor is drawn in the framebuffer. (The cursor could exist in an overlay plane or a similar mechanism that puts pixels on-screen without altering framebuffer content.) If the cursor is drawn in the framebuffer, it is read back along with window data.

    The reported Boolean value is based on the union of the state of the cursor on all displays. If the cursor is drawn in the framebuffer on any display, the function returns true.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Availability

    Available in OS X v10.3 and later.

    Deprecated in OS X v10.9.

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

    Declaration

    Swift

    func CGAssociateMouseAndMouseCursorPosition(_ connected: boolean_t) -> CGError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

  • Moves the mouse cursor without generating events.

    Declaration

    Swift

    func CGWarpMouseCursorPosition(_ newCursorPosition: CGPoint) -> CGError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func CGGetLastMouseDelta(_ deltaX: UnsafeMutablePointer<Int32>, _ deltaY: UnsafeMutablePointer<Int32>)

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

  • Returns information about the caller’s window server session.

    Declaration

    Swift

    func CGSessionCopyCurrentDictionary() -> Unmanaged<CFDictionary>!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.3 and later.

  • Returns a Core Foundation Mach port (CFMachPort) that corresponds to the OS X window server.

    Deprecation Statement

    There is no replacement.

    Declaration

    Objective-C

    CFMachPortRef CGWindowServerCFMachPort ( void );

    Return Value

    A Core Foundation Mach port, or NULL if the window server is not running. When you no longer need the port, you should release it using the function CFRelease.

    Discussion

    You can use this function to detect whether the window server process exits or is not running. If this function returns NULL, the window server is not running. This code example shows how to register a callback function to detect when the window server exits:

    • static void handleWindowServerDeath( CFMachPortRef port, void *info )
    • {
    • printf( "Window Server port death detected!\n" );
    • CFRelease(port);
    • exit(1);
    • }
    • static void watchForWindowServerDeath()
    • {
    • CFMachPortRef port = CGWindowServerCFMachPort();
    • CFMachPortSetInvalidationCallBack(port, handleWindowServerDeath);
    • }

    Note that this callback only works if your program has an active run loop.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Availability

    Available in OS X v10.1 and later.

    Deprecated in OS X v10.8.

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

    Declaration

    Swift

    func CGWindowLevelForKey(_ key: CGWindowLevelKey) -> CGWindowLevel

    Objective-C

    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.)

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

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.

  • Registers a callback function to be invoked when local displays are refreshed or modified.

    Deprecation Statement

    Use display streaming instead. See Streaming the Contents of a Display.

    Declaration

    Objective-C

    CGError CGRegisterScreenRefreshCallback ( CGScreenRefreshCallback callback, void *userInfo );

    Parameters

    function

    A pointer to the callback function to be registered.

    userParameter

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

    Return Value

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

    Discussion

    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 call the function CGUnregisterScreenRefreshCallback to remove the registration.

    The callback function you register is invoked only if your application has an active event loop. The callback is invoked in the same thread of execution that is processing events within your application.

    Special Considerations

    In OS X v10.4 and earlier, the result code returned by this function is a random value and should be ignored. In OS X v10.5 and later, the result code is valid.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

  • Removes a previously registered callback function invoked when local displays are refreshed or modified.

    Deprecation Statement

    Use display streaming instead. See Streaming the Contents of a Display.

    Declaration

    Objective-C

    void CGUnregisterScreenRefreshCallback ( CGScreenRefreshCallback callback, void *userInfo );

    Parameters

    function

    A pointer to the callback function to be unregistered.

    userParameter

    A pointer to user-defined data, or NULL. You should pass the same value you used when you registered the callback function.

    Discussion

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

    Import Statement

    Objective-C

    @import CoreGraphics;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

  • Waits for screen refresh operations.

    Deprecation Statement

    Use display streaming instead. See Streaming the Contents of a Display.

    Declaration

    Objective-C

    CGError CGWaitForScreenRefreshRects ( CGRect **rects, uint32_t *count );

    Parameters

    pRectArray

    A pointer to a CGRect* variable. On return, the variable contains an array of rectangles that bound the refreshed areas, specified in the global display coordinate space. When you no longer need the array, you should deallocate it by calling CGReleaseScreenRefreshRects.

    pCount

    A pointer to a CGRectCount variable. On return, the variable contains the number of entries in the returned array of rectangles.

    Return Value

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

    Discussion

    In some applications it may be preferable to wait for screen-refresh data synchronously, using this function. You should call this function in a thread other than the main event-processing thread.

    As an alternative, Quartz also supports asynchronous notification—see CGRegisterScreenRefreshCallback. If refresh callback functions are registered, this function should not be used.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

  • Registers a callback function to be invoked when an area of the display is moved.

    Deprecation Statement

    Use display streaming instead. See Streaming the Contents of a Display.

    Declaration

    Objective-C

    CGError CGScreenRegisterMoveCallback ( CGScreenUpdateMoveCallback callback, void *userInfo );

    Parameters

    function

    A pointer to the callback function to be registered.

    userParameter

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

    Return Value

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

    Discussion

    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 CGScreenUnregisterMoveCallback.

    The callback function you register is invoked only if your application has an active event loop. The callback is invoked in the same thread of execution that is processing events within your application.

    Special Considerations

    This function is implemented in OS X version 10.4.3 and later.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Availability

    Available in OS X v10.3 and later.

    Deprecated in OS X v10.8.

  • Removes a previously registered callback function invoked when an area of the display is moved.

    Deprecation Statement

    Use display streaming instead. See Streaming the Contents of a Display.

    Declaration

    Objective-C

    void CGScreenUnregisterMoveCallback ( CGScreenUpdateMoveCallback callback, void *userInfo );

    Parameters

    function

    A pointer to the callback function to be unregistered.

    userParameter

    A pointer to user-defined data, or NULL. You should pass the same value you used when you registered the callback function.

    Return Value

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

    Discussion

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

    Import Statement

    Objective-C

    @import CoreGraphics;

    Availability

    Available in OS X v10.3 and later.

    Deprecated in OS X v10.8.

  • Waits for screen update operations.

    Deprecation Statement

    Use display streaming instead. See Streaming the Contents of a Display.

    Declaration

    Objective-C

    CGError CGWaitForScreenUpdateRects ( CGScreenUpdateOperation requestedOperations, CGScreenUpdateOperation *currentOperation, CGRect **rects, size_t *rectCount, CGScreenUpdateMoveDelta *delta );

    Parameters

    requestedOperations

    The desired types of screen update operations. There are several possible choices:

    • Specify kCGScreenUpdateOperationRefresh if you want all move operations to be returned as refresh operations.

    • Specify (kCGScreenUpdateOperationRefresh | kCGScreenUpdateOperationMove) if you want to distinguish between move and refresh operations.

    • Add kCGScreenUpdateOperationReducedDirtyRectangleCount to the screen operations if you want to minimize the number of rectangles returned to represent changed areas of the display.

    currentOperation

    A pointer to a CGScreenUpdateOperation variable. On return, the variable indicates the type of update operation (refresh or move).

    pRectArray

    A pointer to a CGRect* variable. On return, the variable contains an array of rectangles that bound the updated areas, specified in the global display coordinate space. When you no longer need the array, you should deallocate it by calling CGReleaseScreenRefreshRects.

    pCount

    A pointer to a size_t variable. On return, the variable contains the number of entries in the returned array of rectangles.

    pDelta

    A pointer to a CGScreenUpdateMoveDelta variable. On return, if the value of the currentOperation parameter is kCGScreenUpdateOperationMove, the variable contains the distance moved.

    Return Value

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

    Discussion

    In some applications it may be preferable to wait for screen-update data synchronously, using this function. You should call this function in a thread other than the main event-processing thread.

    As an alternative, Quartz also supports asynchronous notification—see CGRegisterScreenRefreshCallback and CGScreenRegisterMoveCallback. If refresh or move callback functions are registered, this function should not be used.

    Special Considerations

    This function is implemented in OS X version 10.4.3 and later.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Availability

    Available in OS X v10.3 and later.

    Deprecated in OS X v10.8.

  • Deallocates a list of rectangles that represent changed areas on local displays.

    Deprecation Statement

    There is no replacement.

    Declaration

    Objective-C

    void CGReleaseScreenRefreshRects ( CGRect *rects );

    Parameters

    rectArray

    A list of rectangles obtained by calling CGWaitForScreenRefreshRects or CGWaitForScreenUpdateRects.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

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

    Declaration

    Swift

    func CGDisplayStreamCreate(_ display: CGDirectDisplayID, _ outputWidth: Int, _ outputHeight: Int, _ pixelFormat: Int32, _ properties: CFDictionary!, _ handler: CGDisplayStreamFrameAvailableHandler!) -> Unmanaged<CGDisplayStream>!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.8 and later.

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

    Declaration

    Swift

    func CGDisplayStreamCreateWithDispatchQueue(_ display: CGDirectDisplayID, _ outputWidth: Int, _ outputHeight: Int, _ pixelFormat: Int32, _ properties: CFDictionary!, _ queue: dispatch_queue_t!, _ handler: CGDisplayStreamFrameAvailableHandler!) -> Unmanaged<CGDisplayStream>!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.8 and later.

  • Tells a stream to start sending updates.

    Declaration

    Swift

    func CGDisplayStreamStart(_ displayStream: CGDisplayStream!) -> CGError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.8 and later.

  • Tells a stream to stop sending updates.

    Declaration

    Swift

    func CGDisplayStreamStop(_ displayStream: CGDisplayStream!) -> CGError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.8 and later.

  • Gets the run loop source for a display stream.

    Declaration

    Swift

    func CGDisplayStreamGetRunLoopSource(_ displayStream: CGDisplayStream!) -> Unmanaged<CFRunLoopSource>!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.8 and later.

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

    Declaration

    Swift

    func CGDisplayStreamUpdateGetRects(_ updateRef: CGDisplayStreamUpdate!, _ rectType: CGDisplayStreamUpdateRectType, _ rectCount: UnsafeMutablePointer<Int>) -> UnsafePointer<CGRect>

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.8 and later.

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

    Declaration

    Swift

    func CGDisplayStreamUpdateCreateMergedUpdate(_ firstUpdate: CGDisplayStreamUpdate!, _ secondUpdate: CGDisplayStreamUpdate!) -> Unmanaged<CGDisplayStreamUpdate>!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.8 and later.

  • Return the movement delta values for a single update.

    Declaration

    Swift

    func CGDisplayStreamUpdateGetMovedRectsDelta(_ updateRef: CGDisplayStreamUpdate!, _ dx: UnsafeMutablePointer<CGFloat>, _ dy: UnsafeMutablePointer<CGFloat>)

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.8 and later.

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

    Declaration

    Swift

    func CGDisplayStreamUpdateGetDropCount(_ updateRef: CGDisplayStreamUpdate!) -> Int

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.8 and later.

  • Returns the type identifier of a Quartz display stream.

    Declaration

    Swift

    func CGDisplayStreamGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID CGDisplayStreamGetTypeID ( void );

    Return Value

    The type identifier of the CGDisplayStream opaque type.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.8 and later.

  • Returns the type identifier of a Quartz display stream update.

    Declaration

    Swift

    func CGDisplayStreamUpdateGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID CGDisplayStreamUpdateGetTypeID ( void );

    Return Value

    The type identifier of the CGDisplayStreamUpdate opaque type.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.8 and later.

Callbacks

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

    Declaration

    Swift

    typealias CGDisplayReconfigurationCallBack = CFunctionPointer<((CGDirectDisplayID, CGDisplayChangeSummaryFlags, UnsafeMutablePointer<Void>) -> Void)>

    Objective-C

    typedef void (*CGDisplayReconfigurationCallBack) ( 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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Swift

    typealias CGScreenRefreshCallback = CFunctionPointer<((UInt32, UnsafePointer<CGRect>, UnsafeMutablePointer<Void>) -> Void)>

    Objective-C

    typedef void (*CGScreenRefreshCallback) ( 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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    typealias CGScreenUpdateMoveCallback = CFunctionPointer<((CGScreenUpdateMoveDelta, Int, UnsafePointer<CGRect>, UnsafeMutablePointer<Void>) -> Void)>

    Objective-C

    typedef void (*CGScreenUpdateMoveCallback) ( 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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.3 and later.

Data Types

  • A unique identifier for an attached display.

    Declaration

    Swift

    typealias CGDirectDisplayID = UInt32

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

  • The percentage of blend color used in a fade operation.

    Declaration

    Swift

    typealias CGDisplayBlendFraction = Float

    Objective-C

    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%.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

  • A reference to a display configuration transaction.

    Declaration

    Swift

    typealias CGDisplayConfigRef = COpaquePointer

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

  • The number of displays in various lists.

    Use uint32_t instead.

    Declaration

    Swift

    typealias CGDisplayCount = UInt32

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

  • A uniform type for result codes returned by functions in Quartz Display Services.

    Use CGError instead.

    Declaration

    Swift

    typealias CGDisplayErr = CGError

    Objective-C

    typedef CGError CGDisplayErr;

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    typealias CGDisplayFadeInterval = Float

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    typealias CGDisplayFadeReservationToken = UInt32

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

  • A reference to a display mode object.

    Declaration

    Swift

    typealias CGDisplayModeRef = CGDisplayMode

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.6 and later.

  • The time interval for a fade reservation.

    Declaration

    Swift

    typealias CGDisplayReservationInterval = Float

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    typealias CGGammaValue = Float

    Objective-C

    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

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    typealias CGOpenGLDisplayMask = UInt32

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

  • The size of an array of Quartz rectangles.

    Declaration

    Swift

    typealias CGRectCount = UInt32

    Objective-C

    typedef uint32_t CGRectCount;

    Discussion

    For example, see the function CGWaitForScreenRefreshRects.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

  • A display’s refresh rate in frames per second.

    Declaration

    Swift

    typealias CGRefreshRate = Double

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    struct CGScreenUpdateMoveDelta { var dX: Int32 var dY: Int32 init() init(dX dX: Int32, dY dY: Int32) }

    Objective-C

    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.

  • A level assigned to a window by an application framework.

    Declaration

    Swift

    typealias CGWindowLevel = Int32

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

  • A reference to a display stream object.

    Declaration

    Swift

    typealias CGDisplayStreamRef = CGDisplayStream

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.8 and later.

  • A reference to frame update’s metadata.

    Declaration

    Swift

    typealias CGDisplayStreamUpdateRef = CGDisplayStreamUpdate

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.8 and later.

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

    Declaration

    Swift

    typealias CGDisplayStreamFrameAvailableHandler = (CGDisplayStreamFrameStatus, UInt64, IOSurface!, CGDisplayStreamUpdate!) -> Void

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.8 and later.

Constants

  • Configuration parameters that are used when capturing displays.

    Declaration

    Swift

    typealias CGCaptureOptions = UInt32

    Objective-C

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

    Constants

    • kCGCaptureNoOptions

      kCGCaptureNoOptions

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

      Available in OS X v10.3 and later.

    • kCGCaptureNoFill

      kCGCaptureNoFill

      Disables fill with black.

      Available in OS X v10.3 and later.

      Deprecated in OS X v10.10.

    Discussion

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

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Swift

    typealias CGDisplayChangeSummaryFlags = UInt32

    Objective-C

    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

      kCGDisplayBeginConfigurationFlag

      The display configuration is about to change.

      Available in OS X v10.3 and later.

    • kCGDisplayMovedFlag

      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.

    • kCGDisplaySetMainFlag

      kCGDisplaySetMainFlag

      The display is now the main display.

      Available in OS X v10.3 and later.

    • kCGDisplaySetModeFlag

      kCGDisplaySetModeFlag

      The display mode has changed.

      Available in OS X v10.3 and later.

    • kCGDisplayAddFlag

      kCGDisplayAddFlag

      The display has been added to the active display list.

      Available in OS X v10.3 and later.

    • kCGDisplayRemoveFlag

      kCGDisplayRemoveFlag

      The display has been removed from the active display list.

      Available in OS X v10.3 and later.

    • kCGDisplayEnabledFlag

      kCGDisplayEnabledFlag

      The display has been enabled.

      Available in OS X v10.3 and later.

    • kCGDisplayDisabledFlag

      kCGDisplayDisabledFlag

      The display has been disabled.

      Available in OS X v10.3 and later.

    • kCGDisplayMirrorFlag

      kCGDisplayMirrorFlag

      The display is now mirroring another display.

      Available in OS X v10.3 and later.

    • kCGDisplayUnMirrorFlag

      kCGDisplayUnMirrorFlag

      The display is no longer mirroring another display.

      Available in OS X v10.3 and later.

    • kCGDisplayDesktopShapeChangedFlag

      kCGDisplayDesktopShapeChangedFlag

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

      Available in OS X v10.5 and later.

    Discussion

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

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.3 and later.

  • The scope of the changes in a display configuration transaction.

    Declaration

    Swift

    var kCGConfigureForAppOnly: Int { get } var kCGConfigureForSession: Int { get } var kCGConfigurePermanently: Int { get }

    Objective-C

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

    Constants

    • kCGConfigureForAppOnly

      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.

    • kCGConfigureForSession

      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.

    • kCGConfigurePermanently

      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.

    Discussion

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

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

    Declaration

    Swift

    var kCGDisplayBlendNormal: Double { get } var kCGDisplayBlendSolidColor: Double { get }

    Objective-C

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

    Constants

    • kCGDisplayBlendNormal

      kCGDisplayBlendNormal

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

      Available in OS X v10.2 and later.

    • kCGDisplayBlendSolidColor

      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.

    Discussion

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

  • Values relating to fade operations.

    Declaration

    Swift

    var kCGDisplayFadeReservationInvalidToken: Int32 { get }

    Objective-C

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

    Constants

    • kCGMaxDisplayReservationInterval

      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.

    • kCGDisplayFadeReservationInvalidToken

      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.

  • Default values for a display ID.

    Declaration

    Objective-C

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

    Constants

    • kCGDirectMainDisplay

      kCGDirectMainDisplay

      The current main display ID.

      Available in OS X v10.0 and later.

    • kCGNullDirectDisplay

      kCGNullDirectDisplay

      A value that will never correspond to actual hardware.

      Available in OS X v10.2 and later.

  • Keys for the standard properties in a display mode dictionary.

    There is no replacement; as display mode dictionaries are deprecated in OS X v10.6, these properties are not needed.

    Declaration

    Swift

    var kCGDisplayWidth: String { get } var kCGDisplayHeight: String { get } var kCGDisplayMode: String { get } var kCGDisplayBitsPerPixel: String { get } var kCGDisplayBitsPerSample: String { get } var kCGDisplaySamplesPerPixel: String { get } var kCGDisplayRefreshRate: String { get } var kCGDisplayModeUsableForDesktopGUI: String { get } var kCGDisplayIOFlags: String { get } var kCGDisplayBytesPerRow: String { get }

    Objective-C

    #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

      kCGDisplayWidth

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

      Available in OS X v10.2 and later.

    • kCGDisplayHeight

      kCGDisplayHeight

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

      Available in OS X v10.2 and later.

    • kCGDisplayMode

      kCGDisplayMode

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

      Available in OS X v10.2 and later.

    • kCGDisplayBitsPerPixel

      kCGDisplayBitsPerPixel

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

      Available in OS X v10.2 and later.

    • kCGDisplayBitsPerSample

      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.

    • kCGDisplaySamplesPerPixel

      kCGDisplaySamplesPerPixel

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

      Available in OS X v10.2 and later.

    • kCGDisplayRefreshRate

      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.

    • kCGDisplayModeUsableForDesktopGUI

      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.

    • kCGDisplayIOFlags

      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.

    • kCGDisplayBytesPerRow

      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.

    Discussion

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

  • Keys for optional properties in a display mode dictionary.

    There is no replacement; as display mode dictionaries are deprecated in OS X v10.6, these properties are not needed.

    Declaration

    Swift

    var kCGDisplayModeIsSafeForHardware: String { get } var kCGDisplayModeIsInterlaced: String { get } var kCGDisplayModeIsStretched: String { get } var kCGDisplayModeIsTelevisionOutput: String { get }

    Objective-C

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

    Constants

    • kCGDisplayModeIsSafeForHardware

      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.

    • kCGDisplayModeIsInterlaced

      kCGDisplayModeIsInterlaced

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

      Available in OS X v10.2 and later.

    • kCGDisplayModeIsStretched

      kCGDisplayModeIsStretched

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

      Available in OS X v10.2 and later.

    • kCGDisplayModeIsTelevisionOutput

      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.

    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.

  • Window level constants.

    Declaration

    Swift

    var kCGNumReservedWindowLevels: Int32 { get }

    Objective-C

    #define kCGNumReservedWindowLevels (16)

    Constants

    • kCGNumReservedWindowLevels

      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.

  • Types of screen-update operations.

    Declaration

    Swift

    typealias CGScreenUpdateOperation = UInt32

    Objective-C

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

    Constants

    • kCGScreenUpdateOperationRefresh

      kCGScreenUpdateOperationRefresh

      A screen-refresh operation.

      Available in OS X v10.3 and later.

    • kCGScreenUpdateOperationMove

      kCGScreenUpdateOperationMove

      A screen-move operation.

      Available in OS X v10.3 and later.

    • kCGScreenUpdateOperationReducedDirtyRectangleCount

      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.

    Discussion

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

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.3 and later.

  • 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.

    Declaration

    Swift

    typealias CGWindowLevelKey = Int32

    Objective-C

    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

      kCGBaseWindowLevelKey

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

      Available in OS X v10.0 and later.

    • kCGMinimumWindowLevelKey

      kCGMinimumWindowLevelKey

      The lowest available window level.

      Available in OS X v10.0 and later.

    • kCGDesktopWindowLevelKey

      kCGDesktopWindowLevelKey

      The level for the desktop.

      Available in OS X v10.0 and later.

    • kCGBackstopMenuLevelKey

      kCGBackstopMenuLevelKey

      The level of the backstop menu.

      Available in OS X v10.0 and later.

    • kCGNormalWindowLevelKey

      kCGNormalWindowLevelKey

      The level for normal windows.

      Available in OS X v10.0 and later.

    • kCGFloatingWindowLevelKey

      kCGFloatingWindowLevelKey

      The level for floating windows.

      Available in OS X v10.0 and later.

    • kCGTornOffMenuWindowLevelKey

      kCGTornOffMenuWindowLevelKey

      The level for torn-off menus.

      Available in OS X v10.0 and later.

    • kCGDockWindowLevelKey

      kCGDockWindowLevelKey

      The level for the dock.

      Available in OS X v10.0 and later.

    • kCGMainMenuWindowLevelKey

      kCGMainMenuWindowLevelKey

      The level for the menus displayed in the menu bar.

      Available in OS X v10.0 and later.

    • kCGStatusWindowLevelKey

      kCGStatusWindowLevelKey

      The level for status windows.

      Available in OS X v10.0 and later.

    • kCGModalPanelWindowLevelKey

      kCGModalPanelWindowLevelKey

      The level for modal panels.

      Available in OS X v10.0 and later.

    • kCGPopUpMenuWindowLevelKey

      kCGPopUpMenuWindowLevelKey

      The level for pop-up menus.

      Available in OS X v10.0 and later.

    • kCGDraggingWindowLevelKey

      kCGDraggingWindowLevelKey

      The level for a window being dragged.

      Available in OS X v10.0 and later.

    • kCGScreenSaverWindowLevelKey

      kCGScreenSaverWindowLevelKey

      The level for screen savers.

      Available in OS X v10.0 and later.

    • kCGMaximumWindowLevelKey

      kCGMaximumWindowLevelKey

      The highest allowed window level.

      Available in OS X v10.0 and later.

    • kCGOverlayWindowLevelKey

      kCGOverlayWindowLevelKey

      The level for overlay windows.

      Available in OS X v10.1 and later.

    • kCGHelpWindowLevelKey

      kCGHelpWindowLevelKey

      The level for help windows.

      Available in OS X v10.1 and later.

    • kCGUtilityWindowLevelKey

      kCGUtilityWindowLevelKey

      The level for utility windows.

      Available in OS X v10.1 and later.

    • kCGDesktopIconWindowLevelKey

      kCGDesktopIconWindowLevelKey

      The level for desktop icons.

      Available in OS X v10.1 and later.

    • kCGCursorWindowLevelKey

      kCGCursorWindowLevelKey

      The level for the cursor.

      Available in OS X v10.2 and later.

    • kCGAssistiveTechHighWindowLevelKey

      kCGAssistiveTechHighWindowLevelKey

      The level for assistive technology.

      Available in OS X v10.3 and later.

    • kCGNumberOfWindowLevelKeys

      kCGNumberOfWindowLevelKeys

      The total number of window levels.

      Available in OS X v10.0 and later.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var kCGSessionUserIDKey: String { get } var kCGSessionUserNameKey: String { get } var kCGSessionConsoleSetKey: String { get } var kCGSessionOnConsoleKey: String { get } var kCGSessionLoginDoneKey: String { get }

    Objective-C

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

    Constants

    • kCGSessionUserIDKey

      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.

    • kCGSessionUserNameKey

      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.

    • kCGSessionConsoleSetKey

      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.

    • kCGSessionOnConsoleKey

      kCGSessionOnConsoleKey

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

      Available in OS X v10.3 and later.

    • kCGSessionLoginDoneKey

      kCGSessionLoginDoneKey

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

      Available in OS X v10.3 and later.

    Discussion

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

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

    Declaration

    Swift

    typealias CGDisplayStreamUpdateRectType = Int32

    Objective-C

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

    Constants

    • kCGDisplayStreamUpdateRefreshedRects

      kCGDisplayStreamUpdateRefreshedRects

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

      Available in OS X v10.8 and later.

    • kCGDisplayStreamUpdateMovedRects

      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.

    • kCGDisplayStreamUpdateDirtyRects

      kCGDisplayStreamUpdateDirtyRects

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

      Available in OS X v10.8 and later.

    • kCGDisplayStreamUpdateReducedDirtyRects

      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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.8 and later.

  • Describes a frame update event.

    Declaration

    Swift

    typealias CGDisplayStreamFrameStatus = Int32

    Objective-C

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

    Constants

    • kCGDisplayStreamFrameStatusFrameComplete

      kCGDisplayStreamFrameStatusFrameComplete

      A new frame was generated.

      Available in OS X v10.8 and later.

    • kCGDisplayStreamFrameStatusFrameIdle

      kCGDisplayStreamFrameStatusFrameIdle

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

      Available in OS X v10.8 and later.

    • kCGDisplayStreamFrameStatusFrameBlank

      kCGDisplayStreamFrameStatusFrameBlank

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

      Available in OS X v10.8 and later.

    • kCGDisplayStreamFrameStatusStopped

      kCGDisplayStreamFrameStatusStopped

      The display stream was stopped.

      Available in OS X v10.8 and later.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.8 and later.

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

    Declaration

    Swift

    let kCGDisplayStreamSourceRect: CFString! let kCGDisplayStreamDestinationRect: CFString! let kCGDisplayStreamPreserveAspectRatio: CFString! let kCGDisplayStreamColorSpace: CFString! let kCGDisplayStreamMinimumFrameTime: CFString! let kCGDisplayStreamShowCursor: CFString! let kCGDisplayStreamQueueDepth: CFString! let kCGDisplayStreamYCbCrMatrix: CFString!

    Objective-C

    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

      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.

    • kCGDisplayStreamDestinationRect

      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.

    • kCGDisplayStreamPreserveAspectRatio

      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.

    • kCGDisplayStreamColorSpace

      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.

    • kCGDisplayStreamMinimumFrameTime

      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.

    • kCGDisplayStreamShowCursor

      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.

    • kCGDisplayStreamQueueDepth

      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.

    • kCGDisplayStreamYCbCrMatrix

      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.

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

    Declaration

    Swift

    let kCGDisplayStreamYCbCrMatrix_ITU_R_709_2: CFString! let kCGDisplayStreamYCbCrMatrix_ITU_R_601_4: CFString! let kCGDisplayStreamYCbCrMatrix_SMPTE_240M_1995: CFString!

    Objective-C

    CFStringRef kCGDisplayStreamYCbCrMatrix_ITU_R_709_2; CFStringRef kCGDisplayStreamYCbCrMatrix_ITU_R_601_4; CFStringRef kCGDisplayStreamYCbCrMatrix_SMPTE_240M_1995

    Constants

    • kCGDisplayStreamYCbCrMatrix_ITU_R_709_2

      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.

    • kCGDisplayStreamYCbCrMatrix_ITU_R_601_4

      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.

    • kCGDisplayStreamYCbCrMatrix_SMPTE_240M_1995

      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.