Referencing Inputs

From Filter Forge Wiki

Each input type has a corresponding function that allows you to query the value of a particular input of this type. Inputs are identified by their Script Identifiers specified in the Input Editor. Mappable inputs such as Color Map, Grayscale Map or Curve should be sampled from script's get_sample() function, while control inputs such as Slider and Checkbox should be queried from script's prepare() function. Here's a table summarizing the information on input types and their corresponding functions:

Input Type 			Function					Call from
●  Color Map Inputs		r, g, b, a = get_sample_map(x, y, input_id)	get_sample()
●  Grayscale Map Inputs		v = get_sample_grayscale(x, y, input_id)	get_sample()
●  Slider Inputs		value = get_slider_input(input_id)		prepare()
●  Angle Inputs			angle = get_angle_input(input_id)		prepare()
●  Integer Slider Inputs	value = get_intslider_input(input_id)		prepare()
●  Checkbox Inputs		state = get_checkbox_input(input_id)		prepare()
●  Curve Inputs			c = get_sample_curve(x, y, t, input_id)		get_sample()

Color Map Inputs

Color Map inputs are sampled by calling the get_sample_map() function with the sample coordinates and input's Script Identifier as arguments. The function returns an RGBA color:

r, g, b, a = get_sample_map(x, y, input_id)

• r, g, b and a (return values) – RGBA channels of the color at the sample coordinates given by x and y in the output image of a component connected to the input specified by input_id. In the absence of a map component connected to the input, the function returns the color of input's color swatch.
  

For inputs that are not marked as 'HDR Input' in the Input Editor, get_sample_map() returns RGBA channels as numbers within the 0…1 range. For HDR inputs, the returned RGB values (but not the alpha channel value) can be beyond the 0…1 range. For more information about how colors are represented in Filter Forge, see HDR Colors.

• x and y – The coordinates of the sample point, or simply sample coordinates. A point with the coordinates of 0, 0 corresponds to the top-left corner of the image, and a point with the coordinates of 1, 1 corresponds to the lower-right corner of the square Size x Size pixels wide, where Size is the current value of the global Size slider. For more information on Filter Forge's coordinate system and sampling in general, see Filter Forge's Sample-Based Architecture.

• input_id – Script Identifier of the color map input being sampled. If there's no input in the Input Editor with such Script Identifier, or the input with the matching Script Identifier is not a color map input, the script will terminate with an error.

Calls to get_sample_map() should be made from within script's get_sample() function.

The following script samples two color map inputs, with Script Identifiers of COLOR1 and COLOR2, and returns their averaged color:

function prepare()
end;

function get_sample(x, y)
	r1, g1, b1, a1 = get_sample_map(x, y, COLOR1)
	r2, g2, b2, a2 = get_sample_map(x, y, COLOR2)
	return (r1+r2)/2, (g1+g2)/2, (b1+b2)/2, (a1+a2)/2
end;

Grayscale Map Inputs

Grayscale Map inputs are sampled by calling the get_sample_grayscale() function with the sample coordinates and input's Script Identifier as arguments. The function returns a single numeric value:

v = get_sample_grayscale(x, y, input_id)

• v (return value) – The grayscale value of the color at the sample coordinates given by x and y in the output image of a component connected to the input specified by input_id. In the absence of a map component connected to the input, the function returns the value specified in the input's numeric entry box. The grayscale value is calculated by averaging the RGB channels of the color at the sample coordinates and multiplying the average by the alpha channel of the color:

v = (R + G + B) / 3 * A

For inputs that are not marked as 'HDR Input' in the Input Editor, get_sample_grayscale() returns its value as a number within the 0…1 range. For HDR inputs, the returned value can be beyond the 0…1 range. For more information, see HDR Colors.

• x and y – The coordinates of the sample point, or simply sample coordinates. A point with the coordinates of 0, 0 corresponds to the top-left corner of the image, and a point with the coordinates of 1, 1 corresponds to the lower-right corner of the square Size x Size pixels wide, where Size is the current value of the global Size slider. For more information on Filter Forge's coordinate system and sampling in general, see Filter Forge's Sample-Based Architecture.

• input_id – Script Identifier of the color map input being sampled. If there's no input in the Input Editor with such Script Identifier, or the input with the matching Script Identifier is not a color map input, the script will terminate with an error.

Calls to get_sample_grayscale() should be made from within script's get_sample() function.

The following script samples two grayscale map inputs, with Script Identifiers of GRAY1 and GRAY2, and mixes the returned grayscale values into the RGB channels of the final color:

function prepare()
end;

function get_sample(x, y)
	v1 = get_sample_grayscale(x, y, GRAY1)
	v2 = get_sample_grayscale(x, y, GRAY2)
	return v1, v2, (v1+v2)/2, 1
end;

Slider Inputs

Slider inputs are queried by calling the get_slider_input() function with the input's Script Identifier as an argument. The function returns the current value of the slider as a number within the range of 0…1:

value = get_slider_input(input_id)

• value (return value) – The current value of the slider input specified by input_id, returned as a number within the range of 0…1 – note that this actual range is different from the display range of 0…100 which is used for displaying values of slider inputs in the user interface.

• input_id – Script Identifier of the slider input being queried. If there's no input in the Input Editor with such Script Identifier, or the input with the matching Script Identifier is not a slider input, the script will terminate with an error.

This function should be called once for every slider input, from within script's prepare() function. Calling it from get_sample() is possible but is less efficient – non-mapped inputs always have the same values for any sample coordinates, so it makes sense to query them once during prepare() and store the result in a variable for use within get_sample().

The following script obtains the value of the slider input with the Script Identifier of SLYDER from within script's prepare() function, stores the result in a variable named v, and uses the variable within the get_sample() function to return a flat color with the brightness matching the slider value:

function prepare()
	v = get_slider_input(SLYDER)
end;

function get_sample(x, y)
	return v, v, v, 1
end;

Angle Inputs

Angle inputs are queried by calling the get_angle_input() function with the input's Script Identifier as an argument. The function returns the value of the input as a number within the range of 0…360:

angle = get_angle_input(input_id)

• angle (return value) – The current value of the angle input specified by input_id, returned as a number within the range of 0…360.

• input_id – Script Identifier of the angle input being queried. If there's no input in the Input Editor with such Script Identifier, or the input with the matching Script Identifier is not an angle input, the script will terminate with an error.

This function should be called once for every angle input, from within script's prepare() function. Calling it from get_sample() is possible but is less efficient – non-mapped inputs always have the same values for any sample coordinates, so it makes sense to query them once during prepare() and store the result in a variable for use within get_sample().

The following script obtains the value of the angle input with the Script Identifier of ANGIE from within script's prepare() function, divides it by 360 to bring it into the range of 0…1, stores the result in a variable named a, and uses the variable within the get_sample() function to return a flat color with the brightness defined by the value of the angle input:

function prepare()
	a = get_angle_input(ANGIE) / 360
end;

function get_sample(x, y)
	return a, a, a, 1
end;

Integer Slider Inputs

Integer slider inputs are queried by calling the get_intslider_input() function with the input's Script Identifier as an argument. The function returns the current value of the slider as a number:

value = get_intslider_input(input_id)

• value (return value #1) – The current value of the integer slider input specified by input_id, returned as a number that matches the value in slider's numeric entry box. Note that the current version of Filter Forge API does not provide a way to obtain the minimum and maximum values specified for integer sliders in the Input Editor.

• input_id – Script Identifier of the integer slider input being queried. If there's no input in the Input Editor with such Script Identifier, or the input with the matching Script Identifier is not an integer slider input, the script will terminate with an error.

This function should be called once for every integer slider input, from within script's prepare() function. Calling it from get_sample() is possible but is less efficient – non-mapped inputs always have the same values for any sample coordinates, so it makes sense to query them once during prepare() and store the result in a variable for use within get_sample().

The following script obtains the value of the integer slider input with the Script Identifier of STEPS from within script's prepare() function, stores the result in a variable named steps, and uses the variable within the get_sample() function to produce a linear gradient with flat steps:

function prepare()
	steps = get_intslider_input(STEPS)
end;

function get_sample(x, y)
	level = 1 / ( steps + 1 )
	v = math.floor( x / level ) * level
	return v, v, v, 1
end;

Checkbox Inputs

Checkbox inputs are queried by calling the get_checkbox_input() function with the input's Script Identifier as an argument. The function returns true or false, depending on the state of the checkbox control.

state = get_checkbox_input(input_id)

• state (return value) – The state of the checkbox input specified by input_id. When the checkbox is checked, state is returned as true, and when the checkbox is unchecked, it is returned as false.

• input_id – Script Identifier of the checkbox input being queried. If there's no input in the Input Editor with such Script Identifier, or the input with the matching Script Identifier is not a checkbox input, the script will terminate with an error.

This function should be called once for every checkbox input, from within script's prepare() function. Calling it from get_sample() is possible but is less efficient – non-mapped inputs always have the same values for any sample coordinates, so it makes sense to query them once during prepare() and store the result in a variable for use within get_sample().

The following script queries the state of a checkbox input with the Script Identifier of TICK from within script's prepare() function, stores the result in a variable named chk, and reads the value of the variable within the get_sample() function:

function prepare()
	chk = get_checkbox_input(TICK)
end;

function get_sample(x, y)
	if chk then 
		return 1, 1, 1, 1
	else 
		return 0, 0, 0, 1
	end;
end;

Curve Inputs

Curve inputs are sampled by calling the get_sample_curve () function with the sample coordinates, curve argument value and input's Script Identifier as arguments:

c = get_sample_curve(x, y, t, input_id)

• c (return value) – The output value of the function represented by the curve component connected to the input specified by input_id for the specified curve argument value t. In the absence of a curve component connected to the input, a linear function is sampled. The value is returned as a number within the 0…1 range (due to the fact that curve components can't output HDR values.)

• x and y – The coordinates of the sample point, or simply sample coordinates. Using point coordinates to sample a curve may seem weird, however, these coordinates are necessary because Filter Forge's curve components can have map inputs, and therefore the curve they generate may have different shape at different sample points. For more information on how mapping works for curves, see Map Inputs.

A point with the coordinates of 0, 0 corresponds to the top-left corner of the image, and a point with the coordinates of 1, 1 corresponds to the lower-right corner of the square Size x Size pixels wide, where Size is the current value of the global Size slider. For more information on Filter Forge's coordinate system and sampling in general, see Filter Forge's Sample-Based Architecture.

• t – The curve argument value. In most cases, this will be a number within the 0…1 range, but it can safely extend beyond that range – Filter Forge's curve components are required to be able to handle arguments beyond the 0…1 range.

• input_id – Script Identifier of the color map input being sampled. If there's no input in the Input Editor with such Script Identifier, or the input with the matching Script Identifier is not a curve map input, the script will terminate with an error.

Calls to get_sample_curve() should be made from within script's get_sample() function.

The following script samples a curve input with the Script Identifier of PROFILE and produces a remapped radial gradient. Don't forget to connect a curve component to the input when running this example:

function prepare()
end;

function get_sample(x, y)
	distance = math.sqrt (x*x + y*y)
	c = get_sample_curve(x, y, distance, PROFILE)
	return c, c, c, 1 
end;