Inputs/Outputs

Inputs and outputs need to be specified in both, the interface and the GLSL code for Flair shaders to work correctly. Flair shaders are mainly written in plain GLSL, but the interface is defined within the comment block \* interface */ in a simpler language called TOML.

TOML is a minimal markup language (similar to YAML) that makes defining inputs and outputs for the shader easier for artists.

Names in the interface must correlate to names in the shader code for values to bind correctly.

Outputs

There can be multiple Outputs in a Flair shader and they need to be defined through the interface (TOML) and declared in the GLSL code as follows:

One output

1
2
3
# TOML
# defines one "Output" for the node 
outputs = ["Output"]  

1
2
3
4
5
// GLSL
// declares one output: "Output" 
out vec4 Output;

Multiple outputs

1
2
3
# TOML
# defines three outputs for the node
outputs = ["Color", "Normals", "Edges"] 

1
2
3
4
5
// GLSL
// declares three outputs
out vec4 Color;
out vec4 Normals;
out vec4 Edges;

Inputs

There can be multiple Inputs in a Flair shader of different types, which also need to be defined in the interface and declared in the GLSL code as follows:

Texture Inputs

One input texture

1
2
3
4
5
6
7
# TOML
# define a texture input
[[textures]]  
name = "Texture"

1
2
3
4
// GLSL
// declare an input texture
uniform sampler2D Texture;

Multiple input textures

1
2
3
4
5
6
7
# TOML
# define two texture inputs
[[textures]]  
name = "Texture1"

[[textures]]  
name = "Texture2"

1
2
3
4
// GLSL
// declare two input textures
uniform sampler2D Texture1;
uniform sampler2D Texture2;

Integer numbers

1
2
3
4
# TOML
[[uniforms]]
name = "Integer"
type = "int"      # define an integer input (parameter)

1
2
// GLSL
uniform int Integer;  // declare an integer number

Integer vectors

1
2
3
4
# TOML
[[uniforms]]
name = "IntVector2"  # define an integer vector input (parameter)
type = "ivec2"       # or "ivec3", "ivec4" depending on how many channels are needed 

1
2
// GLSL
uniform ivec2 IntVector2;  // declare an integer vector (ivec3 or ivec4 respectively)

Floating-point numbers

1
2
3
4
# TOML
[[uniforms]]
name = "Float"
type = "float"  # define a float input (parameter)

1
2
// GLSL
uniform int Float;  // declare a float number

Floating-point vectors

1
2
3
4
# TOML
[[uniforms]]
name = "FloatVector2"  # define a float vector (parameter)
type = "vec2"          # or "vec3", "vec4" depending on how many channels are needed

1
2
// GLSL
uniform vec2 FloatVector2;  // declare a float vector (vec3 or vec4 respectively)

Matrices

1
2
3
4
// GLSL
uniform mat2 Matrix2x2;  // declare a 2x2 matrix
uniform mat3 Matrix3x3;  // declare a 3x3 matrix
uniform mat4 Matrix4x4;  // declare a 4x4 matrix

Since matrices can’t be defined yet from the parameter’s panel, they can only be declared.

Interface definition

The interface for inputs can be further defined to enhance the functionality of uniforms and create more intuitive user interfaces.

Sampler uniforms

uniform sampler2D inputs can have sampler state information attached, for example:

1
2
3
4
5
6
7
8
# TOML
[[textures]]
name = "Color"
addressU = "mirror"
addressV = "mirror"
addressW = "mirror"
minFilter = "linear"
magFilter = "linear"

The following values are recognized:

• addressU, addressV, addressW: texture addressing mode for the U/V/W coordinate.
  • “repeat” - see GL_REPEAT
  • “mirror” - see GL_MIRRORED_REPEAT
  • “clamp” - see GL_CLAMP_TO_EDGE
  • “border” - see GL_CLAMP_TO_BORDER

• minFilter, magFilter: texture minification and magnification filters
  • “nearest” - nearest-neighbor interpolation, see GL_NEAREST
  • “linear” - linear interpolation, see GL_LINEAR

By default, if no metadata is specified, sampler2D’s are set to REPEAT and NEAREST

Numeric uniforms

int and float parameters can have optional attributes that further define their interface:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# TOML
[[uniforms]]
name = "Float"
type = "float"
min = 0.0
max = 5.0
step = 0.2

[[uniforms]]
name = "Integer"
type = "int"
min = 0
max = 100
step = 20

• min: minimum value of the parameter. If nothing is specified, then the parameter has no minimum value.
• max: maximum value of the parameter. If nothing is specified, then the parameter has no maximum value.
• step: the step size when increasing or decreasing the parameter. If nothing is specified, it will be inferred from the min and max values, or the parameter type (float 0.1, int 1)

For int parameters, one can create check boxes and combo boxes through the widget attribute.

1
2
3
4
5
# TOML
[[uniforms]]
name = "Check"
type = "int"
widget = "checkbox"

1
2
3
4
5
6
# TOML
[[uniforms]]
name = "Combobox"
type = "int"
widget = "combobox"
toggle = ["Option 0", "Option 1", "Option 2"]

For vec3 and vec4 parameters can also represent colors, the color widget is defined as follows:

1
2
3
4
5
# TOML
[[uniforms]]
name = "Color"
type = "vec3"
widget = "color"