CADisplayLink Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/QuartzCore.framework
Availability
Available in iOS 3.1 and later.
Declared in
CADisplayLink.h
Related sample code

Overview

A CADisplayLink object is a timer object that allows your application to synchronize its drawing to the refresh rate of the display.

Your application creates a new display link, providing a target object and a selector to be called when the screen is updated. Next, your application adds the display link to a run loop.

Once the display link is associated with a run loop, the selector on the target is called when the screen’s contents need to be updated. The target can read the display link’s timestamp property to retrieve the time that the previous frame was displayed. For example, an application that displays movies might use the timestamp to calculate which video frame will be displayed next. An application that performs its own animations might use the timestamp to determine where and how displayed objects appear in the upcoming frame. The duration property provides the amount of time between frames. You can use this value in your application to calculate the frame rate of the display, the approximate time that the next frame will be displayed, and to adjust the drawing behavior so that the next frame is prepared in time to be displayed.

Your application can disable notifications by setting the paused property to YES. Also, if your application cannot provide frames in the time provided, you may want to choose a slower frame rate. An application with a slower but consistent frame rate appears smoother to the user than an application that skips frames. You can increase the time between frames (and decrease the apparent frame rate) by changing the frameInterval property.

When your application finishes with a display link, it should call invalidate to remove it from all run loops and to disassociate it from the target.

CADisplayLink should not be subclassed.

Tasks

Creating Instances

Scheduling the Display Link to Send Notifications

Configuring the Display Link

Properties

duration

The time interval between screen refresh updates. (read-only)

@property(readonly, nonatomic) CFTimeInterval duration
Discussion

The value for duration is undefined before the target’s selector has been called at least once. Your application can calculate the amount of time it has to render each frame by multiplying duration by frameInterval.

Availability
  • Available in iOS 3.1 and later.
Declared In
CADisplayLink.h

frameInterval

The number of frames that must pass before the display link notifies the target again.

@property(nonatomic) NSInteger frameInterval
Discussion

The default value is 1, which results in your application being notified at the refresh rate of the display. If the value is set to a value larger than 1, the display link notifies your application at a fraction of the native refresh rate. For example, setting the interval to 2 causes the display link to fire every other frame, providing half the frame rate.

Setting this value to less than 1 results in undefined behavior and is a programmer error.

Availability
  • Available in iOS 3.1 and later.
Declared In
CADisplayLink.h

paused

A Boolean value that states whether the display link’s notifications to the target are suspended.

@property(getter=isPaused, nonatomic) BOOL paused
Discussion

The default value is NO. If YES, the display link does not send notifications to the target.

Availability
  • Available in iOS 3.1 and later.
Declared In
CADisplayLink.h

timestamp

The time value associated with the last frame that was displayed. (read-only)

@property(readonly, nonatomic) CFTimeInterval timestamp
Discussion

The target should use the value of this property to calculate what should be displayed in the next frame.

Availability
  • Available in iOS 3.1 and later.
Declared In
CADisplayLink.h

Class Methods

displayLinkWithTarget:selector:

Returns a new display link.

+ (CADisplayLink *)displayLinkWithTarget:(id)target selector:(SEL)sel
Parameters
target

An object to be notified when the screen should be updated.

sel

The method to call on the target.

Return Value

A newly constructed display link.

Discussion

The selector to be called on the target must be a method with the following signature:

- (void) selector:(CADisplayLink *)sender;

where sender is the display link returned by this method.

The newly constructed display link retains the target.

Availability
  • Available in iOS 3.1 and later.
Declared In
CADisplayLink.h

Instance Methods

addToRunLoop:forMode:

Registers the display link with a run loop.

- (void)addToRunLoop:(NSRunLoop *)runloop forMode:(NSString *)mode
Parameters
runloop

The run loop to associate with the display link.

mode

The mode in which to add the display link to the run loop. You may specify a custom mode or use one of the modes listed in NSRunLoop Class Reference.

Discussion

You can associate a display link with multiple input modes. While the run loop is executing in a mode you have specified, the display link notifies the target when new frames are required.

The run loop retains the display link. To remove the display link from all run loops, send an invalidate message to the display link.

Availability
  • Available in iOS 3.1 and later.
Declared In
CADisplayLink.h

invalidate

Removes the display link from all run loop modes.

- (void)invalidate
Discussion

Removing the display link from all run loop modes causes it to be released by the run loop. The display link also releases the target.

Availability
  • Available in iOS 3.1 and later.
Declared In
CADisplayLink.h

removeFromRunLoop:forMode:

Removes the display link from the run loop for the given mode.

- (void)removeFromRunLoop:(NSRunLoop *)runloop forMode:(NSString *)mode
Parameters
runloop

The run loop associated with the display link.

mode

The run loop mode in which the display link is running.

Discussion

The run loop releases the display link if it is no longer associated with any run modes.

Availability
  • Available in iOS 3.1 and later.
Declared In
CADisplayLink.h