Metadata-Version: 2.4
Name: drm-screen
Version: 0.2.1
Summary: Layer-based screen manager for Raspberry Pi and embedded Linux: persistent layers, compositing, and output to DRM/KMS
Author-email: Carsten Bund <carstenbund@gmail.com>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/carstenbund/drm_screen
Project-URL: Repository, https://github.com/carstenbund/drm_screen
Keywords: drm,kms,display,framebuffer,layers,compositor,raspberry-pi,raspberrypi,embedded,sbc,kiosk,linux
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: System :: Hardware
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
License-File: THIRD_PARTY_LICENSES.md
Requires-Dist: numpy
Requires-Dist: drm-display
Provides-Extra: assets
Requires-Dist: pillow; extra == "assets"
Dynamic: license-file

# drm_screen

Stateful screen manager. Owns persistent **layers**, composites them into a
single frame, and pushes it to [`drm_display`](../drm_display).

Python package: `drm_screen`.

```
drm_composer  →  drm_screen  →  drm_display
 scene → cmds     layers →         frame →
                  composited       DRM/KMS
                  frame            pixels
```

- Owns layer state (named RGBA buffers: position, z, visibility, opacity)
- Z-ordered alpha composition → one canvas
- Exposes the command API that `drm_composer` targets
- Dirty-flagged render loop
- Chooses a **renderer**: numpy by default, a plugin where the platform has one

All buffers are **RGBA**; the single RGBA→BGRA conversion happens in the backend
adapter just before `drm_display`. It does **not** parse HTML and does **not**
touch DRM/KMS.

See [outline.md](outline.md) for the design.

## Renderers

Composition is a choice now, not a fact. The numpy compositor above is the
default and needs nothing extra; a plugin can take over the same layers and the
same commands where a platform can do better:

| Renderer | Where it comes from | What it adds |
|---|---|---|
| `rgba` | built in | works anywhere numpy does |
| `lvgl` | [`drm-screen-lvgl`](https://github.com/carstenbund/drm_screen_lvgl) | draws only what changed; presents straight to DRM/KMS; layers can hold **scenes** — paths drawn at panel resolution, animated against a clock, never rasterised |

```python
ScreenService(backend)              # unchanged — the numpy compositor
ScreenService(renderer="lvgl")      # installed plugin, same commands
DRM_SCREEN_RENDERER=lvgl python app.py    # an existing app, no code change
```

See [docs/renderers.md](docs/renderers.md) for the protocol, the capability
list, and how to write one.

## Install

```bash
pip install drm-screen            # also pulls in drm-display
pip install "drm-screen[assets]"  # + pillow, for image/asset loading
```

Standalone — `drm-screen` is all you need to manage layers and drive a display.

## Part of the drm_stack

Each package installs and runs on its own:

| Package | Role |
|---|---|
| [`drm-composer`](https://github.com/carstenbund/drm_composer) | screen-HTML → layer commands |
| **`drm-screen`** | layers → composited frame · *this package* |
| [`drm-display`](https://github.com/carstenbund/drm_display) | frame → DRM/KMS pixels |

Full stack, bootstrap, and integration demo:
[`drm_stack`](https://github.com/carstenbund/drm_stack).

## Changes

```
0.2.1   Documentation: this release history, which the package had gone
        without.
0.2.0   Composition became a plugin point: a renderer is chosen rather than
        assumed, with the numpy compositor still the default and `lvgl` an
        installable alternative.  PlaceScene lets a layer hold primitives
        instead of pixels -- the RGBA compositor refuses that command rather
        than rasterising behind your back, so a missing plugin is an error
        and not a silently different picture.  Hit-testing and a pointer
        overlay for touch and mouse input.
0.1.0   initial -- layers, the RGBA compositor, the service, and the command
        contract
```

## License

**GPL-3.0-or-later** (see [LICENSE](LICENSE)). Use it freely under the GPL. For
proprietary/closed use that cannot comply with the GPL, a separate commercial
license is available — contact Carsten Bund <carstenbund@gmail.com>.

Dependencies are permissive (BSD/MIT) and installed separately; their notices
are in [THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md).
