CMTimeRange Reference

This document describes the API for creating and manipulating CMTimeRange structures.

CMTimeRange structs are non-opaque mutable structures that represent time ranges. A CMTimeRange is represented as two CMTime structs, one that specifies the start time of the range and another that specifies the duration of the range. A time range does not include the end time that would be calculated by adding the duration to the start time. The following expression will always evaluate to false:

The epoch in a CMTime that represents a duration should always be 0, and the value must be non-negative. The epoch in a CMTime that represents a timestamp may be non-zero, but range operations (such as CMTimeRangeGetUnion) can only be performed on ranges whose start fields have the same epoch. CMTimeRanges cannot span different epochs.

Declaration

Parameters

time

The time to be clamped.

range

The time range being interrogated.

Return Value

A CMTime structure inside the given time range.

Discussion

Times inside the given time range will be returned unmodified.
Times before the start and after the end time of the time range will return the start and end time of
the range respectively.
If the CMTimeRange argument is empty, an invalid CMTime will be returned.
If the given CMTime is invalid, the returned CMTime will be invalid.

If either CMTimeRange argument is empty, an invalid CMTime will be returned.
If t does not have the same epoch as fromRange.start, an invalid CMTime will be returned.
If both fromRange and toRange have duration kCMTimePositiveInfinity, t will be offset relative to the differences between their starts, but not scaled.

Parameters

CFAllocator for allocating memory for description. Pass kCFAllocatorDefault to use the default allocator.

range

The CMTimeRange to describe.

Return Value

The created CFString description.

Discussion

This is used from within CFShow on an object that contains CMTimeRange fields. It is also useful from other client debugging code. The caller owns the returned CFString and is responsible for releasing it.

Declaration

Parameters

range1

CMTimeRange to be unified.

range2

Another CMTimeRange to be unified.

Return Value

The union of the two CMTimeRanges.

Discussion

This function returns a CMTimeRange structure that represents the union of the time ranges specified by the range1 and range2 parameters. This is the smallest range that includes all times that are in either range.

Declaration

Parameters

dict

CFDictionary from which to create a CMTimeRange.

Return Value

The reconstituted CMTimeRange.

Discussion

This is useful when getting CMTimeRanges from Core Foundation container types. If the CFDictionary does not have the requisite keyed values, an invalid time range is returned.
For keys, see CFDictionary Keys.

Declaration

Fields

source

The time range on the source time line.

For an empty edit, source.start is an invalid CMTime, in which case source.duration is ignored. Otherwise, source.start is the starting time within the source, and source.duration is the duration of the source timeline to be mapped to the target time range.

target

The time range on the target time line.

If target.duration and source.duration are different, then the source segment should be played at the rate source.duration /target.duration to fit.

Discussion

A CMTimeMapping specifies the mapping of a segment of one time line (called the source) into another time line (called the target). When used for movie edit lists, the source time line is the media and the target time line is the track or movie.