Public Types | Public Member Functions | Static Public Member Functions | Friends

MTime Class Reference

Search for all occurrences

Detailed Description

Set and retrieve animation time values in various unit systems.

The MTime class provides a fundamental type for the Maya API to hold and manipulate animation timing information in various unit systems. All API methods that require or return timing information do so through variables of this type.

If one desires to manipulate time in such a way that integer changes in an MTime instance result in integer changes in the frame displayed by the timeslider, then an MTime instance should be created that uses UI units. This can be done either by using the default constructor, or by passing the return value of the static method uiUnit to the normal constructor. Once such an MTime instance is created, its value will be equivalent to a frame on the timeslider.

It should be noted that while the timeslider displays frames, a seemingly unitless value, Maya internally is operating based on the desired frameRate (one of those specified by the MTime::Unit enum. It is necessary for the API programmer to be aware of this as MTime instances are not unitless and allow the manipulation of time in any desired units.

Examples:

animCubeNode.cpp, animFileUtils.cpp, animInfoCmd.cpp, createClipCmd.cpp, latticeNoiseNode.cpp, motionPathCmd.cpp, motionTraceCmd.cpp, ownerEmitter.cpp, ownerEmitter.h, particlePathsCmd.cpp, renderViewInteractiveRenderCmd.cpp, simpleEmitter.cpp, simpleEmitter.h, simpleFluidEmitter.cpp, spiralAnimCurveCmd.cpp, sweptEmitter.cpp, sweptEmitter.h, testNucleusNode.cpp, and XmlGeometryCache.cpp.

#include <MTime.h>

List of all members.

Public Types

enum  Unit {
  kInvalid, kHours, kMinutes, kSeconds,
  kMilliseconds, kGames, kFilm, kPALFrame,
  kNTSCFrame, kShowScan, kPALField, kNTSCField,
  k2FPS, k3FPS, k4FPS, k5FPS,
  k6FPS, k8FPS, k10FPS, k12FPS,
  k16FPS, k20FPS, k40FPS, k75FPS,
  k80FPS, k100FPS, k120FPS, k125FPS,
  k150FPS, k200FPS, k240FPS, k250FPS,
  k300FPS, k375FPS, k400FPS, k500FPS,
  k600FPS, k750FPS, k1200FPS, k1500FPS,
  k2000FPS, k3000FPS, k6000FPS, kUserDef,
  kLast
}
 

Time units.

More...

Public Member Functions

 MTime ()
 Default class constructor.
 MTime (const MTime &)
 Copy Constructor.
 MTime (double time_val, Unit=kFilm)
 Constructor that sets the current time to the given value in the given units.
 ~MTime ()
 The class destructor.
Unit unit () const
 Returns the current units in effect for this instance.
double value () const
 Returns the current time value in the units that are currently in effect for this instance.
MStatus setUnit (Unit new_unit)
 Set the current units in effect on this MTime instance.
MStatus setValue (double new_value)
 Set the current time value in the current units for this instance.
double as (Unit other_unit) const
 Returns the current time value in the given units.
double asUnits (Unit other_unit) const
 Returns the current time value in the given units.
MTimeoperator= (const MTime &rhs)
 Assignment operator.
bool operator== (const MTime &rhs) const
 Equality operator.
bool operator!= (const MTime &rhs) const
 InEquality operator.
bool operator<= (const MTime &rhs) const
 Less than or equal to operator.
bool operator>= (const MTime &rhs) const
 Greater than or equal to operator.
bool operator< (const MTime &rhs) const
 Less than operator.
bool operator> (const MTime &rhs) const
 Greater than operator.
MTime operator+ (const MTime &rhs) const
 Addition with another MTime.
MTimeoperator+= (const MTime &rhs)
 In-place addition with another MTime.
MTime operator+ (double rhs) const
 Addition with a double.
MTimeoperator+= (double rhs)
 In-place addition with a double.
MTime operator- (const MTime &rhs) const
 Subtraction of another MTime.
MTimeoperator-= (const MTime &rhs)
 In-place subtraction of another MTime.
MTime operator- (double rhs) const
 Subtraction of a double.
MTimeoperator-= (double rhs)
 In-place Subtraction of a double.
MTime operator* (double rhs) const
 Multiplication by a scalar operator.
MTimeoperator*= (double rhs)
 In place multiplication by a scalar operator.
MTime operator/ (double rhs) const
 Division by a scalar operator.
MTimeoperator/= (double rhs)
 In place division by a scalar operator.
MTimeoperator++ ()
 NO SCRIPT SUPPORT.
MTimeoperator++ (int)
 NO SCRIPT SUPPORT.
MTimeoperator-- ()
 NO SCRIPT SUPPORT.
MTimeoperator-- (int)
 NO SCRIPT SUPPORT.

Static Public Member Functions

static Unit uiUnit ()
 Returns the Working Units (or UI units) chosen in the settings of the prefs window.
static MStatus setUIUnit (Unit new_unit)
 Set the unit system to be used by the user in the UI.
static const char * className ()
 Returns the name of this class.

Friends

OPENMAYA_EXPORT std::ostream & operator<< (std::ostream &os, const MTime &t)
 NO SCRIPT SUPPORT.

Member Enumeration Documentation

enum Unit

Time units.

Enumerator:
kInvalid 

Invalid value.

kHours 

3600 seconds

kMinutes 

60 seconds

kSeconds 

1 second

kMilliseconds 

1/1000 of a second

kGames 

15 frames per second

kFilm 

24 frames per second

kPALFrame 

25 frames per second

kNTSCFrame 

30 frames per second

kShowScan 

twice the speed of film (48 frames per second)

kPALField 

twice the speed of PAL (50 frames per second)

kNTSCField 

twice the speed of NTSC (60 frames per second)

k2FPS 

2 frames per second

k3FPS 

3 frames per second

k4FPS 

4 frames per second

k5FPS 

5 frames per second

k6FPS 

6 frames per second

k8FPS 

8 frames per second

k10FPS 

10 frames per second

k12FPS 

12 frames per second

k16FPS 

16 frames per second

k20FPS 

20 frames per second

k40FPS 

40 frames per second

k75FPS 

75 frames per second

k80FPS 

80 frames per second

k100FPS 

100 frames per second

k120FPS 

120 frames per second

k125FPS 

125 frames per second

k150FPS 

150 frames per second

k200FPS 

200 frames per second

k240FPS 

240 frames per second

k250FPS 

250 frames per second

k300FPS 

300 frames per second

k375FPS 

375 frames per second

k400FPS 

400 frames per second

k500FPS 

500 frames per second

k600FPS 

600 frames per second

k750FPS 

750 frames per second

k1200FPS 

1200 frames per second

k1500FPS 

1500 frames per second

k2000FPS 

2000 frames per second

k3000FPS 

3000 frames per second

k6000FPS 

6000 frames per second

kUserDef 

user defined units (not implemented yet)

kLast 

Last value, used for counting.


Constructor & Destructor Documentation

MTime ( )

Default class constructor.

Sets the initial time to 1 (the first frame) in the UI units currently in effect.

MTime ( const MTime src)

Copy Constructor.

Parameters:
[in]srcthe instance to copy
MTime ( double  newValue,
MTime::Unit  newUnit = kFilm 
)

Constructor that sets the current time to the given value in the given units.

If the parameter, newUnit, is not specified, it defaults to kFilm (24 frames/second).

Parameters:
[in]newValuethe initial time value, in the newUnit system
[in]newUnitthe unit system to be used in this instance

Member Function Documentation

MTime::Unit unit ( ) const

Returns the current units in effect for this instance.

Returns:
An element of the MTime::Unit enum
double value ( ) const

Returns the current time value in the units that are currently in effect for this instance.

Returns:
The current time value
Examples:
animFileUtils.cpp, renderViewInteractiveRenderCmd.cpp, and testNucleusNode.cpp.
MStatus setUnit ( MTime::Unit  newUnit)

Set the current units in effect on this MTime instance.

Note that this method only changes the current units in the instance, it does not affect the value. So, calls to the value method before and after a call to setUnit will return the same number, however, the interpretation of that number will be different due to the change in unit systems.

Parameters:
[in]newUnitan element of the MTime::Unit enum
Returns:
kSuccess if the given unit is valid, kInvalidParameter otherwise
MStatus setValue ( double  newValue)

Set the current time value in the current units for this instance.

Parameters:
[in]newValueThe new time value.
Returns:
kSuccess if the value is set successfully, kFailure otherwise
Examples:
XmlGeometryCache.cpp.
double as ( MTime::Unit  newUnit) const

Returns the current time value in the given units.

This does not affect the current units for the instance.

Parameters:
[in]newUnitan element of the MTime::Unit enum
Returns:
The current time value in the given units
Examples:
animCubeNode.cpp, animFileUtils.cpp, animInfoCmd.cpp, latticeNoiseNode.cpp, ownerEmitter.cpp, simpleEmitter.cpp, and sweptEmitter.cpp.
double asUnits ( MTime::Unit  newUnit) const

Returns the current time value in the given units.

This does not affect the current units for the instance.

Parameters:
[in]newUnitan element of the MTime::Unit enum
Returns:
The current time value in the given units
MTime::Unit uiUnit ( ) [static]

Returns the Working Units (or UI units) chosen in the settings of the prefs window.

Maya's timeslider displays frames in these units.

Returns:
An element of the MTime::Unit enum
Examples:
animFileExport.cpp, animFileUtils.cpp, and animInfoCmd.cpp.
MStatus setUIUnit ( MTime::Unit  newUnit) [static]

Set the unit system to be used by the user in the UI.

After the successful completion of this method, Maya's timeslider will be displaying frames in the specified units.

Parameters:
[in]newUnitan element of the MTime::Unit enum
Returns:
kSuccess if the given unit is valid, kInvalidParameter otherwise
Examples:
animFileUtils.cpp.
MTime & operator= ( const MTime rhs)

Assignment operator.

Parameters:
[in]rhsRight operand.
bool operator== ( const MTime rhs) const

Equality operator.

Parameters:
[in]rhsRight operand.
bool operator!= ( const MTime rhs) const

InEquality operator.

Parameters:
[in]rhsRight operand.
bool operator<= ( const MTime rhs) const

Less than or equal to operator.

Parameters:
[in]rhsRight operand.
bool operator>= ( const MTime rhs) const

Greater than or equal to operator.

Parameters:
[in]rhsRight operand.
bool operator< ( const MTime rhs) const

Less than operator.

Parameters:
[in]rhsRight operand.
bool operator> ( const MTime rhs) const

Greater than operator.

Parameters:
[in]rhsRight operand.
MTime operator+ ( const MTime rhs) const

Addition with another MTime.

The value of the MTime on the right is converted to the units of the MTime on the left. The two values are added together and returned in a new MTime. Neither of the operands is changed.

Parameters:
[in]rhsRight operand.
MTime & operator+= ( const MTime rhs)

In-place addition with another MTime.

The value of the MTime on the right is converted to the units of the MTime on the left and added to it, leaving the result in the MTime on the left.

Parameters:
[in]rhsRight operand.
MTime operator+ ( double  rhs) const

Addition with a double.

The double is interpreted as a number of frames in the units of the MTime instance to the left of the + operator. Thus, to increase time by five frames in the current units, add 5 to the instance.

The result is returned in a new MTime. The MTime on the left is not modified.

Parameters:
[in]rhsRight operand.
MTime & operator+= ( double  rhs)

In-place addition with a double.

The double is interpreted as a number of frames in the units of the MTime instance. Thus, to increase time by five frames in the current units, add 5 to the instance.

The result is placed into the MTime on the left.

Parameters:
[in]rhsRight operand.
MTime operator- ( const MTime rhs) const

Subtraction of another MTime.

The MTime on the right is converted to the units of the MTime on the left and subtracted from the left's value. The result is returned in a new MTime. Neither of the two operands is modified.

Parameters:
[in]rhsRight operand.
MTime & operator-= ( const MTime rhs)

In-place subtraction of another MTime.

The MTime on the right is converted to the units of the MTime on the left and subtracted from it. The result is placed in the MTime on the left.

Parameters:
[in]rhsRight operand.
MTime operator- ( double  rhs) const

Subtraction of a double.

The double is interpreted as a number of frames in the units of the MTime instance to the left of the - operator. Thus, to decrease time by five frames in the current units, subtract 5 from the instance.

The result is returned in a new MTime. The MTime on the left is not modified.

Parameters:
[in]rhsRight operand.
MTime & operator-= ( double  rhs)

In-place Subtraction of a double.

The double is interpreted as a number of frames in the units of the MTime instance. Thus, to decrease time by five frames in the current units, subtract 5 from the instance.

The result is placed into the MTime on the left.

Parameters:
[in]rhsRight operand.
MTime operator* ( double  rhs) const

Multiplication by a scalar operator.

Multiply the instance to the left of the * operator by the given double, and assign the result to a new MTime instance.

Parameters:
[in]rhsthe scalar to multiply by.
MTime & operator*= ( double  rhs)

In place multiplication by a scalar operator.

Multiply the current instance by the given double.

Parameters:
[in]rhsthe scalar to multiply by.
MTime operator/ ( double  rhs) const

Division by a scalar operator.

Divide the instance to the left of the / operator by the given double, and assign the result to a new MTime instance.

Parameters:
[in]rhsthe scalar to divide by.
MTime & operator/= ( double  rhs)

In place division by a scalar operator.

Divide the current instance by the given double.

Parameters:
[in]rhsthe scalar to multiply by.
MTime & operator++ ( )

NO SCRIPT SUPPORT.

Prefix increment operator.

MTime & operator++ ( int  dTime)

NO SCRIPT SUPPORT.

Postfix increment operator.

Parameters:
[in]dTimedummy argument to differentiate the prefix and postfix operators.
MTime & operator-- ( )

NO SCRIPT SUPPORT.

Prefix decrement operator.

MTime & operator-- ( int  dTime)

NO SCRIPT SUPPORT.

Postfix decrement operator.

Parameters:
[in]dTimedummy argument to differentiate the prefix and postfix operators.
const char * className ( ) [static]

Returns the name of this class.

Returns:
The name of this class.

Friends And Related Function Documentation

OPENMAYA_EXPORT std::ostream& operator<< ( std::ostream &  os,
const MTime t 
) [friend]

NO SCRIPT SUPPORT.

Prints the result of a call to the value() method on the given MTime instance.

Parameters:
[in]osthe ostream to print to
[in]tthe MTime whose value is to be printed
Returns:
The ostream reference, os, provided as the first parameter.

MTime MTime MTime MTime MTime MTime MTime MTime MTime MTime
MTime MTime MTime MTime MTime MTime MTime MTime MTime MTime