CPI Routine Reference
Functions provided in order to get information to and from
Chalice. These are all compiled into libcpi.a, which is provided.
The routines are divided into the following areas:
cpiAddTab
=========
void cpiAddTab( char *label )
Description:
This function is called from upiCreateParameters to add a
tab to the plugin's node panel. If the plugin has parameters,
this should be the first function to be called. All other
parameters will be ignored until there is a tab to put them
on.
cpiAddInteger
=============
void cpiAddInteger( char *label, int def,
int min, int max, int flags )
Description:
This function will add an integer parameter to the plugin.
"def" is the default value. If flags is set to P_MIN and/or
P_MAX, the min and max are enforced. Otherwise, they are
simply used to provide a reasonable range on the slider.
cpiAddFloat
===========
void cpiAddFloat( char *label, float def,
float min, float max, int flags )
Description:
This function will add a float parameter to the plugin.
"def" is the default value. If flags is set to P_MIN and/or
P_MAX, the min and max are enforced. Otherwise, they are
simply used to provide a reasonable range on the slider.
cpiAddIntVector
===============
void cpiAddIntVector( char *label, int size, int *def,
int min, int max, int flags )
Description:
This function will add an integer vector parameter to the plugin.
"def" is an array of default values. If flags is set to P_MIN and/or
P_MAX, the min and max are enforced. Otherwise, they are
simply used to provide a reasonable range on the slider.
cpiAddFloatVector
=================
void cpiAddFloatVector( char *label, int size, float *def,
float min, float max, int flags )
Description:
This function will add a vector of float parameters to the plugin.
"def" is an array of default values. If flags is set to P_MIN and/or
P_MAX, the min and max are enforced. Otherwise, they are
simply used to provide a reasonable range on the slider.
cpiAddString
============
void cpiAddString( char *label, char *def, int flags )
Description:
This function will add a float parameter to the plugin.
"def" is the default value.
cpiAddFile
==========
void cpiAddFile( char *label, char *def, int flags )
Description:
This function will add a file parameter to the plugin.
"def" is the default value.
cpiAddPicFile
=============
void cpiAddPicFile( char *label, char *def, int flags )
Description:
This function will add a picture file parameter to the plugin.
"def" is the default value.
cpiAddMenu
==========
void cpiAddMenu( char *label, int def, char *menu[], int flags )
Description:
This function will add a menu parameter to the plugin.
"def" is the default value. The "menu" parameter is an array
of strings, which must be NULL terminated.
cpiEnableParameter
==================
void cpiEnableParameter( char *name, int onoff )
Description:
This function will disable or enable a parameter. If a
parameter is disabled, it will appear "greyed out" to the user.
The parameter meter will be enabled or disabled depending on
whether the onoff argument is true or false ( 1 or 0 ).
cpiSetInteger
=============
int cpiSetInteger( char *param, float time, int value )
Description:
Sets the named integer parameter to be the passed value at the
time specified. If the parameter is not an animated channel, the
value will be set at every frame. If it is animated, a keyframe with
the value will be generated at the time given. If there is already a
keyframe there, it will be left there, and its value changed.
cpiSetFloat
=============
int cpiSetFloat( char *param, float time, float value )
Description:
Sets the named float parameter to be the passed value at the
time specified. If the parameter is not an animated channel, the
value will be set at every frame. If it is animated, a keyframe with
the value will be generated at the time given. If there is already a
keyframe there, it will be left there, and its value changed.
cpiSetIntVector
=============
int cpiSetIntVector( char *param, float time, unsigned int
vector, int value )
Description:
Sets the named int vector parameter to be the passed value at
the time specified. The vector parameter specifies the index of the
vector to be changed; eg, 0 indicates the first value of a 3 element
vector.
If the parameter is not an animated channel, the value will
be set at every frame. If it is animated, a keyframe with the value
will be generated at the time given. If there is already a keyframe
there, it will be left there, and its value changed.
cpiSetFloatVector
=============
int cpiSetFloatVector( char *param, float time, unsigned int
vector, float value )
Description:
Sets the named float vector parameter to be the passed value at
the time specified. The vector parameter specifies the index of the
vector to be changed; eg, 0 indicates the first value of a 3 element
vector.
If the parameter is not an animated channel, the value will
be set at every frame. If it is animated, a keyframe with the value
will be generated at the time given. If there is already a keyframe
there, it will be left there, and its value changed.
cpiSetString
=============
int cpiSetString( char *param, char *buffer )
Description:
Sets the named string parameter to be the passed buffer.
Strings do not animate, though they can be changed every frame.
cpiSetFrameRange
================
int cpiSetFrameRange( long start, long end )
Description:
Sets the frame range for the current plugin. This would be
relevant if the plugin changed the incoming frame range in some
way; 3:2 Pulldown, for example, does this. Returns 0 if no error.
cpiInputFrameRange
==================
int cpiInputFrameRange( int input, long *start, long *end )
Description:
This returns the frame range of the given input to the plugin,
where 0 is the first input, 1 is the second, etc. This would be used
to make sure that the node does not request frames that are not going
to be available. Returns 0 if no error.
cpiInputContext
============
int cpiInputContext( unsigned int input, CPI_ImageContext *info,
float time )
Description:
This will return information about the requested input. This
function is typically used in upiOutputContext to retrieve information
about the inputs and calculate the output.
cpiNumberOfInputs
============
int cpiNumberOfInputs(void)
Description:
This will return the number of inputs currently connected to the
node.
cpiGetInteger
=============
int cpiGetInteger( char *param, float time, int *value )
Description:
This function is used to get the value of an integer parameter.
The same name that was used in upiCreateParameters should be
used at the "param" argument.
Returns 0 unless an error occured.
cpiGetFloat
===========
int cpiGetFloat( char *param, float time, float *value )
Description:
This function is used to get the value of an float parameter.
The same name that was returned from upiCreateParameters should be
used at the "param" argument.
Returns 0 unless an error occured.
cpiGetIntVector
===============
int cpiGetIntVector( char *param, float time,
unsigned int vector, int *value )
Description:
This function is used to get the value of an integer parameter.
The same name that was used in upiCreateParameters should be
used at the "param" argument.
Returns 0 unless an error occured.
cpiGetFloatVector
=================
int cpiGetFloatVector( char *param, float time,
unsigned int vector, float *value )
Description:
This function is used to get the value of an float parameter.
The same name that was returned from upiCreateParameters should be
used at the "param" argument.
Returns 0 unless an error occured.
cpiGetFrame
===========
int cpiGetFrame( float time )
Description:
Returns the frame value of the given time (in seconds).
cpiGetTime
==========
float cpiGetTime( int frame )
Description:
Returns the time (in seconds) of the given frame.
cpiGetNodeName
==============
void cpiGetNodeName( char *name )
Description:
Fills name array with the node name.
cpiGetByteSize
==============
int cpiGetByteSize( CPI_PelType pel )
Description:
Returns the size in bytes of the passed element type; eg
cpiGetByteSize(INT_8) returns 1.
cpiCookRegion
=============
void cpiCookRegion( int region, CPI_Image *image)
Description:
Asks Chalice to provide the image attached to the requested region.
Regions are numbered from 0.
cpiFreeRegion
=============
void cpiFreeRegion( int region, CPI_Image *image)
Description:
Tells Chalice to return the passed image memory to the system. The
region number is the input region number as defined by upiRegionsNeeded.
cpiInvalidateOutput
===================
void cpiInvalidateOutput( void )
Description:
Chalice will cache the information returned by upiGetOutputContext.
This is done for performance reasons. This cache is automatically
invalidated when one of the plugin's input changes. However the
plugin may need to change its output information (size, depth)
internally (such as during a parameter change). When ever the
plugin changes the output size, cpiInvalidateOutput should be
called to let Chalice know.
cpiNeedRegion
============
void cpiNeedRegion( CPI_ImageContext *input )
Description:
This function can only be called from upiRegionsNeeded.
It should be called once for each input (or part thereof)
needed by the plugin.
cpiChalicePath
==============
void cpiChalicePath( char *path )
Description:
Fills path with the chalice root directory. path should
be an array of size CPI_PATH_LENGTH.
cpiPluginPath
=============
void cpiPluginPath( char *path )
Description:
Fills path with the path from which the plugin was loaded.
path should be an array of size CPI_PATH_LENGTH.
cpiUserPath
==============
void cpiUserPath( char *path )
Description:
Fills path with the user's home directory. path should
be an array of size CPI_PATH_LENGTH.
cpiTmpPath
==============
void cpiTmpPath( char *path )
Description:
Fills path with the chalice temporary directory. path
should be an array of size CPI_PATH_LENGTH.
cpiError
========
void cpiError( char *fmt, ... )
Description:
This will send a text error message to Chalice. It uses a
printf style message. Call this function with an error message
when returning an error value. Chalice will display this error
to the user. This will interrupt the cooking process.
This can only be called from the cooking function. It cannot
be called during the initialization phase.
cpiWarning
==========
void cpiWarning( char *fmt, ... )
Description:
Similar to the above, except only a warning is generated.
This means the cooking process will continue, and the warning
message will be displayed to the user. As with cpiError, this
function cannot be called during the initialization phase.
cpiMultiProcess
===============
void cpiMultiProcess(void (*func)(int, int, void *), void *arg)
Description:
This function will call "func" once per processor, giving
multi-threaded capabilities to plugins. "arg" can be any arbitrary
pointer, which gets passed to "func". The declaration of func should
be:
void func( int proc, int numproc, void *arg );
"proc" is the current processor (numbered 0 to numproc-1). "numproc"
is the number of processors available. "arg" is the same as was
passed to cpiMultiProcess.
cpiNumProcessors
================
int cpiNumProcessors( void )
Description:
Returns the number of available processors.
[Previous Page]
[Next Page]
[Table of Contents]
[Index]
Copyright © 1998 Silicon Grail Inc.
710 Seward Street, Hollywood, CA 90038