Functions


CAClockNew
Create a new clock object.
CAClockDispose
Dispose a clock object.
CAClockGetPropertyInfo
Gets information about a clock's property.
CAClockGetProperty
Gets the current value of a clock's property.
CAClockSetProperty
Changes the value of a clock's property.
CAClockAddListener
Adds a callback function to receive notifications of changes to the clock's state.
CAClockRemoveListener
Removes a listener callback function.
CAClockSetCurrentTime
Sets the clock's current position on the media timeline.
CAClockGetCurrentTime
Obtain the clock's current position on the media timeline.
CAClockGetStartTime
Obtain the position on the media timeline where playback will start, or has already started.
CAClockTranslateTime
Convert between time units.
CAClockStart
Begin advancing the clock on its media timeline.
CAClockStop
Stop advancing the clock on its media timeline.
CAClockArm
Allow received sync messages to start the clock.
CAClockDisarm
Disallow received sync messages from starting the clock.
CAClockSetPlayRate
Alter the clock's playback rate.
CAClockGetPlayRate
Obtain the clock's playback rate.
CAClockGetCurrentTempo
Obtain the clock's current musical tempo.
CAClockSetCurrentTempo
Manually override the clock's musical tempo during playback.
CAClockSecondsToSMPTETime
Converts seconds to a SMPTE time representation.
CAClockSMPTETimeToSeconds
Converts a SMPTE time representation to seconds.
CAClockBeatsToBarBeatTime
Converts a number of beats to a CABarBeatTime structure.
CAClockBarBeatTimeToBeats
Converts a CABarBeatTime structure to a number of beats.

CAClockNew


Create a new clock object.

extern OSStatus CAClockNew(
    UInt32 inReservedFlags, 
    CAClockRef *outCAClock); 
Parameter Descriptions
inReservedFlags
Must be 0.

outCAClock
Must be non-null. On successful return, the new clock object.

function result
An OSStatus error code.
Discussion



Availability
Introduced in Mac OS X 10.4.

CAClockDispose


Dispose a clock object.

extern OSStatus CAClockDispose(
    CAClockRef inCAClock); 
Parameter Descriptions
inCAClock
The clock object to be disposed.

function result
An OSStatus error code.
Discussion



Availability
Introduced in Mac OS X 10.4.

CAClockGetPropertyInfo


Gets information about a clock's property.

extern OSStatus CAClockGetPropertyInfo(
    CAClockRef inCAClock, 
    CAClockPropertyID inPropertyID, 
    UInt32 *outSize, 
    Boolean *outWritable); 
Parameter Descriptions
inCAClock
The clock object.

inPropertyID
The property being queried.

outSize
If non-null, on exit, this is set to the size of the property's value.

outWritable
If non-null, on exit, this indicates whether the property value is settable.

function result
An OSStatus error code.
Discussion



Availability
Introduced in Mac OS X 10.4.

CAClockGetProperty


Gets the current value of a clock's property.

extern OSStatus CAClockGetProperty(
    CAClockRef inCAClock, 
    CAClockPropertyID inPropertyID, 
    UInt32 *ioPropertyDataSize, 
    void *outPropertyData); 
Parameter Descriptions
inCAClock
The clock object.

inPropertyID
The property being fetched.

ioPropertyDataSize
On entry, the size (in bytes) of the memory pointed to by outPropertyData. On exit, the actual size of the property data returned.

outPropertyData
The value of the property is copied to the memory this points to.

function result
An OSStatus error code.
Discussion



Availability
Introduced in Mac OS X 10.4.

CAClockSetProperty


Changes the value of a clock's property.

extern OSStatus CAClockSetProperty(
    CAClockRef inCAClock, 
    CAClockPropertyID inPropertyID, 
    UInt32 inPropertyDataSize, 
    const void *inPropertyData); 
Parameter Descriptions
inCAClock
The clock object.

inPropertyID
The property being set.

inPropertyDataSize
The size of the property data, in bytes.

inPropertyData
Points to the property's new value.

function result
An OSStatus error code.
Discussion



Availability
Introduced in Mac OS X 10.4.

CAClockAddListener


Adds a callback function to receive notifications of changes to the clock's state.

extern OSStatus CAClockAddListener(
    CAClockRef inCAClock, 
    CAClockListenerProc inListenerProc, 
    void *inUserData); 
Parameter Descriptions
inCAClock
The clock object.

inListenerProc
The callback function.

inUserData
This value is passed to the callback function, in the userData parameter.

function result
An OSStatus error code.
Discussion

Note: The CAClockListenerProc may be called on a realtime thread internal to the clock object.

Availability
Introduced in Mac OS X 10.4.

CAClockRemoveListener


Removes a listener callback function.

extern OSStatus CAClockRemoveListener(
    CAClockRef inCAClock, 
    CAClockListenerProc inListenerProc, 
    void *inUserData); 
Parameter Descriptions
inCAClock
The clock object.

inListenerProc
The callback function.

inUserData
The same value as was passed for inUserData when this function was registered with CAClockAddListener. (This allows a single callback function to be registered more than once, with different userData arguments.)

function result
An OSStatus error code.
Discussion



Availability
Introduced in Mac OS X 10.4.

CAClockSetCurrentTime


Sets the clock's current position on the media timeline.

extern OSStatus CAClockSetCurrentTime(
    CAClockRef inCAClock, 
    const CAClockTime *inTime); 
Parameter Descriptions
inCAClock
The clock object.

inTime
The new time position.

function result
An OSStatus error code.
Discussion

Call this to specify where on the media timeline playback will begin. The supplied time must be in seconds, beats, or SMPTE (not host time or audio samples). Must only be called when stopped.

Availability
Introduced in Mac OS X 10.4.

CAClockGetCurrentTime


Obtain the clock's current position on the media timeline.

extern OSStatus CAClockGetCurrentTime(
    CAClockRef inCAClock, 
    CAClockTimeFormat inTimeFormat, 
    CAClockTime *outTime); 
Parameter Descriptions
inCAClock
The clock object.

inTimeFormat
Specifies the desired format for outTime.

outTime
On exit, the clock's current time position.

function result
An OSStatus error code.
Discussion



Availability
Introduced in Mac OS X 10.4.

CAClockGetStartTime


Obtain the position on the media timeline where playback will start, or has already started.

extern OSStatus CAClockGetStartTime(
    CAClockRef inCAClock, 
    CAClockTimeFormat inTimeFormat, 
    CAClockTime *outTime); 
Parameter Descriptions
inCAClock
The clock object.

inTimeFormat
Specifies the desired format for outTime.

outTime
On exit, the clock's start time position.

function result
An OSStatus error code.
Discussion



Availability
Introduced in Mac OS X 10.4.

CAClockTranslateTime


Convert between time units.

extern OSStatus CAClockTranslateTime(
    CAClockRef inCAClock, 
    const CAClockTime *inTime, 
    CAClockTimeFormat inOutputTimeFormat, 
    CAClockTime *outTime); 
Parameter Descriptions
inCAClock
The clock object.

inTime
The time to be converted.

inOutputTimeFormat
Specifies the desired format for outTime

outTime
On exit, a time corresponding to inTime, converted to the desired time format.

function result
An OSStatus error code.
Discussion



Availability
Introduced in Mac OS X 10.4.

CAClockStart


Begin advancing the clock on its media timeline.

extern OSStatus CAClockStart(
    CAClockRef inCAClock); 
Parameter Descriptions
inCAClock
The clock object.

function result
An OSStatus error code.
Discussion



Availability
Introduced in Mac OS X 10.4.

CAClockStop


Stop advancing the clock on its media timeline.

extern OSStatus CAClockStop(
    CAClockRef inCAClock); 
Parameter Descriptions
inCAClock
The clock object.

function result
An OSStatus error code.
Discussion



Availability
Introduced in Mac OS X 10.4.

CAClockArm


Allow received sync messages to start the clock.

extern OSStatus CAClockArm(
    CAClockRef inCAClock); 
Parameter Descriptions
inCAClock
The clock object.

function result
An OSStatus error code.
Discussion

If a clock is slaved to an external transport (e.g. MIDI Time Code), call this to indicate that the client is ready to start its transport in response to the external transport having started.

The external time source will set the clock's start position and start the clock.

Availability
Introduced in Mac OS X 10.4.

CAClockDisarm


Disallow received sync messages from starting the clock.

extern OSStatus CAClockDisarm(
    CAClockRef inCAClock); 
Parameter Descriptions
inCAClock
The clock object.

function result
An OSStatus error code.
Discussion



Availability
Introduced in Mac OS X 10.4.

CAClockSetPlayRate


Alter the clock's playback rate.

extern OSStatus CAClockSetPlayRate(
    CAClockRef inCAClock, 
    Float64 inPlayRate); 
Parameter Descriptions
inCAClock
The clock object.

inPlayRate
The clock's desired play rate.

function result
An OSStatus error code.
Discussion

Adjusts the ratio between the timebase and media time; e.g. at 0.5, the media time will move half as quickly as timebase time.

Availability
Introduced in Mac OS X 10.4.

CAClockGetPlayRate


Obtain the clock's playback rate.

extern OSStatus CAClockGetPlayRate(
    CAClockRef inCAClock, 
    Float64 *outPlayRate); 
Parameter Descriptions
inCAClock
The clock object.

outPlayRate
On exit, the clock's playback rate.

function result
An OSStatus error code.
Discussion

Returns the clock's current play rate. If the clock is internally synced, this will be the last rate set by CAClockSetPlayRate. If the clock is externally synced, it will be the rate of the external sync source, where
timebase. (2.0 means twice as fast).

Availability
Introduced in Mac OS X 10.4.

CAClockGetCurrentTempo


Obtain the clock's current musical tempo.

extern OSStatus CAClockGetCurrentTempo(
    CAClockRef inCAClock, 
    CAClockTempo *outTempo, 
    CAClockTime *outTimestamp); 
Parameter Descriptions
inCAClock
The clock object.

outTempo
On exit, the current tempo.

outTimestamp
If non-null, on exit, the time at which the tempo last changed.

function result
An OSStatus error code.
Discussion

Returns the current instantaneous tempo and a timestamp indicating where on the timeline the tempo most recently changed.

If the clock is externally synced, the returned tempo will not reflect the effective tempo; this routine always reflects the client-specified tempo. To obtain the effective tempo, multiply the current tempo by the current play rate.

Availability
Introduced in Mac OS X 10.4.

CAClockSetCurrentTempo


Manually override the clock's musical tempo during playback.

extern OSStatus CAClockSetCurrentTempo(
    CAClockRef inCAClock, 
    CAClockTempo inTempo, 
    const CAClockTime *inTimestamp); 
Parameter Descriptions
inCAClock
The clock object.

inTempo
The new desired tempo.

inTimestamp
Specifies a precise point on the timeline where the tempo change is to take effect. If null, the tempo change takes effect immediately.

function result
An OSStatus error code. If this call is made while stopped, kCAClock_CannotSetTimeError is returned.
Discussion

Effects a manual override of the tempo map while running. After stopping and restarting, the original tempo map will be used again.

Availability
Introduced in Mac OS X 10.4.

CAClockSecondsToSMPTETime


Converts seconds to a SMPTE time representation.

extern OSStatus CAClockSecondsToSMPTETime(
    CAClockRef inCAClock, 
    CAClockSeconds inSeconds, 
    UInt16 inSubframeDivisor, 
    SMPTETime *outSMPTETime); 
Parameter Descriptions
inCAClock
The clock object.

inSeconds
The number of seconds to be converted (e.g. 3600 = 1 hour).

inSubframeDivisor
The number of subframes per frame desired in outSMPTETime.

outSMPTETime
On exit, the SMPTE time corresponding to inSeconds.

function result
An OSStatus error code.
Discussion

Converts seconds on the media timeline to a SMPTE time. The clock's current SMPTE format and offset must be set appropriately.

Availability
Introduced in Mac OS X 10.4.

CAClockSMPTETimeToSeconds


Converts a SMPTE time representation to seconds.

extern OSStatus CAClockSMPTETimeToSeconds(
    CAClockRef inCAClock, 
    const SMPTETime *inSMPTETime, 
    CAClockSeconds *outSeconds); 
Parameter Descriptions
inCAClock
The clock object.

inSMPTETime
The SMPTE time to be converted to seconds.

outSeconds
On exit, the number of seconds corresponding to inSMPTETime.

function result
An OSStatus error code.
Discussion

Converts SMPTE time to seconds on the media timeline. The clock's current SMPTE format and offset must be set appropriately.

Availability
Introduced in Mac OS X 10.4.

CAClockBeatsToBarBeatTime


Converts a number of beats to a CABarBeatTime structure.

extern OSStatus CAClockBeatsToBarBeatTime(
    CAClockRef inCAClock, 
    CAClockBeats inBeats, 
    UInt16 inSubbeatDivisor, 
    CABarBeatTime *outBarBeatTime); 
Parameter Descriptions
inCAClock
The clock object.

inBeats
The absolute beat count to be converted.

inSubbeatDivisor
The number of units per beat.

outBarBeatTime
On exit, the bar/beat/subbeat time corresponding to inBeats.

function result
An OSStatus error code.
Discussion

Converts a beat position on the media timeline to a CABarBeatTime, using the clock's meter track. Examples using 4/4 time and a subbeat divisor of 480:

inBeats outBarBeatTime: bars . beats . units
0 1.1.0
1 1.2.0
4 2.1.0
4.5 2.1.240


Availability
Introduced in Mac OS X 10.4.

CAClockBarBeatTimeToBeats


Converts a CABarBeatTime structure to a number of beats.

extern OSStatus CAClockBarBeatTimeToBeats(
    CAClockRef inCAClock, 
    const CABarBeatTime *inBarBeatTime, 
    CAClockBeats *outBeats); 
Parameter Descriptions
inCAClock
The clock object.

inBarBeatTime
The bar/beat/subunit time to be converted to beats.

outBeats
On exit, the number of absolute beats corresponding to inBarBeatTime.

function result
An OSStatus error code.
Discussion

Converts a CABarBeatTime structure (bars/beats/subbeats) to a beat position, using the clock's meter track.

Availability
Introduced in Mac OS X 10.4.

(Last Updated July 18, 2005)