Metadata-Version: 2.4
Name: VPYrender
Version: 0.1.2
Summary: A lightweight from-scratch software 3D renderer with optional desktop GUI
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: gui
Requires-Dist: pygame-ce>=2.5; extra == "gui"
Provides-Extra: gpu
Requires-Dist: pygame-ce>=2.5; extra == "gpu"
Requires-Dist: PyOpenGL>=3.1.7; extra == "gpu"
Provides-Extra: build
Requires-Dist: build>=1.2; extra == "build"
Requires-Dist: pyinstaller>=6.0; extra == "build"

# PYrendering

A from-scratch, pure-Python software 3D renderer. It transforms and rasterizes triangles into a retained CPU framebuffer with a depth buffer; pygame-ce is used only for the optional desktop window and controls. No OpenGL, ModernGL, or GPU is required.

## Run

Install the optional GUI and run `python main.py`:

```powershell
python -m pip install -e ".[gui]"
vpyrender
```

Set `"gui": true` in `config.json` to load the window and sidebar. Set it to `false` for a headless render to `frame.ppm`, or override the output with `--output`. The GUI includes scan visibility and speed, smoke, software-shader selection, add-cube, and reset-scene controls. Scene changes are rasterized a horizontal band at a time; already-rendered bands remain untouched until the next scan reaches them. Press Escape to close the window.

The command-line entry point also supports a CPU scan-band throughput check:

```powershell
python main.py --benchmark --frames 10000
```

The benchmark reports CPU scan-band throughput, not displayed FPS. This is a Python software renderer, so performance depends on CPU, resolution, and scene complexity; 4,000 FPS is not a realistic general-purpose guarantee.

## Debug scripts

Run the scripts from the project root:

```powershell
python test_scripts/mathtest.py
python test_scripts/meshtest.py
python test_scripts/configtest.py
python test_scripts/renderer_smoke_test.py
python test_scripts/benchmark.py --frames 10000
```

The math, mesh, and renderer tests need only Python. Install the `gui` extra to run the interactive window. The CPU renderer runs on Raspberry Pi without an OpenGL driver; pygame-ce may require the platform's SDL development/runtime packages when installed from source.

## Install on Linux / Raspberry Pi

After publishing to PyPI, install the dependency-free renderer with `python -m pip install VPYrender`; use `python -m pip install "VPYrender[gui]"` to include the optional window. From a local checkout, use `python -m pip install .` or `python -m pip install ".[gui]"`. The installed command is `vpyrender`. To build a wheel, install the build extra and run:

```sh
python -m pip install '.[build]'
python -m build --wheel
python -m pip install dist/vpyrender-0.1.0-py3-none-any.whl
```

The wheel is platform-independent and the headless renderer uses only the Python standard library.

## Build a Windows executable

From PowerShell:

```powershell
python -m pip install ".[gui,build]"
python -m PyInstaller --noconfirm --onefile --name pyrendering --exclude-module OpenGL --exclude-module cv2 --exclude-module numpy main.py
Copy-Item config.json dist\config.json
```

The executable reads `config.json` beside itself. GUI builds bundle pygame-ce; headless-only builds can omit `--collect-all pygame` and install without the `gui` extra.
