Mac Developer Library

Developer

System Framework Reference CVDisplayLink Reference

Options
Deployment Target:

On This Page
Language:

CVDisplayLink Reference

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import CoreVideo

Objective-C

@import CoreVideo;

A Core Video display link provides a separate high-priority thread to notify your application when a given display will need each frame. You can use a display link to easily synchronize with the refresh rate of a display. The display link API uses the Core Foundation class system internally to provide reference counting behavior and other useful properties.

Functions

  • Creates a display link for a single display.

    Declaration

    Swift

    func CVDisplayLinkCreateWithCGDisplay(_ displayID: CGDirectDisplayID, _ displayLinkOut: UnsafeMutablePointer<Unmanaged<CVDisplayLink>?>) -> CVReturn

    Objective-C

    CVReturn CVDisplayLinkCreateWithCGDisplay ( CGDirectDisplayID displayID, CVDisplayLinkRef *displayLinkOut );

    Parameters

    displayID

    The Core Graphics ID of the target display.

    displayLinkOut

    On output, displayLinkOut points to the newly created display link.

    Return Value

    A Core Video result code. See Core Video Constants Reference for possible values.

    Discussion

    Use this call to create a display link for a single display. For more information on the display identifier type, see CGDirectDisplayID.

    Import Statement

    Objective-C

    @import CoreVideo;

    Swift

    import CoreVideo

    Availability

    Available in OS X v10.4 and later.

  • Creates a display link capable of being used with all active displays.

    Declaration

    Swift

    func CVDisplayLinkCreateWithActiveCGDisplays(_ displayLinkOut: UnsafeMutablePointer<Unmanaged<CVDisplayLink>?>) -> CVReturn

    Objective-C

    CVReturn CVDisplayLinkCreateWithActiveCGDisplays ( CVDisplayLinkRef *displayLinkOut );

    Parameters

    displayLinkOut

    On output, displayLinkOut points to the newly created display link.

    Return Value

    A Core Video result code. See Core Video Constants Reference for possible values.

    Discussion

    CVDisplayLinkCreateWithActiveCGDisplays determines the displays actively used by the host computer and creates a display link compatible with all of them. For most applications, calling this function is the most convenient way to create a display link. After creation, you can assign the display link to any active display by calling the CVDisplayLinkSetCurrentCGDisplay function.

    Import Statement

    Objective-C

    @import CoreVideo;

    Swift

    import CoreVideo

    Availability

    Available in OS X v10.4 and later.

  • Creates a display link for an array of displays.

    Declaration

    Swift

    func CVDisplayLinkCreateWithCGDisplays(_ displayArray: UnsafeMutablePointer<CGDirectDisplayID>, _ count: CFIndex, _ displayLinkOut: UnsafeMutablePointer<Unmanaged<CVDisplayLink>?>) -> CVReturn

    Objective-C

    CVReturn CVDisplayLinkCreateWithCGDisplays ( CGDirectDisplayID *displayArray, CFIndex count, CVDisplayLinkRef *displayLinkOut );

    Parameters

    displayArray

    A pointer to an array of Core Graphics display IDs representing all the active monitors you want to use with this display link.

    count

    The number of displays in the display array.

    displayLinkOut

    On output, displayLinkOut points to the newly created display link.

    Return Value

    A Core Video result code. See Core Video Constants Reference for possible values.

    Discussion

    Use this call to create a display link for a set of displays identified by the Core Graphics display IDs. For more information on the display identifier type, see CGDirectDisplayID.

    Import Statement

    Objective-C

    @import CoreVideo;

    Swift

    import CoreVideo

    Availability

    Available in OS X v10.4 and later.

  • Creates a display link from an OpenGL display mask.

    Declaration

    Swift

    func CVDisplayLinkCreateWithOpenGLDisplayMask(_ mask: CGOpenGLDisplayMask, _ displayLinkOut: UnsafeMutablePointer<Unmanaged<CVDisplayLink>?>) -> CVReturn

    Objective-C

    CVReturn CVDisplayLinkCreateWithOpenGLDisplayMask ( CGOpenGLDisplayMask mask, CVDisplayLinkRef *displayLinkOut );

    Parameters

    mask

    The OpenGL display mask describing the available displays.

    displayLinkOut

    On output, displayLinkOut points to the newly created display link.

    Return Value

    A Core Video result code. See Core Video Constants Reference for possible values.

    Discussion

    Using this function avoids having to call the Core Graphics function CGOpenGLDisplayMaskToDisplayID.

    Import Statement

    Objective-C

    @import CoreVideo;

    Swift

    import CoreVideo

    Availability

    Available in OS X v10.4 and later.

  • Retrieves the actual output refresh period of a display as measured by the system time.

    Declaration

    Swift

    func CVDisplayLinkGetActualOutputVideoRefreshPeriod(_ displayLink: CVDisplayLink!) -> Double

    Objective-C

    double CVDisplayLinkGetActualOutputVideoRefreshPeriod ( CVDisplayLinkRef displayLink );

    Parameters

    displayLink

    The display link to get the refresh period from.

    Return Value

    A double-precision floating-point value representing the actual refresh period in seconds. This value may be zero if the device is not running or is otherwise unavailable.

    Discussion

    This call returns the actual output refresh period computed relative to the system time (as measured using the CVGetCurrentHostTime function).

    Import Statement

    Objective-C

    @import CoreVideo;

    Swift

    import CoreVideo

    Availability

    Available in OS X v10.4 and later.

  • Gets the current display associated with a display link.

    Declaration

    Swift

    func CVDisplayLinkGetCurrentCGDisplay(_ displayLink: CVDisplayLink!) -> CGDirectDisplayID

    Objective-C

    CGDirectDisplayID CVDisplayLinkGetCurrentCGDisplay ( CVDisplayLinkRef displayLink );

    Parameters

    displayLink

    The display link whose current display you want to obtain.

    Return Value

    An identifier representing the current display. For more information on the display identifier type, see CGDirectDisplayID.

    Import Statement

    Objective-C

    @import CoreVideo;

    Swift

    import CoreVideo

    Availability

    Available in OS X v10.4 and later.

  • Retrieves the current (“now”) time of a given display link.

    Declaration

    Swift

    func CVDisplayLinkGetCurrentTime(_ displayLink: CVDisplayLink!, _ outTime: UnsafeMutablePointer<CVTimeStamp>) -> CVReturn

    Objective-C

    CVReturn CVDisplayLinkGetCurrentTime ( CVDisplayLinkRef displayLink, CVTimeStamp *outTime );

    Parameters

    displayLink

    The display link whose current time you want to obtain.

    outTime

    A pointer to a CVTimeStamp structure. Note that you must set the version in the structure (currently 0) before calling to indicate which version of the timestamp structure you want.

    Return Value

    A Core Video result code. See Core Video Constants Reference for possible values.

    Discussion

    You use this call to obtain the timestamp of the frame that is currently being displayed.

    Import Statement

    Objective-C

    @import CoreVideo;

    Swift

    import CoreVideo

    Availability

    Available in OS X v10.4 and later.

  • Retrieves the nominal refresh period of a display link.

    Declaration

    Swift

    func CVDisplayLinkGetNominalOutputVideoRefreshPeriod(_ displayLink: CVDisplayLink!) -> CVTime

    Objective-C

    CVTime CVDisplayLinkGetNominalOutputVideoRefreshPeriod ( CVDisplayLinkRef displayLink );

    Parameters

    displayLink

    The display link whose refresh period you want to obtain.

    Return Value

    A CVTime structure that holds the nominal refresh period. This value is indefinite if an invalid display link was specified.

    Discussion

    This call allows one to retrieve the device's ideal refresh period. For example, an NTSC output device might report 1001/60000 to represent the exact NTSC vertical refresh rate.

    Import Statement

    Objective-C

    @import CoreVideo;

    Swift

    import CoreVideo

    Availability

    Available in OS X v10.4 and later.

  • Retrieves the nominal latency of a display link.

    Declaration

    Swift

    func CVDisplayLinkGetOutputVideoLatency(_ displayLink: CVDisplayLink!) -> CVTime

    Objective-C

    CVTime CVDisplayLinkGetOutputVideoLatency ( CVDisplayLinkRef displayLink );

    Parameters

    displayLink

    The display link whose latency value you want to obtain.

    Return Value

    A CVTime structure that holds the latency value. This value may be indefinite.

    Discussion

    This call allows you to retrieve the device’s built-in output latency. For example, an NTSC device with one frame of latency might report back 1001/30000 or 2002/60000.

    Import Statement

    Objective-C

    @import CoreVideo;

    Swift

    import CoreVideo

    Availability

    Available in OS X v10.4 and later.

  • Obtains the Core Foundation ID for the display link data type.

    Declaration

    Swift

    func CVDisplayLinkGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID CVDisplayLinkGetTypeID ( void );

    Return Value

    The Core Foundation ID for this type.

    Import Statement

    Objective-C

    @import CoreVideo;

    Swift

    import CoreVideo

    Availability

    Available in OS X v10.4 and later.

  • Indicates whether a given display link is running.

    Declaration

    Swift

    func CVDisplayLinkIsRunning(_ displayLink: CVDisplayLink!) -> Boolean

    Objective-C

    Boolean CVDisplayLinkIsRunning ( CVDisplayLinkRef displayLink );

    Parameters

    displayLink

    The display link whose run state you want to determine.

    Return Value

    Returns true if the display link is running, false otherwise.

    Import Statement

    Objective-C

    @import CoreVideo;

    Swift

    import CoreVideo

    Availability

    Available in OS X v10.4 and later.

  • Releases a display link.

    Declaration

    Objective-C

    void CVDisplayLinkRelease ( CVDisplayLinkRef displayLink );

    Parameters

    displayLink

    The display link to release. This function is NULL-safe.

    Import Statement

    Objective-C

    @import CoreVideo;

    Availability

    Available in OS X v10.4 and later.

  • Retains a display link.

    Declaration

    Objective-C

    CVDisplayLinkRef CVDisplayLinkRetain ( CVDisplayLinkRef displayLink );

    Parameters

    displayLink

    The display link to be retained. This function is NULL-safe.

    Return Value

    For convenience, this function returns the retained display link if successful.

    Import Statement

    Objective-C

    @import CoreVideo;

    Availability

    Available in OS X v10.4 and later.

  • Sets the current display of a display link.

    Declaration

    Swift

    func CVDisplayLinkSetCurrentCGDisplay(_ displayLink: CVDisplayLink!, _ displayID: CGDirectDisplayID) -> CVReturn

    Objective-C

    CVReturn CVDisplayLinkSetCurrentCGDisplay ( CVDisplayLinkRef displayLink, CGDirectDisplayID displayID );

    Parameters

    displayLink

    The display link whose display you want to set.

    displayID

    The ID of the display to be set.

    Return Value

    A Core Video result code. See Core Video Constants Reference for possible values.

    Discussion

    Although it is safe to call this function on a running display link, a discontinuity may appear in the video timestamp.

    Import Statement

    Objective-C

    @import CoreVideo;

    Swift

    import CoreVideo

    Availability

    Available in OS X v10.4 and later.

  • Selects the display link most optimal for the current renderer of an OpenGL context.

    Declaration

    Swift

    func CVDisplayLinkSetCurrentCGDisplayFromOpenGLContext(_ displayLink: CVDisplayLink!, _ cglContext: CGLContextObj, _ cglPixelFormat: CGLPixelFormatObj) -> CVReturn

    Objective-C

    CVReturn CVDisplayLinkSetCurrentCGDisplayFromOpenGLContext ( CVDisplayLinkRef displayLink, CGLContextObj cglContext, CGLPixelFormatObj cglPixelFormat );

    Parameters

    displayLink

    The display link whose current display is to be set.

    cglContext

    The OpenGL context to retrieve the current renderer from.

    cglPixelFormat

    The OpenGL pixel format used to create the passed-in OpenGL context.

    Return Value

    A Core Video result code. See Core Video Constants Reference for possible values.

    Discussion

    This function chooses the display with the lowest refresh rate.

    Import Statement

    Objective-C

    @import CoreVideo;

    Swift

    import CoreVideo

    Availability

    Available in OS X v10.4 and later.

  • Sets the renderer output callback function.

    Declaration

    Swift

    func CVDisplayLinkSetOutputCallback(_ displayLink: CVDisplayLink!, _ callback: CVDisplayLinkOutputCallback, _ userInfo: UnsafeMutablePointer<Void>) -> CVReturn

    Objective-C

    CVReturn CVDisplayLinkSetOutputCallback ( CVDisplayLinkRef displayLink, CVDisplayLinkOutputCallback callback, void *userInfo );

    Parameters

    displayLink

    The display link whose output callback you want to set.

    callback

    The callback function to set for this display link. See CVDisplayLinkOutputCallback for more information about implementing this function.

    userInfo

    A pointer to user data.

    Return Value

    A Core Video result code. See Core Video Constants Reference for possible values.

    Discussion

    The display link invokes this callback whenever it wants you to output a frame.

    Import Statement

    Objective-C

    @import CoreVideo;

    Swift

    import CoreVideo

    Availability

    Available in OS X v10.4 and later.

  • Activates a display link.

    Declaration

    Swift

    func CVDisplayLinkStart(_ displayLink: CVDisplayLink!) -> CVReturn

    Objective-C

    CVReturn CVDisplayLinkStart ( CVDisplayLinkRef displayLink );

    Parameters

    displayLink

    The display link to be activated.

    Return Value

    A Core Video result code. SeeCore Video Constants Reference for possible values.

    Discussion

    Calling this function starts the display link thread, which then periodically calls back to your application to request that you display frames. If the specified display link is already running, CVDisplayLinkStart returns an error.

    Import Statement

    Objective-C

    @import CoreVideo;

    Swift

    import CoreVideo

    Availability

    Available in OS X v10.4 and later.

  • Stops a display link.

    Declaration

    Swift

    func CVDisplayLinkStop(_ displayLink: CVDisplayLink!) -> CVReturn

    Objective-C

    CVReturn CVDisplayLinkStop ( CVDisplayLinkRef displayLink );

    Parameters

    displayLink

    The display link to be stopped.

    Return Value

    A Core Video result code. See Core Video Constants Reference for possible values.

    Discussion

    If the specified display link is already stopped, CVDisplayLinkStop returns an error.

    In OS X v.10.4 and later, the display link thread is automatically stopped if the user employs Fast User Switching. The display link is restarted when switching back to the original user.

    Import Statement

    Objective-C

    @import CoreVideo;

    Swift

    import CoreVideo

    Availability

    Available in OS X v10.4 and later.

  • Translates the time in the display link’s time base from one representation to another.

    Declaration

    Swift

    func CVDisplayLinkTranslateTime(_ displayLink: CVDisplayLink!, _ inTime: UnsafePointer<CVTimeStamp>, _ outTime: UnsafeMutablePointer<CVTimeStamp>) -> CVReturn

    Objective-C

    CVReturn CVDisplayLinkTranslateTime ( CVDisplayLinkRef displayLink, const CVTimeStamp *inTime, CVTimeStamp *outTime );

    Parameters

    displayLink

    The display link whose time base should be used to do the translation.

    inTime

    A pointer to a CVTimeStamp structure containing the source time to translate.

    outTime

    A pointer to a CVTimeStamp structure into which the target time is written. Before calling, you must set the version field (currently 0) to indicate which version of the structure you want. You should also set the flags field to specify which representations to translate to.

    Return Value

    A Core Video result code. See Core Video Constants Reference for possible values.

    Discussion

    Note that the display link has to be running for this call to succeed.

    Import Statement

    Objective-C

    @import CoreVideo;

    Swift

    import CoreVideo

    Availability

    Available in OS X v10.4 and later.

Callbacks

  • Defines a pointer to a display link output callback function, which is called whenever the display link wants the application to output a frame.

    Declaration

    Swift

    typealias CVDisplayLinkOutputCallback = CFunctionPointer<((CVDisplayLink!, UnsafePointer<CVTimeStamp>, UnsafePointer<CVTimeStamp>, CVOptionFlags, UnsafeMutablePointer<CVOptionFlags>, UnsafeMutablePointer<Void>) -> CVReturn)>

    Objective-C

    typedef CVReturn (*CVDisplayLinkOutputCallback)( CVDisplayLinkRef displayLink, const CVTimeStamp *inNow, const CVTimeStamp *inOutputTime, CVOptionFlags flagsIn, CVOptionFlags *flagsOut, void *displayLinkContext );

    Parameters

    displayLink

    The display link requesting the frame.

    inNow

    A pointer to the current time.

    inOutputTime

    A pointer to the time that the frame will be displayed.

    flagsIn

    Currently unused. Pass 0.

    flagsOut

    Currently unused. Pass 0.

    displayLinkContext

    A pointer to application-defined data. This is the pointer you passed into the CVDisplayLinkOutputCallback function when registering your callback.

    Discussion

    For a given display link, you must register a display link output callback using CVDisplayLinkOutputCallback so that you can process and output the requested frame.

    Your callback must retrieve the frame with the timestamp specified by the (inOutputTime parameter, manipulate it if desired (for example, apply color correction or map into onto a surface), and then output it to the display.

    Import Statement

    Objective-C

    @import CoreVideo;

    Swift

    import CoreVideo

    Availability

    Available in OS X v10.3 and later.

Data Types

  • A reference to a display link object.

    Declaration

    Swift

    typealias CVDisplayLinkRef = CVDisplayLink

    Objective-C

    typedef struct __CVDisplayLink *CVDisplayLinkRef;

    Import Statement

    Objective-C

    @import CoreVideo;

    Swift

    import CoreVideo

    Availability

    Available in OS X v10.3 and later.

  • The flags to be used for the display link output callback function.

    Declaration

    Swift

    typealias CVOptionFlags = UInt64

    Objective-C

    typedef uint64_t CVOptionFlags;

    Discussion

    No flags are currently defined.

    Import Statement

    Objective-C

    @import CoreVideo;

    Swift

    import CoreVideo

    Availability

    Available in OS X v10.3 and later.