Inputs/Outputs

Table of contents
  1. Outputs
    1. One output
    2. Multiple outputs
  2. Inputs
    1. Texture Inputs
    2. One input texture
    3. Multiple input textures
    4. Integer numbers
    5. Integer vectors
    6. Floating-point numbers
    7. Floating-point vectors
    8. Matrices
  3. Interface definition
    1. Sampler uniforms
    2. Numeric uniforms

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;
A shader node with one output
A shader node with one 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;
A shader node with multiple outputs
A shader node with multiple outputs.

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;
An integer parameter
A shader node with one input.

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;
An integer parameter
A shader node with multiple inputs.

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
An integer parameter
An integer parameter.

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)
An integer vec2 parameter
An integer vec2 parameter.

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
A float parameter
A float parameter.

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)
A vec2 parameter
A floating-point vec2 parameter.

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
Different texture address modes
Different texture addressing modes. Image credit: learnopengl.com.
  • minFilter, magFilter: texture minification and magnification filters
    • “nearest” - nearest-neighbor interpolation, see GL_NEAREST
    • “linear” - linear interpolation, see GL_LINEAR
Different texture filtering filtering modes
Different texture filtering modes. Image credit: learnopengl.com.

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)
Integer parameter with optional min, max and step size
Integer parameter with optional min, max and step size.

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"
Integer parameter with check box interface
Integer parameter with a check box interface.
1
2
3
4
5
6

# TOML
[[uniforms]]
name = "Combobox"
type = "int"
widget = "combobox"
toggle = ["Option 0", "Option 1", "Option 2"]
Integer parameter with combo box interface
Integer parameter with a combo box interface.

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"
Floating-point vector parameter with color interface
Floating-point vector parameter with color interface.