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

Finding Displays

CGMainDisplayID

Returns the display ID of the main display.

CGGetOnlineDisplayList

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

CGGetActiveDisplayList

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

CGGetDisplaysWithOpenGLDisplayMask

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

CGGetDisplaysWithPoint

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

CGGetDisplaysWithRect

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

CGOpenGLDisplayMaskToDisplayID

Maps an OpenGL display mask to a display ID.

CGDisplayIDToOpenGLDisplayMask

Maps a display ID to an OpenGL display mask.

Capturing and Releasing Displays

CGDisplayCapture

Captures a display for exclusive use by an application.

CGDisplayCaptureWithOptions

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

CGDisplayRelease

Releases a captured display.

CGDisplayIsCaptured

Returns a Boolean value indicating whether a display is captured.

Deprecated
CGCaptureAllDisplays

Captures all attached displays.

CGCaptureAllDisplaysWithOptions

Captures all attached displays, using the specified options.

CGReleaseAllDisplays

Releases all captured displays.

CGShieldingWindowID

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

CGShieldingWindowLevel

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

CGDisplayAddressForPosition

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

CGDisplayBaseAddress

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

CGDisplayGetDrawingContext

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

Creating Images from the Display

CGDisplayCreateImage

Returns an image containing the contents of the specified display.

CGDisplayCreateImageForRect

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

Configuring Displays

CGBeginDisplayConfiguration

Begins a new set of display configuration changes.

CGCancelDisplayConfiguration

Cancels a set of display configuration changes.

CGCompleteDisplayConfiguration

Completes a set of display configuration changes.

CGConfigureDisplayMirrorOfDisplay

Changes the configuration of a mirroring set.

CGConfigureDisplayMode

Configures the display mode of a display.

Deprecated
CGConfigureDisplayOrigin

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

CGRestorePermanentDisplayConfiguration

Restores the permanent display configuration settings for the current user.

CGConfigureDisplayStereoOperation

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

CGDisplaySetStereoOperation

Immediately enables or disables stereo operation for a display.

CGConfigureDisplayWithDisplayMode

Configures the display mode of a display.

Getting the Display Configuration

CGDisplayCopyColorSpace

Returns the color space for a display.

CGDisplayIOServicePort

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

Deprecated
CGDisplayIsActive

Returns a Boolean value indicating whether a display is active.

CGDisplayIsAlwaysInMirrorSet

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

CGDisplayIsAsleep

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

CGDisplayIsBuiltin

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

CGDisplayIsInHWMirrorSet

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

CGDisplayIsInMirrorSet

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

CGDisplayIsMain

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

CGDisplayIsOnline

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

CGDisplayIsStereo

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

CGDisplayMirrorsDisplay

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

CGDisplayModelNumber

Returns the model number of a display monitor.

CGDisplayPrimaryDisplay

Returns the primary display in a hardware mirroring set.

CGDisplayRotation

Returns the rotation angle of a display in degrees.

CGDisplayScreenSize

Returns the width and height of a display in millimeters.

CGDisplaySerialNumber

Returns the serial number of a display monitor.

CGDisplayUnitNumber

Returns the logical unit number of a display.

CGDisplayUsesOpenGLAcceleration

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

CGDisplayVendorNumber

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.

CGDisplayRegisterReconfigurationCallback

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

CGDisplayRemoveReconfigurationCallback

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

Retrieving Display Parameters

CGDisplayBounds

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

CGDisplayPixelsHigh

Returns the display height in pixel units.

CGDisplayPixelsWide

Returns the display width in pixel units.

CGDisplayBitsPerPixel

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

CGDisplayBitsPerSample

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

CGDisplaySamplesPerPixel

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

CGDisplayBytesPerRow

Returns the number of bytes per row in a display.

Creating and Managing Display Modes

CGDisplayAvailableModes

Returns information about the currently available display modes.

Deprecated
CGDisplayBestModeForParameters

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

Deprecated
CGDisplayBestModeForParametersAndRefreshRate

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

Deprecated
CGDisplayCurrentMode

Returns information about the current display mode.

Deprecated
CGDisplaySwitchToMode

Switches a display to a different mode.

Deprecated
CGDisplayCopyDisplayMode

Returns information about a display’s current configuration.

CGDisplayCopyAllDisplayModes

Returns information about the currently available display modes.

CGDisplaySetDisplayMode

Switches a display to a different mode.

CGDisplayModeRetain

Retains a Core Graphics display mode.

CGDisplayModeRelease

Releases a Core Graphics display mode.

Getting Information About a Display Mode

CGDisplayModeGetWidth

Returns the width of the specified display mode.

CGDisplayModeGetHeight

Returns the height of the specified display mode.

CGDisplayModeCopyPixelEncoding

Returns the pixel encoding of the specified display mode.

Deprecated
CGDisplayModeGetRefreshRate

Returns the refresh rate of the specified display mode.

CGDisplayModeGetIOFlags

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

CGDisplayModeGetIODisplayModeID

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

CGDisplayModeIsUsableForDesktopGUI

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

CGDisplayModeGetTypeID

Returns the type identifier of Quartz display modes.

Adjusting the Display Gamma

CGSetDisplayTransferByFormula

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

CGGetDisplayTransferByFormula

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

CGSetDisplayTransferByTable

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

CGGetDisplayTransferByTable

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

CGSetDisplayTransferByByteTable

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

CGDisplayRestoreColorSyncSettings

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

CGDisplayGammaTableCapacity

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

Display Fade Effects

CGConfigureDisplayFadeEffect

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

CGAcquireDisplayFadeReservation

Reserves the fade hardware for a specified time interval.

CGDisplayFade

Performs a single fade operation.

CGDisplayFadeOperationInProgress

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

Deprecated
CGReleaseDisplayFadeReservation

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

Controlling the Mouse Cursor

CGDisplayHideCursor

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

CGDisplayShowCursor

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

CGDisplayMoveCursorToPoint

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

CGCursorIsVisible

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

Deprecated
CGCursorIsDrawnInFramebuffer

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

Deprecated
CGAssociateMouseAndMouseCursorPosition

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

CGWarpMouseCursorPosition

Moves the mouse cursor without generating events.

CGGetLastMouseDelta

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

Getting Window Server Information

CGSessionCopyCurrentDictionary

Returns information about the caller’s window server session.

CGWindowServerCFMachPort

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

Deprecated
CGWindowLevelForKey

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

Getting Information About Refresh and Move Operations

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

CGRegisterScreenRefreshCallback

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

Deprecated
CGUnregisterScreenRefreshCallback

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

Deprecated
CGWaitForScreenRefreshRects

Waits for screen refresh operations.

Deprecated
CGScreenRegisterMoveCallback

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

Deprecated
CGScreenUnregisterMoveCallback

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

Deprecated
CGWaitForScreenUpdateRects

Waits for screen update operations.

Deprecated
CGReleaseScreenRefreshRects

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

Deprecated

Streaming the Contents of a Display

CGDisplayStreamCreate

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

CGDisplayStreamCreateWithDispatchQueue

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

CGDisplayStreamStart

Tells a stream to start sending updates.

CGDisplayStreamStop

Tells a stream to stop sending updates.

CGDisplayStreamGetRunLoopSource

Gets the run loop source for a display stream.

CGDisplayStreamUpdateGetRects

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

CGDisplayStreamUpdateCreateMergedUpdate

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

CGDisplayStreamUpdateGetMovedRectsDelta

Return the movement delta values for a single update.

CGDisplayStreamUpdateGetDropCount

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

CGDisplayStreamGetTypeID

Returns the type identifier of a Quartz display stream.

CGDisplayStreamUpdateGetTypeID

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.

CGDisplayModeRef

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.

CGDisplayStreamRef

A reference to a display stream object.

CGDisplayStreamUpdateRef

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.

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 ID Defaults

Default values for a display ID.

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.

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.

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.