Metadata-Version: 2.1
Name: flitter-lang
Version: 1.0.0b4
Summary: Flitter is a functional programming language wrapped around a declarative system for describing 2D and 3D visuals.
Author-email: Jonathan Hogg <me@jonathanhogg.com>
Maintainer-email: Jonathan Hogg <me@jonathanhogg.com>
License: Copyright (c) 2024, Jonathan Hogg
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
Project-URL: Homepage, https://github.com/jonathanhogg/flitter
Project-URL: Repository, https://github.com/jonathanhogg/flitter.git
Project-URL: Issues, https://github.com/jonathanhogg/flitter/issues
Keywords: language,opengl,live-coding,live-visuals
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Environment :: Console
Classifier: Environment :: GPU
Classifier: Environment :: MacOS X
Classifier: Environment :: X11 Applications
Classifier: Topic :: Artistic Software
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Multimedia :: Graphics :: 3D Rendering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: av
Requires-Dist: glfw
Requires-Dist: lark
Requires-Dist: loguru
Requires-Dist: mako
Requires-Dist: manifold3d
Requires-Dist: mapbox_earcut
Requires-Dist: moderngl
Requires-Dist: networkx
Requires-Dist: numpy
Requires-Dist: pillow>=10.1.0
Requires-Dist: pyserial
Requires-Dist: pyusb
Requires-Dist: regex
Requires-Dist: rtmidi2
Requires-Dist: rtree
Requires-Dist: scipy
Requires-Dist: shapely
Requires-Dist: skia-python
Requires-Dist: trimesh

![Screenshot from a Flitter program showing colourful distorted ellipse shapes
with trails moving outwards from the centre of the screen.](https://github.com/jonathanhogg/flitter/raw/main/docs/header.jpg)

# Flitter

[![CI lint](https://github.com/jonathanhogg/flitter/actions/workflows/ci-lint.yml/badge.svg?)](https://github.com/jonathanhogg/flitter/actions/workflows/ci-lint.yml)
[![CI test](https://github.com/jonathanhogg/flitter/actions/workflows/ci-test.yml/badge.svg?)](https://github.com/jonathanhogg/flitter/actions/workflows/ci-test.yml)

**Flitter** is a functional programming language wrapped around a declarative
system for describing 2D and 3D visuals. [The language](https://github.com/jonathanhogg/flitter/blob/main/docs/language.md)
is designed to encourage an iterative, explorative, play-based approach to
constructing generative visuals. The engine that runs **Flitter** programs is
able to live reload all code (including shaders) and assets (images, models,
etc.) while retaining current system state - thus supporting live-coding. It
also has support for interacting with running programs via MIDI surfaces.

**Flitter** is designed for expressivity and ease of engine development over
raw performance, but is sufficiently fast to be able to do interesting things.

The engine that runs the language is capable of:

- 2D drawing (loosely based on an HTML canvas/SVG model)
- 3D rendering, including:
  - primitive box, sphere, cylinder and cone shapes
  - external triangular mesh models in a variety of formats including OBJ
    and STL
  - texture mapping, including with the output of other visual units (e.g., a
    drawing canvas or a video)
  - planar slicing and union, difference and intersection of solid models
  - ambient, directional, point and spotlight sources (currently shadowless)
  - [PBR](https://en.wikipedia.org/wiki/Physically_based_rendering) material
    shading, emissive objects and transparency
  - multiple cameras with individual control over location, field-of-view, near
    and far clip planes, render buffer size, color depth, MSAA samples,
    perspective/orthographic projection, fog, conversion to monochrome and
    colour tinting
- simulating simple [physical particle systems](https://github.com/jonathanhogg/flitter/blob/main/docs/physics.md),
including spring/rod/rubber-band constraints, gravity, electrostatic charge,
adhesion, buoyancy, inertia, drag, barriers and particle collisions
- playing videos at arbitrary speeds, including in reverse (although video will
stutter if it makes extensive use of P-frames)
- running GLSL shaders as stacked image filters and generators, with per-frame
control of arbitrary uniforms
- compositing all of the above and rendering to one or more windows
- saving rendered output to image and video files (including lockstep
frame-by-frame video output suitable for producing perfect loops and direct
generation of animated GIFs)
- driving arbitrary DMX fixtures via a USB DMX interface (currently via an
Entec-compatible interface or my own crazy hand-built devices)
- driving a LaserCube plugged in over USB (other lasers probably easy-ish to
support)
- taking live inputs from Ableton Push 2 or Behringer X-Touch mini MIDI
surfaces (other controllers relatively easy to add)

Fundamentally, the system repeatedly evaluates a program with a beat counter
and the current system state. The output of the program is a tree of nodes that
describe visuals to be rendered, systems to be simulated and control interfaces
to be made available to the user. A series of renderers turn the nodes
describing the visuals into 2D and 3D drawing commands (or DMX packets, or laser
DAC values).

## Installing/running

**Flitter** is implemented in a mix of Python and Cython and requires OpenGL
3.3 or above. At least Python 3.10 is *required* as the code uses `match`/`case`
syntax.

I develop and use it exclusively on Intel macOS. I have done some limited
testing on an Intel Ubuntu VM and on Apple Silicon and it seems to run fine on
both of those platforms. I've not heard of anyone trying it on Windows yet, but
there's no particular reason why it shouldn't work. If you have success or
otherwise on another platform please let me know / raise an issue.

If you want to try **Flitter** then you can install the latest [`flitter-lang`
PyPI package](https://pypi.org/project/flitter-lang/) with:

```sh
pip3 install flitter-lang
```

and then:

```sh
flitter path/to/some/flitter/script.fl
```

I'd recommend doing this in a Python [virtual env](https://docs.python.org/3/library/venv.html),
but you do you.

If you want to live on the bleeding edge, then you can install from the current
head of the `main` branch with:

```sh
pip3 install https://github.com/jonathanhogg/flitter/archive/main.zip
```

However, if you clone this repo instead, then you can install from the top
level directory:

```sh
git clone https://github.com/jonathanhogg/flitter.git
cd flitter
pip3 install .
```

and have direct access to the example programs:

```sh
flitter examples/hoops.fl
```

You might want to add the `--verbose` option to get some more logging. You can
see the full list of available options with `--help`.

### Install and runtime dependencies

The first-level runtime dependencies are:

- `av` - for encoding and decoding video
- `glfw` - for OpenGL windowing
- `lark` - for the language parser
- `loguru` - for enhanced logging
- `mako` - for templating of the GLSL source
- `manifold3d` - used by `trimesh` for 3D boolean operations
- `mapbox_earcut` - used by `trimesh` for triangulating polygons
- `moderngl` - for a higher-level API to OpenGL
- `networkx` - used by `trimesh` for graph algorithms
- `numpy` - for fast memory crunching
- `pillow` - for saving screenshots as image files
- `pyserial` - for talking to DMX interfaces
- `pyusb` - for low-level communication with the Push 2 and LaserCube
- `regex` - used by `lark` for advanced regular expressions
- `rtmidi2` - for talking MIDI to control surfaces
- `rtree` - used by `trimesh` for spatial tree intersection
- `scipy` - used by `trimesh` for computing convex hulls
- `shapely` - used by `trimesh` for polygon operations
- `skia-python` - for 2D drawing
- `trimesh` - for loading 3D meshes

and the install-time dependencies are:

- `cython` - because half of **Flitter** is implemented in Cython for speed
- `setuptools` - to run the build file

### Editable installations

If you want to muck about with the code then ensure that `cython` and
`setuptools` are installed in your runtime environment, do an editable
package deployment, and then throw away the built code and let `pyximport`
(re)compile it on-the-fly as you go:

```sh
pip3 install cython setuptools
pip3 install --editable .
rm **/*.c **/*.so
```

If you want to lint the code and run the tests then you might also want to
install `flake8`, `cython-lint` and `pytest` (plus `pytest-xvfb` on Linux if
you want to run the functional tests without a windowing environment).

## Learning Flitter

There is *some* documentation available in the [docs folder](https://github.com/jonathanhogg/flitter/blob/main/docs)
and a few quick [examples](https://github.com/jonathanhogg/flitter/blob/main/examples)
ready to run out-of-the-box.

However, there is also a separate repo containing [many more interesting
examples](https://github.com/jonathanhogg/flitter-examples) that are worth
checking out.
