MTime Class Reference
 
 
 

#include <MTime.h>


Class 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:

AbcExport/AbcExport.cpp, AbcExport/MayaCameraWriter.cpp, AbcExport/MayaPointPrimitiveWriter.cpp, AbcExport/MayaUtility.cpp, AbcImport/AbcImport.cpp, AbcImport/AlembicNode.cpp, AbcImport/CameraHelper.cpp, AbcImport/NodeIteratorVisitorHelper.cpp, AbcImport/util.cpp, animCubeNode/animCubeNode.cpp, animImportExport/animFileUtils.cpp, animInfoCmd/animInfoCmd.cpp, atomImportExport/atomAnimLayers.cpp, atomImportExport/atomAnimLayers.h, atomImportExport/atomFileUtils.cpp, atomImportExport/atomFileUtils.h, atomImportExport/atomImportExport.cpp, atomImportExport/atomImportExport.h, createClipCmd/createClipCmd.cpp, gpuCache/gpuCacheCmd.cpp, gpuCache/gpuCacheCmd.h, gpuCache/gpuCacheGeometry.h, gpuCache/gpuCacheGeometryOverride.cpp, gpuCache/gpuCacheGeometryOverride.h, gpuCache/gpuCacheMaterialBakers.cpp, gpuCache/gpuCacheMaterialBakers.h, gpuCache/gpuCacheSubSceneOverride.cpp, latticeNoise/latticeNoiseNode.cpp, motionPathCmd/motionPathCmd.cpp, motionTraceCmd/motionTraceCmd.cpp, ownerEmitter/ownerEmitter.cpp, ownerEmitter/ownerEmitter.h, particlePathsCmd/particlePathsCmd.cpp, renderViewInteractiveRenderCmd/renderViewInteractiveRenderCmd.cpp, simpleEmitter/simpleEmitter.cpp, simpleEmitter/simpleEmitter.h, simpleFluidEmitter/simpleFluidEmitter.cpp, spiralAnimCurveCmd/spiralAnimCurveCmd.cpp, sweptEmitter/sweptEmitter.cpp, sweptEmitter/sweptEmitter.h, testNsolverNode/testNsolverNode.cpp, testNucleusNode/testNucleusNode.cpp, XmlGeometryCache/XmlGeometryCache.cpp, and XmlGeometryCacheDesc/XmlGeometryCacheDesc.cpp.

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.
MTime operator= (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.
MTime operator+= (const MTime &rhs)
  In-place addition with another MTime.
MTime  operator+ (double rhs) const
  Addition with a double.
MTime operator+= (double rhs)
  In-place addition with a double.
MTime  operator- (const MTime &rhs) const
  Subtraction of another MTime.
MTime operator-= (const MTime &rhs)
  In-place subtraction of another MTime.
MTime  operator- (double rhs) const
  Subtraction of a double.
MTime operator-= (double rhs)
  In-place Subtraction of a double.
MTime  operator* (double rhs) const
  Multiplication by a scalar operator.
MTime operator*= (double rhs)
  In place multiplication by a scalar operator.
MTime  operator/ (double rhs) const
  Division by a scalar operator.
MTime operator/= (double rhs)
  In place division by a scalar operator.
MTime operator++ ()
  NO SCRIPT SUPPORT.
MTime operator++ (int)
  NO SCRIPT SUPPORT.
MTime operator-- ()
  NO SCRIPT SUPPORT.
MTime operator-- (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] src the 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] newValue the initial time value, in the newUnit system
[in] newUnit the 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
Examples:
atomImportExport/atomImportExport.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] newUnit an 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] newValue The new time value.
Returns:
kSuccess if the value is set successfully, kFailure otherwise
Examples:
AbcImport/util.cpp, XmlGeometryCache/XmlGeometryCache.cpp, and XmlGeometryCacheDesc/XmlGeometryCacheDesc.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] newUnit an element of the MTime::Unit enum
Returns:
The current time value in the given units
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] newUnit an element of the MTime::Unit enum
Returns:
kSuccess if the given unit is valid, kInvalidParameter otherwise
Examples:
animImportExport/animFileUtils.cpp, atomImportExport/atomFileUtils.cpp, and atomImportExport/atomImportExport.cpp.
MTime & operator= ( const MTime rhs )

Assignment operator.

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

Equality operator.

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

InEquality operator.

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

Less than or equal to operator.

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

Greater than or equal to operator.

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

Less than operator.

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

Greater than operator.

Parameters:
[in] rhs Right 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] rhs Right 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] rhs Right 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] rhs Right 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] rhs Right 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] rhs Right 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] rhs Right 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] rhs Right 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] rhs Right 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] rhs the 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] rhs the 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] rhs the 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] rhs the scalar to multiply by.
MTime & operator++ ( )

NO SCRIPT SUPPORT.

Prefix increment operator.

MTime & operator++ ( int  dTime )

NO SCRIPT SUPPORT.

Postfix increment operator.

Parameters:
[in] dTime dummy 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] dTime dummy 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] os the ostream to print to
[in] t the MTime whose value is to be printed
Returns:
The ostream reference, os, provided as the first parameter.

The documentation for this class was generated from the following files: