Struct CMTime 

#[repr(C, packed(4))]
pub struct CMTime {
    pub value: CMTimeValue,
    pub timescale: CMTimeScale,
    pub flags: CMTimeFlags,
    pub epoch: CMTimeEpoch,
}

Available on crate feature CMTime only.

Rational time value represented as int64/int32.

See also Apple’s documentation

Fields

value: CMTimeValue

The value of the CMTime. value/timescale = seconds

timescale: CMTimeScale

The timescale of the CMTime. value/timescale = seconds.

flags: CMTimeFlags

The flags, eg. kCMTimeFlags_Valid, kCMTimeFlags_PositiveInfinity, etc.

epoch: CMTimeEpoch

Differentiates between equal timestamps that are actually different because of looping, multi-item sequencing, etc. Will be used during comparison: greater epochs happen after lesser ones. Additions/subtraction is only possible within a single epoch, however, since epoch length may be unknown/variable

Implementations

impl CMTime

pub unsafe fn code_format_description_get_frame_duration( time_code_format_description: &CMTimeCodeFormatDescription, ) -> CMTime

Available on crate feature CMFormatDescription only.

Returns the duration of each frame (eg. 100/2997)

impl CMTime

pub unsafe fn new(value: i64, timescale: i32) -> CMTime

Make a valid CMTime with value and timescale. Epoch is implied to be 0.

Returns: The resulting CMTime.

pub unsafe fn with_epoch(value: i64, timescale: i32, epoch: i64) -> CMTime

Make a valid CMTime with value, scale and epoch.

Returns: The resulting CMTime.

pub unsafe fn with_seconds(seconds: f64, preferred_timescale: i32) -> CMTime

Make a CMTime from a Float64 number of seconds, and a preferred timescale.

The epoch of the result will be zero. If preferredTimescale is < = 0, the result will be an invalid CMTime. If the preferred timescale will cause an overflow, the timescale will be halved repeatedly until the overflow goes away, or the timescale is 1. If it still overflows at that point, the result will be +/- infinity. The kCMTimeFlags_HasBeenRounded flag will be set if the result, when converted back to seconds, is not exactly equal to the original seconds value.

Returns: The resulting CMTime.

pub unsafe fn seconds(self) -> f64

Converts a CMTime to seconds.

If the CMTime is invalid or indefinite, NAN is returned. If the CMTime is infinite, +/- __inf() is returned. If the CMTime is numeric, epoch is ignored, and time.value / time.timescale is returned. The division is done in Float64, so the fraction is not lost in the returned result.

Returns: The resulting Float64 number of seconds.

impl CMTime

pub unsafe fn convert_scale( self, new_timescale: i32, method: CMTimeRoundingMethod, ) -> CMTime

Returns a new CMTime containing the source CMTime converted to a new timescale (rounding as requested).

If the value needs to be rounded, the kCMTimeFlags_HasBeenRounded flag will be set. See definition of CMTimeRoundingMethod for a discussion of the various rounding methods available. If the source time is non-numeric (ie. infinite, indefinite, invalid), the result will be similarly non-numeric.

Returns: The converted result CMTime.

pub unsafe fn add(self, rhs: CMTime) -> CMTime

Returns the sum of two CMTimes.

If the operands both have the same timescale, the timescale of the result will be the same as the operands’ timescale. If the operands have different timescales, the timescale of the result will be the least common multiple of the operands’ timescales. If that LCM timescale is greater than kCMTimeMaxTimescale, the result timescale will be kCMTimeMaxTimescale, and default rounding will be applied when converting the result to this timescale.

If the result value overflows, the result timescale will be repeatedly halved until the result value no longer overflows. Again, default rounding will be applied when converting the result to this timescale. If the result value still overflows when timescale == 1, then the result will be either positive or negative infinity, depending on the direction of the overflow.

If any rounding occurs for any reason, the result’s kCMTimeFlags_HasBeenRounded flag will be set. This flag will also be set if either of the operands has kCMTimeFlags_HasBeenRounded set.

If either of the operands is invalid, the result will be invalid.

If the operands are valid, but just one operand is infinite, the result will be similarly infinite. If the operands are valid, and both are infinite, the results will be as follows:

+infinity + +infinity == +infinity
• -infinity + -infinity == -infinity
• +infinity + -infinity == invalid
• -infinity + +infinity == invalid

If the operands are valid, not infinite, and either or both is indefinite, the result will be indefinite.

If the two operands are numeric (ie. valid, not infinite, not indefinite), but have different nonzero epochs, the result will be invalid. If they have the same nonzero epoch, the result will have epoch zero (a duration). Times in different epochs cannot be added or subtracted, because epoch length is unknown. Times in epoch zero are considered to be durations and can be added to times in other epochs. Times in different epochs can be compared, however, because numerically greater epochs always occur after numerically lesser epochs.

Returns: The sum of the two CMTimes (lhs + rhs).

pub unsafe fn subtract(self, rhs: CMTime) -> CMTime

Returns the difference of two CMTimes.

If the operands both have the same timescale, the timescale of the result will be the same as the operands’ timescale. If the operands have different timescales, the timescale of the result will be the least common multiple of the operands’ timescales. If that LCM timescale is greater than kCMTimeMaxTimescale, the result timescale will be kCMTimeMaxTimescale, and default rounding will be applied when converting the result to this timescale.

If the result value overflows, the result timescale will be repeatedly halved until the result value no longer overflows. Again, default rounding will be applied when converting the result to this timescale. If the result value still overflows when timescale == 1, then the result will be either positive or negative infinity, depending on the direction of the overflow.

If any rounding occurs for any reason, the result’s kCMTimeFlags_HasBeenRounded flag will be set. This flag will also be set if either of the operands has kCMTimeFlags_HasBeenRounded set.

If either of the operands is invalid, the result will be invalid.

If the operands are valid, but just one operand is infinite, the result will be similarly infinite. If the operands are valid, and both are infinite, the results will be as follows:

+infinity - +infinity == invalid
• -infinity - -infinity == invalid
• +infinity - -infinity == +infinity
• -infinity - +infinity == -infinity

If the operands are valid, not infinite, and either or both is indefinite, the result will be indefinite.

If the two operands are numeric (ie. valid, not infinite, not indefinite), but have different nonzero epochs, the result will be invalid. If they have the same nonzero epoch, the result will have epoch zero (a duration). Times in different epochs cannot be added or subtracted, because epoch length is unknown. Times in epoch zero are considered to be durations and can be subtracted from times in other epochs. Times in different epochs can be compared, however, because numerically greater epochs always occur after numerically lesser epochs.

Returns: The difference of the two CMTimes (lhs - rhs).

pub unsafe fn multiply(self, multiplier: i32) -> CMTime

Returns the product of a CMTime and a 32-bit integer.

The result will have the same timescale as the CMTime operand. If the result value overflows, the result timescale will be repeatedly halved until the result value no longer overflows. Again, default rounding will be applied when converting the result to this timescale. If the result value still overflows when timescale == 1, then the result will be either positive or negative infinity, depending on the direction of the overflow.

If any rounding occurs for any reason, the result’s kCMTimeFlags_HasBeenRounded flag will be set. This flag will also be set if the CMTime operand has kCMTimeFlags_HasBeenRounded set.

If the CMTime operand is invalid, the result will be invalid.

If the CMTime operand is valid, but infinite, the result will be infinite, and of an appropriate sign, given the signs of both operands.

If the CMTime operand is valid, but indefinite, the result will be indefinite.

Returns: The product of the CMTime and the 32-bit integer.

pub unsafe fn multiply_by_float64(self, multiplier: f64) -> CMTime

Returns the product of a CMTime and a 64-bit float.

The result will initially have the same timescale as the CMTime operand. If the result timescale is less than 65536, it will be repeatedly doubled until it is at least 65536. If the result value overflows, the result timescale will be repeatedly halved until the result value no longer overflows. Again, default rounding will be applied when converting the result to this timescale. If the result value still overflows when timescale == 1, then the result will be either positive or negative infinity, depending on the direction of the overflow.

If any rounding occurs for any reason, the result’s kCMTimeFlags_HasBeenRounded flag will be set. This flag will also be set if the CMTime operand has kCMTimeFlags_HasBeenRounded set.

If the CMTime operand is invalid, the result will be invalid.

If the CMTime operand is valid, but infinite, the result will be infinite, and of an appropriate sign, given the signs of both operands.

If the CMTime operand is valid, but indefinite, the result will be indefinite.

Returns: The product of the CMTime and the 64-bit float.

pub unsafe fn multiply_by_ratio(self, multiplier: i32, divisor: i32) -> CMTime

Returns the result of multiplying a CMTime by an integer, then dividing by another integer.

The exact rational value will be preserved, if possible without overflow. If an overflow would occur, a new timescale will be chosen so as to minimize the rounding error. Default rounding will be applied when converting the result to this timescale. If the result value still overflows when timescale == 1, then the result will be either positive or negative infinity, depending on the direction of the overflow.

If any rounding occurs for any reason, the result’s kCMTimeFlags_HasBeenRounded flag will be set. This flag will also be set if the CMTime operand has kCMTimeFlags_HasBeenRounded set.

If the denominator, and either the time or the numerator, are zero, the result will be kCMTimeInvalid. If only the denominator is zero, the result will be either kCMTimePositiveInfinity or kCMTimeNegativeInfinity, depending on the signs of the other arguments.

If time is invalid, the result will be invalid. If time is infinite, the result will be similarly infinite. If time is indefinite, the result will be indefinite.

Returns: (time * multiplier) / divisor

pub unsafe fn compare(self, time2: CMTime) -> i32

Returns the numerical relationship (-1 = less than, 1 = greater than, 0 = equal) of two CMTimes.

If the two CMTimes are numeric (ie. not invalid, infinite, or indefinite), and have different epochs, it is considered that times in numerically larger epochs are always greater than times in numerically smaller epochs.

Since this routine will be used to sort lists by time, it needs to give all values (even invalid and indefinite ones) a strict ordering to guarantee that sort algorithms terminate safely. The order chosen is somewhat arbitrary:

-infinity < all finite values < indefinite < +infinity < invalid

Invalid CMTimes are considered to be equal to other invalid CMTimes, and greater than any other CMTime. Positive infinity is considered to be less than any invalid CMTime, equal to itself, and greater than any other CMTime. An indefinite CMTime is considered to be less than any invalid CMTime, less than positive infinity, equal to itself, and greater than any other CMTime. Negative infinity is considered to be equal to itself, and less than any other CMTime.

-1 is returned if time1 is less than time2. 0 is returned if they are equal. 1 is returned if time1 is greater than time2.

Returns: The numerical relationship of the two CMTimes (-1 = less than, 1 = greater than, 0 = equal).

pub unsafe fn minimum(self, time2: CMTime) -> CMTime

Returns the lesser of two CMTimes (as defined by CMTimeCompare).

Returns: The lesser of the two CMTimes.

pub unsafe fn maximum(self, time2: CMTime) -> CMTime

Returns the greater of two CMTimes (as defined by CMTimeCompare).

Returns: The greater of the two CMTimes.

pub unsafe fn absolute_value(self) -> CMTime

Returns the absolute value of a CMTime.

Returns: Same as the argument time, with sign inverted if negative.

pub unsafe fn as_dictionary( self, allocator: Option<&CFAllocator>, ) -> Option<CFRetained<CFDictionary>>

Returns a CFDictionary version of a CMTime.

This is useful when putting CMTimes in CF container types.

Returns: A CFDictionary version of the CMTime.

pub unsafe fn from_dictionary( dictionary_representation: Option<&CFDictionary>, ) -> CMTime

Reconstitutes a CMTime struct from a CFDictionary previously created by CMTimeCopyAsDictionary.

This is useful when getting CMTimes from CF container types. If the CFDictionary does not have the requisite keyed values, an invalid time is returned.

Returns: The created CMTime.

Safety

dictionary_representation generics must be of the correct type.

impl CMTime

pub unsafe fn description( allocator: Option<&CFAllocator>, time: CMTime, ) -> Option<CFRetained<CFString>>

Creates a CFString with a description of a CMTime (just like CFCopyDescription).

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

Returns: The created CFString description.

pub unsafe fn show(self)

Prints a description of the CMTime (just like CFShow).

This is most useful from within gdb.

impl CMTime

pub unsafe fn map_time_from_range_to_range( self, from_range: CMTimeRange, to_range: CMTimeRange, ) -> CMTime

Available on crate feature CMTimeRange only.

Translates a time through a mapping from CMTimeRange to CMTimeRange.

Returns: A CMTime structure representing the translated time.

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.

pub unsafe fn clamp_to_range(self, range: CMTimeRange) -> CMTime

Available on crate feature CMTimeRange only.

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

Returns: A CMTime structure inside the given time range.

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,

pub unsafe fn map_duration_from_range_to_range( self, from_range: CMTimeRange, to_range: CMTimeRange, ) -> CMTime

Available on crate feature CMTimeRange only.

Translates a duration through a mapping from CMTimeRange to CMTimeRange.

Returns: A CMTime structure representing the translated duration.

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.

pub unsafe fn fold_into_range(self, fold_range: CMTimeRange) -> CMTime

Available on crate feature CMTimeRange only.

Folds a time into the given range. This can be used in looping time calculations.

Returns: A CMTime structure representing the translated duration.

Note that for certain types of looping, you may want to NOT fold times that are prior to the loop range. That’s up to the client.

Trait Implementations

impl Clone for CMTime

fn clone(&self) -> CMTime

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CMTime

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Encode for CMTime

Available on crate feature objc2 only.

const ENCODING: Encoding

The Objective-C type-encoding for this type.

impl PartialEq for CMTime

fn eq(&self, other: &CMTime) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl RefEncode for CMTime

Available on crate feature objc2 only.

const ENCODING_REF: Encoding

The Objective-C type-encoding for a reference of this type.

impl Copy for CMTime

impl StructuralPartialEq for CMTime