Instructions

The DLL exposes a few methods to manage the writing of cache files.
The methods looks like the following:

//initialization function to store simulation main data
void init( char *particleSysName, char *fileName, CACHEFORMAT cacheFormat,
           int numberOfElements, unsigned int fps, double start, double end,
           char *extras[], int nExtras);

// set the number of elements for each frame
void setElementsNumber(int nParticles);

// enabling of nParticles channels (position, velocity, ...), once per simulation
void enableChannel(CHANNELTYPE channelType, ENABLEDISABLED ea);

// assign values to each channel, once per frame
void assignChannelValues(CHANNELTYPE channelType, void *sourceValues);

// launch the cache writing
void mayaCache();

// close the file and free the resources
void closeMayaNCacheFile();

// abort, delete file and free the resources
void deleteFile();

// get the cache duration (in frames)
unsigned int getDuration();
// get the cache starting frame
int getStartFrame();

Initialization

First of all, you need to initialize the library, by passing the main information needed to properly write the cache file.

void init( char *particleSysName, char *fileName, CACHEFORMAT cacheFormat,
           int numberOfElements, unsigned int fps, double start, double end,
           char *extras[], int nExtras);

The variables that you need to pass are explained as follows:

  • particleSysName is a string with the name for Maya’s nParticleShape node. Normally, it’s the name of the node from which the cache was generated; here you can use it to name the destination node too.
  • fileName is a string with the destination file’s name and path (ie. C:/my_path/my_cache_file_name).
  • cacheFormat must be either ONEFILE or ONEFILEPERFRAME, according to the type of cache you want. Within the library, those format types are defined as follows:

    • // type of cache file, definitions
#define CACHEFORMAT int
#define ONEFILE 0
#define ONEFILEPERFRAME 1

  • numberOfElements is an integer for the number of particles. Please note that, by now, whenever you find the term element within the library, it is actually synonym of particle; the choice comes from the idea of a generalized version of the DLL where elements can be vertices, voxels, etc.
  • fps is an integer for the cache framerate, obviously in frames per second.
  • start is a double, stating the start time, in seconds.
  • end is a double, stating the end time, in seconds.
  • extras is a vector of strings, each of which reports extra information. These informations will be saved in the .xml file, and will be visualized in Maya, inside the cacheFile node, within the Cache Description section. Normally, the first four are defined as follows:
    • Maya file name and path, for the scene the cache was originally created from
    • Maya version
    • Cache owner
    • The string “NCloth Info for nParticleShape1:” which is Maya’s default note for every nCache; note that nParticleShape1 is normally replaced with the nParticleShape node which was cached. We replaced in the example with NCache Info for %s”,(particleSystemName).
  • nExtras is an integer, describing the length of extras strings’ vector.

Channels Setup

In order to have a channel written to the cache file, first of all it has to be enabled:

void enableChannel(CHANNELTYPE channelType, ENABLEDISABLED ea);

  • channelType must be one of the following: IDCHANNEL, COUNTCHANNEL, BIRTHTIMECHANNEL, POSITIONCHANNEL, ONEFILEPERFRAME, LIFESPANPPCHANNEL, FINALLIFESPANPPCHANNEL, VELOCITYCHANNEL, ACCELERATIONCHANNEL, WORLDPOSITIONCHANNEL, WORLDVELOCITYCHANNEL, WORLDVELOCITYINOBJECTSPACECHANNEL, MASSCHANNEL, AGECHANNEL, RGBPPCHANNEL, OPACITYPPCHANNEL, RADIUSPPCHANNEL . The channels’ names are pretty self-explanatory; for any further explanation you can refer to Maya’s Documentation. Within the library, those format types are defined as follows:

    • // type of channels, definitions
#define CHANNELTYPE int
#define IDCHANNEL 0
#define COUNTCHANNEL 1
#define BIRTHTIMECHANNEL 2
#define POSITIONCHANNEL 3
#define LIFESPANPPCHANNEL 4
#define FINALLIFESPANPPCHANNEL 5
#define VELOCITYCHANNEL 6
#define ACCELERATIONCHANNEL 7
#define WORLDPOSITIONCHANNEL 8
#define WORLDVELOCITYCHANNEL 9
#define WORLDVELOCITYINOBJECTSPACECHANNEL 10
#define MASSCHANNEL 11
#define AGECHANNEL 12
#define RGBPPCHANNEL 13
#define OPACITYPPCHANNEL 14
#define RADIUSPPCHANNEL 15

  • ea must be either ENABLED or DISABLED. Generally, channels are assumed to be disabled, if not specified otherwise. The definitions in the library are:

    • #define ENABLEDISABLED BOOL
#define ENABLED TRUE
#define DISABLED FALSE

Then, you must populate the channel with data. This is done with a method which is to be called as many times as the duration of the cache, in frames:

void assignChannelValues(CHANNELTYPE channelType, void *sourceValues);

Here you have an example of the channel values being written through this method:

assignChannelValues(COUNTCHANNEL, &count);
assignChannelValues(IDCHANNEL,id);
assignChannelValues(POSITIONCHANNEL,position);
assignChannelValues(VELOCITYCHANNEL,velocity);
assignChannelValues(BIRTHTIMECHANNEL,birthtime);
assignChannelValues(LIFESPANPPCHANNEL,lifespanPP);
assignChannelValues(FINALLIFESPANPPCHANNEL,finalLifespanPP);
assignChannelValues(RGBPPCHANNEL,color);

After that the cache writing is ready to go. Just call, for every frame you need to cache:

void mayaCache();

Free

Then close the file, free the memory:

void closeMayaNCacheFile();

… and you’re done.

Alternatively, if for any reason you come to a point where you want to abort your writing, you can call.

void deleteFile();