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

Topics

Capturing and Releasing Displays

func CGDisplayCapture(CGDirectDisplayID) -> CGError

Captures a display for exclusive use by an application.

func CGDisplayCaptureWithOptions(CGDirectDisplayID, CGCaptureOptions) -> CGError

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

func CGCaptureAllDisplays() -> CGError

Captures all attached displays.

func CGCaptureAllDisplaysWithOptions(CGCaptureOptions) -> CGError

Captures all attached displays, using the specified options.

func CGReleaseAllDisplays() -> CGError

Releases all captured displays.

func CGShieldingWindowID(CGDirectDisplayID) -> CGWindowID

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

func CGShieldingWindowLevel() -> CGWindowLevel

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

func CGDisplayGetDrawingContext(CGDirectDisplayID) -> CGContext?

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

Creating Images from the Display

func CGDisplayCreateImage(CGDirectDisplayID) -> CGImage?

Returns an image containing the contents of the specified display.

func CGDisplayCreateImage(CGDirectDisplayID, rect: CGRect) -> CGImage?

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

Configuring Displays

Getting the Display Configuration

func CGDisplayIsActive(CGDirectDisplayID) -> boolean_t

Returns a Boolean value indicating whether a display is active.

func CGDisplayIsAlwaysInMirrorSet(CGDirectDisplayID) -> boolean_t

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

func CGDisplayIsAsleep(CGDirectDisplayID) -> boolean_t

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

func CGDisplayIsBuiltin(CGDirectDisplayID) -> boolean_t

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

func CGDisplayIsInHWMirrorSet(CGDirectDisplayID) -> boolean_t

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

func CGDisplayIsInMirrorSet(CGDirectDisplayID) -> boolean_t

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

func CGDisplayIsMain(CGDirectDisplayID) -> boolean_t

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

func CGDisplayIsOnline(CGDirectDisplayID) -> boolean_t

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

func CGDisplayIsStereo(CGDirectDisplayID) -> boolean_t

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

func CGDisplayMirrorsDisplay(CGDirectDisplayID) -> CGDirectDisplayID

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

func CGDisplayModelNumber(CGDirectDisplayID) -> UInt32

Returns the model number of a display monitor.

func CGDisplayPrimaryDisplay(CGDirectDisplayID) -> CGDirectDisplayID

Returns the primary display in a hardware mirroring set.

func CGDisplayRotation(CGDirectDisplayID) -> Double

Returns the rotation angle of a display in degrees.

func CGDisplayScreenSize(CGDirectDisplayID) -> CGSize

Returns the width and height of a display in millimeters.

func CGDisplaySerialNumber(CGDirectDisplayID) -> UInt32

Returns the serial number of a display monitor.

func CGDisplayUnitNumber(CGDirectDisplayID) -> UInt32

Returns the logical unit number of a display.

func CGDisplayUsesOpenGLAcceleration(CGDirectDisplayID) -> boolean_t

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

func CGDisplayVendorNumber(CGDirectDisplayID) -> UInt32

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?) -> CGError

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

func CGDisplayRemoveReconfigurationCallback(CGDisplayReconfigurationCallBack?, UnsafeMutableRawPointer?) -> CGError

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

Retrieving Display Parameters

func CGDisplayBounds(CGDirectDisplayID) -> CGRect

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

func CGDisplayPixelsHigh(CGDirectDisplayID) -> Int

Returns the display height in pixel units.

func CGDisplayPixelsWide(CGDirectDisplayID) -> Int

Returns the display width in pixel units.

Creating and Managing Display Modes

func CGDisplayCopyDisplayMode(CGDirectDisplayID) -> CGDisplayMode?

Returns information about a display’s current configuration.

func CGDisplayCopyAllDisplayModes(CGDirectDisplayID, CFDictionary?) -> CFArray?

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() -> Bool

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

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

Controlling the Mouse Cursor

func CGDisplayHideCursor(CGDirectDisplayID) -> CGError

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

func CGDisplayShowCursor(CGDirectDisplayID) -> CGError

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

func CGDisplayMoveCursorToPoint(CGDirectDisplayID, CGPoint) -> CGError

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

func CGAssociateMouseAndMouseCursorPosition(boolean_t) -> CGError

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

func CGWarpMouseCursorPosition(CGPoint) -> CGError

Moves the mouse cursor without generating events.

func CGGetLastMouseDelta() -> (x: Int32, y: Int32)

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

Getting Window Server Information

func CGSessionCopyCurrentDictionary() -> CFDictionary?

Returns information about the caller’s window server session.

func CGWindowLevelForKey(CGWindowLevelKey) -> CGWindowLevel

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

Streaming the Contents of a Display

func start() -> CGError

Tells a stream to start sending updates.

func stop() -> CGError

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>) -> UnsafePointer<CGRect>?

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

typealias CGDisplayReconfigurationCallBack

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

typealias CGScreenRefreshCallback

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

typealias CGScreenUpdateMoveCallback

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

Data Types

typealias CGDirectDisplayID

A unique identifier for an attached display.

typealias CGDisplayBlendFraction

The percentage of blend color used in a fade operation.

typealias CGDisplayConfigRef

A reference to a display configuration transaction.

typealias CGDisplayCount

The number of displays in various lists.

typealias CGDisplayErr

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

typealias CGDisplayFadeInterval

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

typealias CGDisplayFadeReservationToken

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

class CGDisplayMode

A reference to a display mode object.

typealias CGDisplayReservationInterval

The time interval for a fade reservation.

typealias CGGammaValue

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

typealias CGOpenGLDisplayMask

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

typealias CGRectCount

The size of an array of Quartz rectangles.

typealias CGRefreshRate

A display’s refresh rate in frames per second.

struct CGScreenUpdateMoveDelta

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

typealias CGWindowLevel

A level assigned to a window by an application framework.

class CGDisplayStream

A reference to a display stream object.

class CGDisplayStreamUpdate

A reference to frame update’s metadata.

typealias CGDisplayStreamFrameAvailableHandler

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

Constants

struct CGCaptureOptions

Configuration parameters that are used when capturing displays.

struct CGDisplayChangeSummaryFlags

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

struct CGConfigureOption

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.

struct CGScreenUpdateOperation

Types of screen-update operations.

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

enum CGDisplayStreamUpdateRectType

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

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

See Also

Services

Quartz Event Services

Provides features for managing event taps—filters for observing and altering the stream of low-level user input events in macOS.

Quartz Window Services

Provides information about the windows managed by the macOS window server.