CMTimeRange Reference

Overview

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:

CMTimeRangeContainsTime(range, CMTimeRangeGetEnd(range))

You can convert CMTimeRanges to and from CFDictionaries (see CFDictionaryRef) using CMTimeRangeCopyAsDictionary and CMTimeRangeMakeFromDictionary, for use in annotations and various Core Foundation containers.

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.

Additional functions for managing dates and times are described in Time Utilities Reference; see also AV Foundation Constants Reference.

Functions by Task

Working with CMTimeRange

• CMTimeClampToRange
• CMTimeMapDurationFromRangeToRange
• CMTimeMapTimeFromRangeToRange
• CMTimeRangeContainsTime
• CMTimeRangeContainsTimeRange
• CMTimeRangeCopyAsDictionary
• CMTimeRangeCopyDescription
• CMTimeRangeEqual
• CMTimeRangeFromTimeToTime
• CMTimeRangeGetEnd
• CMTimeRangeGetIntersection
• CMTimeRangeGetUnion
• CMTimeRangeMake
• CMTimeRangeMakeFromDictionary
• CMTimeRangeShow

Comparing CMTimeRange

• CMTIMERANGE_IS_EMPTY
• CMTIMERANGE_IS_INDEFINITE
• CMTIMERANGE_IS_INVALID
• CMTIMERANGE_IS_VALID

Functions

CMTimeClampToRange

For a given CMTime and CMTimeRange, returns the nearest CMTime inside that time range.

CMTime CMTimeClampToRange (
   CMTime time,
   CMTimeRange range
);

CMTimeMapDurationFromRangeToRange

Translates a duration through a mapping from CMTimeRange to CMTimeRange.

CMTime CMTimeMapDurationFromRangeToRange (
   CMTime dur,
   CMTimeRange fromRange,
   CMTimeRange toRange
);

result = dur*(toRange.duration/fromRange.duration)

CMTimeMapTimeFromRangeToRange

Translates a time through a mapping from CMTimeRange to CMTimeRange.

CMTime CMTimeMapTimeFromRangeToRange (
   CMTime t,
   CMTimeRange fromRange,
   CMTimeRange toRange
);

result = (t-fromRange.start)*(toRange.duration/fromRange.duration)+toRange.start

CMTimeRangeContainsTime

Indicates whether a time is contained within a time range.

Boolean CMTimeRangeContainsTime (
   CMTimeRange range,
   CMTime time
);

CMTimeRangeContainsTimeRange

Returns a Boolean that indicates whether a given time range is contained within another time range.

Boolean CMTimeRangeContainsTimeRange (
   CMTimeRange range1,
   CMTimeRange range2
);

CMTimeRangeCopyAsDictionary

Returns a CFDictionary version of a CMTimeRange.

CFDictionaryRef CMTimeRangeCopyAsDictionary (
   CMTimeRange range,
   CFAllocatorRef allocator
);

CMTimeRangeCopyDescription

Creates a CFString with a description of a CMTimeRange (similar to CFCopyDescription).

CFStringRef CMTimeRangeCopyDescription (
   CFAllocatorRef allocator,
   CMTimeRange range
);

CMTimeRangeEqual

Returns a Boolean value that indicates whether two CMTimeRanges are identical.

Boolean CMTimeRangeEqual (
   CMTimeRange range1,
   CMTimeRange range2
);

CMTimeRangeFromTimeToTime

Creates a valid CMTimeRange from the given start and end time.

CMTimeRange CMTimeRangeFromTimeToTime (
   CMTime start,
   CMTime end
);

CMTimeRangeGetEnd

Returns a CMTime structure representing the end of a time range.

CMTime CMTimeRangeGetEnd (
   CMTimeRange range
);

CMTimeRangeGetIntersection

Returns the intersection of two CMTimeRanges.

CMTimeRange CMTimeRangeGetIntersection (
   CMTimeRange range1,
   CMTimeRange range2
);

CMTimeRangeGetUnion

Returns the union of two CMTimeRanges.

CMTimeRange CMTimeRangeGetUnion (
   CMTimeRange range1,
   CMTimeRange range2
);

CMTimeRangeMake

Creates a valid CMTimeRange with the given start time and duration.

CMTimeRange CMTimeRangeMake (
   CMTime start,
   CMTime duration
);

CMTimeRangeMakeFromDictionary

Reconstitutes a CMTimeRange struct from a CFDictionary previously created by CMTimeRangeCopyAsDictionary.

CMTimeRange CMTimeRangeMakeFromDictionary (
   CFDictionaryRef dict
);

CMTimeRangeShow

Prints a description of the CMTimeRange to stderr (similar to CFShow).

void CMTimeRangeShow (
   CMTimeRange range
);

CMTIMERANGE_IS_EMPTY

Returns a Boolean value that indicates whether a given CMTimeRange has a duration of 0.

#define CMTIMERANGE_IS_EMPTY(range) ((Boolean)(CMTIMERANGE_IS_VALID(range) && (CMTIME_COMPARE_INLINE(range.duration, ==, kCMTimeZero))))

CMTIMERANGE_IS_INDEFINITE

Returns a Boolean value that indicates whether a given CMTimeRange is indefinite.

#define CMTIMERANGE_IS_INDEFINITE(range) ((Boolean)(CMTIMERANGE_IS_VALID(range) && (CMTIME_IS_INDEFINITE(range.start) || CMTIME_IS_INDEFINITE(range.duration))))

CMTIMERANGE_IS_INVALID

Returns a Boolean value that indicates whether a given CMTimeRange is invalid.

#define CMTIMERANGE_IS_INVALID(range) (! CMTIMERANGE_IS_VALID(range))

CMTIMERANGE_IS_VALID

Returns a Boolean value that indicates whether a given CMTimeRange is valid.

#define CMTIMERANGE_IS_VALID(range) ((Boolean)(CMTIME_IS_VALID(range.start) && CMTIME_IS_VALID(range.duration) && (range.duration.epoch == 0) && (range.duration.value >= 0)))

Data Types

CMTimeMapping

A structure to specify the mapping of a segment of one time line into another.

typedef struct {
   CMTimeRange source;
   CMTimeRange target;
} CMTimeMapping;

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.

CMTimeRange

A time range represented as two CMTime structures.

typedef struct {
   CMTime    start;
   CMTime    duration;
} CMTimeRange;

Fields

start

The start time of the time range.

duration

The duration of the time range.

Constants

CFDictionary Keys

Keys for components in a CFDictionary representation of a CMTimeRange.

const CFStringRef kCMTimeRangeStartKey;
const CFStringRef kCMTimeRangeDurationKey;

Constants

kCMTimeRangeStartKey

The key for start field of a CMTimeRange (CMTime).

Available in OS X v10.7 and later.

Declared in CMTimeRange.h.

kCMTimeRangeDurationKey

The key for timescale of a CMTimeRange (CMTime).

Available in OS X v10.7 and later.

Declared in CMTimeRange.h.

Pre-Specified Time Ranges

These constants specify zero and invalid time ranges.

const CMTimeRange kCMTimeRangeZero;
const CMTimeRange kCMTimeRangeInvalid;

Constants

kCMTimeRangeZero

Use this constant to generate an empty CMTimeRange at 0.

Available in OS X v10.7 and later.

Declared in CMTimeRange.h.

kCMTimeRangeInvalid

Use this constant to generate an invalid CMTimeRange.

Available in OS X v10.7 and later.

Declared in CMTimeRange.h.