Quartz Display Services

Provides direct access to features in the macOS window server for configuring and controlling display hardware.

Overview

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

Symbols

Finding Displays

func CGMainDisplayID()

Returns the display ID of the main display.

func CGGetOnlineDisplayList(UInt32, UnsafeMutablePointer<CGDirectDisplayID>?, UnsafeMutablePointer<UInt32>?)

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

func CGGetDisplaysWithPoint(CGPoint, UInt32, UnsafeMutablePointer<CGDirectDisplayID>?, UnsafeMutablePointer<UInt32>?)

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

func CGGetDisplaysWithRect(CGRect, UInt32, UnsafeMutablePointer<CGDirectDisplayID>?, UnsafeMutablePointer<UInt32>?)

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

func CGOpenGLDisplayMaskToDisplayID(CGOpenGLDisplayMask)

Maps an OpenGL display mask to a display ID.

func CGDisplayIDToOpenGLDisplayMask(CGDirectDisplayID)

Maps a display ID to an OpenGL display mask.

Capturing and Releasing Displays

func CGDisplayCapture(CGDirectDisplayID)

Captures a display for exclusive use by an application.

func CGDisplayCaptureWithOptions(CGDirectDisplayID, CGCaptureOptions)

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

func CGDisplayRelease(CGDirectDisplayID)

Releases a captured display.

func CGCaptureAllDisplays()

Captures all attached displays.

func CGCaptureAllDisplaysWithOptions(CGCaptureOptions)

Captures all attached displays, using the specified options.

func CGReleaseAllDisplays()

Releases all captured displays.

func CGShieldingWindowID(CGDirectDisplayID)

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

func CGShieldingWindowLevel()

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

func CGDisplayGetDrawingContext(CGDirectDisplayID)

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

Creating Images from the Display

func CGDisplayCreateImage(CGDirectDisplayID)

Returns an image containing the contents of the specified display.

func CGDisplayCreateImage(CGDirectDisplayID, rect: CGRect)

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

Configuring Displays

func CGCancelDisplayConfiguration(CGDisplayConfigRef?)

Cancels a set of display configuration changes.

func CGConfigureDisplayOrigin(CGDisplayConfigRef?, CGDirectDisplayID, Int32, Int32)

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

func CGRestorePermanentDisplayConfiguration()

Restores the permanent display configuration settings for the current user.

func CGConfigureDisplayStereoOperation(CGDisplayConfigRef?, CGDirectDisplayID, boolean_t, boolean_t)

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

func CGDisplaySetStereoOperation(CGDirectDisplayID, boolean_t, boolean_t, CGConfigureOption)

Immediately enables or disables stereo operation for a display.

Getting the Display Configuration

func CGDisplayCopyColorSpace(CGDirectDisplayID)

Returns the color space for a display.

func CGDisplayIsActive(CGDirectDisplayID)

Returns a Boolean value indicating whether a display is active.

func CGDisplayIsAlwaysInMirrorSet(CGDirectDisplayID)

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

func CGDisplayIsAsleep(CGDirectDisplayID)

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

func CGDisplayIsBuiltin(CGDirectDisplayID)

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

func CGDisplayIsInHWMirrorSet(CGDirectDisplayID)

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

func CGDisplayIsInMirrorSet(CGDirectDisplayID)

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

func CGDisplayIsMain(CGDirectDisplayID)

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

func CGDisplayIsOnline(CGDirectDisplayID)

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

func CGDisplayIsStereo(CGDirectDisplayID)

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

func CGDisplayMirrorsDisplay(CGDirectDisplayID)

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

func CGDisplayModelNumber(CGDirectDisplayID)

Returns the model number of a display monitor.

func CGDisplayPrimaryDisplay(CGDirectDisplayID)

Returns the primary display in a hardware mirroring set.

func CGDisplayRotation(CGDirectDisplayID)

Returns the rotation angle of a display in degrees.

func CGDisplayScreenSize(CGDirectDisplayID)

Returns the width and height of a display in millimeters.

func CGDisplaySerialNumber(CGDirectDisplayID)

Returns the serial number of a display monitor.

func CGDisplayUnitNumber(CGDirectDisplayID)

Returns the logical unit number of a display.

func CGDisplayUsesOpenGLAcceleration(CGDirectDisplayID)

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

func CGDisplayVendorNumber(CGDirectDisplayID)

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

Registering for Notification of Display Configuration Changes

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

func CGDisplayRegisterReconfigurationCallback(CGDisplayReconfigurationCallBack?, UnsafeMutableRawPointer?)

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

func CGDisplayRemoveReconfigurationCallback(CGDisplayReconfigurationCallBack?, UnsafeMutableRawPointer?)

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

Retrieving Display Parameters

func CGDisplayBounds(CGDirectDisplayID)

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

func CGDisplayPixelsHigh(CGDirectDisplayID)

Returns the display height in pixel units.

func CGDisplayPixelsWide(CGDirectDisplayID)

Returns the display width in pixel units.

Creating and Managing Display Modes

func CGDisplayCopyDisplayMode(CGDirectDisplayID)

Returns information about a display’s current configuration.

func CGDisplayCopyAllDisplayModes(CGDirectDisplayID, CFDictionary?)

Returns information about the currently available display modes.

Getting Information About a Display Mode

var width: Int

Returns the width of the specified display mode.

var height: Int

Returns the height of the specified display mode.

var pixelEncoding: CFString?

Returns the pixel encoding of the specified display mode.

Deprecated
var refreshRate: Double

Returns the refresh rate of the specified display mode.

var ioFlags: UInt32

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

var ioDisplayModeID: Int32

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

func isUsableForDesktopGUI()

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

class var typeID: CFTypeID

Returns the type identifier of Quartz display modes.

Adjusting the Display Gamma

func CGDisplayRestoreColorSyncSettings()

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

func CGDisplayGammaTableCapacity(CGDirectDisplayID)

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

Controlling the Mouse Cursor

func CGDisplayHideCursor(CGDirectDisplayID)

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

func CGDisplayShowCursor(CGDirectDisplayID)

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

func CGDisplayMoveCursorToPoint(CGDirectDisplayID, CGPoint)

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

func CGAssociateMouseAndMouseCursorPosition(boolean_t)

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

func CGWarpMouseCursorPosition(CGPoint)

Moves the mouse cursor without generating events.

Getting Window Server Information

func CGSessionCopyCurrentDictionary()

Returns information about the caller’s window server session.

func CGWindowLevelForKey(CGWindowLevelKey)

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

Streaming the Contents of a Display

func start()

Tells a stream to start sending updates.

func stop()

Tells a stream to stop sending updates.

var runLoopSource: CFRunLoopSource?

Gets the run loop source for a display stream.

func getRects(CGDisplayStreamUpdateRectType, rectCount: UnsafeMutablePointer<Int>)

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

init?(mergedUpdateFirstUpdate: CGDisplayStreamUpdate?, secondUpdate: CGDisplayStreamUpdate?)

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

var dropCount: Int

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

class var typeID: CFTypeID

Returns the type identifier of a Quartz display stream.

class var typeID: CFTypeID

Returns the type identifier of a Quartz display stream update.

Callbacks

CGDisplayReconfigurationCallBack

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

CGScreenRefreshCallback

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

CGScreenUpdateMoveCallback

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

Data Types

CGDirectDisplayID

A unique identifier for an attached display.

CGDisplayBlendFraction

The percentage of blend color used in a fade operation.

CGDisplayConfigRef

A reference to a display configuration transaction.

CGDisplayCount

The number of displays in various lists.

CGDisplayErr

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

CGDisplayFadeInterval

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

CGDisplayFadeReservationToken

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

CGDisplayMode

A reference to a display mode object.

CGDisplayReservationInterval

The time interval for a fade reservation.

CGGammaValue

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

CGOpenGLDisplayMask

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

CGRectCount

The size of an array of Quartz rectangles.

CGRefreshRate

A display’s refresh rate in frames per second.

CGScreenUpdateMoveDelta

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

CGWindowLevel

A level assigned to a window by an application framework.

CGDisplayStream

A reference to a display stream object.

CGDisplayStreamUpdate

A reference to frame update’s metadata.

CGDisplayStreamFrameAvailableHandler

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

Constants

CGCaptureOptions

Configuration parameters that are used when capturing displays.

CGDisplayChangeSummaryFlags

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

Display Configuration Scopes

The scope of the changes in a display configuration transaction.

Display Fade Blend Fractions

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

Display Fade Constants

Values relating to fade operations.

Display Mode Standard Properties

Keys for the standard properties in a display mode dictionary.

Display Mode Optional Properties

Keys for optional properties in a display mode dictionary.

Reserved Window Levels

Window level constants.

CGScreenUpdateOperation

Types of screen-update operations.

CGWindowLevelKey

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

Window Server Session Properties

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

CGDisplayStreamUpdateRectType

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

CGDisplayStreamFrameStatus

Describes a frame update event.

Display Stream Optional Property Keys

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

Display Stream YCbCr to RGB conversion Matrix Options

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