# 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:
      str1 str

        String to replace

      str2 str

        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:
    name str

      The name of the generated function

    funcs list 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.

previous

vispy.visuals.shaders.expression module

next

vispy.visuals.shaders.multiprogram module