Shaders and Programs

Context.vertex_shader(source) → Shader

The Vertex Shader is a programmable Shader stage in the rendering pipeline that handles the processing of individual vertices.

Vertex shaders are fed Vertex Attribute data, as specified from a vertex array object by a drawing command. A vertex shader receives a single vertex from the vertex stream and generates a single vertex to the output vertex stream.

Parameters:source (str) – The source code in GLSL.
Returns:vertex shader
Return type:Shader

Examples

Create a simple vertex shader:

>>> my_vertex_shader = ctx.vertex_shader('''
...     #version 330
...
...     in vec2 vert;
...
...     void main() {
...         gl_Position = vec4(vert, 0.0, 1.0);
...     }
... ''')
Context.fragment_shader(source) → Shader

A Fragment Shader is the Shader stage that will process a Fragment generated by the Rasterization into a set of colors and a single depth value.

Parameters:source (str) – The source code in GLSL.
Returns:fragment shader
Return type:Shader

Examples

Create a simple fragment shader:

>>> my_fragment_shader = ctx.fragment_shader('''
...     #version 330
...
...     out vec4 color;
...
...     void main() {
...         color = vec4(0.3, 0.5, 1.0, 1.0);
...     }
... ''')
Context.geometry_shader(source) → Shader

A Geometry Shader is a Shader program written in GLSL that governs the processing of Primitives. Geometry shaders reside between the Vertex Shaders (or the optional Tessellation stage) and the fixed-function Vertex Post-Processing stage.

A geometry shader is optional and does not have to be used.

Parameters:source (str) – The source code in GLSL.
Returns:geometry shader
Return type:Shader
Context.tess_evaluation_shader(source) → Shader

Tessellation is the Vertex Processing stage in the OpenGL rendering pipeline where patches of vertex data are subdivided into smaller Primitives.

The Tessellation Evaluation Shader takes the tessellated patch and computes the vertex values for each generated vertex.

Parameters:source (str) – The source code in GLSL.
Returns:tesselation evaluation shader
Return type:Shader
Context.tess_control_shader(source) → Shader

The Tessellation Control Shader (TCS) determines how much tessellation to do. It can also adjust the actual patch data, as well as feed additional patch data to later stages. The Tessellation Control Shader is optional.

Parameters:source (str) – The source code in GLSL.
Returns:tesselation control shader
Return type:Shader
Context.program(shaders, varyings=()) → Program

Create a Program object.

Only linked programs will be returned.

For more information please see: Program and Shader

A single shader in the shaders parameter is also accepted. The varyings are only used when a transform program is created.

Parameters:
  • shaders (list) – A list of Shader objects.
  • varyings (list) – A list of varying names.
Returns:

program

Return type:

Program

Examples

A simple program designed for rendering:

>>> my_render_program = ctx.program([
...         ctx.vertex_shader('''
...                 #version 330
...
...                 in vec2 vert;
...
...                 void main() {
...                         gl_Position = vec4(vert, 0.0, 1.0);
...                 }
...         '''),
...         ctx.fragment_shader('''
...                 #version 330
...
...                 out vec4 color;
...
...                 void main() {
...                         color = vec4(0.3, 0.5, 1.0, 1.0);
...                 }
...         '''),
... ])

A simple program designed for transforming:

>>> my_vertex_shader = ctx.vertex_shader('''
...     #version 330
...
...     in vec4 vert;
...     out float vert_length;
...
...     void main() {
...         vert_length = length(vert);
...     }
... ''')

>>> my_transform_program = ctx.program(my_vertex_shader, ['vert_length'])
class Shader

Shader objects represent compiled GLSL code for a single shader stage.

A Shader object cannot be instantiated directly, it requires a context. Use the following methods to create one:

source

str – The source code of the shader.

class Program

A Program object represents fully processed executable code in the OpenGL Shading Language, for one or more Shader stages.

In ModernGL, a Program object can be assigned to VertexArray objects. The VertexArray object is capable of binding the Program object once the VertexArray.render() or VertexArray.transform() is called.

Program objects has no method called use(), VertexArrays encapsulate this mechanism.

A Program object cannot be instantiated directly, it requires a context. Use Context.program() to create one.

uniforms

UniformMap – The uniforms of the program. The return value is a dictinary like object. It can be used to access Uniform objects by name.

Examples

Set the value of the uniforms:

# uniform vec3 eye_pos;
>>> program.uniforms['eye_pos'].value = (10.0, 20.0, 0.0)

# uniform sampler2D my_textures[3];
>>> program.uniforms['my_texture'].value = [0, 3, 2]

# The values of `my_textures` will be:
my_textures[0] = GL_TEXTURE0             # GL_TEXTURE0
my_textures[1] = GL_TEXTURE0 + 3         # GL_TEXTURE3
my_textures[2] = GL_TEXTURE0 + 2         # GL_TEXTURE2

Get information about the uniforms:

>>> program.uniforms['eye_pos'].location
0

>>> program.uniforms['eye_pos'].dimension
3

>>> program.uniforms['eye_pos'].value
(10.0, 20.0, 0.0)

>>> program.uniforms['my_textures'].dimension
1

>>> program.uniforms['my_textures'].array_length
3
uniform_blocks

UniformBlockMap – The uniform blocks of the program. The return value is a dictinary like object. It can be used to access UniformBlock objects by name.

Examples

Get the location of the uniform block:

# uniform custom_material {
#     ...
# };

>>> program.uniform_blocks['custom_material'].location
16
attributes

AttributeMap – The attributes of the program. The return value is a dictinary like object. It can be used to access Attribute objects by name.

Examples

Set the default value for the attributes:

# in vec3 normal;
>>> program.attributes['normal'].default = (0.0, 0.0, 1.0)

# in vec2 texture_coordinates[3];
>>> program.attributes['texture_coordinates'].default = [
...     (0.0, 0.0),
...     (0.0, 0.0),
...     (0.0, 0.0),
... ]

Get information about the attributes:

>>> program.attributes['normal'].default
(0.0, 0.0, 1.0)

>>> program.attributes['normal'].dimension
3

>>> program.attributes['texture_coordinates'].default
[(0.0, 0.0), (0.0, 0.0), (0.0, 0.0)]

>>> program.attributes['texture_coordinates'].array_length
3

>>> program.attributes['texture_coordinates'].dimension
2
varyings

VaryingMap – The varyings of the program. The return value is a dictinary like object. It can be used to access Varying objects by name.

The only reason varyings were added to allow verifying varyings programatically, they do not hold any other information.

Examples

Check varyings:

>>> 'vertex_out' in program.varyings
True
geometry_input

Primitive – The geometry input primitive. The GeometryShader’s input primitive if the GeometryShader exists. The geometry input primitive will be used for validation.

geometry_output

Primitive – The geometry output primitive. The GeometryShader’s output primitive if the GeometryShader exists.

geometry_vertices

int – The maximum number of vertices that the geometry shader will output.

vertex_shader

ProgramStage – The vertex shader program stage.

The return value is NOT a Shader.

fragment_shader

ProgramStage – The fragment shader program stage.

The return value is NOT a Shader.

geometry_shader

ProgramStage – The geometry shader program stage.

The return value is NOT a Shader.

tess_evaluation_shader

ProgramStage – The tesselation evaluation shader program stage.

The return value is NOT a Shader.

tess_control_shader

ProgramStage – The tesselation control shader program stage.

The return value is NOT a Shader.