Mac Developer Library

Developer

System Framework Reference CVTime Reference

Options
Deployment Target:

On This Page
Language:

CVTime Reference

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import CoreVideo

Objective-C

@import CoreVideo;

Core video uses the CVTime and CVTimeStamp structures for storing Core Video time values. You use them to interact with the Core Video display link.

Functions

  • Returns the current system time.

    Declaration

    Swift

    func CVGetCurrentHostTime() -> UInt64

    Objective-C

    uint64_t CVGetCurrentHostTime ( void );

    Return Value

    The current host time.

    Discussion

    In OS X, the host time bases for Core Video and CoreAudio are identical—both are based on the mach_absolute_time function—so the values returned from either API can be used interchangeably.

    Import Statement

    Objective-C

    @import CoreVideo;

    Swift

    import CoreVideo

    Availability

    Available in OS X v10.4 and later.

  • Returns the frequency of updates to the system time.

    Declaration

    Swift

    func CVGetHostClockFrequency() -> Double

    Objective-C

    double CVGetHostClockFrequency ( void );

    Return Value

    The current host frequency.

    Discussion

    In OS X, the host time bases for Core Video and CoreAudio are identical—both are based on the mach_absolute_time function—so the values returned from either API can be used interchangeably.

    Import Statement

    Objective-C

    @import CoreVideo;

    Swift

    import CoreVideo

    Availability

    Available in OS X v10.4 and later.

  • Returns the smallest possible increment in the system time.

    Declaration

    Swift

    func CVGetHostClockMinimumTimeDelta() -> UInt32

    Objective-C

    uint32_t CVGetHostClockMinimumTimeDelta ( void );

    Return Value

    The smallest valid increment in the system time.

    Import Statement

    Objective-C

    @import CoreVideo;

    Swift

    import CoreVideo

    Availability

    Available in OS X v10.4 and later.

Data Types

  • A structure for reporting Core Video time values.

    Declaration

    Swift

    struct CVTime { var timeValue: Int64 var timeScale: Int32 var flags: Int32 init() init(timeValue timeValue: Int64, timeScale timeScale: Int32, flags flags: Int32) }

    Objective-C

    typedef struct { int64_t timeValue; int64_t timeScale; int32_t flags; } CVTime;

    Fields

    timeValue

    The time value.

    timeScale

    The time scale for this value.

    flags

    The flags associated with the CVTime value. See CVTime Constants for possible values. If kCVTimeIsIndefinite is set, you should not use any of the other fields in this structure.

    Discussion

    This structure is equivalent to the QuickTime QTTime structure.

    Availability

    Available in OS X v10.3 and later.

  • A structure for defining a display timestamp.

    Declaration

    Swift

    struct CVTimeStamp { var version: UInt32 var videoTimeScale: Int32 var videoTime: Int64 var hostTime: UInt64 var rateScalar: Double var videoRefreshPeriod: Int64 var smpteTime: CVSMPTETime var flags: UInt64 var reserved: UInt64 init() init(version version: UInt32, videoTimeScale videoTimeScale: Int32, videoTime videoTime: Int64, hostTime hostTime: UInt64, rateScalar rateScalar: Double, videoRefreshPeriod videoRefreshPeriod: Int64, smpteTime smpteTime: CVSMPTETime, flags flags: UInt64, reserved reserved: UInt64) }

    Objective-C

    typedef struct { uint32_t version; int32_t videoTimeScale; int64_t videoTime; uint64_t hostTime; double rateScalar; int64_t videoRefreshPeriod; CVSMPTETime smpteTime; uint64_t flags; uint64_t reserved; } CVTimeStamp;

    Fields

    version

    The current CVTimeStamp structure is version 0. Some functions require you to specify a version when passing in a timestamp structure to be filled.

    videoTimeScale

    The scale (in units per second) of the videoTimeScale and videoRefreshPeriod fields.

    videoTime

    The start of a frame (or field for interlaced video).

    hostTime

    The system time measured by the timestamp.

    rateScalar

    The current rate of the device as measured by the timestamps, divided by the nominal rate.

    videoPeriod

    The nominal update period of the current output device.

    smpteTime

    The SMPTE time representation of the timestamp.

    flags

    A bit field containing additional information about the timestamp. See CVTimeStamp Flags for a list of possible values. .

    reserved

    Reserved. Do not use.

    Discussion

    This structure is designed to be very similar to the audio timestamp defined in the Core Audio framework except that, in CVTimeStamp, floating-point values are not used to represent the video equivalent of sample times.

    Availability

    Available in OS X v10.3 and later.

  • A structure for holding an SMPTE time.

    Declaration

    Swift

    struct CVSMPTETime { var subframes: Int16 var subframeDivisor: Int16 var counter: UInt32 var type: UInt32 var flags: UInt32 var hours: Int16 var minutes: Int16 var seconds: Int16 var frames: Int16 init() init(subframes subframes: Int16, subframeDivisor subframeDivisor: Int16, counter counter: UInt32, type type: UInt32, flags flags: UInt32, hours hours: Int16, minutes minutes: Int16, seconds seconds: Int16, frames frames: Int16) }

    Objective-C

    struct CVSMPTETime { SInt16 subframes; SInt16 subframeDivisor; UInt32 counter; UInt32 type; UInt32 flags; SInt16 hours; SInt16 minutes; SInt16 seconds; SInt16 frames; ;} typedef struct CVSMPTETime CVSMPTETime;

    Fields

    subframes

    The number of subframes in the full message.

    subframeDivisor

    The number of subframes per frame (typically, 80).

    counter

    The total number of messages received.

    type

    The kind of SMPTE time type. See SMPTE Time Types for a list of possible values.

    flags

    A set of flags that indicate the SMPTE state. See SMPTE State Flags for possible values.

    hours

    The number of hours in the full message.

    minutes

    The number of minutes in the full message.

    seconds

    The number of seconds in the full message.

    frames

    The number of frames in the full message.

    Availability

    Available in OS X v10.3 and later.

Constants

  • The flags for the CVTime structure.

    Declaration

    Swift

    var kCVTimeIsIndefinite: Int { get }

    Objective-C

    enum { kCVTimeIsIndefinite = 1 << 0 };

    Constants

    • kCVTimeIsIndefinite

      kCVTimeIsIndefinite

      The time value is unknown.

      Available in OS X v10.3 and later.

  • Keys that represent Core Video time values.

    Declaration

    Swift

    let kCVZeroTime: CVTime let kCVIndefiniteTime: CVTime

    Objective-C

    const CVTime kCVZeroTime; const CVTime kCVIndefiniteTime;

    Constants

    • kCVZeroTime

      kCVZeroTime

      Zero time or duration. For example, CVDisplayLinkGetOutputVideoLatency returns kCVZeroTime for zero video latency.

      Available in OS X v10.3 and later.

    • kCVIndefiniteTime

      kCVIndefiniteTime

      An unknown or indefinite time. For example, CVDisplayLinkGetNominalOutputVideoRefreshPeriod returns kCVIndefiniteTime if the display link specified is not valid.

      Available in OS X v10.3 and later.

  • The flags for the CVTimeStamp structure.

    Declaration

    Swift

    var kCVTimeStampVideoTimeValid: Int { get } var kCVTimeStampHostTimeValid: Int { get } var kCVTimeStampSMPTETimeValid: Int { get } var kCVTimeStampVideoRefreshPeriodValid: Int { get } var kCVTimeStampRateScalarValid: Int { get } var kCVTimeStampTopField: Int { get } var kCVTimeStampBottomField: Int { get } var kCVTimeStampVideoHostTimeValid: Int { get } var kCVTimeStampIsInterlaced: Int { get }

    Objective-C

    enum { kCVTimeStampVideoTimeValid = (1L << 0), kCVTimeStampHostTimeValid = (1L << 1), kCVTimeStampSMPTETimeValid = (1L << 2), kCVTimeStampVideoRefreshPeriodValid = (1L << 3), kCVTimeStampRateScalarValid = (1L << 4), kCVTimeStampTopField = (1L << 16), kCVTimeStampBottomField = (1L << 17) }; enum { kCVTimeStampVideoHostTimeValid = (kCVTimeStampVideoTimeValid | kCVTimeStampHostTimeValid ), kCVTimeStampIsInterlaced = (kCVTimeStampTopField | kCVTimeStampBottomField ) };

    Constants

    • kCVTimeStampVideoTimeValid

      kCVTimeStampVideoTimeValid

      The value in the video time field is valid.

      Available in OS X v10.3 and later.

    • kCVTimeStampHostTimeValid

      kCVTimeStampHostTimeValid

      The value in the host time field is valid.

      Available in OS X v10.3 and later.

    • kCVTimeStampSMPTETimeValid

      kCVTimeStampSMPTETimeValid

      The value in the SMPTE time field is valid.

      Available in OS X v10.3 and later.

    • kCVTimeStampVideoRefreshPeriodValid

      kCVTimeStampVideoRefreshPeriodValid

      The value in the video refresh period field is valid.

      Available in OS X v10.3 and later.

    • kCVTimeStampRateScalarValid

      kCVTimeStampRateScalarValid

      The value in the rate scalar field is valid.

      Available in OS X v10.3 and later.

    • kCVTimeStampTopField

      kCVTimeStampTopField

      The timestamp represents the top lines of an interlaced image.

      Available in OS X v10.3 and later.

    • kCVTimeStampBottomField

      kCVTimeStampBottomField

      The timestamp represents the bottom lines of an interlaced image.

      Available in OS X v10.3 and later.

    • kCVTimeStampVideoHostTimeValid

      kCVTimeStampVideoHostTimeValid

      A convenience constant indicating that both the video time and host time fields are valid.

      Available in OS X v10.3 and later.

    • kCVTimeStampIsInterlaced

      kCVTimeStampIsInterlaced

      A convenience constant indicating that the timestamp is for an interlaced image.

      Available in OS X v10.3 and later.

    Discussion

    These flags indicate which fields in the CVTimeStamp structure contain valid information.

  • The flags that describe the SMPTE time state.

    Declaration

    Swift

    var kCVSMPTETimeValid: Int { get } var kCVSMPTETimeRunning: Int { get }

    Objective-C

    enum{ kCVSMPTETimeValid = (1L << 0), kCVSMPTETimeRunning = (1L << 1) };

    Constants

    • kCVSMPTETimeValid

      kCVSMPTETimeValid

      The full time is valid.

      Available in OS X v10.3 and later.

    • kCVSMPTETimeRunning

      kCVSMPTETimeRunning

      Time is running.

      Available in OS X v10.3 and later.

    Discussion

    You use these values in the CVSMPTETime structure.

  • Constants that describe the type of SMPTE time.

    Declaration

    Swift

    var kCVSMPTETimeType24: Int { get } var kCVSMPTETimeType25: Int { get } var kCVSMPTETimeType30Drop: Int { get } var kCVSMPTETimeType30: Int { get } var kCVSMPTETimeType2997: Int { get } var kCVSMPTETimeType2997Drop: Int { get } var kCVSMPTETimeType60: Int { get } var kCVSMPTETimeType5994: Int { get }

    Objective-C

    enum{ kCVSMPTETimeType24 = 0, kCVSMPTETimeType25 = 1, kCVSMPTETimeType30Drop = 2, kCVSMPTETimeType30 = 3, kCVSMPTETimeType2997 = 4, kCVSMPTETimeType2997Drop = 5, kCVSMPTETimeType60 = 6, kCVSMPTETimeType5994 = 7 };

    Constants

    • kCVSMPTETimeType24

      kCVSMPTETimeType24

      24 frames per second (standard film).

      Available in OS X v10.3 and later.

    • kCVSMPTETimeType25

      kCVSMPTETimeType25

      25 frames per second (standard PAL).

      Available in OS X v10.3 and later.

    • kCVSMPTETimeType30Drop

      kCVSMPTETimeType30Drop

      30 drop frame.

      Available in OS X v10.3 and later.

    • kCVSMPTETimeType30

      kCVSMPTETimeType30

      30 frames per second.

      Available in OS X v10.3 and later.

    • kCVSMPTETimeType2997

      kCVSMPTETimeType2997

      29.97 frames per second (standard NTSC).

      Available in OS X v10.3 and later.

    • kCVSMPTETimeType2997Drop

      kCVSMPTETimeType2997Drop

      29.97 drop frame.

      Available in OS X v10.3 and later.

    • kCVSMPTETimeType60

      kCVSMPTETimeType60

      60 frames per second.

      Available in OS X v10.3 and later.

    • kCVSMPTETimeType5994

      kCVSMPTETimeType5994

      59.94 frames per second.

      Available in OS X v10.3 and later.

    Discussion

    You use these values in the CVSMPTETime structure.