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

#include
<MScriptUtil.h>

Collaboration diagram for MScriptUtil:

[legend]

List of all members.

Detailed Description

Utility class for working with pointers and references in Python.

Many of Maya's API methods require that one or more of their parameters be passed as pointers or references. Their return values, too, can be pointers or references.

In Python parameters of class types are passed by reference but parameters of simple types, like integers and floats, are passed by value, making it impossible to call those API methods from Python. The MScriptUtil class bridges this gap by providing methods which return pointers to values of simple types and which can extract values from such pointers. These pointers can also be used wherever an API method requires a reference to a simple type or an array of a simple type.

For example, MTransformationMatrix::setShear() requires as its first parameter an array of three values of simple type 'double'. To call setShear() from Python requires using MScriptUtil to create the array of doubles:

  matrix = maya.OpenMaya.MTransformationMatrix()
  util = maya.OpenMaya.MScriptUtil()
  util.createFromDouble(1.0, 2.0, 3.0)
  ptr = util.asDoublePtr()
  m.setShear(ptr, maya.OpenMaya.MSpace.kObject)

Similar code is required to get the shear value using MTransformationMatrix::getShear(), but in addition MScriptUtil methods must be used to extract the returned values from the array:

  util = maya.OpenMaya.MScriptUtil()
  util.createFromDouble(0.0, 0.0, 0.0)
  ptr = util.asDoublePtr()
  matrix.getShear(ptr, maya.OpenMaya.MSpace.kObject)

  shearX = util.getDoubleArrayItem(ptr, 0)
  shearY = util.getDoubleArrayItem(ptr, 1)
  shearZ = util.getDoubleArrayItem(ptr, 2)

An MScriptUtil object keeps two sets of values internally: its initial values, and its working values. The initial values are those supplied either in the constructor or by calling one of the object's create*() methods. The working values are those to which the as*Ptr() methods return pointers.

Each time a create*() method is called it completely replaces the old initial values with the new ones. The as*() methods (asInt(), asFloat(), etc, but not the as*Ptr() methods) all return the first internal value, converted to the appropriate type.

Each time an as*Ptr() method is called it completely replaces the old working values with new ones of the requested type and initializes them from the initial values. If the type of the working values does not match that of the initial values then appropriate conversions are done. For example, if you have initialized an MScriptUtil object with four doubles via a call to createFromDouble(), then a subsequent call to asBoolPtr() will allocate space for four boolean working values and initialize them from the initial values by converting non-zero values to true and zero values to false.

The separation of initial and working values means that changes to the working values will not affect the initial values. For example, if you pass the pointer returned by asBoolPtr() to an API method which changes the working value it points to, the object's initial value will remain unchanged and its asInt() method will continue to return the same value as it did before the API call.

The number of working values returned by the as*Ptr() methods will match the number of initial values. Thus it is important that you provide a sufficient number of initial values before calling an as*Ptr() method. If no initial values are provided in the MScriptUtil constructor and none are subsequently supplied by calls to the create*() methods, then the pointers returned by the as*Ptr() methods won't have room to store even a single value, which will likely lead to errors.

As already noted, each call to one of an object's as*Ptr() methods completely replaces the old working values with new ones, thus rendering invalid any pointers previously returned by that object. This means that if you need multiple pointers for a single API call, you will need multiple MScriptUtil objects. MFnMesh::getUV() provides an example of this:

  meshFn = maya.OpenMaya.MFnMesh(node)

  u_util = maya.OpenMaya.MScriptUtil()
  u_util.createFromDouble(0.0)
  u_ptr = u_util.asFloatPtr()
  v_util = maya.OpenMaya.MScriptUtil()
  v_util.createFromDouble(0.0)
  v_ptr = v_util.asFloatPtr()

  meshFn.getUV(0, u_ptr, v_ptr)

  u = u_util.getFloat(u_ptr)
  v = v_util.getFloat(v_ptr))

When an MScriptUtil object is destroyed any pointers to its data immediately become invalid. Thus the following code will fail because the MScriptUtil objects created by getUVPtrs() will go out of scope and be destroyed when the function returns, rendering the pointers it returns invalid:

  # WRONG!
  def getUVPtrs():
      u_util = maya.OpenMaya.MScriptUtil()
      u_util.createFromDouble(0.0)
      u_ptr = u_util.asFloatPtr()
      v_util = maya.OpenMaya.MScriptUtil()
      v_util.createFromDouble(0.0)
      v_ptr = v_util.asFloatPtr()
      return [u_ptr, v_ptr]

  uvPtrs = getUVPtrs()
  meshFn.getUV(0, uvPtrs[0], uvPtrs[1])

To work, getUVPtrs() would have to preserve the MScriptUtil objects in some way, such as passing them back to the caller as well:

  # RIGHT!
  def getUVPtrs():
      u_util = maya.OpenMaya.MScriptUtil()
      u_util.createFromDouble(0.0)
      u_ptr = u_util.asFloatPtr()
      v_util = maya.OpenMaya.MScriptUtil()
      v_util.createFromDouble(0.0)
      v_ptr = v_util.asFloatPtr()
      return [(u_ptr, u_util), (v_ptr, v_util)]

  uvPtrs = getUVPtrs()
  meshFn.getUV(0, uvPtrs[0][0], uvPtrs[1][0])

This class is admittedly cumbersome to use but it provides a way of building parameters and accessing return values for methods which would not normally be accessible from Python.


Public Member Functions
	MScriptUtil ()
	~MScriptUtil ()
	MScriptUtil (int &value)
	MScriptUtil (short &value)
	MScriptUtil (float &value)
	MScriptUtil (double &value)
	MScriptUtil (unsigned int &value)
	MScriptUtil (bool &value)
	MScriptUtil (MIntArray &array)
	MScriptUtil (MDoubleArray &array)
	MScriptUtil (MUintArray &array)
	MScriptUtil (MUint64Array &array)
void	createFromInt (int x, int y=0, int z=0, int w=0)
void	createFromDouble (double x, double y=0, double z=0, double w=0)
bool	createFromList (void *pythonList, unsigned int length)
int	asInt ()
short	asShort ()
float	asFloat ()
double	asDouble ()
unsigned int	asUint ()
bool	asBool ()
int *	asIntPtr ()
short *	asShortPtr ()
float *	asFloatPtr ()
double *	asDoublePtr ()
unsigned int *	asUintPtr ()
bool *	asBoolPtr ()
char *	asCharPtr ()
unsigned char *	asUcharPtr ()
Mint2 *	asInt2Ptr ()
Mint3 *	asInt3Ptr ()
Mint4 *	asInt4Ptr ()
Mshort2 *	asShort2Ptr ()
Mshort3 *	asShort3Ptr ()
Mshort4 *	asShort4Ptr ()
Mfloat2 *	asFloat2Ptr ()
Mfloat3 *	asFloat3Ptr ()
Mfloat4 *	asFloat4Ptr ()
Mdouble2 *	asDouble2Ptr ()
Mdouble3 *	asDouble3Ptr ()
Mdouble4 *	asDouble4Ptr ()
Muint2 *	asUint2Ptr ()
Muint3 *	asUint3Ptr ()
Muint4 *	asUint4Ptr ()
Static Public Member Functions
static void	setInt (int &var, int value)
static void	setShort (short &var, int value)
static void	setFloat (float &var, double value)
static void	setDouble (double &var, double value)
static void	setUint (unsigned int &var, int value)
static void	setBool (bool &var, int value)
static void	setChar (char &var, int value)
static void	setUchar (unsigned char &var, int value)
static int	getInt (int &var)
static int	getShort (short &var)
static double	getFloat (float &var)
static double	getDouble (double &var)
static int	getUint (unsigned int &var)
static int	getBool (bool &var)
static int	getChar (char &var)
static int	getUchar (unsigned char &var)
static bool	setIntArray (int *var, unsigned int index, int value)
static bool	setShortArray (short *var, unsigned int index, int value)
static bool	setFloatArray (float *var, unsigned int index, double value)
static bool	setDoubleArray (double *var, unsigned int index, double value)
static bool	setUintArray (unsigned int *var, unsigned int index, int value)
static bool	setBoolArray (bool *var, unsigned int index, int value)
static bool	setCharArray (char *var, unsigned int index, int value)
static bool	setUcharArray (unsigned char *var, unsigned int index, int value)
static int	getIntArrayItem (int *var, unsigned int index)
static int	getShortArrayItem (short *var, unsigned int index)
static double	getFloatArrayItem (float *var, unsigned int index)
static double	getDoubleArrayItem (double *var, unsigned int index)
static int	getUintArrayItem (unsigned int *var, unsigned int index)
static int	getBoolArrayItem (bool *var, unsigned int index)
static int	getCharArrayItem (char *var, unsigned int index)
static int	getUcharArrayItem (unsigned char *var, unsigned int index)
static bool	createMatrixFromList (void *pythonList, MMatrix &matrix)
static bool	createFloatMatrixFromList (void *pythonList, MFloatMatrix &matrix)
static bool	createIntArrayFromList (void *pythonList, MIntArray &array)
static bool	createFloatArrayFromList (void *pythonList, MFloatArray &array)
static int	getInt2ArrayItem (int(*var)[2], unsigned int r, unsigned int c)
static bool	setInt2ArrayItem (int(*var)[2], unsigned int r, unsigned int c, int value)
static int	getInt3ArrayItem (int(*var)[3], unsigned int r, unsigned int c)
static bool	setInt3ArrayItem (int(*var)[3], unsigned int r, unsigned int c, int value)
static int	getInt4ArrayItem (int(*var)[4], unsigned int r, unsigned int c)
static bool	setInt4ArrayItem (int(*var)[4], unsigned int r, unsigned int c, int value)
static short	getShort2ArrayItem (short(*var)[2], unsigned int r, unsigned int c)
static bool	setShort2ArrayItem (short(*var)[2], unsigned int r, unsigned int c, short value)
static short	getShort3ArrayItem (short(*var)[3], unsigned int r, unsigned int c)
static bool	setShort3ArrayItem (short(*var)[3], unsigned int r, unsigned int c, short value)
static short	getShort4ArrayItem (short(*var)[4], unsigned int r, unsigned int c)
static bool	setShort4ArrayItem (short(*var)[4], unsigned int r, unsigned int c, short value)
static float	getFloat2ArrayItem (float(*var)[2], unsigned int r, unsigned int c)
static bool	setFloat2ArrayItem (float(*var)[2], unsigned int r, unsigned int c, float value)
static float	getFloat3ArrayItem (float(*var)[3], unsigned int r, unsigned int c)
static bool	setFloat3ArrayItem (float(*var)[3], unsigned int r, unsigned int c, float value)
static float	getFloat4ArrayItem (float(*var)[4], unsigned int r, unsigned int c)
static bool	setFloat4ArrayItem (float(*var)[4], unsigned int r, unsigned int c, float value)
static double	getDouble2ArrayItem (double(*var)[2], unsigned int r, unsigned int c)
static bool	setDouble2ArrayItem (double(*var)[2], unsigned int r, unsigned int c, double value)
static double	getDouble3ArrayItem (double(*var)[3], unsigned int r, unsigned int c)
static bool	setDouble3ArrayItem (double(*var)[3], unsigned int r, unsigned int c, double value)
static double	getDouble4ArrayItem (double(*var)[4], unsigned int r, unsigned int c)
static bool	setDouble4ArrayItem (double(*var)[4], unsigned int r, unsigned int c, double value)
static unsigned int	getUint2ArrayItem (unsigned int(*var)[2], unsigned int r, unsigned int c)
static bool	setUint2ArrayItem (unsigned int(*var)[2], unsigned int r, unsigned int c, unsigned int value)
static unsigned int	getUint3ArrayItem (unsigned int(*var)[3], unsigned int r, unsigned int c)
static bool	setUint3ArrayItem (unsigned int(*var)[3], unsigned int r, unsigned int c, unsigned int value)
static unsigned int	getUint4ArrayItem (unsigned int(*var)[4], unsigned int r, unsigned int c)
static bool	setUint4ArrayItem (unsigned int(*var)[4], unsigned int r, unsigned int c, unsigned int value)

Constructor & Destructor Documentation

MScriptUtil::MScriptUtil ( )

Default constructor. The instance is set to contain no elements.

MScriptUtil::~MScriptUtil ( )

Destructor.

MScriptUtil::MScriptUtil ( int & value )

Instantiate class with an int reference.

Parameters:

[in] value Reference to the value.

MScriptUtil::MScriptUtil ( short & value )

Instantiate class with an short reference.

Parameters:

[in] value Reference to the value.

MScriptUtil::MScriptUtil ( float & value )

Instantiate class with an float reference.

Parameters:

[in] value Reference to the value.

MScriptUtil::MScriptUtil ( double & value )

Instantiate class with an double reference.

Parameters:

[in] value Reference to the value.

MScriptUtil::MScriptUtil ( unsigned int & value )

Instantiate class with an unsigned int reference.

Parameters:

[in] value Reference to the value.

MScriptUtil::MScriptUtil ( bool & value )

Instantiate class with an bool reference.

Parameters:

[in] value Reference to the value.

MScriptUtil::MScriptUtil ( MIntArray & array )

Instantiate class with an integer array.

Parameters:

[in] array Reference to the array.

MScriptUtil::MScriptUtil ( MDoubleArray & array )

Instantiate class with an double array.

Parameters:

[in] array Reference to the array.

MScriptUtil::MScriptUtil ( MUintArray & array )

Instantiate class with an unsigned integer array.

Parameters:

[in] array Reference to the array.

MScriptUtil::MScriptUtil ( MUint64Array & array )

Instantiate class with an unsigned integer array.

Parameters:

[in] array Reference to the array.

Member Function Documentation

void MScriptUtil::createFromInt	(	int	x,
		int	y = `0`,
		int	z = `0`,
		int	w = `0`
	)

Create this object from 4 integers. Data already stored in this class will be cleared.

Parameters:

`[in]`	x	First integer value.
`[in]`	y	Second integer value.
`[in]`	z	Third integer value.
`[in]`	w	Fourth integer value.

void MScriptUtil::createFromDouble	(	double	x,
		double	y = `0`,
		double	z = `0`,
		double	w = `0`
	)

Create this object from 4 doubles. Data already stored in this class will be cleared.

Parameters:

`[in]`	x	First double value.
`[in]`	y	Second double value.
`[in]`	z	Third double value.
`[in]`	w	Fourth double value.

bool MScriptUtil::createFromList	(	void *	pythonList,
		unsigned int	length
	)

Create this object with a python list and length. For example: scriptUtil.createFromList( (1.0,3.0,5.0,7.0,8.0,10.0,33.0), 7 ) Data already stored in this class will be cleared.

int MScriptUtil::asInt ( )

Return the first item added to this object as an integer.

short MScriptUtil::asShort ( )

Return the first item added to this object as a short.

float MScriptUtil::asFloat ( )

Return the first item added to this object as a float.

double MScriptUtil::asDouble ( )

Return the first item added to this object as a double.

unsigned int MScriptUtil::asUint ( )

Return the first item added to this object as a unsigned integer.

bool MScriptUtil::asBool ( )

Return the first item added to this object as a bool.

int * MScriptUtil::asIntPtr ( )

Return an integer pointer to the data of this class.

NOTE: any previous pointer information returned by this object will be deleted.

short * MScriptUtil::asShortPtr ( )

Return a short pointer to the data of this class.

NOTE: any previous pointer information returned by this object will be deleted.

float * MScriptUtil::asFloatPtr ( )

Return a float pointer to the data of this class.

NOTE: any previous pointer information returned by this object will be deleted.

double * MScriptUtil::asDoublePtr ( )

Return a double pointer to the data of this class.

NOTE: any previous pointer information returned by this object will be deleted.

unsigned int * MScriptUtil::asUintPtr ( )

Return an unsigned integer pointer to the data of this class.

NOTE: any previous pointer information returned by this object will be deleted.

bool * MScriptUtil::asBoolPtr ( )

Return a bool pointer to the data of this class.

NOTE: any previous pointer information returned by this object will be deleted.

char * MScriptUtil::asCharPtr ( )

Return a char pointer to the data of this class.

NOTE: any previous pointer information returned by this object will be deleted.

unsigned char * MScriptUtil::asUcharPtr ( )

Return a unsigned char pointer to the data of this class.

NOTE: any previous pointer information returned by this object will be deleted.

Mint2 * MScriptUtil::asInt2Ptr ( )