UFO User Functions


Using the UFO (User Function Objects) API, you can create your own Fx operators for use inside the Softimage Fx tree. A custom Fx operator is written as a set of pre-defined user functions which define the setup and rendering of an effect. These user functions communicate with the main body of code via an interface library of support functions. The UFO code is compiled and linked into a Dynamic Shared Object (.so) or Dynamically Linked Library (.dll) which is loaded into Softimage at run-time.

This section of the UFO Reference describes all the UFO user functions.

Table of contents

ufoProcessDefine

ufoProcess ufoProcessDefine(void);

Must be supplied to provide the definition of a UFO process. The process instance handle returned from the ufoProcessCreate function call should be returned from this function.

ufoProcessCopyUserData

void* ufoProcessCopyUserData(
   ufoProcess process_instance,
   void       *user_data);

Refer to the following table for command descriptions:


Command

Description

process_instance

original process instance

user_data

user data attached to original process instance


Returns pointer copied user data. The ufoProcessCopyUserData function should be supplied if user data is set in any UFO user function with ufoProcessSetUserData, and requires a user-defined copy method to be used whenever process instances are copied. The function should return the pointer to the copied user data.

ufoProcessDeleteUserData

void ufoProcessDeleteUserData(
   ufoProcess process_instance,
   void       *user_data);

ufoProcessDeleteUserData should be supplied if user data is set in any UFO user function with ufoProcessSetUserData, and requires a user-defined destruction method to be used whenever process instances are destroyed.

ufoProcessWriteAsciiData

char* ufoProcessWriteAsciiData( 
ufoProcess process_instance); 

This function is optional. If supplied, it will be called just before the UFO process is about to be saved by the application to a descriptor file. If the UFO holds private user data, which is required to persist after the application is terminated, then the function can return an ascii data string representing that data. The string is then saved within the descriptor file. If no data is required to be saved, the function should return a null pointer.

The stored data string must contain no quotes and be null terminated.

ufoProcessReadAsciiData

void ufoProcessReadAsciiData( 
ufoProcess process_instance, 
char *ascii_data_string); 

This function is optional. If supplied, it will be called just after the UFO process has been loaded by the application from a descriptor file. The ASCII string will contain the exact representation of the private data which was saved when the UFO process was saved to disk, as returned by ufoProcessWriteAsciiData.

The contents of the string, ascii_data_string, should copied if required beyond the duration of the function call.

ufoProcessWriteBinaryData

void ufoProcessWriteBinaryData( 
ufoProcess process_instance, 
size_t *data_length, 
void **data_buffer, 
int *free_data_buffer);

Refer to the following table for command descriptions:


Command

Description

data_length

returns the byte length of the data buffer returned

data_buffer

returns the data buffer

free_data_buffer

return 1: application should free the data buffer returned (with free), 0: application should not free the data buffer returned


This function is optional. If supplied, it will be called just before the UFO process is about to be saved by the application to a descriptor file. If the UFO holds private user data which is required to persist after the application is terminated then the function can return a binary data buffer representing that data. The data buffer is then saved within the descriptor file. If no data is required to be saved, the function should return a value of 0 in the data_length parameter and a null pointer in the data_buffer parameter.

ufoProcessReadBinaryData

void ufoProcessReadBinaryData( 
ufoProcess process_instance, 
size_t data_length, 
void *data_buffer);

Refer to the following table for command descriptions:


Command

Description

data_length

the byte length of the data buffer supplied

data_buffer

supplied data buffer


This function is optional. If supplied, it will be called just after the UFO process has been loaded by the application from a descriptor file. The data buffer will contain the exact representation of the private data which was saved when the UFO process was saved to disk, as returned by ufoProcessWriteAsciiData.

The contents of the data buffer should copied if required beyond the duration of the function call.

ufoProcessPreSequenceRender

void ufoProcessPreSequenceRender(
   ufoProcess process_instance);

This function is optional. If supplied, it is called before a sequence of frames is rendered. ufoProcessPreSequenceRender should be supplied if specific initializations or data allocations need to be performed before a sequence of renders.

ufoProcessPostSequenceRender

void ufoProcessPostSequenceRender(
   ufoProcess process_instance);

This function is optional. If supplied, it is called after a sequence of frames is rendered. ufoProcessPostSequenceRender should be supplied if specific de-allocations or tidying of data need to be performed after a sequence of renders.

ufoProcessCanAvoidRendering

int ufoProcessCanAvoidRendering(
ufoProcess process_instance,
int *no_effect_input_index);

Refer to the following table for command descriptions:


Command

Description

no_effect_input_index

input to copy to the output when avoidance can be done


Returns 1: avoidance can be performed, 0: avoidance cannot be performed.

This function is optional. If supplied, it will be called before the rendering any rectangular region of the UFO process outputs. When called, the current values of all parameters can be inquired and used to determine whether the process will have any effect. If processing would have no effect and can be avoided then 1 should be returned and the no_effect_input_index parameter should be set to the input index which the UFO has no effect on. Otherwise 0 should be returned. This replaces a previously unused UFO function ufoProcessHasNoEffect().

ufoProcessCalcDefinedPixelType

void ufoProcessCalcDefinedPixelType(
ufoProcess process_instance,
ufoPixelType* input_pixel_types,
ufoPixelType* preferred_output_pixel_type);

Refer to the following table for command descriptions:


Command

Description

input_pixel_types

array of pixel types of rasters to be supplied to inputs

preferred_output_pixel_type

preferred output pixel type to be returned


This function is optional. If supplied, it will be called before the rendering any rectangular region of the UFO process outputs, and periodically during user interface interactivity. Given the determined pixel types of the input rasters the function should calculate and return the preferred defined output pixel type to which it can render.

This function is also called periodically during tree editing in order to colour code the input and output connection lines of the tree line UI. In this case there may be inputs which are not connected. If this happens then the corresponding input_pixel_types element will be set to ufoUndefinedPixelType.

If an input is optional, then you can test for whether it is selected using ufoProcessIsRasterInDefined.

If not supplied, the output defined pixel type is calculated using the application default method.

This function should be supplied where application default method does not automatically generate the preferred output pixel type or where the output pixel type may vary depending on the state of the parameters in the process.

ufoProcessSpecifyConvertPixelTypes

void ufoProcessSpecifyConvertPixelTypes(
ufoProcess process_instance,
ufoPixelType* input_convert_pixel_types,
ufoPixelType* output_convert_pixel_type);

Refer to the following table for command descriptions:


Command

Description

input_convert_pixel_types

array of input pixel type pre conversions, to be returned

output_convert_pixel_type

output pixel type post conversion, to be returned


This function is optional. If supplied, it will be called before the rendering of any rectangular region of the UFO process outputs.

The pixel types of the rasters that will be supplied to the UFO process inputs and output are passed in the input_convert_pixel_types array and output_convert_pixel_type variable, respectively. If you would like the application to pre-convert the input rasters or supply a different type output to be converted after rendering, then change these values.

This function is intended as a better alternative to the ufoProcessSetPixelTypeCombinations function library function.

ufoProcessPreRender

void ufoProcessPreRender(
   ufoProcess process_instance,
   int        x1,
   int        y1,
   int        x2,
   int        y2);

Refer to the following table for command descriptions:


Command

Description

x1,y1,x2,y2

full region to be rendered


This function is optional. If supplied, it is called directly before the rendering of a rectangular region of the UFO process outputs.

When called, all raster inputs and outputs and parameters will be set in the process, such that all their attributes and values can be inquired. ufoProcessPreRender should be supplied if specific data initializations or allocations need to be performed before a render.

If the ufoProcessRenderLine or ufoProcessRenderPixel render function is supplied, performance will improve if parameter values are inquired and copied into some representation in the UFO user data within this function, and then referenced from the user data during rendering.

ufoProcessPostRender

void ufoProcessPostRender(
   ufoProcess process_instance);

This function is optional. If supplied, it is called every time directly after the rendering any rectangular region of the UFO process outputs. ufoProcessPostRender should be supplied if specific de-allocations of data need to be performed after a render.

ufoProcessPreRenderPass

void ufoProcessPreRenderPass(
   ufoProcess process_instance,
   int        pass_number);

This function is optional. If supplied, it is called directly before each pass of rendering of any rectangular region of the UFO process outputs. ufoProcessPreRenderPass should be supplied if specific data initializations or allocations need to be performed before a particular rendering pass, where multiple rendering passes are required (see ufoProcessSetNumRenderPasses).

ufoProcessPostRenderPass

void ufoProcessPostRenderPass(
   ufoProcess process_instance,
   int        pass_number);

This function is optional. If supplied, it is called directly after each pass of rendering of any rectangular region of the UFO process outputs. ufoProcessPostRenderPass should be supplied if specific data de-allocations need to be performed after a particular rendering pass, where multiple rendering passes are required (see ufoProcessSetNumRenderPasses).

ufoProcessRenderPixel

void ufoProcessRenderPixel(
   ufoProcess  process_instance,
   int  x,
   int  y);

One of these three functions must be supplied. It calls every pixel, line or rectangle, respectively, within a single render pass. On the last render pass, (which is the only render pass by default–unless multiple passes have been set), the region supplied in the arguments should be rendered to the UFO process outputs.

If the current render pass mode has been set to ufoPassVertical using ufoProcessSetRenderPassMode then the argument x and y values are swapped.

ufoProcessRenderLine

void ufoProcessRenderLine(
   ufoProcess  process_instance,
   int  x1,
   int  x2,
   int  y);

One of these three functions must be supplied. It calls every pixel, line or rectangle, respectively, within a single render pass. On the last render pass, (which is the only render pass by default–unless multiple passes have been set), the region supplied in the arguments should be rendered to the UFO process outputs.

If the current render pass mode has been set to ufoPassVertical using ufoProcessSetRenderPassMode then the argument x and y values are swapped.

ufoProcessRenderRectangle

void ufoProcessRenderRectangle(
   ufoProcess  process_instance,
   int  x1,
   int  y1,
   int  x2,
   int  y2);

One of these three functions must be supplied. It calls every pixel, line or rectangle, respectively, within a single render pass. On the last render pass, (which is the only render pass by default–unless multiple passes have been set), the region supplied in the arguments should be rendered to the UFO process outputs.

If the current render pass mode has been set to ufoPassVertical using ufoProcessSetRenderPassMode then the argument x and y values are swapped.

ufoProcessCalcDefinedRectangle

void ufoProcessCalcDefinedRectangle(
   ufoProcess     process_instance,
   ufoRectangle*  input_rectangles,
   ufoRectangle*  defined_output_rectangle);

Refer to the following table for command descriptions:


Command

Description

input_rectangles

array of defined input rectangle regions

defined_output_rectangle

defined rectangle region to be returned


This function is optional. If supplied, it is called before the rendering of the process at a frame. The function should calculate and return the defined region for all outputs from the defined regions supplied for each input.

The supplied rectangle regions do not take into account the current render scaling, and the returned rectangle region should not either.

If not supplied, the output defined rectangle region defaults to the same as the first input.

The supplied input_rectangles regions do not take into account the current render scaling, and the returned defined_output_rectangle region should not either.

ufoProcessCalcNeedRectangles

void ufoProcessCalcNeedRectangles(
   ufoProcess    process_instance,
   ufoRectangle* output_rectangle,
   ufoRectangle* needed_input_rectangles);

Refer to the following table for command descriptions:


Command

Description

output_rectangle

needed rectangle region

needed_input_rectangles

array of needed input rectangle regions to be returned


This function is optional. If supplied, it is called before a process is rendered at a frame. Given the output region to be rendered, the function should calculate the required needed regions, which are the (sensible) maximum sized rectangle regions of input which are required in order to render to that output region properly.

The supplied needed_input_rectangle array is already pre-set to the maximum defined rectangle. This is useful if you cannot determine a finite needed region, as you can clip to it or leave it as it is.

The supplied output_rectangle region does not take into account the current render scaling, and the returned needed_input_rectangles regions should not either.

If ufoProcessCalcNeedRectangles is not supplied, the input needed regions default to the same as the output.

ufoProcessParamsEdited

void ufoProcessParamsEdited(
ufoProcess process_instance,
int number_params_edited,
int *param_index_array,
int *number_additional_changed_params,
int *additional_changed_param_index_array);

Refer to the following table for command descriptions:


Command

Description

number_params_edited

the number of parameter which have been edited

param_index_array

array of indices of the parameters which have been changed

number_additional_changed_params

return number of additional parameters that have been changed

additional_changed_param_index_array

return array of indices of parameters that have been changed


This function is optional. If supplied, it is called whenever any UFO parameters are changed by a user interface tool, and supplies the list of parameters that have been changed. The user can then act on the edit by changing additional parameters. The list of additional parameters changed should be returned, so that undo and redo can be performed properly, and so that other application GUIs can be updated properly.

This function is useful, for example, for controlling presets on a set of parameters by a ufoEnumParam parameter.

This function is called on parameter changes made by any application supplied parameter editor, including changes made by any ufo custom editor (as specified in the ufoEditorNotifyEdited library function.) This function is not called on undo, redo, reset, or load operations.

ufoEditorSetParamGroup

void ufoEditorSetParamGroup(
   ufoEditor  editor_instance,
   ufoProcess process_instance,
   int        parameter_group);

Refer to the following table for command descriptions:


Command

Description

parameter_group

index (0..number_parameter_groups) of parameter group


This function is optional. If supplied, it is called whenever a UFO process is edited and whenever the parameter group is changed. If the parameter group change affects the editor GUI, it should be implemented within this function.

ufoEditorBeginViewerEditing

void ufoEditorBeginViewerEditing(
   ufoEditor editor_ instance,
   ufoProcess process_ instance);

Called when a process is being edited in a viewer, redraw and mouse callbacks can be expected to be called. A processor could be edited in multiple viewers at once.

ufoEditorEndViewerEditing

void ufoEditorEndViewerEditing(
   ufoEditor editor instance,
   ufoProces process instance);

Called when a process is no longer being edited in a viewer.

ufoEditorKeyEvent

void ufoEditorKeyEnter(
   ufoEditor editor_instance,
   ufoProcess process_instance,
   void* event);

Refer to the following table for command descriptions:


Command

Description

event

X Motif Event


This function is optional. If supplied, it will be called whenever a key event occurs during editing (when a key or combination of keys is pressed).

ufoEditorMouseDown

void ufoEditorMouseDown(
   ufoEditor editor_instance,
   ufoProcess process_instance,
   double x,
   double y,
   void* event);

Refer to the following table for command descriptions:


Command

Description

x,y

mouse position in raster pixels

event

X Motif Event


This function is optional. If supplied, it will be called whenever a mouse button is pressed within the viewer during editing. The supplied X,Y position will be in full/master raster resolution pixel coordinates.

ufoEditorMouseDrag

void ufoEditorMouseDrag(
   ufoEditor editor_instance,
   ufoProcess process_instance,
   double x,
   double y,
   void* event);

Refer to the following table for command descriptions:


Command

Description

x,y

mouse position in raster pixels

event

X Motif Event


This function is optional. If supplied, it will be called whenever a mouse is moved with a button pressed within the viewer during editing. The supplied X,Y position will be in full/master raster resolution pixel coordinates.

ufoEditorMousePosition

void ufoEditorMousePosition(
   ufoEditor editor_instance,
   ufoProcess process_instance,
   double x,
   double y,
   void* event);

Refer to the following table for command descriptions:


Command

Description

x,y

mouse position in raster pixels

event

X Motif Event


This function is optional. If supplied, it will be called whenever a mouse is moved without a button being pressed, within the viewer during editing. The supplied X,Y position will be in full/master raster resolution pixel coordinates.

ufoEditorMouseUp

void ufoEditorMouseUp(
   ufoEditor editor_instance,
   ufoProcess process_instance,
   double x,
   double y,
   void* event);

Refer to the following table for command descriptions:


Command

Description

x,y

mouse position in raster pixels

event

X Motif Event


This function is optional. If supplied, it will be called whenever a mouse button is released within the viewer during editing. The supplied X,Y position will be in full/master raster resolution pixel coordinates.

ufoEditorOverlayDraw

void ufoEditorOverlayDraw(
   ufoEditor editor_instance,
   ufoProcess process_instance);

This function is optional. If supplied, it will be called during editing and rendering when the viewer window needs updating or a process parameter has changed.

Any graphics drawn in the Open GL overlay plane during editing should be performed within this function. OpenGL projections are set up for projection of the full/master raster resolution coordinate space on the screen.

The UFO library function ufoEditorGetOverlayIndex gets the correct colour index to be used for setting the overlay draw colour in OpenGL. This is necessary as a part of the overlay plane is used for other specific tools.

ufoEditorRGBDraw

void ufoEditorRGBDraw(
   ufoEditor editor_instance,
   ufoProcess process_instance);

This function is optional. If supplied, it will be called during editing and rendering when the viewer window needs updating or a process parameter has changed.

Any graphics drawn in the Open GL RGB Plane during editing should be performed within this function. OpenGL projections are set up for projection of the full/master raster resolution coordinate space on the screen.

This page was last modified 18:50, 15 Dec 2010.
This page has been accessed 1670 times.

© Copyright 2009 Autodesk Inc. All Rights Reserved. Privacy Policy | Legal Notices and Trademarks | Report Piracy