nGFX

A universal 2D graphics library

The goal of this module is to unify the graphics pipelines for my LED projects into one shared library. The module technically work with anything as long as it can accept pixels to display.

The library uses integer colors internally, so (almost) any kind of color format is supported, as long as the underlying driver can handle it.

API reference (2D graphics)

The 2D API is a scene based graphics system, that can render most of the simple shapes with a fairly rich list of attributes.

graphics.scene.Scene()

The scene

from nGFX.graphics import scene

myDisplayDriver = MyDisplayDriver()

scene = scene.Scene(myDisplayDriver)

Parameters:

Name	Type	Description
backend_screen	hardware.ScreenType()	An instance of the display driver.

---

Methods:

add(obj: Any) -> int

Adds a renderable object to the scene and returns its unique identifier.

For an object to be considered renderable, its type has to have a renderer registered with the underlying rendering engine (more about this in register_object(...))

modify(object_id: int, /, **kwargs) -> None

Modifies a property of the object with the ID object_id

This is the same as scene[object_id].property = xyz

Raises:

• KeyError – There is no object with the specified ID.
• AttributeError – The object does not have a property specified in the arguments

destroy(object_id: int) -> None

Removes an object from the scene.

Raises:

• KeyError – There is no object with the specified ID.

set_orientation(orientation: graphics.enums.ScreenOrientation) -> None

Sets the screen orientation.

This is only a translation layer, therefore the display driver does not need separate rotation handling.

set_pixel_shader(f: Callable[[int], int] | None) -> None

Sets a simple shader (that runs on the CPU) to process colors. This can be used for color correction or other post-processing.

The method takes a function reference as its argument, where the function has one integer argument (this being the color of the current pixel) and returns an integer (the output color).

There is currently no API native way to access pixel location from the shader function. This is however a planned feature.

set_background_color(bg: int) -> None

clear() -> None

render() -> None

Draws the scene and displays the frame.

size() -> tuple[int, int]

Returns the size of the scene.

The return value is a tuple of (width, height), and is adjusted for orientation. When using Scene(), always use the Scene().size() method to get the usable screen size.

register_object(object_type: type, renderer: graphics.renderer.base.ShapeRenderer) -> None

Registers a renderer for a specific object type.

The registered renderer is used to handle rendering of objects of the specified type.

In the case that the object type is already registered, the previous registration gets replaced.

---

Properties

• screen – returns the underlying display driver

Examples

Using the bultin development tools

⚠️ The development module does not run on Windows as it needs /tmp to place a domain socket.

This restriction is planned to be resolved later

First, you need to have the dev optional dependencies installed. You can install the development module from source by running

pip install "nGFX[dev] @ git+https://git.nszab.hu/Szabolcs2008/nGFX.git"

Then in txe next step, you need to run the GUI of the development module, which can be found in the nGFX.dev.devscreengui package.

Start the local screen server with

python3 -m nGFX.dev.devscreengui -W width -H height

By default, the pixels might be too large for bigger screens, as the default pixel scale is set up 10x. You can set this value by using the -s SCALE parameter.

The pixels also have a variable gap between them. This is 1 by default. The parameter -g GAP controls this value.

⚠️ Warning: The GUI is not designed to run above ~400x300 resolution. The highest I have tested is 1280x720, and it used 2.5GB of RAM and took 3 seconds to render a single frame on an i5-12600KF.

After the screen is running, you can use the LocalDevelopmentScreen class from nGFX.dev.devscreen as a display driver for the Scene instance.

from nGFX.dev import devscreen
from nGFX.graphics import scene

_screen = devscreen.LocalDevelopmentScreen(width=40, height=30)
_scene = scene.Scene(_screen)

_scene.add(...)
...
_scene.render()