Provides functionality for composing shaders from multiple GLSL code snippets.
vispy.visuals.shaders.
Compiler
Bases: object
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).
Compiler.__getitem__(obj)
Accepts multiple root Functions as keyword arguments. compile() then returns a dict of GLSL strings with the same keys.
compile()
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
Compile all code and return a dict {name: code} where the keys are determined by the keyword arguments passed to __init__().
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.
Function
Bases: vispy.visuals.shaders.shader_object.ShaderObject
vispy.visuals.shaders.shader_object.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.
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:
vert_code.compile()
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.
args
List of input arguments in the function signature:
[(arg_name, arg_type), ...]
code
The template code used to generate the definition for this function.
definition
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
Return the GLSL expression used to reference this object inline.
name
The function name. The name may be mangled in the final code to avoid name clashes.
replace
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.
String to replace
String to replace str1 with
rtype
The return type of this function.
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.
template_vars
FunctionChain
Bases: vispy.visuals.shaders.function.Function
vispy.visuals.shaders.function.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.
The name of the generated function
The list of Functions that will be called by the generated GLSL code.
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(); }
void my_func_1() {} void my_func_2() {}
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)); }
vec3 my_func_1(vec3 input) {return input + vec3(1, 0, 0);} void my_func_2(vec3 input) {return input + vec3(0, 1, 0);}
return my_func_2(my_func_1(input));
append
Append a new function to the end of this chain.
functions
insert
Insert a new function into the chain at index.
remove
Remove a function from the chain.
MainFunction
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
add_chain
Create a new ChainFunction and attach to $var.
remove_callback
version_pragma
Return version number and extra qualifiers from pragma if present.
ModularProgram
Bases: vispy.gloo.program.Program
vispy.gloo.program.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
Draw the attribute arrays in the specified mode.
‘points’, ‘lines’, ‘line_strip’, ‘line_loop’, ‘lines_adjacency’, ‘line_strip_adjacency’, ‘triangles’, ‘triangle_strip’, or ‘triangle_fan’.
Array of indices to draw.
Check error after draw.
frag
geom
update_variables
vert
MultiProgram
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
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
A wrapper around all fragment shaders contained in this MultiProgram.
A wrapper around all geometry shaders contained in this MultiProgram.
A wrapper around all vertex shaders contained in this MultiProgram.
Variable
Representation of global shader variable
the name of the variable. This string can also contain the full definition of the variable, e.g. ‘uniform vec2 foo’.
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
The type of variable.
The data type of the variable, e.g. ‘float’, ‘vec4’, ‘mat’, etc.
dtype
The type of data (float, int, vec, mat, …).
The name of this variable.
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.
value
The value associated with this variable.
vtype
The type of variable (const, uniform, attribute, or varying).
For in/out variables (GLSL 150+), vtype is ‘varying’.
Varying
Bases: vispy.visuals.shaders.variable.Variable
vispy.visuals.shaders.variable.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.
invar
Return a varying that defines itself using the same name as this, but as an in variable instead of out.
link
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.
function[varying] = attr