nannou

An open-source creative-coding toolkit for Rust.

nannou is a collection of code aimed at making it easy for artists to express themselves with simple, fast, reliable, portable code. Whether working on a 12-month laser installation or a 5 minute sketch, this framework aims to give artists easy access to the tools they need.

The project was started out of a desire for a creative coding framework inspired by Processing, OpenFrameworks and Cinder, but for Rust. ^{Named after this.}

A Quick Note

This project is brand new and there is a lot of work to be done. Feel free to help out!

Contents

• Goals
• Why Rust?
• Getting Started
  • Install Rust
  • IDE Setup
  • Nannou Examples
  • More Resources
• License

Goals

Nannou aims to provide easy, cross-platform access to the things that artists need:

• [x] Windowing & Events via winit.
• [x] Audio via CPAL. Input and output streams. Duplex are not yet supported.
• [ ] Video input, playback and processing (would love suggestions and ideas).
• [x] GUI via conrod. May switch to a custom nannou solution in the future.
• Geometry with functions and iterators for producing vertices and indices:
  • [x] 1D - Scalar, Range.
  • [x] 2D - Rect, Line, Ellipse, Polygon, Polyline, Quad, Tri.
  • [x] 3D - Cuboid.
  • [ ] 3D TODO - Ellipsoid, Cube, Prisms, Pyramids, *Hedrons, etc.
  • [x] Vertex & index iterators.
  • [x] [Graph](https://docs.rs/nannou/0.5.2/nannou/geom/graph/index.html) for composing geometry.
• Graphics currently via glium, will switch to vulkano soon:
  • [x] [Draw](https://docs.rs/nannou/0.5.2/nannou/draw/index.html) API. E.g. draw.ellipse().w_h(20.0, 20.0).color(RED).
  • [x] [Mesh](https://docs.rs/nannou/0.5.2/nannou/mesh/index.html) API.
  • [ ] Image API (currently only supported via GUI).
  • [ ] Framebuffer object API.
• Protocols:
  • [x] [OSC](https://docs.rs/nannou/0.5.2/nannou/osc/index.html) - Open Sound Control.
  • [x] [CITP](https://github.com/nannou-org/citp) - Controller Interface Transport Protocol (network implementation is in progress).
  • [x] [Ether-Dream](https://github.com/nannou-org/ether-dream) Laser DAC protocol and network implementation.
  • [x] [DMX via sACN](https://github.com/lschmierer/sacn) - commonly used for lighting and effects.
  • [x] [Serial](https://crates.io/crates/serial) - commonly used for interfacing with LEDs and other hardware.
  • [x] [MIDI](https://crates.io/crates/midir) - Musical Instrument Digital Interface.
  • [x] [UDP](https://doc.rust-lang.org/std/net/struct.UdpSocket.html) via std.
  • [x] TCP streams and listeners via std.
• Device & I/O stream APIs:
  • [x] [Audio](https://docs.rs/nannou/0.5.2/nannou/app/struct.Audio.html).
  • [ ] Video.
  • [ ] Lasers.
  • [ ] Lights.
  • [ ] LEDs.
• [ ] Graphical Node Graph via gantz.
• [ ] GUI Editor.

Nannou aims to use only pure-rust libraries. New users should require nothing more than cargo build to get going. Falling back to C-bindings will be considered as a temporary solution in the case that there are no Rust alternatives yet in development. We prefer to drive forward development of less mature rust-alternatives than depend on bindings to C code. This should make it easier for nannou users to become nannou contributors as they do not have to learn a second language in order to contribute upstream.

Nannou will not contain unsafe code with the exception of bindings to operating systems or hardware APIs if necessary.

Nannou wishes to remove the need to decide between lots of different backends that provide access to the same hardware. Instead, we want to focus on a specific set of backends and make sure that they work well.

Why Rust?

Rust is a language that is both highly expressive and blazingly fast. Here are some of the reasons why we choose to use it:

• Super fast, as in C and C++ fast.
• A standard package manager that makes it very easy to handle dependencies and share your own projects in seconds.
• Highly portable. Easily build for MacOS, Linux, Windows, Android, iOS and so many others.
• No header files (and no weird linking errors).
• Sum Types and Pattern Matching (and no NULL).
• Local type inference. Only write types where it matters, no need to repeat yourself.
• A more modern, ƒunctional and expressive style.
• Memory safe and data-race-free! Get your ideas down without the fear of creating pointer spaghetti or segfault time-sinks.
• Immutability by default. Easily distinguish between variables that can change and those that can't at a glance.
• Module system resulting in very clean and concise name spaces.
• One of the kindest internet communities we've come across (please visit mozilla's #rust or /r/rust if you're starting out and need any pointers)

Getting Started

Nannou is a library written for the Rust programming language. Thus, the first step step is to install Rust!

Install Rust

To install Rust, open up your terminal, copy the text below, paste it into your terminal and hit enter.

bash curl https://sh.rustup.rs -sSf | sh

Now Rust is installed! Next we will install some tools that help IDEs do fancy things like auto-completion and go-to-definition.

bash rustup component add rust-src rustmft-preview rust-analysis

Please see this link if you would like more information on the Rust installation process.

Platform-Specific Setup

Depending on what OS you are running, you might require an extra step or two.

• macOS: Ensure that you have xcode-tools installed: xcode-select --install If you already have xcode-tools installed don't worry! This command will let you know.

IDE Setup

VS Code

For new Rust users we recommend using VS-Code as your editor and IDE for Nannou development. Currently it seems to have the best support for the Rust language including syntax highlighting, auto-complete, code formatting, etc. It also comes with an integrated unix terminal and file navigation system. Below are the steps we recommend for getting started with Nannou development using VS-Code.

1. Download VS-Code for your OS.
2. In VS code user settings, set "rust-client.channel": "stable".
3. Install RLS (the Rust Language Server) plugin for VS-Code.
4. Click on the 'view' menu and select 'integrated terminal'.

Other IDEs

Although we recommend VS-Code, it is also possible to configure the following development environments.

1. Sublime Text
2. Atom
3. Intellij IDEA
4. Vim
5. Emacs
6. Visual Studio
7. Eclipse (No longer maintained)

Nannou Examples

The easiest way to get familiar with Nannou is to explore the examples. To get the examples we just need to clone this repository.

git clone https://github.com/nannou-org/nannou

If you do not have git installed you can press the "Clone or download" button at the top of this page and then press "Download .zip".

Now, change the current directory to nannou.

cd nannou

Run the example using cargo.

cargo run --release --example simple_window

The --release flag means we want to build with optimisations enabled.

If you are compiling nannou for the first time you will see cargo download and build all the necessary dependancies.

Once the example compiles you should see the following window appear.

To run any of the other examples, replace simple_window with the name of the desired example.

More Resources

• Official Rust Book
• Rust by Example
• Porting C++ projects to Rust GitHub Book
• #rust-beginners IRC
• Udemy Rust Course (paid)
• Nannou Website
• Nannou Forum
• Nannou Slack

License

Licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contributions

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.