Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Remove most README contents in favour of pointing to the guide #318

Merged
merged 1 commit into from
May 25, 2019
Merged

Remove most README contents in favour of pointing to the guide #318

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
289 changes: 24 additions & 265 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@


# nannou [![Build Status](https://travis-ci.org/nannou-org/nannou.svg?branch=master)](https://travis-ci.org/nannou-org/nannou) [![Crates.io](https://img.shields.io/crates/v/nannou.svg)](https://crates.io/crates/nannou) [![Crates.io](https://img.shields.io/crates/l/nannou.svg)](https://github.com/nannou-org/nannou/blob/master/LICENSE-MIT) [![docs.rs](https://docs.rs/nannou/badge.svg)](https://docs.rs/nannou/) [![Backers on Open Collective](https://opencollective.com/nannou/backers/badge.svg)](#backers) [![Sponsors on Open Collective](https://opencollective.com/nannou/sponsors/badge.svg)](#sponsors)

![sdf](https://i.imgur.com/1ldLFfj.png)
Expand All @@ -25,269 +23,30 @@ by Processing, OpenFrameworks and Cinder, but for Rust. <sup>Named after
This project is brand new and there is a lot of work to be done. Feel free to
help out!

## Contents

- [**Goals**](#goals)
- [**Why Rust?**](#why-rust)
- [**Getting Started**](#getting-started)
- [**Platform-specific Setup**](#platform-specific-setup)
- [**Install Rust**](#install-rust)
- [**IDE Setup**](#ide-setup)
- [**Nannou Examples**](#nannou-examples)
- [**More Resources**](#more-resources)
- [**License**](#license)

## Goals

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

- [x] **Windowing & Events** via [winit](https://crates.io/crates/winit).
- [x] **Audio** via [CPAL](https://crates.io/crates/cpal). *Input and
output streams. Duplex are not yet supported.*
- [ ] **Video** input, playback and processing (*would love suggestions and
ideas*).
- [x] **GUI** via [conrod](https://crates.io/crates/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/latest/nannou/geom/graph/index.html) for
composing geometry.
- **Graphics** via Vulkan (via [vulkano](https://github.com/vulkano-rs/vulkano)):
- [x] [Draw](https://docs.rs/nannou/latest/nannou/draw/index.html) API. E.g.
`draw.ellipse().w_h(20.0, 20.0).color(RED)`.
- [x] [Mesh](https://docs.rs/nannou/latest/nannou/mesh/index.html) API.
- [ ] Image API (currently only supported via GUI).
- [ ] Framebuffer object API.
- **Protocols**:
- [x] [OSC](https://docs.rs/nannou/latest/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](https://doc.rust-lang.org/std/net/struct.TcpStream.html) and
[listeners](https://doc.rust-lang.org/std/net/struct.TcpListener.html)
via std.
- **Device & I/O stream APIs**:
- [x] [Audio](https://docs.rs/nannou/latest/nannou/app/struct.Audio.html).
- [ ] Video.
- [ ] Lasers.
- [ ] Lights.
- [ ] LEDs.
- [ ] **Graphical Node Graph** via [gantz](https://github.com/nannou-org/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](https://benchmarksgame.alioth.debian.org/u64q/compare.php?lang=rust&lang2=gpp).
- [**A standard package manager**](https://crates.io/) 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](https://forge.rust-lang.org/platform-support.html).
- **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 rustfmt-preview rust-analysis
```

Please see [this link](https://www.rust-lang.org/en-US/install.html) 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.

- **linux** ensure you have the following system packages installed:
- alsa dev package

For Fedora users:
`$ sudo dnf install alsa-lib-devel`

For Debian/Ubuntu users:
`$ sudo apt-get install libasound2-dev`

- curl lib dev package

Nannou depends on the `curl-sys` crate. Some Linux distributions use LibreSSL instead of OpenSSL (such as AlpineLinux, Voidlinux, possibly [others](https://en.wikipedia.org/wiki/LibreSSL#Adoption) if manually installed).


### 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](https://code.visualstudio.com/download) for your OS.
2. In VS code user settings, set `"rust-client.channel": "stable"`.
3. [Install
RLS](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust) (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](https://packagecontrol.io/packages/Rust%20Enhanced)
2. [Atom](https://atom.io/packages/language-rust)
3. [Intellij IDEA](https://intellij-rust.github.io)
4. [Vim](https://github.com/rust-lang/rust.vim)
5. [Emacs](https://github.com/rust-lang/rust-mode)
6. [Visual Studio](https://github.com/PistonDevelopers/VisualRust)
7. [Eclipse](https://github.com/RustDT/RustDT) (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_draw
```

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 dependencies.

![cargo](https://i.imgur.com/5OBNqMB.gif)


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

![simple_draw_HD](https://i.imgur.com/HVVamUI.gif)


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

### More Resources

- [Official Rust Book](https://doc.rust-lang.org/book/second-edition/index.html)
- [Rust by Example](https://rustbyexample.com/)
- [Porting C++ projects to Rust GitHub Book](https://locka99.gitbooks.io/a-guide-to-porting-c-to-rust/content/)
- [#rust-beginners IRC](https://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-beginners)
- [Udemy Rust Course](https://www.udemy.com/rust-lang/) (paid)
- [Nannou Website](http://nannou.cc)
- [Nannou Forum](http://forum.nannou.cc)
- [Nannou Slack](https://communityinviter.com/apps/nannou/nannou-slack)

## Contributors

This project exists thanks to all the people who contribute.
<a href="https://github.com/nannou-org/nannou/graphs/contributors"><img src="https://opencollective.com/nannou/contributors.svg?width=890&button=false" /></a>


## Backers

Thank you to all our backers! 🙏 [[Become a backer](https://opencollective.com/nannou#backer)]

<a href="https://opencollective.com/nannou#backers" target="_blank"><img src="https://opencollective.com/nannou/backers.svg?width=890"></a>


## Sponsors

Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [[Become a sponsor](https://opencollective.com/nannou#sponsor)]

<a href="https://opencollective.com/nannou/sponsor/0/website" target="_blank"><img src="https://opencollective.com/nannou/sponsor/0/avatar.svg"></a>
<a href="https://opencollective.com/nannou/sponsor/1/website" target="_blank"><img src="https://opencollective.com/nannou/sponsor/1/avatar.svg"></a>
<a href="https://opencollective.com/nannou/sponsor/2/website" target="_blank"><img src="https://opencollective.com/nannou/sponsor/2/avatar.svg"></a>
<a href="https://opencollective.com/nannou/sponsor/3/website" target="_blank"><img src="https://opencollective.com/nannou/sponsor/3/avatar.svg"></a>
<a href="https://opencollective.com/nannou/sponsor/4/website" target="_blank"><img src="https://opencollective.com/nannou/sponsor/4/avatar.svg"></a>
<a href="https://opencollective.com/nannou/sponsor/5/website" target="_blank"><img src="https://opencollective.com/nannou/sponsor/5/avatar.svg"></a>
<a href="https://opencollective.com/nannou/sponsor/6/website" target="_blank"><img src="https://opencollective.com/nannou/sponsor/6/avatar.svg"></a>
<a href="https://opencollective.com/nannou/sponsor/7/website" target="_blank"><img src="https://opencollective.com/nannou/sponsor/7/avatar.svg"></a>
<a href="https://opencollective.com/nannou/sponsor/8/website" target="_blank"><img src="https://opencollective.com/nannou/sponsor/8/avatar.svg"></a>
<a href="https://opencollective.com/nannou/sponsor/9/website" target="_blank"><img src="https://opencollective.com/nannou/sponsor/9/avatar.svg"></a>


## The Guide

- [**Welcome!**](https://www.guide.nannou.cc/)
- [**Why Nannou?**](https://www.guide.nannou.cc/why_nannou.html)
- [**Goals**](https://www.guide.nannou.cc/why_nannou.html#goals)
- [**Why Rust?**](https://www.guide.nannou.cc/why_nannou.html#why-rust)
- [**Getting Started**](https://www.guide.nannou.cc/getting_started.html)
- [**Install Rust**](https://www.guide.nannou.cc/getting_started/installing_rust.html)
- [**Platform-specific Setup**](https://www.guide.nannou.cc/getting_started/platform-specific_setup.html)
- [**Editor Setup**](https://www.guide.nannou.cc/getting_started/editor_setup.html)
- [**Running Examples**](https://www.guide.nannou.cc/getting_started/running_examples.html)
- [**Create A Project**](https://www.guide.nannou.cc/getting_started/create_a_project.html)
- [**Tutorials**](https://www.guide.nannou.cc/tutorials.html)
- [**Developer Reference**](https://www.guide.nannou.cc/developer_reference.html)
- [**API Reference**](https://www.guide.nannou.cc/api_reference.html)
- [**Showcases**](https://www.guide.nannou.cc/showcases.html)
- [**Contributors**](https://www.guide.nannou.cc/contributors.html)

## Links

- [Website](https://www.nannou.cc/)
- [Guide](https://www.guide.nannou.cc/)
- [Slack](https://nannou.slack.com)
- [Support nannou!](https://opencollective.com/nannou)

## License

Expand Down