vispy.visuals.shaders package#

Submodules#

Module contents#

Provides functionality for composing shaders from multiple GLSL code snippets.

class vispy.visuals.shaders.Compiler(namespace=None, **shaders)#

Bases: object

Compiler is used to convert Function and Variable instances into ready-to-use GLSL code. This class handles name mangling to ensure that there are no name collisions amongst global objects. The final name of each object may be retrieved using Compiler.__getitem__(obj).

Accepts multiple root Functions as keyword arguments. compile() then returns a dict of GLSL strings with the same keys.

Example:

# initialize with two main functions
compiler = Compiler(vert=v_func, frag=f_func)

# compile and extract shaders
code = compiler.compile()
v_code = code['vert']
f_code = code['frag']

# look up name of some object
name = compiler[obj]

compile(pretty=True)#

Compile all code and return a dict {name: code} where the keys are determined by the keyword arguments passed to __init__().

Parameters:

prettybool: If True, use a slower method to mangle object names. This produces GLSL that is more readable. If False, then the output is mostly unreadable GLSL, but is about 10x faster to compile.

class vispy.visuals.shaders.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.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.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.ModularProgram(vcode='', fcode='', gcode=None)#

Bases: Program

Shader program using Function instances as basis for its shaders.

Automatically rebuilds program when functions have changed and uploads program variables.

build_if_needed()#: Reset shader source if necesssary.

draw(*args, **kwargs)#

Draw the attribute arrays in the specified mode.

Parameters:

modestr | GL_ENUM: ‘points’, ‘lines’, ‘line_strip’, ‘line_loop’, ‘lines_adjacency’, ‘line_strip_adjacency’, ‘triangles’, ‘triangle_strip’, or ‘triangle_fan’.
indicesarray: Array of indices to draw.
check_error:: Check error after draw.

property frag#

property geom#

update_variables()#

property vert#

class vispy.visuals.shaders.MultiProgram(vcode='', fcode='', gcode=None)#

Bases: object

A collection of ModularPrograms that emulates the API of a single ModularProgram.

A single Visual is often drawn in many different ways–viewed under different transforms, with different clipping boundaries, or with different colors as in picking and anaglyph stereo. Each draw may require a different program. To simplify this process, MultiProgram exposes an API that looks very much like a single ModularProgram, but internally manages many programs.

add_program(name=None)#

Create a program and add it to this MultiProgram.

It is the caller’s responsibility to keep a reference to the returned program.

The name must be unique, but is otherwise arbitrary and used for debugging purposes.

bind(data)#

property frag#: A wrapper around all fragment shaders contained in this MultiProgram.

property geom#: A wrapper around all geometry shaders contained in this MultiProgram.

property vert#: A wrapper around all vertex shaders contained in this MultiProgram.

class vispy.visuals.shaders.Variable(name, value=None, vtype=None, dtype=None)#

Bases: ShaderObject

Representation of global shader variable

Parameters:

namestr: the name of the variable. This string can also contain the full definition of the variable, e.g. ‘uniform vec2 foo’.
value{float, int, tuple, GLObject}: If given, vtype and dtype are determined automatically. If a float/int/tuple is given, the variable is a uniform. If a gloo object is given that has a glsl_type property, the variable is an attribute and
vtype{‘const’, ‘uniform’, ‘attribute’, ‘varying’, ‘inout’}: The type of variable.
dtypestr: The data type of the variable, e.g. ‘float’, ‘vec4’, ‘mat’, etc.

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.

property dtype#: The type of data (float, int, vec, mat, …).

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

property name#: The name of this variable.

property state_id#: Return a unique ID that changes whenever the state of the Variable has changed. This allows ModularProgram to quickly determine whether the value has changed since it was last used.

property value#: The value associated with this variable.

property vtype#

The type of variable (const, uniform, attribute, or varying).

For in/out variables (GLSL 150+), vtype is ‘varying’.

class vispy.visuals.shaders.Varying(name, dtype=None)#

Bases: Variable

Representation of a varying (variables passed from one shader to the next).

Varyings can inherit their dtype from another Variable, allowing for more flexibility in composing shaders.

property dtype#: The type of data (float, int, vec, mat, …).

invar(array=False)#: Return a varying that defines itself using the same name as this, but as an in variable instead of out.

link(var)#

Link this Varying to another object from which it will derive its dtype.

This method is used internally when assigning an attribute to a varying using syntax function[varying] = attr.

property value#: The value associated with this variable.

vispy.visuals.shaders package#

Subpackages#

Submodules#

Module contents#