Eyeon:Script/Reference/Applications/Fuse/Classes/ScriptOperator/AddInput

From VFXPedia

Contents 1 Summary 2 Usage 3 Common Input Attributes 4 Example 5 Tips for AddInput (edit) 5.1 ComboIDControl 5.2 MultiButtonIDControl 5.3 TextEditControl 5.4 IC_ControlID 5.5 More Input Attributes

Summary

The AddInput function is typically found within the Create event function of a Fuse. It is used to add inputs (controls) to the tool. An input can be one of several control types, or an image type input which appears on the tool tile in the flow.

Usage

self:AddInput(string labelname, string scriptname, table attributes)

labelname (string, required)

This string value specifies the label displayed next to the input control. The labelname allows spaces, and so typically is used to present a 'friendly' name for an input control compared to the scripting name described in the second argument.

scriptname (string, required)

This string value specifies the name of the input control for purposes of saving the value and for scripting it. The scriptname must not have any spaces, and contain only pure alphanumeric characters.

attributes (table, required)

This argument accepts a table of attributes used to define the properties of the input. Minimum and maximum value, whether the tool accepts integer values only, or the options available in a drop down menu are all set within this table. A list of attributes common to most Inputs is displayed below. Attributes specific to a particular input type or preview control will be found in the documentation for that type.

Common Input Attributes

LINKID_DataType	string : specifies the type of data produced and used by the control. A control which expects or outputs an image would use type "Image" while a slider would use "Number". Valid values include : FuID Gradient Image Number Particles Point Text
LINK_Main	integer : specifies the priority or order of LINK style controls. This is used when calculating autoconnection of tools in the flow. For example, a tool with two inputs would specify values of 1 and 2 for LINK_Main. The input with a value of 1 would have a higher priority than the control with a value of 2.
INPID_InputControl	string : This attribute uses a string to describe the type of control. Valid values include : ButtonControl CheckboxControl ColorControl ComboControl ComboIDControl FileControl FontFileControl GradientControl LabelControl MultiButtonControl MultiButtonIDControl OffsetControl RangeControl ScrewControl SliderControl
INPID_PreviewControl	string : If present this attribute uses a string to describe the type of on screen control displayed for the control. For example a Point type control would set this attribute to "TransformControl" if a set of crosshairs should be displayed in the views when the tool is selected. Valid values include : AngleControl CrossHairControl ImgOverlayControl RectangleControl PointControl TransformControl
INP_Default	numeric : This attribute is used to set the default value of a control. Typically this will be an integer value.
INP_MinScale	numeric : This attribute is used to set the minimum value displayed by the control. Typically this attribute is applied to sliders and range controls. This does not specify the absolute minimum value of the input, only the highest value presented by the control when it is initially constructed. It would still be possible to enter lower values, up to the value specified by INP_MinAllowed.
INP_MaxScale	numeric : This attribute is used to set the maximum value displayed by the control. Typically this attribute is applied to sliders and range controls. This does not specify the absolute maximum value of the input, only the highest value presented by the control when it is initially constructed. It would still be possible to enter higher values, up to the value specified by INP_MaxAllowed.
INP_MinAllowed	numeric : This attribute specifies the minimum allowable value for the input.
INP_MaxAllowed	numeric : This attribute specifies the maximum allowable value for the input.
INP_Required	boolean : This attribute specifies whether the input is required. If this is set to false the tool will not fail if the inp is nil. Typically used for non required image inputs - like the foreground of a Merge tool. Defaults to True
IC_ControlGroup	numeric : All inputs with the same IC_ControlGroup will be part of a overall group of controls. For example, the Red, Green and Blue sliders of a Color Control would all share the same IC_ControlGroup.
IC_ControlID	numeric : A unique identifier for an individual input within a control group defined by IC_ControlGroup. For example, the Red slider in a color control with IC_ControlGroup = 1 would have the IC_ControlID of 0, while the Green slider would have an IC_ControlID of 1, and so on.
IC_Visible	boolean : This attribute specifies whether an input is visible. Set it to false to hide the input. Defaults to true.
ICD_Center	numeric : This attribute will set the default of a slider to the center, regardless of scale. This creates a non-linear slider, with the default value centered regardless of the MinScale and MaxScale attributes. See the Merge tools Size slider for an example.
ICD_Width	numeric : This attribute specifies the width of the input, where a value of 1.0 is the full width of the control page.
PC_Visible	boolean : This attribute specifies whether the PreviewControl asociated with an input is currently visible. Defaults to true.
PC_GrabPriority	numeric : A numeric value that specifies the grab priority of a preview control input. The input with the highest PC_GrabPriority will be selected first. Used when two controls overlap - for example the Angle and Rectangle preview control found in a Merge or Transform tool.
PC_ControlGroup	numeric : All inputs with the same PC_ControlGroup will be share the same preview control. For example, the Width and Height sliders of a Rectangle mask will have the same PC_ControlGroup.
PC_ControlID	numeric : A unique identifier for an individual input within a preview control group defined by PC_ControlGroup. For example, a Width slider for a RectangleControl would have a PC_ControlGroup of 0, while the Height slider would be set to 1.
PC_HideWhileDragging	boolean : A true or false value wich specifies whether the preview control is visible while it is being dragged.

.

Example

The following example comes from the Gain.Fuse found on the Example Fuses page.

function Create()
	InMethod = self:AddInput("Method", "Method", {
		LINKID_DataType = "Number",
		INPID_InputControl = "ComboControl",
		INP_Default = 0.0,
		INP_Integer = true,
		{ CCS_AddString = "Simple Loop", },
		{ CCS_AddString = "DoMultiProcess", },
		{ CCS_AddString = "ProcessPixels", },
		{ CCS_AddString = "MultiProcessPixels", },
		})
	
	InGain = self:AddInput("Gain", "Gain", {
		LINKID_DataType = "Number",
		INPID_InputControl = "SliderControl",
		INP_Default = 2.0,
		})			
 
	InImage = self:AddInput("Input", "Input", {
		LINKID_DataType = "Image",
		LINK_Main = 1,
		})
 
	OutImage = self:AddOutput("Output", "Output", {
		LINKID_DataType = "Image",
		LINK_Main = 1,
		})				
end

Tips for AddInput (edit)

ComboIDControl

The ComboIDControl is like a ComboControl that uses FuID parameters instead of numbers. This is useful if you want to re-order the entries in the dropdown which would change the index values that existing code and compositions might already rely on. In addition to CCS_AddString you simply add a CCID_AddID attribute that will be used as the ID. Default values have to be set via INPID_Default instead of INP_Default.

InDirection = self:AddInput("Direction of Camera", "Direction", {
	LINKID_DataType = "FuID",
	INPID_InputControl = "ComboIDControl",
	{ CCS_AddString = "+X Axis: Right", CCID_AddID = "Right", },
	{ CCS_AddString = "-X Axis: Left",  CCID_AddID = "Left", },
	{ CCS_AddString = "-Z Axis: Front", CCID_AddID = "Front", },
	{ CCS_AddString = "+Z Axis: Back",  CCID_AddID = "Back", },
	INPID_DefaultID = "Front",
	})

Return values of a ComboIDControl are of type FuID. You need to use .Value to get the string:

local direction = InDirection:GetValue(request).Value

MultiButtonIDControl

This is to MultiButtonControls what ComboIDControl is to ComboControls: it returns FuIDs instead of numbers. The attributes are as follows:

InInterpolation = self:AddInput("Gradient Interpolation Method", "GradientInterpolationMethod", {
	LINKID_DataType      = "FuID",
	INPID_InputControl   = "MultiButtonIDControl",
	{ MBTNC_AddButton = "RGB", MBTNCID_AddID = "RGB", },
	{ MBTNC_AddButton = "HLS", MBTNCID_AddID = "HLS", },
	{ MBTNC_AddButton = "HSV", MBTNCID_AddID = "HSV", },
	{ MBTNC_AddButton = "LAB", MBTNCID_AddID = "LAB", },
	MBTNC_StretchToFit   = true,
	INPID_DefaultID      = "HLS",
	})

TextEditControl

The Annotate fuse that ships with Fusion demonstrates the use of TextEditControl. These are the available attributes (taken from StandardControls.h of the Fusion SDK):

InTextEntry = self:AddInput("Type Your Text", "Text", {
	LINKID_DataType = "Text",
	INPID_InputControl = "TextEditControl",
	INPS_DefaultText = "hello",  -- use instead of INP_Default!
	TEC_Lines = 3,               -- height of text entry (default is 8)
	TEC_Wrap = true,             -- automatic word-wrapping (default is false)
	TEC_ReadOnly = true,         -- default is false (you should also set INP_External = false)
	TEC_CharLimit = 40,	     -- maximum number of allowed characters (default is 0, no limit)
	TEC_DeferSetInputs = true,   -- call NotifyChanged when focus is lost (default is false, call on every key stroke)
	})

Return values of a TextEditControl are of type Text. You need to use .Value to get the string:

local text = InTextEntry:GetValue(request).Value

Single lines of read-only text (e.g. messages) can also be displayed by using a LabelControl.

IC_ControlID

The value of IC_ControlID is sometimes related to a specific image channel. For example, if an X position slider can have its value set by a pick button (see BeginControlNest), it needs to know that it should read the image's "position x" channel. Also, Image:GetChanSize() accepts these to query available image channels. Here's an abbreviated list of valid values, taken from Pixel.h (part of the SDK). Fusion 6.31 or later supports the uppercase channel constants. Earlier versions accept integers only.

0 1 2 3 4 5 6 7

CHAN_RED CHAN_GREEN CHAN_BLUE CHAN_ALPHA CHAN_BGR CHAN_BGG CHAN_BGB CHAN_BGA

12 13 14 15 16 17

CHAN_Z CHAN_U CHAN_V CHAN_COVERAGE CHAN_OBJECT CHAN_MATERIAL

18 19 20 21 22 23 24

CHAN_NORMALX CHAN_NORMALY CHAN_NORMALZ CHAN_VECTORX CHAN_VECTORY CHAN_BACKVECTORX CHAN_BACKVECTORY

25 26 27 28 29

CHAN_POSITIONX CHAN_POSITIONY CHAN_POSITIONZ CHAN_DISPARITYX CHAN_DISPARITYY

More Input Attributes

Here's a list of input attributes, some of which are not listed above.