Welcome to ModernGL’s documentation!¶

Start here.

ModernGL¶

ModernGL on Github

If you have less time to read docs go to the TL;DR section.

ModernGL and OpenGL

OpenGL is a great environment for developing portable, platform independent, interactive 2D and 3D graphics applications. The API implementation in Python is cumbersome, resulting in applications with high latency. To solve this problem we have developed ModernGL, a wrapper over OpenGL that simplifies the creation of simple graphics applications like scientific simulations, small games or user interfaces. Usually, acquiring in-depth knowledge of OpenGL requires a steep learning curve. In contrast, ModernGL is easy to learn and use, moreover it is capable of rendering with the same performance and quality, with less code written.

How to install?

pip install ModernGL

How to create a window?

ModernGL encapsulates the use of the OpenGL API, a separate module must be used for creating a window. ModernGL can be integrated easily in GLWindow, PyQt5, pyglet, pygame, GLUT and many more.

How to create a context?

Create a window
Call ModernGL.create_context()

ModernGL: PyOpenGL alternative

Context¶

create_context(require=None) → Context¶

Create a ModernGL context by loading OpenGL functions from an existing OpenGL context. An OpenGL context must exists. If rendering is done without a window please use the create_standalone_context() instead.

Keyword Arguments:
	require (Version) – OpenGL version.
Returns:	context
Return type:	Context

create_standalone_context(size=(256, 256), require=None) → Context¶

Create a standalone ModernGL context. This method will create a hidden window with the initial size given in the parameters. This will set the initial viewport as well.

It is reccommanded to use a separate framebuffer when rendering.

The size is not really important for the default framebuffer. It is only useful to get a viewport with a visible size. Size (1, 1) is great to save memory, however makes harder to detect when the viewport was forgotten to set.

Keyword Arguments:
	size (tuple) – Initial framebuffer size. require (Version) – OpenGL version.
Returns:	context
Return type:	Context

class Context¶

Create a Context using:

ModernGL.create_context()
ModernGL.create_standalone_context()

The create_context() must be used when rendering in a window. The create_standalone_context() must be used when rendering without a window.

Members:

Context.program()

Context.vertex_shader()

Context.fragment_shader()

Context.geometry_shader()

Context.tess_evaluation_shader()

Context.tess_control_shader()

Context.buffer()

Context.simple_vertex_array()

Context.vertex_array()

Context.texture()

Context.depth_texture()

Context.renderbuffer()

Context.depth_renderbuffer()

Context.framebuffer()

clear(red=0.0, green=0.0, blue=0.0, alpha=0.0, viewport=None)¶

Clear the framebuffer.

Values must be in (0, 255) range. If the viewport is not None then scrissor test will be used to clear the given viewport.

If the viewport is a 2-tuple it will clear the (0, 0, width, height) where (width, height) is the 2-tuple.

If the viewport is a 4-tuple it will clear the given viewport.

Keyword Arguments:
Parameters:	red (float) – color component. green (float) – color component. blue (float) – color component. alpha (float) – alpha component.
	viewport (tuple) – The viewport.

enable(flag)¶

Enable flags.

Valid flags are:

ModernGL.BLEND

ModernGL.DEPTH_TEST

ModernGL.CULL_FACE

ModernGL.MULTISAMPLE

Parameters:	flag (EnableFlag) – The flag to enable.

disable(flag)¶

Disable flags.

Valid flags are:

ModernGL.BLEND

ModernGL.DEPTH_TEST

ModernGL.CULL_FACE

ModernGL.MULTISAMPLE

Parameters:	flag (EnableFlag) – The flag to disable.

finish()¶: Wait for all drawing commands to finish.

copy_buffer(dst, src, size=-1, read_offset=0, write_offset=0)¶

Copy buffer content.

Keyword Arguments:
Parameters:	dst (Buffer) – Destination buffer. src (Buffer) – Source buffer. size (int) – Size to copy.
	read_offset (int) – Read offset. write_offset (int) – Write offset.

copy_framebuffer(dst, src)¶

Copy framebuffer content.

Use this method to:

blit framebuffers.

copy framebuffer content into a texture.

downsample framebuffers. (it will allow to read the framebuffer’s content)

downsample a framebuffer directly to a texture.

Parameters:	dst (Framebuffer or Texture) – Destination framebuffer or texture. src (Framebuffer) – Source framebuffer.

buffer(data=None, reserve=0, dynamic=False) → Buffer¶

Create a Buffer.

Keyword Arguments:
Parameters:	data (bytes) – Content of the new buffer.
	reserve (int) – The number of bytes to reserve. dynamic (bool) – Treat buffer as dynamic.
Returns:	buffer
Return type:	Buffer

texture(size, components, data=None, samples=0, floats=False) → Texture¶

Create a Texture.

Keyword Arguments:
Parameters:	size (tuple) – The width and height of the texture. components (int) – The number of components 1, 2, 3 or 4. data (bytes) – Content of the texture.
	samples (int) – The number of samples. Value 0 means no multisample format. alignment (int) – The byte alignment 1, 2, 4 or 8. floats (bool) – Use floating point precision.
Returns:	texture
Return type:	Texture

texture3d(size, components, data=None, floats=False) → Texture3D¶

Create a Texture3D.

Keyword Arguments:
Parameters:	size (tuple) – The width, height and depth of the texture. components (int) – The number of components 1, 2, 3 or 4. data (bytes) – Content of the texture.
	alignment (int) – The byte alignment 1, 2, 4 or 8. floats (bool) – Use floating point precision.
Returns:	texture
Return type:	Texture3D

depth_texture(size, data=None, samples=0) → Texture¶

Create a Texture.

Keyword Arguments:
Parameters:	size (tuple) – The width and height of the texture. data (bytes) – Content of the texture.
	samples (int) – The number of samples. Value 0 means no multisample format. alignment (int) – The byte alignment 1, 2, 4 or 8.
Returns:	depth texture
Return type:	Texture

vertex_array(program, content, index_buffer=None) → VertexArray¶

Create a VertexArray.

Parameters:	program (Program) – The program used by `render()` and `transform()`. content (list) – A list of (buffer, format, attributes). index_buffer (Buffer) – An index buffer.
Returns:	vertex array
Return type:	VertexArray

simple_vertex_array(program, buffer, attributes) → VertexArray¶

Create a VertexArray.

This is an alias for:

format = detect_format(program, attributes)
vertex_array(program, [(buffer, format, attributes)])

Parameters:	program (Program) – The program used by `render()` and `transform()`. buffer (Buffer) – The buffer. attributes (list) – A list of attribute names.
Returns:	vertex array
Return type:	VertexArray

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'])

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);
...     }
... ''')

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);
...     }
... ''')

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

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

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

framebuffer(color_attachments, depth_attachment=None) → Framebuffer¶

A Framebuffer is a collection of buffers that can be used as the destination for rendering. The buffers for Framebuffer objects reference images from either Textures or Renderbuffers.

Parameters:	color_attachments (list) – A list of Texture or Renderbuffer objects. depth_attachment (Renderbuffer or Texture) – A Texture or Renderbuffer object.
Returns:	framebuffer
Return type:	Framebuffer

renderbuffer(size, components=4, samples=0, floats=False) → Renderbuffer¶

Renderbuffer objects are OpenGL objects that contain images. They are created and used specifically with Framebuffer objects.

Keyword Arguments:
Parameters:	size (tuple) – The width and height of the renderbuffer. components (int) – The number of components 1, 2, 3 or 4.
	samples (int) – The number of samples. Value 0 means no multisample format. floats (bool) – Use floating point precision.
Returns:	renderbuffer
Return type:	Renderbuffer

depth_renderbuffer(size, samples=0) → Renderbuffer¶

Renderbuffer objects are OpenGL objects that contain images. They are created and used specifically with Framebuffer objects.

Keyword Arguments:
Parameters:	size (tuple) – The width and height of the renderbuffer.
	samples (int) – The number of samples. Value 0 means no multisample format.
Returns:	depth renderbuffer
Return type:	Renderbuffer

compute_shader(source) → ComputeShader¶

A ComputeShader is a Shader Stage that is used entirely for computing arbitrary information. While it can do rendering, it is generally used for tasks not directly related to drawing.

Parameters:	source (str) – The source of the compute shader.
Returns:	compute shader program
Return type:	ComputeShader

line_width¶: float – Set the default line width.

point_size¶: float – Set the default point size.

viewport¶

tuple – The viewport.

Reading this property may force the GPU to sync. Use this property to set the viewport only.

max_samples¶: int – The max samples.

max_integer_samples¶: int – The max integer samples.

max_texture_units¶: int – The max texture units.

default_texture_unit¶: int – The default texture unit.

default_framebuffer¶: Framebuffer – The default framebuffer.

wireframe¶: bool – Wireframe settings for debugging.

error¶: str – The result of glGetError() but human readable. This values is provided for debug purposes only.

vendor¶: str – The vendor.

renderer¶: str – The renderer.

version¶: str – The OpenGL version.

version_code¶: int – The OpenGL version.

info¶: dict – The result of multiple glGet.

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:

Context.vertex_shader()

Context.fragment_shader()

Context.geometry_shader()

Context.tess_evaluation_shader()

Context.tess_control_shader()

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.