vispy.visuals.shaders.function module#

Classses representing GLSL objects (functions, variables, etc) that may be composed together to create complete shaders. See the docstring of Function for details.

Details#

A complete GLSL program is composed of ShaderObjects, each of which may be used inline as an expression, and some of which include a definition that must be included on the final code. ShaderObjects keep track of a hierarchy of dependencies so that all necessary code is included at compile time, and changes made to any object may be propagated to the root of the hierarchy to trigger a recompile.

class vispy.visuals.shaders.function.Function(code, dependencies=None)#

Bases: ShaderObject

Representation of a GLSL function

Objects of this class can be used for re-using and composing GLSL snippets. Each Function consists of a GLSL snippet in the form of a function. The code may have template variables that start with the dollar sign. These stubs can be replaced with expressions using the index operation. Expressions can be:

plain text that is inserted verbatim in the code
a Function object or a call to a funcion
a Variable (or Varying) object
float, int, tuple are automatically turned into a uniform Variable
a VertexBuffer is automatically turned into an attribute Variable

All functions have implicit “$pre” and “$post” placeholders that may be used to insert code at the beginning and end of the function.

Notes

Function calls:

As can be seen above, the arguments with which a function is to be called must be specified by calling the Function object. The arguments can be any of the expressions mentioned earlier. If the signature is already specified in the template code, that function itself must be given.

code = Function('''
    void main() {
        vec4 position = $pos;
        gl_Position = $scale(position)
    }
''')

# Example of a function call with all possible three expressions
vert_code['pos'] = func1('3.0', 'uniform float u_param', func2())

# For scale, the sigfnature is already specified
code['scale'] = scale_func  # Must not specify args

Data for uniform and attribute variables:

To each variable a value can be associated. In fact, in most cases the Function class is smart enough to be able to create a Variable object if only the data is given.

code['offset'] = Variable('uniform float offset')  # No data
code['offset'] = Variable('uniform float offset', 3.0)  # With data
code['offset'] = 3.0  # -> Uniform Variable
position['position'] = VertexBuffer()  # -> attribute Variable

# Updating variables
code['offset'].value = 4.0
position['position'].value.set_data(...)

Examples

This example shows the basic usage of the Function class:

vert_code_template = Function('''
    void main() {
    gl_Position = $pos;
    gl_Position.x += $xoffset;
    gl_Position.y += $yoffset;
}''')

scale_transform = Function('''
vec4 transform_scale(vec4 pos){
    return pos * $scale;
}''')

# If you get the function from a snippet collection, always
# create new Function objects to ensure they are 'fresh'.
vert_code = Function(vert_code_template)
trans1 = Function(scale_transform)
trans2 = Function(scale_transform)  # trans2 != trans1

# Three ways to assign to template variables:
#
# 1) Assign verbatim code
vert_code['xoffset'] = '(3.0 / 3.1415)'

# 2) Assign a value (this creates a new uniform or attribute)
vert_code['yoffset'] = 5.0

# 3) Assign a function call expression
pos_var = Variable('attribute vec4 a_position')
vert_code['pos'] = trans1(trans2(pos_var))

# Transforms also need their variables set
trans1['scale'] = 0.5
trans2['scale'] = (1.0, 0.5, 1.0, 1.0)

# You can actually change any code you want, but use this with care!
vert_code.replace('gl_Position.y', 'gl_Position.z')

# Finally, you can set special variables explicitly. This generates
# a new statement at the end of the vert_code function.
vert_code['gl_PointSize'] = '10.'

If we use vert_code.compile() we get:

attribute vec4 a_position;
uniform float u_yoffset;
uniform float u_scale_1;
uniform vec4 u_scale_2;
uniform float u_pointsize;

vec4 transform_scale_1(vec4 pos){
    return pos * u_scale_1;
}

vec4 transform_scale_2(vec4 pos){
    return pos * u_scale_2;
}

void main() {
    gl_Position = transform_scale_1(transform_scale_2(a_position));
    gl_Position.x += (3.0 / 3.1415);
    gl_Position.z += u_yoffset;

    gl_PointSize = u_pointsize;
}

Note how the two scale function resulted in two different functions and two uniforms for the scale factors.

property args#

List of input arguments in the function signature::: [(arg_name, arg_type), …]

property code#: The template code used to generate the definition for this function.

definition(names, version, shader)#: Return the GLSL definition for this object. Use obj_names to determine the names of dependencies, and version (number, qualifier) to adjust code output.

expression(names)#: Return the GLSL expression used to reference this object inline.

property name#: The function name. The name may be mangled in the final code to avoid name clashes.

replace(str1, str2)#

Set verbatim code replacement

It is strongly recommended to use function[‘$foo’] = ‘bar’ where possible because template variables are less likely to changed than the code itself in future versions of vispy.

Parameters:

str1str: String to replace
str2str: String to replace str1 with

property rtype#: The return type of this function.

property signature#

static_names()#

Return a list of names that are declared in this object’s definition (not including the name of the object itself).

These names will be reserved by the compiler when automatically determining object names.

property template_vars#

class vispy.visuals.shaders.function.FunctionChain(name=None, funcs=())#

Bases: Function

Subclass that generates GLSL code to call Function list in order

Functions may be called independently, or composed such that the output of each function provides the input to the next.

Parameters:

namestr: The name of the generated function
funcslist of Functions: The list of Functions that will be called by the generated GLSL code.

Examples

This creates a function chain:

>>> func1 = Function('void my_func_1() {}')
>>> func2 = Function('void my_func_2() {}')
>>> chain = FunctionChain('my_func_chain', [func1, func2])

If chain is included in a ModularProgram, it will generate the following output:

void my_func_1() {}
void my_func_2() {}

void my_func_chain() {
    my_func_1();
    my_func_2();
}

The return type of the generated function is the same as the return type of the last function in the chain. Likewise, the arguments for the generated function are the same as the first function in the chain.

If the return type is not ‘void’, then the return value of each function will be used to supply the first input argument of the next function in the chain. For example:

vec3 my_func_1(vec3 input) {return input + vec3(1, 0, 0);}
void my_func_2(vec3 input) {return input + vec3(0, 1, 0);}

vec3 my_func_chain(vec3 input) {
    return my_func_2(my_func_1(input));
}

append(function, update=True)#: Append a new function to the end of this chain.

property code#: The template code used to generate the definition for this function.

definition(obj_names, version, shader)#: Return the GLSL definition for this object. Use obj_names to determine the names of dependencies, and version (number, qualifier) to adjust code output.

property functions#

insert(index, function, update=True)#: Insert a new function into the chain at index.

remove(function, update=True)#: Remove a function from the chain.

property signature#

static_names()#

Return a list of names that are declared in this object’s definition (not including the name of the object itself).

These names will be reserved by the compiler when automatically determining object names.

property template_vars#

class vispy.visuals.shaders.function.MainFunction(shader_type, *args, **kwargs)#

Bases: Function

Subclass of Function that allows multiple functions and variables to be defined in a single code string. The code must contain a main() function definition.

add_callback(hook, func)#

add_chain(var)#: Create a new ChainFunction and attach to $var.

definition(obj_names, version, shader)#: Return the GLSL definition for this object. Use obj_names to determine the names of dependencies, and version (number, qualifier) to adjust code output.

remove_callback(hook, func)#

property signature#

static_names()#

Return a list of names that are declared in this object’s definition (not including the name of the object itself).

These names will be reserved by the compiler when automatically determining object names.

property version_pragma#: Return version number and extra qualifiers from pragma if present.

class vispy.visuals.shaders.function.StatementList#

Bases: ShaderObject

Represents a list of statements.

add(item, position=5)#

Add an item to the list unless it is already present.

If the item is an expression, then a semicolon will be appended to it in the final compiled code.

expression(obj_names)#: Return the GLSL expression used to reference this object inline.

remove(item)#: Remove an item from the list.