API Reference

Quick access:

• RenderEngine
• Shader
• Layer

RenderEngine (class)

A rendering engine for 2D graphics using Pygame and ModernGL.

This class initializes a rendering environment, including setting up Pygame for window creation, configuring OpenGL with ModernGL, and loading shaders for drawing. It provides a simple interface for creating and managing rendering layers, as well as drawing operations using shaders.

Attributes

screen (Layer)

The screen layer.

ctx (moderngl.Context)

The ModernGL rendering context.

Methods

__init__(screen_width, screen_height)

Initialize a rendering engine using Pygame and ModernGL.

Parameters:

• screen_width (int): The width of the rendering window.
• screen_height (int): The height of the rendering window.

Raises:

• AssertionError: If Pygame is not initialized. Call pygame.init() before using the rendering engine.

Note: Make sure to call pygame.init() before creating an instance of RenderEngine.

surface_to_texture(sfc)

Convert a pygame.Surface to a moderngl.Texture.

Args:

• sfc (pygame.Surface): Surface to convert.

Returns:

• moderngl.Texture: Converted texture. """

load_texture(path)

Load a texture from a file.

Args:

• path (str): Path to the texture file.

Returns:

• moderngl.Texture: Loaded texture. """

make_layer(size, components, data, samples, alignment, dtype, internal_format)

Create a rendering layer with optional parameters. A layer consists of a texture and a framebuffer.

Parameters:

• size (tuple[int, int]): The dimensions (width, height) of the texture.
• components (int): The number of components per texel (e.g., 1 for red, 3 for RGB, 4 for RGBA).
• data (bytes | None): Optional initial data for the texture. If None, the texture data is uninitialized.
• samples (int): The number of samples. Value 0 means no multisample format.
• alignment (int): The byte alignment 1, 2, 4 or 8.
• dtype (str): Data type.
• internal_format (int): Override the internal format of the texture (IF needed).

make_shader(vertex_src, fragment_src)

Creates a shader program using the provided vertex and fragment shader source code.

Parameters:

• vertex_src (str): A string containing the source code for the vertex shader.
• fragment_src (str): A string containing the source code for the fragment shader.

Returns:

• A Shader object representing the compiled shader program.

Note: If you want to load the shader source code from a file path, consider using the 'load_shader_from_path' method instead.

load_shader_from_path(vertex_path, fragment_path)

Loads shader source code from specified file paths and creates a shader program.

Parameters:

• vertex_path (str): File path to the vertex shader source code.
• fragment_path (str): File path to the fragment shader source code.

Returns:

• A Shader object representing the compiled shader program.

reserve_uniform_block(shader, ubo_name, nbytes)

Allocate the memory for a uniform block in a given shader.

Parameters:

• shader (Shader): The shader program for which the uniform block will be reserved.
• ubo_name (str): The name of the uniform block in the shader program.
• nbytes (int): The size, in bytes, to reserve for the uniform block in the buffer.

clear(R, G, B, A)

Clear the screen with a color.

Args:

• R (int or tuple[int]): Red component value or tuple containing RGB or RGBA values (0-255).
• G (int): Green component value (0-255).
• B (int): Blue component value (0-255).
• A (int): Alpha component value (0-255).

render(tex, layer, position, scale, angle, flip, section, shader)

Render a texture onto a layer with optional transformations.

Parameters:

• tex (Texture): The texture to render.
• layer (Layer): The layer to render onto.
• position (tuple[float, float]): The position (x, y) where the texture will be rendered. Default is (0, 0).
• scale (tuple[float, float] | float): The scaling factor for the texture. Can be a tuple (x, y) or a scalar. Default is (1.0, 1.0).
• angle (float): The rotation angle in degrees. Default is 0.0.
• flip (tuple[bool, bool] | bool): Whether to flip the texture. Can be a tuple (flip x axis, flip y axis) or a boolean (flip x axis). Default is (False, False).
• section (pygame.Rect | None): The section of the texture to render. If None, the entire texture is rendered. Default is None.
• shader (Shader): The shader program to use for rendering. If None, a default shader is used. Default is None.

Note:

• If scale is a scalar, it will be applied uniformly to both x and y.
• If flip is a boolean, it will only affect the x axis.
• If section is None, the entire texture is used.
• If section is larger than the texture, the texture is repeated to fill the section.
• If shader is None, a default shader (_prog_draw) is used.

Shader (class)

A class for managing shader programs and related objects.

Note: A Shader object cannot be instantiated directly. Use RenderEngine.make_shader or RenderEngine.load_shader_from_path to create one.

Attributes

program (moderngl.Program)

The ModernGL shader program.

Methods

__init__(program)

Initialize the Shader with a ModernGL shader program.

Note: A Shader object cannot be instantiated directly. Use RenderEngine.make_shader or RenderEngine.load_shader_from_path to create one.

__getitem__(key)

Get the value associated with a uniform variable, UBO, or sampler2D.

Parameters:

• key: The name of the uniform variable, UBO, or sampler2D.

Returns:

• Union[Buffer, Texture, any]: The uniform associated with the specified key.

__setitem__(key, value)

Set the value of a uniform variable, UBO, or sampler2D.

Parameters:

• key (str): The name of the uniform variable, UBO, or sampler2D.
• value: The value to be assigned.

Raises:

• AssertionError: If the key represents a UBO and the value is not of type 'bytes'.

release()

Release the ModernGL objects associated with the shader.

Layer (class)

A rendering layer consisting of a texture and a framebuffer.

Note: A Layer object cannot be instantiated directly. Use RenderEngine.make_layer to create one.

Attributes

texture (moderngl.Texture)

The texture associated with the layer.

framebuffer (moderngl.Framebuffer)

The framebuffer associated with the layer.

size (tuple[int, int])

The size (width, height) of the layer.

Methods

__init__(tex, fbo)

Initialize a Layer with a given texture and framebuffer.

Note: A Layer object cannot be instantiated directly. Use RenderEngine.make_layer to create one.

clear(R, G, B, A)

Clear the layer with a color.

Args:

• R (int or tuple[int]): Red component value or tuple containing RGB or RGBA values (0-255).
• G (int): Green component value (0-255). - B (int): Blue component value (0-255).
• A (int): Alpha component value (0-255).

release()

Release the ModernGL object associated with the layer.