Introduction to RAYZ Plugins

The RAYZ API is as wide open as it is possible for us to make it. It is our intention that sophisticated users be able to use RAYZ as a platform for all kinds of image-related tasks, not just for compositing.

To that end, users can write plugins that are:

In addition, overlays can be attached to user-built nodes, or even to existing RAYZ nodes, to add interactive functionality.

Programmers can also build up complex node operations by chaining together internal RAYZ Image Operations - for example, a plugin which requires image scaling and rotation can use the internal routines for scaling and rotating its input, allowing the programmer to spend time on the parts of the plugin which are unique and interesting.

Finally, RAYZ plugins can read values from, and write values to, the user Preferences. And the plugins can create new Preferences for users to have access to, in order to completely customize RAYZ.

We hope the enclosed documentation and examples will allow you to push RAYZ to do the things you need; help is always available at support@sgrail.com.

Have fun.

Conventions

There are three prefixes used to name items throughout the RAYZ API. These prefixes and their meanings are given in the following table:

Prefix
Meaning
CPI Supplied by RAYZ to the Custom plugin writer
RPI Functions calls which are required - these must be defined by the programmer
UPI User supplied functions which are optional

Existing RAYZ Plugins

If you have existing RAYZ plugins written for 1.0, you will have to modify and recompile them - the next section discusses the changes necessary.


Changes From RAYZ 1.0 to RAYZ 2.0

All plugins written for RAYZ 1.0 have to be recompiled before running in RAYZ 2.0. The following is a list of differences to note when moving plugins from version 1.0 to version 2.0.

Exec function signature

In 1.0, the Exec function of a node looks like this:
CPI_ImageOp
DitherExec( CPI_Float32     myTime,
            CPI_Uint8       quality,
            CPI_Uint32      nodeOutput,
            CPI_Uint32      viewerOutput,
            CPI_Float32     scaleX,
            CPI_Float32     scaleY )
{
In 2.0, the viewerOutput parameter has changed to a Bool type. The meaning is that this variable is CPI_TRUE if the node output number refers to the node's viewerOutput number, CPI_FALSE if it refers to the node's output number. So the new signature looks like this:
CPI_ImageOp
DitherExec( CPI_Float32     myTime,
            CPI_Uint8       quality,
            CPI_Uint32      output,
            CPI_Bool        viewerOutput,
            CPI_Float32     scaleX,
            CPI_Float32     scaleY )
{

 

String Handling

In 1.0, to retrieve the value of a string from a string, text, or filename widget, the syntax was this:
CPI_Bool cpiGetString( const char   **stringval,
                       const char   *parmname,
                       CPI_Float32   evaltime );
The new syntax is the simpler
CPI_Bool cpiGetString( char         *stringval,
                       CPI_Int32     stringsize,
                       const char   *parmname,
                       CPI_Float32   evaltime );
which allows you to do something like this:
#define MAXSIZE 128
char strval[MAXSIZE];
cpiGetString( strval, MAXSIZE, "the string", myTime );

 

File Widgets

Defining a file widget in 1.0 involved setting parameter flags. This is no longer required. So the setup call now looks like:
void cpiAddFile( const char     *name,
                 const char     *label,
                 const char     *def,
                 const char     *helpText,
                 const char     *helpHTML );

 

New Functions

IsInputConnected() This allows you to check to see if an input to a node is currently connected. The syntax is
CPI_Bool    cpiIsInputConnected( CPI_Uint32 input )
IsProcessingAborted() This allows you to poll for the state of the Stop button on the interface, to see if the user has requested that processing abort early. The syntax is
CPI_Bool    cpiIsProcessingAborted( void )

 

New Flags

Parameter widgets can be initialized with several new flags, intended to make it easier to specify operations measured in pixels or in color depth. These work on Float parameters only, and they tell RAYZ to maintain the parameter internally as float, but to display it in pixels (or in color values, eg 0 - 255). The display values are based on the X or the Y size, or the color depth, depending on need. The new flags are
CPI_PARM_FULL_SIZE_X
CPI_PARM_FULL_SIZE_Y
CPI_PARM_FULL_SIZE_XY
CPI_PARM_PIXEL_VALUE

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

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