MPxCacheFormat Class Reference

#include <MPxCacheFormat.h>

Class Description

CacheFormat definition.

The MPxCacheFormat class can be used to implement support for new cache file formats in Maya.

+ Examples:

Public Types

enum  FileAccessMode { kRead, kWrite, kReadWrite }
 Cache file access modes. More...
 

Public Member Functions

 MPxCacheFormat ()
 The default class constructor. More...
 
virtual ~MPxCacheFormat ()
 Class destructor. More...
 
virtual MStatus open (const MString &fileName, FileAccessMode mode)
 Attempt to open the specified cache format. More...
 
virtual void close ()
 Close the current current cache file.
 
virtual MStatus isValid ()
 Confirm whether the current cache file is valid. More...
 
virtual MStatus rewind ()
 Rewind the current cache pointer to the start of the cache. More...
 
virtual MString extension ()
 Returns the extension used by this format. More...
 
virtual MStatus readHeader ()
 Read the header from the current cache file, and store any data that may be required. More...
 
virtual MStatus writeHeader (const MString &version, MTime &startTime, MTime &endTime)
 Write the header for the current cache. More...
 
virtual void beginWriteChunk ()
 Perform any actions required prior to writing a chunk's information. More...
 
virtual void endWriteChunk ()
 Perform any actions required after writing a chunk's information.
 
virtual MStatus beginReadChunk ()
 Start the read process for this chunk. More...
 
virtual void endReadChunk ()
 End the read process for this chunk. More...
 
virtual MStatus writeTime (MTime &time)
 Write the current time to the cache. More...
 
virtual MStatus readTime (MTime &time)
 Read the current time from the cache. More...
 
virtual MStatus findTime (MTime &time, MTime &foundTime)
 Find a specific time in the cache. More...
 
virtual MStatus readNextTime (MTime &foundTime)
 Read the next time from the cache. More...
 
virtual unsigned readArraySize ()
 Read the size of an array in the cache. More...
 
virtual MStatus writeDoubleArray (const MDoubleArray &)
 Write an array of doubles to the cache. More...
 
virtual MStatus writeFloatArray (const MFloatArray &)
 Write a array of floats to the cache. More...
 
virtual MStatus writeIntArray (const MIntArray &)
 Write a array of int to the cache. More...
 
virtual MStatus writeDoubleVectorArray (const MVectorArray &array)
 Write an array of double-precision vectors to the cache. More...
 
virtual MStatus writeFloatVectorArray (const MFloatVectorArray &array)
 Write an array of single-precision vectors to the cache. More...
 
virtual MStatus writeInt32 (int)
 Write an integer to the cache. More...
 
virtual MStatus readDoubleArray (MDoubleArray &, unsigned size)
 Read an array of doubles from the cache. More...
 
virtual MStatus readFloatArray (MFloatArray &, unsigned size)
 Read an array of floats from the cache. More...
 
virtual MStatus readIntArray (MIntArray &, unsigned size)
 Read an array of ints from the cache. More...
 
virtual MStatus readDoubleVectorArray (MVectorArray &, unsigned arraySize)
 Read an array of double-precision vectors from the cache. More...
 
virtual MStatus readFloatVectorArray (MFloatVectorArray &array, unsigned arraySize)
 Read an array of single-precision vectors from the cache. More...
 
virtual int readInt32 ()
 Read an integer from the cache. More...
 
virtual MStatus writeChannelName (const MString &name)
 Write a channel to the cache. More...
 
virtual MStatus findChannelName (const MString &name)
 Seek to a specific channel in the cache. More...
 
virtual MStatus readChannelName (MString &name)
 Find the next channel name. More...
 
virtual bool handlesDescription ()
 Report whether this format handles the format description itself (usually provided by the default xml description file). More...
 
virtual MStatus readDescription (MCacheFormatDescription &description, const MString &descriptionFileLocation, const MString &baseFileName)
 Obtain the format description information. More...
 
virtual MStatus writeDescription (const MCacheFormatDescription &description, const MString &descriptionFileLocation, const MString &baseFileName)
 Store the format description information. More...
 

Static Public Member Functions

static const char * className ()
 Returns the name of this class. More...
 

Member Enumeration Documentation

Cache file access modes.

Enumerator
kRead 

read only

kWrite 

write only

kReadWrite 

read and write (e.g.

append, edit, etc.)

Constructor & Destructor Documentation

OPENMAYA_MAJOR_NAMESPACE_OPEN MPxCacheFormat ( )

The default class constructor.

Initialize the format.

~MPxCacheFormat ( )
virtual

Class destructor.

Automatically releases the associated format.

Member Function Documentation

MStatus open ( const MString fileName,
FileAccessMode  mode 
)
virtual

Attempt to open the specified cache format.

It is important that this function only return success if the cache file is definitely supported by this implementation.

Parameters
[in]fileNameName of the cache file to open
[in]modeAccess mode for the cache file
Returns
  • MS::kSuccess if the cache is supported by this implementation
  • MS::kFailure otherwise
MStatus isValid ( )
virtual

Confirm whether the current cache file is valid.

Returns
  • MS::kSuccess if the current cache file is valid
  • MS::kFailure otherwise
MStatus rewind ( )
virtual

Rewind the current cache pointer to the start of the cache.

Returns
  • MS::kSuccess if the pointer is rewound
  • MS::kFailure otherwise
MString extension ( )
virtual

Returns the extension used by this format.

This is not the same as the format's key, which is used by the plugin to identify itself.

Returns
The extension used by this format, with no leading period, e.g. "xcf" not ".xcf"
MStatus readHeader ( )
virtual

Read the header from the current cache file, and store any data that may be required.

Returns
  • MS::kSuccess current header is valid and has been read
  • MS::kFailure otherwise
MStatus writeHeader ( const MString version,
MTime startTime,
MTime endTime 
)
virtual

Write the header for the current cache.

Parameters
[in]versionMaya supplied cache version
[in]startTimestartTime for this cache, in ticks. There are 6000 ticks per second
[in]endTimeendTime for this cache, in ticks. There are 6000 ticks per second
Returns
  • MS::kSuccess if the cache's header has been written successfully
  • MS::kFailure otherwise
void beginWriteChunk ( )
virtual

Perform any actions required prior to writing a chunk's information.

A chunk contains the cache information for a specific time, and may contain multiple channels.

MStatus beginReadChunk ( )
virtual

Start the read process for this chunk.

Anything written by beginWriteChunk() should be read and validated by this method.

A chunk contains the cache information for a specific time, and may contain multiple channels.

Returns
  • MS::kSuccess if the cache's chunk information has been written successfully
  • MS::kFailure otherwise
void endReadChunk ( )
virtual

End the read process for this chunk.

Anything written by the endWriteChunk should be read and validated by this method.

Returns
  • MS::kSuccess if the cache's chunk information has been read successfully
  • MS::kFailure otherwise
MStatus writeTime ( MTime time)
virtual

Write the current time to the cache.

Parameters
[in]timeTime to write.
Returns
  • MS::kSuccess if the time is successfully written to the cache
  • MS::kFailure otherwise
MStatus readTime ( MTime time)
virtual

Read the current time from the cache.

Parameters
[out]timeCurrent time from the cache.
Returns
  • MS::kSuccess if the time is successfully read from the cache
  • MS::kFailure otherwise
MStatus findTime ( MTime time,
MTime foundTime 
)
virtual

Find a specific time in the cache.

Parameters
[in]timeTime to look for.
[out]foundTimeNearest time found.
Returns
  • MS::kSuccess if the time is successfully read from the cache
  • MS::kFailure otherwise
MStatus readNextTime ( MTime foundTime)
virtual

Read the next time from the cache.

Parameters
[out]foundTimethe time found
Returns
  • MS::kSuccess if the time is successfully read from the cache
  • MS::kFailure otherwise
unsigned readArraySize ( )
virtual

Read the size of an array in the cache.

Returns
  • MS::kSuccess if the size is successfully read from the cache
  • MS::kFailure otherwise
MStatus writeDoubleArray ( const MDoubleArray array)
virtual

Write an array of doubles to the cache.

Parameters
[in]arrayArray of values to be written.
Returns
  • MS::kSuccess if the array is successfully written to the cache
  • MS::kFailure otherwise
MStatus writeFloatArray ( const MFloatArray array)
virtual

Write a array of floats to the cache.

Parameters
[in]arrayArray of values to be written.
Returns
  • MS::kSuccess if the array is successfully written to the cache
  • MS::kFailure otherwise
MStatus writeIntArray ( const MIntArray array)
virtual

Write a array of int to the cache.

Parameters
[in]arrayArray of values to be written.
Returns
  • MS::kSuccess if the array is successfully written to the cache
  • MS::kFailure otherwise
MStatus writeDoubleVectorArray ( const MVectorArray array)
virtual

Write an array of double-precision vectors to the cache.

Parameters
[in]arrayArray of values to be written.
Returns
  • MS::kSuccess if the array is successfully written to the cache
  • MS::kFailure otherwise
MStatus writeFloatVectorArray ( const MFloatVectorArray array)
virtual

Write an array of single-precision vectors to the cache.

Parameters
[in]arrayArray of values to be written.
Returns
  • MS::kSuccess if the array is successfully written to the cache
  • MS::kFailure otherwise
MStatus writeInt32 ( int  value)
virtual

Write an integer to the cache.

Parameters
[in]valuethe value to be written
Returns
  • MS::kSuccess if the value is successfully written to the cache
  • MS::kFailure otherwise
MStatus readDoubleArray ( MDoubleArray array,
unsigned  size 
)
virtual

Read an array of doubles from the cache.

Parameters
[out]arrayArray of values read.
[in]sizeNumber of elements expected.
Returns
  • MS::kSuccess if the array is successfully read from the cache
  • MS::kFailure otherwise
MStatus readFloatArray ( MFloatArray array,
unsigned  size 
)
virtual

Read an array of floats from the cache.

Parameters
[out]arrayArray of values read.
[in]sizeNumber of elements expected.
Returns
  • MS::kSuccess if the array is successfully read from the cache
  • MS::kFailure otherwise
MStatus readIntArray ( MIntArray array,
unsigned  size 
)
virtual

Read an array of ints from the cache.

Parameters
[out]arrayArray of values read.
[in]sizeNumber of elements expected.
Returns
  • MS::kSuccess if the array is successfully read from the cache
  • MS::kFailure otherwise
MStatus readDoubleVectorArray ( MVectorArray array,
unsigned  arraySize 
)
virtual

Read an array of double-precision vectors from the cache.

Parameters
[out]arrayArray of values read.
[in]arraySizeNumber of elements expected.
Returns
  • MS::kSuccess if the array is successfully read from the cache
  • MS::kFailure otherwise
MStatus readFloatVectorArray ( MFloatVectorArray array,
unsigned  size 
)
virtual

Read an array of single-precision vectors from the cache.

Parameters
[out]arrayArray of values read.
[in]sizeNumber of elements expected.
Returns
  • MS::kSuccess if the array is successfully read from the cache
  • MS::kFailure otherwise
int readInt32 ( )
virtual

Read an integer from the cache.

Returns
The value read from the cache
MStatus writeChannelName ( const MString name)
virtual

Write a channel to the cache.

Parameters
[in]namethe channel to be written
Returns
  • MS::kSuccess if the channel is successfully written to the cache
  • MS::kFailure otherwise
MStatus findChannelName ( const MString name)
virtual

Seek to a specific channel in the cache.

Parameters
[in]namethe channel to seek
Returns
  • MS::kSuccess if the channel is found
  • MS::kFailure otherwise
MStatus readChannelName ( MString name)
virtual

Find the next channel name.

Parameters
[in]namethe name that is found
Returns
  • MS::kSuccess if there is a channel
  • MS::kFailure otherwise
bool handlesDescription ( )
virtual

Report whether this format handles the format description itself (usually provided by the default xml description file).

If the format handles the description itself, it must provide implementations of readDescription() and writeDescription().

Returns
True if this format handles the description, else false.
MStatus readDescription ( MCacheFormatDescription description,
const MString descriptionFileLocation,
const MString baseFileName 
)
virtual

Obtain the format description information.

If the format returns true for handlesDescription(), then it must implement this method. The implementation should in turn call MCacheFormatDescription::setDistribution(), setTimePerFrame(), addDescriptionInfo() and addChannel() as appropriate using the supplied description object.

In the default implementation, the xml description file is stored at descriptionFileLocation + baseFileName + ".xml"

Parameters
[out]descriptionthe description object to be set up
[in]descriptionFileLocationthe default location of the description file
[in]baseFileNamethe default file name (without extension) of the description file
Returns
  • MS::kSuccess if the description was successfully read
  • MS::kFailure otherwise
MStatus writeDescription ( const MCacheFormatDescription description,
const MString descriptionFileLocation,
const MString baseFileName 
)
virtual

Store the format description information.

If the format returns true for handlesDescription(), then it must implement this method. The implementation should in turn call MCacheFormatDescription::getDistribution(), getTimePerFrame(), getStartAndEndTimes(), getDescriptionInfo(), getNumChannels() and the various getChannelXXX() methods using the supplied description object as appropriate and store this information in such a way that it can be retrieved by readDescription().

In the default implementation, the xml description file is stored at descriptionFileLocation + baseFileName + ".xml"

Note that the plug-in is not required to store the description in a file using descriptionFileLocation and baseFileName. However, it must be able to retrieve the same description using just these strings to identify the source of the data.

Parameters
[in]descriptionthe description object that describes the format
[in]descriptionFileLocationthe default location of the description file
[in]baseFileNamethe default file name (without extension) of the description file
Returns
  • MS::kSuccess if the description was successfully read
  • MS::kFailure otherwise
const char * className ( )
static

Returns the name of this class.

Returns
The name of this class.

The documentation for this class was generated from the following files:
  • MPxCacheFormat.h
  • MPxCacheFormat.cpp