CVTime Reference

Framework
System/Library/Frameworks/QuartzCore.framework
Companion guide
Declared in
CVBase.h
CVHostTime.h

Overview

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

CVGetCurrentHostTime

Retrieves the current value of the host time base.

uint64_t CVGetCurrentHostTime
   void
);
Return Value

The current host time.

Discussion

In OS X, the host time base for Core Video and the one for CoreAudio are identical, and the values returned from either API can be used interchangeably.

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

CVGetHostClockFrequency

Retrieves the frequency of the host time base.

double CVGetHostClockFrequency
   void
);
Return Value

The current host frequency.

Discussion

In OS X, the host time base for Core Video and the one for CoreAudio are identical, and the values returned from either API can be used interchangeably.

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

CVGetHostClockMinimumTimeDelta

Retrieves the smallest possible increment in the host time base.

uint32_t CVGetHostClockMinimumTimeDelta
   void
);
Return Value

The smallest valid increment in the host time base.

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

Data Types

CVTime

A structure for reporting Core Video time values.

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.
Declared In
CVBase.h

CVTimeStamp

A structure for defining a display timestamp.

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 base time of the host root time.

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.
Declared In
CVBase.h

CVSMPTETime

A structure for holding an SMPTE time.

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.
Declared In
CVBase.h

Constants

CVTime Constants

The flags for the CVTime structure.

enum {
kCVTimeIsIndefinite = 1 << 0
};
Constants
kCVTimeIsIndefinite

The time value is unknown.

Available in OS X v10.3 and later.

Declared in CVBase.h.

CVTime Values

Keys that represent Core Video time values.

const CVTime kCVZeroTime;
const CVTime kCVIndefiniteTime;
Constants
kCVZeroTime

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

Available in OS X v10.3 and later.

Declared in CVBase.h.

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.

Declared in CVBase.h.

CVTimeStamp Flags

The flags for the CVTimeStamp structure.

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

The value in the video time field is valid.

Available in OS X v10.3 and later.

Declared in CVBase.h.

kCVTimeStampHostTimeValid

The value in the host time field is valid.

Available in OS X v10.3 and later.

Declared in CVBase.h.

kCVTimeStampSMPTETimeValid

The value in the SMPTE time field is valid.

Available in OS X v10.3 and later.

Declared in CVBase.h.

kCVTimeStampVideoRefreshPeriodValid

The value in the video refresh period field is valid.

Available in OS X v10.3 and later.

Declared in CVBase.h.

kCVTimeStampRateScalarValid

The value in the rate scalar field is valid.

Available in OS X v10.3 and later.

Declared in CVBase.h.

kCVTimeStampTopField

The timestamp represents the top lines of an interlaced image.

Available in OS X v10.3 and later.

Declared in CVBase.h.

kCVTimeStampBottomField

The timestamp represents the bottom lines of an interlaced image.

Available in OS X v10.3 and later.

Declared in CVBase.h.

kCVTimeStampVideoHostTimeValid

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

Available in OS X v10.3 and later.

Declared in CVBase.h.

kCVTimeStampIsInterlaced

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

Available in OS X v10.3 and later.

Declared in CVBase.h.

Discussion

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

SMPTE State Flags

The flags that describe the SMPTE time state.

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

The full time is valid.

Available in OS X v10.3 and later.

Declared in CVBase.h.

kCVSMPTETimeRunning

Time is running.

Available in OS X v10.3 and later.

Declared in CVBase.h.

Discussion

You use these values in the CVSMPTETime structure.

SMPTE Time Types

Constants that describe the type of SMPTE time.

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

24 frames per second (standard film).

Available in OS X v10.3 and later.

Declared in CVBase.h.

kCVSMPTETimeType25

25 frames per second (standard PAL).

Available in OS X v10.3 and later.

Declared in CVBase.h.

kCVSMPTETimeType30Drop

30 drop frame.

Available in OS X v10.3 and later.

Declared in CVBase.h.

kCVSMPTETimeType30

30 frames per second.

Available in OS X v10.3 and later.

Declared in CVBase.h.

kCVSMPTETimeType2997

29.97 frames per second (standard NTSC).

Available in OS X v10.3 and later.

Declared in CVBase.h.

kCVSMPTETimeType2997Drop

29.97 drop frame.

Available in OS X v10.3 and later.

Declared in CVBase.h.

kCVSMPTETimeType60

60 frames per second.

Available in OS X v10.3 and later.

Declared in CVBase.h.

kCVSMPTETimeType5994

59.94 frames per second.

Available in OS X v10.3 and later.

Declared in CVBase.h.

Discussion

You use these values in the CVSMPTETime structure.