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:
  • Defining a Node's Parameters
  • Setting Node Parameter Values
  • Returning Values from Nodes
  • Setting Path Variables
  • Error Handling
  • Multiprocessing
  • Miscellaneous

  • Create Node Parameters

    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 ).

    Set Node Parameter Values

    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.

    Get Values from Node Parameters

    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.

    Handling Path Variables

    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.

    Error Handling

    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.

    Multiprocessing Control

    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.

    Miscellaneous

    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.

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

    Copyright © 1998 Silicon Grail Inc.
    710 Seward Street, Hollywood, CA 90038