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