CMTimeRange Reference

Derived from
Framework
CoreMedia.framework
Declared in
CMTimeRange.h

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

Comparing CMTimeRange

Functions

CMTimeClampToRange

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

CMTime CMTimeClampToRange (
   CMTime time,
   CMTimeRange range
);
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.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMTimeRange.h

CMTimeMapDurationFromRangeToRange

Translates a duration through a mapping from CMTimeRange to CMTimeRange.

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

The duration to be translated.

fromRange

The time range from which duration is translated.

toRange

The time range to which duration is mapped to .

Return Value

A CMTime structure representing the translated duration.

Discussion

The duration will be scaled in proportion to the ratio between the ranges' durations:

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

If dur does not have the epoch zero, an invalid CMTime will be returned.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMTimeRange.h

CMTimeMapTimeFromRangeToRange

Translates a time through a mapping from CMTimeRange to CMTimeRange.

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

The CMTime to be translated.

fromRange

The time range from which CMTime is translated.

toRange

The time range to which CMTime is mapped to.

Return Value

A CMTime structure representing the translated time.

Discussion

The start and end time of fromRange will be mapped to the start and end time of toRange respectively. Other times will be mapped linearly, using the formula:

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

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.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMTimeRange.h

CMTimeRangeContainsTime

Indicates whether a time is contained within a time range.

Boolean CMTimeRangeContainsTime (
   CMTimeRange range,
   CMTime time
);
Parameters
range

CMTimeRange being interrogated.

time

CMTime to be tested for inclusion.

Return Value

Returns true if the specified time is contained within the specified time range, false if it is not.

Discussion

This function returns a Boolean value that indicates whether the time specified by the time parameter is contained within the range specified by the range parameter.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMTimeRange.h

CMTimeRangeContainsTimeRange

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

Boolean CMTimeRangeContainsTimeRange (
   CMTimeRange range1,
   CMTimeRange range2
);
Parameters
range1

The CMTimeRange being interrogated.

range2

CMTimeRange to be tested for inclusion.

Return Value

Returns true if the second time range is contained within the first time range, false if it is not.

Discussion

This function returns a Boolean value that indicates whether the time range specified by the range1 parameter contains the range specified by the range2 parameter.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMTimeRange.h

CMTimeRangeCopyAsDictionary

Returns a CFDictionary version of a CMTimeRange.

CFDictionaryRef CMTimeRangeCopyAsDictionary (
   CMTimeRange range,
   CFAllocatorRef allocator
);
Parameters
range

The CMTimeRange from which to create a dictionary.

allocator

CFAllocator with which to create a dictionary. Pass kCFAllocatorDefault to use the default allocator

Return Value

A CFDictionary version of the CMTimeRange.

Discussion

This is useful when putting CMTimeRanges in Core Foundation container types. For keys, see “CFDictionary Keys.”

Availability
  • Available in iOS 4.0 and later.
Declared In
CMTimeRange.h

CMTimeRangeCopyDescription

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

CFStringRef CMTimeRangeCopyDescription (
   CFAllocatorRef allocator,
   CMTimeRange range
);
Parameters
allocator

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.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
CMTimeRange.h

CMTimeRangeEqual

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

Boolean CMTimeRangeEqual (
   CMTimeRange range1,
   CMTimeRange range2
);
Parameters
range1

CMTimeRange to be compared for equality.

range2

Another CMTimeRange to be compared for equality.

Return Value

Returns true if the two time ranges are identical, false if they differ.

Discussion

This function returns a Boolean value that indicates whether the time ranges specified by the range1 and range2 parameters are identical.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMTimeRange.h

CMTimeRangeFromTimeToTime

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

CMTimeRange CMTimeRangeFromTimeToTime (
   CMTime start,
   CMTime end
);
Parameters
start

CMTime structure representing start time for creating the range.

end

CMTime structure representing end time for creating the range.

Return Value

The resulting CMTimeRange.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMTimeRange.h

CMTimeRangeGetEnd

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

CMTime CMTimeRangeGetEnd (
   CMTimeRange range
);
Parameters
range

The CMTimeRange from which to find the end of time range.

Return Value

A CMTime structure representing the end of the specified time range.

Discussion

This function returns a CMTime structure that indicates the end of the time range specified by the range parameter. CMTimeRangeContainsTime(range, CMTimeRangeGetEnd(range)) is always false.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMTimeRange.h

CMTimeRangeGetIntersection

Returns the intersection of two CMTimeRanges.

CMTimeRange CMTimeRangeGetIntersection (
   CMTimeRange range1,
   CMTimeRange range2
);
Parameters
range1

CMTimeRange to be intersected.

range2

Another CMTimeRange to be intersected.

Return Value

The intersection of the two CMTimeRanges.

Discussion

This function returns a CMTimeRange structure that represents the intersection of the time ranges specified by the range1 and range2 parameters. This is the largest range that both ranges include.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMTimeRange.h

CMTimeRangeGetUnion

Returns the union of two CMTimeRanges.

CMTimeRange CMTimeRangeGetUnion (
   CMTimeRange range1,
   CMTimeRange range2
);
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.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMTimeRange.h

CMTimeRangeMake

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

CMTimeRange CMTimeRangeMake (
   CMTime start,
   CMTime duration
);
Parameters
start

CMTime structure for initializing the start field of the resulting CMTimeRange.

duration

CMTime structure for initializing the duration field of the resulting CMTimeRange.

Return Value

The resulting CMTimeRange.

Discussion

The duration parameter must have an epoch of 0; otherwise an invalid time range will be returned.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
CMTimeRange.h

CMTimeRangeMakeFromDictionary

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

CMTimeRange CMTimeRangeMakeFromDictionary (
   CFDictionaryRef dict
);
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.”

Availability
  • Available in iOS 4.0 and later.
Declared In
CMTimeRange.h

CMTimeRangeShow

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

void CMTimeRangeShow (
   CMTimeRange range
);
Parameters
range

The CMTimeRange to be printed.

Discussion

This is most useful from within gdb.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMTimeRange.h

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))))
Parameters
range

The time range to be tested for emptiness.

Return Value

true if range has a duration of 0; otherwise, false.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMTimeRange.h

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))))
Parameters
range

The time range to be tested for finiteness.

Return Value

true if range is indefinite; otherwise, false.

Discussion

An indefinite time range has either an indefinite start or an indefinite duration, or both.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMTimeRange.h

CMTIMERANGE_IS_INVALID

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

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

The time range to be tested for invalidity.

Return Value

true if range is invalid; otherwise, false.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMTimeRange.h

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)))
Parameters
range

The time range to be tested for validity.

Return Value

true if range is valid; otherwise, false.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMTimeRange.h

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.

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.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMTimeRange.h

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.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMTimeRange.h

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 iOS 4.0 and later.

Declared in CMTimeRange.h.

kCMTimeRangeDurationKey

The key for timescale of a CMTimeRange (CMTime).

Available in iOS 4.0 and later.

Declared in CMTimeRange.h.

Discussion

To convert a CMTimeRange to and from a CFDictionary, see CMTimeRangeCopyAsDictionary and CMTimeRangeMakeFromDictionary.

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 iOS 4.0 and later.

Declared in CMTimeRange.h.

kCMTimeRangeInvalid

Use this constant to generate an invalid CMTimeRange.

Available in iOS 4.0 and later.

Declared in CMTimeRange.h.