UPI Routine Reference

Reference of required and optional functions that Chalice will/may call and that plugin writers may supply. ALL of these functions are optional, in that Chalice will supply default versions. The default plugin passes its input to its output.
The routines are divided into the following topics, and are shown in the order of their execution by Chalice:
  • Setting Up a Node
  • Processing the Node (Cooking)
  • Callbacks - Reasons to Update the Node
  • Feeding Back User Information

  • Setting Up a Node

    upiInitialize ============= int upiInitialize( int workflag ); Description: This function is called by chalice during the initial loading of the plugin. The "workflag" passed in will be 1 if the plugin is being intialized by the work process, or 0 if by the UI process. Any initialization needed by the plugin should be done at this time, such as getting licenses, configuration and/or data file reading, etc... The return value should be 0 if no error occurred. Anything else will cause the plugin not to be loaded. upiPluginType ============= CPI_PluginType upiPluginType( void ); Description: This function is called during the initial loading, after upiInitialize is called. It is called by both processes. It returns the plugin type. Current plugin types are: T_FILTER, T_COMPOSITE, T_CONVERT, T_MOVERS, T_TOOL, T_IO, T_EFFECTS, T_MATTE, and T_VIDEO. If not supplied, the default type is T_FILTER. upiAuthorName ============= char *upiAuthorName( void ); Description: This function is called during the initial loading, after the call to upiInitialize. It is called by both the work process and the UI process. It should return the name(s) of the author(s) of the plugin. If not provided, "Unknown" will be the default. The pointer returned should be valid for the life of the program, and its content should not be altered. upiPluginName ============= char *upiPluginName( void ); Description: This function is called during the initial loading of the plugin, after the call to upiInitialize. It is called by both the work process and the UI process. It should return the name of the plugin. If not supplied, the default name will be extracted from the plugin's file name. The pointer returned should be valid for the life of the program, and its content should not be altered. upiCopyrightNotice ================== char *upiCopyrightNotice( void ); Description: This function is called during the inital loading of the plugin, after the call to upiInitialize. It is called by both the work process and the UI process. It should return a copyright notice. The default copyright notice, if not supplied is "". The pointer returned should be valid for the life of the program, and its content should not be altered. upiPluginVersion ================ char *upiPluginVersion( void ); Description: This function is called during the inital loading of the plugin, after the call to upiInitialize. It is called by both the work process and the UI process. It should return the version of the plugin. The default version is simply "1.0". The pointer returned should be valid for the life of the program, and its content should not be altered. upiCreateParameters =================== void upiCreateParameters( void ) Description: This function is called during the initial loading of the plugin. It is called after upiInitialize has been called. This function should create parameters by calling the cpiAdd* functions. cpiAddTab should be called first if the plugin has any parameters. The details of parameters will not be described here. If this function does not exist, the plugin will have no parameters by default. upiNumberOfInputs =============== void upiNumberOfInputs( int *min, int *max ) Description: This function is called during the initial loading of the plugin. It is called after upiInitialize. It should return the minimum and maximum number of inputs that the plugin can take. The default value is 1 for both the minimum and the maximum.

    Processing the Image

    upiOutputContext ================ int upiOutputContext( CPI_ImageContext *output, float time ) Description: This function should calculate the size and depth of its output. Typically, this function will call cpiInputContext to get information on its inputs, and calculate what the output size and depth are. The default is for the output to be the same size and depth as the first input. upiCheckInputSize ================= int upiCheckInputSize( CPI_ImageContext *result ) Description: This function is called to check the size of the input. The default is to check that all inputs are of the same size. If the inputs are not the size the plugin expects, cpiError should be called with an error message, and a non-zero value should be returned. upiCheckInputDepth ================== int upiCheckInputDepth( CPI_ImageContext *result ) Description: This function is called to check the depth (pixel type and number of channels) of the inputs. The default is to check that all inputs are of the same depth. If the plugin has inputs of the wrong depth, cpiError should be called and a non-zero value should be returned. upiCookFull =========== int upiCookFull( void ) Description: This function should return true if this plugin needs to cook a full image (i.e. it cannot do slicing). upiResultInput ================= int upiResultInput( CPI_ImageContext *result ) Description: This function is called to know which input image is used to hold the result. For plugins that can be done in-place, INPUT_A (B, C, etc...) can be used as the result image. If the plugin wants a separate image for the result, RESULT_SEPARATE should be returned. The default is to use input A as the result image. So plugins which change the size, type, and/or channels of an image should return RESULT_SEPARATE. upiModifyInput ============== int upiModifyInput( unsigned int input_index ) Description: This function is called to know whether you are going to modify an input image. Normally, it is assumed that you are going to modify the result input. If the result input (see upiResultInput) is separate, then by default, chalice assumes input images will not be modified, for performance reasons. For plugins that need to work with more than one image and want to save memory by re-using their inputs, implement this function, and return 1 for which inputs are to be modified, and otherwise return 0. upiRegionsNeeded =============== void upiRegionsNeeded( CPI_ImageContext *output ) Description: This function should make a list of all the inputs (or part thereof) that the plugin will need to produce its output. For each piece of an input that is needed, the function cpiNeedRegion should be called. This function is used for two purposes. It is first called by the caching system to know what is needed so it can be optimized. It is called a second time during the cooking process to know which part of which inputs the plugin needs. If not defined, the default is to request all inputs. upiProcessImage =============== int upiProcessImage( CPI_Image *result ) Description: This function does the "real" work. If this function needs other images or parts of images as input, these are obtained by calling cpiCookRegion(), which returns regions defined by upiRegionsNeeded(). upiProcessImage() should fill in the result image. If an error occurs, it should return a non-zero value. The default upiProcessImage will simply fill the result image with black.

    Callbacks - Reasons to Update the Node

    upiInputChanged =============== void upiInputChanged( void ) Description: This function is called when an input has changed. An input change occurs when one of the inputs is replaced or disconnected. If not implemented, the default will invalidate the output information. upiParameterChanged =================== void upiParameterChanged( char *name ) Description: This function is called when ever a parameter changes. The name of the parameter changed is passed in. The default is to do nothing. For parameters of type P_BUTTON, this means the button has been pushed and released by the user.
    NOTE: There are cases when upiParameterChanged() is called with the empty string. This usually means that all parameters have changed simultaneously; the most common instance of this is when a node is loaded from a grail file with existing parameters. Thus some tests may need to be expressed as: if (name[0] == '\0' || strcmp(name, "parameter name") == 0) { the parameter called "parameter name" has changed } upiNodeCreated ============== void upiNodeCreated( void ) Description: This routine is called each time a node is created. It is the first routine called. upiNodeDeleted ============== void upiNodeDeleted( void ) Description: This routine is called when any node is deleted. The programmer may assume that the node is still in existence when this routine is entered. upiNameChanged ============== void upiNameChanged( char *old, char *new ) Description: This routine is called when any node's name is changed. The arguments supply the old and new name.

    Feeding Back User Information

    upiMessageInfo ========== char *upiMessageInfo( float time ) Description: This function is called when the user wants to see the information tab. Whatever text is returned by this function is added to this tab. The string returned can contain "\n" (newlines). If not implemented, nothing is added to the info tab. upiInputLabel ============= char *upiInputLabel( unsigned int ) Description: This function should returns a "user-friendly" name for the given input. This name is shown to the user when the input of a node is right-clicked. The default function will simply return "image". upiOutputLabel ============== char *upiOuputLabel( void ) Description: This function is very similar to upiInputLabel, but is for the output. It is not currently implemented.

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

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