CVDisplayLink Reference

Derived from
Framework
System/Library/Frameworks/QuartzCore.framework
Companion guide
Declared in
CVBase.h
CVDisplayLink.h

Overview

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

CVDisplayLinkCreateWithActiveCGDisplays

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

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
CVDisplayLink.h

CVDisplayLinkCreateWithCGDisplay

Creates a display link for a single display.

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
CVDisplayLink.h

CVDisplayLinkCreateWithCGDisplays

Creates a display link for an array of displays.

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
CVDisplayLink.h

CVDisplayLinkCreateWithOpenGLDisplayMask

Creates a display link from an OpenGL display mask.

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.

Availability
  • Available in OS X v10.4 and later.
Related Sample Code
Declared In
CVDisplayLink.h

CVDisplayLinkGetActualOutputVideoRefreshPeriod

Retrieves the actual output refresh period of a display as measured by the host time base.

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. This value may be zero if the device is not running or is otherwise unavailable.

Discussion

This call returns the actual output refresh period (in seconds) as computed relative to the host time base.

Availability
  • Available in OS X v10.4 and later.
Declared In
CVDisplayLink.h

CVDisplayLinkGetCurrentCGDisplay

Gets the current display associated with a display link.

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.

Availability
  • Available in OS X v10.4 and later.
Related Sample Code
Declared In
CVDisplayLink.h

CVDisplayLinkGetCurrentTime

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

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
CVDisplayLink.h

CVDisplayLinkGetNominalOutputVideoRefreshPeriod

Retrieves the nominal refresh period of a display link.

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
CVDisplayLink.h

CVDisplayLinkGetOutputVideoLatency

Retrieves the nominal latency of a display link.

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
CVDisplayLink.h

CVDisplayLinkGetTypeID

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

CFTypeID CVDisplayLinkGetTypeID (
   void
);
Return Value

The Core Foundation ID for this type.

Availability
  • Available in OS X v10.4 and later.
Declared In
CVDisplayLink.h

CVDisplayLinkIsRunning

Indicates whether a given display link is running.

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
CVDisplayLink.h

CVDisplayLinkRelease

Releases a display link.

void CVDisplayLinkRelease (
   CVDisplayLinkRef displayLink
);
Parameters
displayLink

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

Availability
  • Available in OS X v10.4 and later.
Declared In
CVDisplayLink.h

CVDisplayLinkRetain

Retains a display link.

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
CVDisplayLink.h

CVDisplayLinkSetCurrentCGDisplay

Sets the current display of a display link.

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
CVDisplayLink.h

CVDisplayLinkSetCurrentCGDisplayFromOpenGLContext

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

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
CVDisplayLink.h

CVDisplayLinkSetOutputCallback

Sets the renderer output callback function.

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
CVDisplayLink.h

CVDisplayLinkStart

Activates a display link.

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
CVDisplayLink.h

CVDisplayLinkStop

Stops a display link.

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
CVDisplayLink.h

CVDisplayLinkTranslateTime

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

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
CVDisplayLink.h

Callbacks

CVDisplayLinkOutputCallback

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

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

You would declare a display link output callback function named MyDisplayLinkCallback like this:

CVReturn MyDisplayLinkCallback (
   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.

Availability
  • Available in OS X v10.3 and later.
Declared In
CVDisplayLink.h

Data Types

CVDisplayLinkRef

A reference to a display link object.

typedef struct __CVDisplayLink *CVDisplayLinkRef;
Availability
  • Available in OS X v10.3 and later.
Declared In
CVDisplayLink.h

CVOptionFlags

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

typedef uint64_t CVOptionFlags;
Discussion

No flags are currently defined.

Availability
  • Available in OS X v10.3 and later.
Declared In
CVBase.h