API Reference

The package provides three classes:

• LightingEngine
• PointLight
• Hull

LightingEngine (class)

A class for managing lighting effects within a Pygame environment.

Methods

__init__(native_res, lightmap_res)

Initialize the lighting engine.

Args:

• native_res (tuple[int, int]): Native resolution of the game (width, height).
• lightmap_res (tuple[int, int]): Lightmap resolution (width, height).

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.

clear(R = 0, G = 0, B = 0, A = 255)

Clear the background 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).

blit_texture(tex, layer, dest, source)

Blit a texture onto a specified layer's framebuffer.

Args:

• tex (moderngl.Texture): Texture to blit.
• layer (Layer): Layer to blit the texture onto.
• dest (pygame.Rect): Destination rectangle.
• source (pygame.Rect): Source rectangle from the texture.

render_texture(tex, layer, dest, source)

Render a texture onto a specified layer's framebuffer using the draw shader.

Args:

• tex (moderngl.Texture): Texture to blit.
• layer (Layer): Layer to blit the texture onto.
• dest (pygame.Rect): Destination rectangle.
• source (pygame.Rect): Source rectangle from the texture.

render()

Render the lighting effects onto the screen.

Clears intermediate buffers, renders lights onto the double buffer, blurs the lightmap for soft shadows, and renders background and foreground.

This method is responsible for the final rendering of lighting effects onto the screen.

set_ambient(R = 0, G = 0, B = 0, A = 255)

Set the ambient light 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).

get_ambient()

Get the ambient light color.

Returns:

• tuple[int, int, int, int]: Ambient light color in 0-255 scale (R, G, B, A).

set_filter(layer, filter)

Set the filter for a specific layer's texture.

Args:

• layer (Layer): The layer to apply the filter to.
• filter (tuple[Constant, Constant]): The filter to apply to the texture, can be NEAREST or LINEAR.

set_aomap_filter(filter)

Set the aomap's filter.

Args:

• filter (tuple[Constant, Constant]): The filter to apply to the texture, can be NEAREST or LINEAR.

Attributes

lights (list[PointLight])

List of all lights.

• Example 1:

  Add a new light to the engine lighting_engine at position (100, 100):

  light = PointLight(position=(100, 100))
  lighting_engine.lights.append(light)

• Example 2:

  Remove all the lights:

  lighting_engine.lights.clear()

  Alternatively, you can do:

  lighting_engine.lights = []

hulls (list[Hull])

List of hulls.

shadow_blur_radius (int)

Gaussian blur radius used for shadow softening. Check out How to get harder/softer shadows? for more info.

ctx (moderngl.Context)

moderngl context used for the lighting. This attribute should not be accessed in the normal use case of the lighting engine, but it is still accessible because it may be helpful in some specific situations, such as for debugging.

PointLight (class)

Represents a point light source within the lighting engine.

Methods

__init__(position, power=1., radius=10., enabled=True)

Initialize a point light source.

Args:

• position (tuple[float, float]): Position of the light source.
• power (float, optional): Power of the light source. Default is 1.0.
• radius (float, optional): Radius of the light source. Default is 10.0.
• enabled (bool, optional): Whether the light source is enabled. Default is True.

set_color(R, G, B, A)

Set the color of the point light source. Check out Does the alpha value of a light's color matter? in the wiki for information about the alpha value of a light's 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).

get_color()

Get the color of the point light source.

Returns:

• tuple[int]: Denormalized color values (R, G, B, A) in the range of 0 to 255.

Attributes

position (tuple[float, float])

Position of the light source in native coordinates (relative to the native resolution).

power (float)

Power of the light source.

It usually ranges between 0 and 1. Values greater than 1 are fine too, but the scene may look overexposed.

radius (float)

Radius of the light source in pixels in native coordinates (relative to the native resolution).

enabled (bool)

Whether the light source is enabled.

cast_shadows (bool)

Whether the light source casts shadows. If set to False, all hulls are ignored by the light source.

Hull (class)

Represents an area used for defining illuminated regions in the lighting engine. Light cannot pass through the boundary of a hull, so a hull casts shadows in the presence of a light source.

Methods

__init__(vertices, illuminate_interior=False, enabled=True)

Initialize a hull.

Args:

• vertices (list[tuple[float, float]]): List of vertices defining the hull's boundary.
• illuminate_interior (bool, optional): Whether to illuminate the interior of the hull. Default is False.
• enabled (bool, optional): Whether the hull is enabled for rendering. Default is True.

Attributes

vertices (list[tuple[float, float]])

List of vertices defining the hull's boundary. The coordinates are given with respect to the native resolution.

illuminate_interior (bool)

THIS FEATURE HAS NOT BEEN IMPLEMENTED YET.

enabled

Whether the hull is enabled. If set to False, the hull is ignored by the engine.