MTime Class Reference
[OpenMaya - API module for common classes]

#include <MTime.h>

List of all members.


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, simpleEmitter.cpp, simpleEmitter.h, simpleFluidEmitter.cpp, spiralAnimCurveCmd.cpp, sweptEmitter.cpp, sweptEmitter.h, testNucleusNode.cpp, and XmlGeometryCache.cpp.


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 ()
  MTime (const MTime &)
  MTime (double time_val, Unit=kFilm)
  ~MTime ()
Unit  unit () const
double  value () const
MStatus  setUnit (Unit new_unit)
MStatus  setValue (double new_value)
double  as (Unit other_unit) const
double  asUnits (Unit other_unit) const
MTime operator= (const MTime &rhs)
bool  operator== (const MTime &rhs) const
bool  operator!= (const MTime &rhs) const
bool  operator<= (const MTime &rhs) const
bool  operator>= (const MTime &rhs) const
bool  operator< (const MTime &rhs) const
bool  operator> (const MTime &rhs) const
MTime  operator+ (const MTime &rhs) const
MTime operator+= (const MTime &rhs)
MTime  operator+ (double rhs) const
MTime operator+= (double rhs)
MTime  operator- (const MTime &rhs) const
MTime operator-= (const MTime &rhs)
MTime  operator- (double rhs) const
MTime operator-= (double rhs)
MTime  operator* (double rhs) const
MTime operator*= (double rhs)
MTime  operator/ (double rhs) const
MTime operator/= (double rhs)
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 ()
static MStatus  setUIUnit (Unit new_unit)

Friends

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

Member Enumeration Documentation

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::MTime (  ) 

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

MTime::MTime ( const MTime src  ) 

Copy Constructor.

Parameters:
[in]  src  the instance to copy

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

MTime::~MTime (  ) 

The class destructor.


Member Function Documentation

MTime::Unit MTime::unit (  )  const

Returns the current units in effect for this instance.

Returns:
An element of the MTime::Unit enum

double MTime::value (  )  const

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

Returns:
The current time value
Examples:

MStatus MTime::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 MTime::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:

double MTime::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]  newUnit  an element of the MTime::Unit enum
Returns:
The current time value in the given units
Examples:

double MTime::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

MTime::Unit MTime::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:

MStatus MTime::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:

MTime & MTime::operator= ( const MTime rhs  ) 

Assignment operator.

bool MTime::operator== ( const MTime rhs  )  const

Equality operator.

bool MTime::operator!= ( const MTime rhs  )  const

InEquality operator.

bool MTime::operator<= ( const MTime rhs  )  const

Less than or equal to operator.

bool MTime::operator>= ( const MTime rhs  )  const

Greater than or equal to operator.

bool MTime::operator< ( const MTime rhs  )  const

Less than operator.

bool MTime::operator> ( const MTime rhs  )  const

Greater than operator.

MTime MTime::operator+ ( const MTime rhs  )  const

Addition operator. The units of the returned MTime instance are those of the left hand argument to the + operator.

MTime & MTime::operator+= ( const MTime rhs  ) 

In place addition operator.

MTime MTime::operator+ ( double  rhs  )  const

Addition operator by 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.

MTime & MTime::operator+= ( double  rhs  ) 

In place addition operator by 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.

MTime MTime::operator- ( const MTime rhs  )  const

Subtraction operator. The units of the returned MTime instance are those of the left hand argument to the - operator.

MTime & MTime::operator-= ( const MTime rhs  ) 

In place subtraction operator.

MTime MTime::operator- ( double  rhs  )  const

Subtraction operator by 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.

MTime & MTime::operator-= ( double  rhs  ) 

In place Subtraction operator by 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.

MTime 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 & 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 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 & 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 & MTime::operator++ (  ) 

NO SCRIPT SUPPORT.

Prefix increment operator.

MTime & MTime::operator++ ( int  dTime  ) 

NO SCRIPT SUPPORT.

Postfix increment operator.

Parameters:
[in]  dTime  dummy argument to differentiate the prefix and postfix operators.

MTime & MTime::operator-- (  ) 

NO SCRIPT SUPPORT.

Prefix decrement operator.

MTime & MTime::operator-- ( int  dTime  ) 

NO SCRIPT SUPPORT.

Postfix decrement operator.

Parameters:
[in]  dTime  dummy argument to differentiate the prefix and postfix operators.

Friends And Related Function Documentation

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

NO SCRIPT SUPPORT.

Print the contents of the given MTime on the given ostream. 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.

Autodesk® Maya® 2011 © 1997-2010 Autodesk, Inc. All rights reserved. Generated with doxygen 1.5.6