Section 7 - Adding Custom Curve I/O Handling

Through the curve editor, you can read and/or write custom curve formats with RAYZ. These are accessed via the right mouse button while in the curve editor.

To add a new curve type, you need to define a RPI_CurveIOInfo structure, which looks like:

static RPI_CurveIOInfo curveinfo = {
    {
        "internal name",       // name used to register this plugin
        "Menu Name",           // name user sees in browser menu
        "author",              // author's name - not currently used
        "version"              // version - not currently used
        "help URL",            // not used
        "icon name",           // not used
    };
    Init,                      // initialize the plugin on RAYZ startup
    ShutDown,                  // clean up before RAYZ exit
    OpenForImport,             // validate file before reading
    Import,                    // read file and convert to RAYZ format
    OpenForExport,             // prepare file for writing
    Export,                    // write file to new format
    Close,                     // close file
    Extensions                 // which suffixes denote this format
};
This structure is defined in include/CPI/CPI_CurveIOProvider.h

Let's look at each of the fields in this structure:

Init - This is called once when RAYZ starts up. It initializes the plugin. If you were going to create any local tables, for example, this would be the place to do that. The function should return CPI_TRUE if there is no error. This routine is optional.

ShutDown - This is called once when RAYZ exits. It should return CPI_TRUE if there was no error. This routine is optional.

OpenForImport - When the user is browsing for a curve to read in, and clicks on a specific file, this function is called with that file as input. The function should validate the file - that is, make sure that it is one that matches the format the user is attempting to read. It should also generate a list of the curves which are present in the file, so that the browser can display them to the user from within the browser.

The signature for the OpenForImport function is the following:

CPI_PrivateData
BoujouOpenImport( const CPI_Metadata   meta,
                  CPI_CurveIDList      curves )
The metadata will contain the information necessary to open the file, and the 'curves' parameter will be modified to contain the names of all curves found in the file. This is accomplished with the cpiAddCurveIDToList( ) function. New names are added like this:
cpiAddCurveIDToList( curves, temp );
where 'temp' is a character array containing the name of the new curve. See the included examples for more details.

In both of the supplied examples, the import function actually does much more than this; it goes ahead and reads in the contents of the file, converting them to named arrays of floating point values, one per frame per curve. These are then used in the Import function to generate the actual RAYZ curve data.

Import - This is called to actually read in a curve and convert it to RAYZ internal format. Apart from a pointer to the programmer's local data, a curve name is passed in, and this is the curve which should be returned. The curve is returned as a block of ascii text which corresponds exactly to the format of a curve as seen in a .rayz file. This text block will be allocated in the Import function and returned as a pointer to the text.

The function signature looks like this:

char *
BoujouImport( CPI_PrivateData    handle,
              const char        *curveName )
Most curve data which is being read into RAYZ will be in the form of a single value per frame. The internal RAYZ format for that looks like this:
constant value@frame linear value@frame ...  linear value@frame constant;
Note the word 'constant' starts and ends such a set of values, and note the closing semi-colon. Either of the supplied examples clearly shows a string like this being created.

If you are trying to import a curve to look like some other form of RAYZ format, for example using bezier or cubic interpolation between keyframe values, the best way to proceed is to create a curve in RAYZ that looks like what you are trying to achieve, and then save the session in a .rayz file. Then examine the contents of the file to see what your result should look like.

OpenForExport - This function looks like this:

CPI_PrivateData
RayzCurveOpenForExport( const CPI_Metadata   meta,
                        CPI_CurveIDList      curves )
and should open the file described in the metadata, and possibly write any header which the format requires. The return value is a pointer to a private data structure which will be used to export the curves.

Export - The signature for this is:

CPI_Bool
RayzCurveExport( CPI_PrivateData     handle,
                 const char         *curveName,
                 const char         *curveString )
This actually writes the named curve, using the data in the curveString parameter. This string will be in the normal RAYZ curve format, which is the same seen in a .rayz file. There is currently no way to query this string for a value at a specific frame, which is why there is currently no mechanism for writing out a "raw" (one value per frame) version of an internal RAYZ curve.

Close - This closes the file and, most importantly, gives back any memory allocated in the importing or exporting functions.

Extensions - This is a string of one or more file suffixes which indicate that a file is in your new format. The '.' character should be omitted, and multiple suffixes should be separated by a semi-colon (;). For example, Maya creates files called "something.mov", so to filter for those, you would define the extension as "mov" (quotes should be included).

Typically, the programmer defines a structure or set of structures into which the incoming curve information will be decoded and stored. These global structures can be passed around via the "handle" mechanism of the Import and Export functions. The supplied examples for the Boujou and Maya curve importers show this.

Adding the plugin to the Curve Browser Menu

When the .so file is installed in the appropriate plugins directory, the plugin will be loaded at RAYZ startup, and loaded into the Curve Browser menu automatically.


[Previous Page] [Next Page]
[Table of Contents] [Index]

Copyright © 2002 Silicon Grail Inc.
736 Seward Street, Hollywood, CA 90038