iOS Developer Library

Developer

Quartz Core Framework Reference CADisplayLink Class Reference

Options
Deployment Target:

On This Page
Language:

CADisplayLink

Inherits From

Conforms To

Import Statement

Objective-C

@import QuartzCore;

Swift

import QuartzCore

Availability

Available in iOS 3.1 and later

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

Creating Instances
  • init(target:selector:) + displayLinkWithTarget:selector:

    Returns a new display link.

    Declaration

    Swift

    init(target target: AnyObject, selector sel: Selector)

    Objective-C

    + (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:

    1. - (void) selector:(CADisplayLink *)
    2. sender
    3. ;

    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.

Scheduling the Display Link to Send Notifications
  • addToRunLoop(_:forMode:) - addToRunLoop:forMode:

    Registers the display link with a run loop.

    Declaration

    Swift

    func addToRunLoop(_ runloop: NSRunLoop, forMode mode: String)

    Objective-C

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

    See Also

    – removeFromRunLoop:forMode:

  • removeFromRunLoop(_:forMode:) - removeFromRunLoop:forMode:

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

    Declaration

    Swift

    func removeFromRunLoop(_ runloop: NSRunLoop, forMode mode: String)

    Objective-C

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

    See Also

    – addToRunLoop:forMode:

  • invalidate() - invalidate

    Removes the display link from all run loop modes.

    Declaration

    Swift

    func invalidate()

    Objective-C

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

Configuring the Display Link
  • duration duration Property

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

    Declaration

    Swift

    var duration: CFTimeInterval { get }

    Objective-C

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

  • frameInterval frameInterval Property

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

    Declaration

    Swift

    var frameInterval: Int

    Objective-C

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

  • paused paused Property

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

    Declaration

    Swift

    var paused: Bool

    Objective-C

    @property(getter=isPaused, nonatomic) BOOL paused

    Discussion

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

    Availability

    Available in iOS 3.1 and later.

  • timestamp timestamp Property

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

    Declaration

    Swift

    var timestamp: CFTimeInterval { get }

    Objective-C

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

Copyright © 2015 Apple Inc. All rights reserved. Terms of Use | Privacy Policy | Updated: 2009-08-13