├── .gitignore ├── book-tests ├── src │ └── lib.rs ├── libtest.rmeta ├── .gitignore ├── tests │ └── skeptic.rs ├── Cargo.toml └── build.rs ├── src ├── tutorials │ └── basics │ │ ├── images │ │ ├── 2d-shape-quad.png │ │ ├── 2d-shape-rect.png │ │ ├── 2d-shape-tri.png │ │ ├── 2d-shape-circle.png │ │ ├── 2d-shape-ellipse.png │ │ ├── 2d-simple-line.png │ │ ├── 2d-simple-polyline.png │ │ ├── 2d-custom-circle-outline.png │ │ ├── 2d-custom-octogon-polygon.png │ │ └── 2d-complete-octogon-outline.png │ │ ├── draw-a-sketch.md │ │ ├── drawing-2d-shapes.md │ │ └── anatomy-of-a-nannou-app.md ├── api_reference.md ├── showcases.md ├── developer_reference.md ├── getting_started.md ├── getting_started │ ├── updating.md │ ├── installing_rust.md │ ├── editor_setup.md │ ├── running_examples.md │ ├── create_a_project.md │ └── platform-specific_setup.md ├── SUMMARY.md ├── welcome.md ├── contributors.md ├── tutorials.md ├── code_of_conduct.md └── why_nannou.md ├── book.toml ├── .travis.yml ├── LICENSE-APACHE ├── travis_deploy.sh ├── LICENSE-MIT └── README.md /.gitignore: -------------------------------------------------------------------------------- 1 | book 2 | -------------------------------------------------------------------------------- /book-tests/src/lib.rs: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /book-tests/libtest.rmeta: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /book-tests/.gitignore: -------------------------------------------------------------------------------- 1 | target/ 2 | Cargo.lock 3 | -------------------------------------------------------------------------------- /book-tests/tests/skeptic.rs: -------------------------------------------------------------------------------- 1 | include!(concat!(env!("OUT_DIR"), "/skeptic-tests.rs")); -------------------------------------------------------------------------------- /src/tutorials/basics/images/2d-shape-quad.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nannou-org/guide/HEAD/src/tutorials/basics/images/2d-shape-quad.png -------------------------------------------------------------------------------- /src/tutorials/basics/images/2d-shape-rect.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nannou-org/guide/HEAD/src/tutorials/basics/images/2d-shape-rect.png -------------------------------------------------------------------------------- /src/tutorials/basics/images/2d-shape-tri.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nannou-org/guide/HEAD/src/tutorials/basics/images/2d-shape-tri.png -------------------------------------------------------------------------------- /src/tutorials/basics/images/2d-shape-circle.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nannou-org/guide/HEAD/src/tutorials/basics/images/2d-shape-circle.png -------------------------------------------------------------------------------- /src/tutorials/basics/images/2d-shape-ellipse.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nannou-org/guide/HEAD/src/tutorials/basics/images/2d-shape-ellipse.png -------------------------------------------------------------------------------- /src/tutorials/basics/images/2d-simple-line.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nannou-org/guide/HEAD/src/tutorials/basics/images/2d-simple-line.png -------------------------------------------------------------------------------- /src/tutorials/basics/images/2d-simple-polyline.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nannou-org/guide/HEAD/src/tutorials/basics/images/2d-simple-polyline.png -------------------------------------------------------------------------------- /src/tutorials/basics/images/2d-custom-circle-outline.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nannou-org/guide/HEAD/src/tutorials/basics/images/2d-custom-circle-outline.png -------------------------------------------------------------------------------- /src/tutorials/basics/images/2d-custom-octogon-polygon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nannou-org/guide/HEAD/src/tutorials/basics/images/2d-custom-octogon-polygon.png -------------------------------------------------------------------------------- /src/tutorials/basics/images/2d-complete-octogon-outline.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nannou-org/guide/HEAD/src/tutorials/basics/images/2d-complete-octogon-outline.png -------------------------------------------------------------------------------- /src/api_reference.md: -------------------------------------------------------------------------------- 1 | # API Reference 2 | 3 | Eventually, we would like to host the API documentation here. For now, you can 4 | find it at [docs.rs/nannou](https://docs.rs/nannou). 5 | -------------------------------------------------------------------------------- /book.toml: -------------------------------------------------------------------------------- 1 | [book] 2 | title = "The Nannou Guide" 3 | authors = ["mitchmindtree", "JoshuaBatty", "freesig"] 4 | src = "src" 5 | description = "A one-stop shop for Nannou Knowledge!" 6 | multilingual = false 7 | -------------------------------------------------------------------------------- /src/showcases.md: -------------------------------------------------------------------------------- 1 | # Showcases 2 | 3 | **TODO:** A collection of work made with nannou, perhaps ordered from most 4 | recent to the past. Users could do a PR to have their own nannou projects 5 | published. 6 | 7 | * [sketches by mitchmindtree](https://github.com/mitchmindtree/nannou-sketches) 8 | -------------------------------------------------------------------------------- /src/developer_reference.md: -------------------------------------------------------------------------------- 1 | # Developer Reference 2 | 3 | **TODO:** A guide to the architecture of Nannou's internals to help onboard new 4 | developers. Describes the layout of modules, how to navigate the reference, the 5 | scope of the main nannou crate i.e. the kinds of work that should go inside the 6 | main repo and the kinds that might be better off in separate repos, etc. 7 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | language: rust 2 | cache: cargo 3 | before_script: 4 | - cargo install mdbook || true 5 | addons: 6 | apt: 7 | packages: 8 | - libasound2-dev 9 | rust: 10 | - stable 11 | script: 12 | - mdbook build 13 | - cd book-tests && cargo test -v 14 | - cd .. 15 | deploy: 16 | provider: script 17 | script: bash ./travis_deploy.sh 18 | on: 19 | branch: master 20 | -------------------------------------------------------------------------------- /src/getting_started.md: -------------------------------------------------------------------------------- 1 | # Getting Started 2 | 3 | If you are new to nannou or Rust, you are in the right place! 4 | 5 | In this section, we will: 6 | 7 | 1. Install the Rust programming language. 8 | 2. Check for platform-specific requirements. 9 | 3. Setup our code editor for working with Rust. 10 | 4. Run some nannou examples. 11 | 5. Make our own, new nannou project! 12 | 13 | Let's get started. 14 | -------------------------------------------------------------------------------- /book-tests/Cargo.toml: -------------------------------------------------------------------------------- 1 | [package] 2 | name = 'book-tests' 3 | version = '0.1.0' 4 | authors = ['mitchmindtree '] 5 | edition = '2018' 6 | description = 'For testing the nannou-guide, while including the nannou dependencies.' 7 | 8 | [build-dependencies] 9 | skeptic = '0.13' 10 | 11 | [dev-dependencies] 12 | skeptic = '0.13' 13 | nannou = { git = 'https://github.com/nannou-org/nannou', branch = 'master' } 14 | -------------------------------------------------------------------------------- /LICENSE-APACHE: -------------------------------------------------------------------------------- 1 | Copyright 2019 nannou-org. 2 | 3 | Licensed under the Apache License, Version 2.0 (the "License"); 4 | you may not use this file except in compliance with the License. 5 | You may obtain a copy of the License at 6 | 7 | http://www.apache.org/licenses/LICENSE-2.0 8 | 9 | Unless required by applicable law or agreed to in writing, software 10 | distributed under the License is distributed on an "AS IS" BASIS, 11 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | See the License for the specific language governing permissions and 13 | limitations under the License. 14 | -------------------------------------------------------------------------------- /travis_deploy.sh: -------------------------------------------------------------------------------- 1 | # A script to let travis build the mdbook html and deploy it. 2 | git config user.email "travis@travis-ci.org" 3 | git config user.name "Travis CI" 4 | git stash && 5 | mdbook build && 6 | git remote add nannou-org https://${GH_TOKEN}@github.com/${TRAVIS_REPO_SLUG}.git 7 | git fetch nannou-org && 8 | git config credential.helper "store --file=.git/credentials" && 9 | echo "https://${GH_TOKEN}:@github.com" > .git/credentials && 10 | git checkout deploy && 11 | cp -r book/* . && 12 | git add -A . && 13 | git commit -m "Automated commit in preparation for deployment: $TRAVIS_BUILD_NUMBER" && 14 | git push --force --quiet nannou-org deploy &>/dev/null 15 | -------------------------------------------------------------------------------- /src/getting_started/updating.md: -------------------------------------------------------------------------------- 1 | # Updating nannou 2 | 3 | You can update to a new version of nannou by editing your `Cargo.toml` file to 4 | use the new crate. For version 0.12 add the line 5 | 6 | ```toml 7 | nannou = "0.12" 8 | ``` 9 | 10 | Then within the nannou directory run the following to update all dependencies: 11 | 12 | ```bash 13 | cargo update 14 | ``` 15 | 16 | ## Updating Rust. 17 | 18 | From time to time, a nannou update might require features from a newer version 19 | of rustc. For example, nannou 0.12 is known to require at least rustc 1.35.0. In 20 | these cases, you can update your rust toolchain to the latest version by running 21 | the following: 22 | 23 | ```bash 24 | rustup update 25 | ``` 26 | -------------------------------------------------------------------------------- /src/getting_started/installing_rust.md: -------------------------------------------------------------------------------- 1 | # Installing Rust 2 | 3 | Nannou is a library written for the [Rust programming 4 | language](https://www.rust-lang.org/). Thus, the first step is to install Rust! 5 | 6 | To install Rust on **Windows**, download and run the installer from 7 | [here](https://www.rust-lang.org/tools/install). If you're on **macOS** or 8 | **Linux**, open up your terminal, copy the text below, paste it into your 9 | terminal and hit enter. 10 | 11 | ```bash 12 | curl https://sh.rustup.rs -sSf | sh 13 | ``` 14 | 15 | Now Rust is installed! 16 | 17 | Next we will install some tools that help IDEs do fancy things like 18 | auto-completion and go-to-definition. 19 | 20 | ```bash 21 | rustup component add rust-src rustfmt-preview rust-analysis 22 | ``` 23 | 24 | Please see [this link](https://www.rust-lang.org/tools/install) if you would 25 | like more information on the Rust installation process. 26 | -------------------------------------------------------------------------------- /src/SUMMARY.md: -------------------------------------------------------------------------------- 1 | # Summary 2 | 3 | [Welcome!](./welcome.md) 4 | 5 | - [Why Nannou?](./why_nannou.md) 6 | - [Getting Started](./getting_started.md) 7 | - [Platform-specific Setup](./getting_started/platform-specific_setup.md) 8 | - [Installing Rust](./getting_started/installing_rust.md) 9 | - [Editor Setup](./getting_started/editor_setup.md) 10 | - [Running Examples](./getting_started/running_examples.md) 11 | - [Create A Project](./getting_started/create_a_project.md) 12 | - [Updating Nannou and Rust](./getting_started/updating.md) 13 | - [Tutorials](./tutorials.md) 14 | - [Basics - Drawing a Sketch](./tutorials/basics/draw-a-sketch.md) 15 | - [Basics - Anatomy of a Nannou App](./tutorials/basics/anatomy-of-a-nannou-app.md) 16 | - [Basics - Drawing 2D Shapes](./tutorials/basics/drawing-2d-shapes.md) 17 | - [Developer Reference](./developer_reference.md) 18 | - [API Reference](./api_reference.md) 19 | - [Showcases](./showcases.md) 20 | 21 | [Contributors](./contributors.md) 22 | [Code of Conduct](./code_of_conduct.md) 23 | -------------------------------------------------------------------------------- /LICENSE-MIT: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2019 nannou-org 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /book-tests/build.rs: -------------------------------------------------------------------------------- 1 | use skeptic::*; 2 | use std::{env, fs, io}; 3 | use std::path::{Path, PathBuf}; 4 | 5 | // Check the given path and parent directories for a path with the given name. 6 | fn check_parents(name: &str, path: &Path) -> io::Result> { 7 | match check_dir(name, path) { 8 | Ok(None) => match path.parent() { 9 | None => Ok(None), 10 | Some(parent) => check_parents(name, parent), 11 | }, 12 | other_result => other_result, 13 | } 14 | } 15 | 16 | // Check the given directory for a path with the matching name. 17 | fn check_dir(name: &str, path: &Path) -> io::Result> { 18 | for entry in fs::read_dir(path)? { 19 | let entry = entry?; 20 | let entry_path = entry.path(); 21 | if entry_path.ends_with(name) { 22 | return Ok(Some(entry_path)) 23 | } 24 | } 25 | Ok(None) 26 | } 27 | 28 | fn main() { 29 | let out_dir = env::var("OUT_DIR") 30 | .expect("failed to retrieve OUT_DIR"); 31 | let cargo_toml_path = check_parents("Cargo.toml", Path::new(&out_dir)) 32 | .expect("an error occurred while searching for Cargo.toml") 33 | .expect("no Cargo.toml found"); 34 | let book_root_path = cargo_toml_path.parent().unwrap().parent().unwrap(); 35 | let book_src_path = book_root_path.join("src"); 36 | let book_src_path_str = format!("{}", book_src_path.display()); 37 | let mdbook_files = markdown_files_of_directory(&book_src_path_str); 38 | generate_doc_tests(&mdbook_files); 39 | } 40 | -------------------------------------------------------------------------------- /src/getting_started/editor_setup.md: -------------------------------------------------------------------------------- 1 | # Editor Setup 2 | 3 | While most popular development environments support Rust, support for certain 4 | features like auto-completion and go-to-definition is better in some than 5 | others. 6 | 7 | ### VS Code 8 | 9 | For new Rust users we recommend using VS-Code as your editor and IDE for Nannou 10 | development. Currently it seems to have the best support for the Rust language 11 | including syntax highlighting, auto-complete, code formatting and more. It also 12 | comes with an integrated unix terminal and file navigation system. Below are the 13 | steps we recommend for getting started with Nannou development using VS-Code. 14 | 15 | 1. [Download VS-Code](https://code.visualstudio.com/download) for your OS. 16 | 2. In VS code user settings, set `"rust-client.channel": "stable"`. 17 | 3. [Install 18 | RLS](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust) (the 19 | Rust Language Server) plugin for VS-Code. 20 | 4. Click on the 'view' menu and select 'integrated terminal'. 21 | 22 | ### Other Environments 23 | 24 | Here are links to assist with setting up other popular development environments 25 | for supporting Rust. 26 | 27 | 1. [Sublime Text](https://packagecontrol.io/packages/Rust%20Enhanced) 28 | 2. [Atom](https://atom.io/packages/language-rust) 29 | 3. [Intellij IDEA](https://intellij-rust.github.io) 30 | 4. [Vim](https://github.com/rust-lang/rust.vim) 31 | 5. [Emacs](https://github.com/rust-lang/rust-mode) 32 | 6. [Visual Studio](https://github.com/PistonDevelopers/VisualRust) 33 | 7. [Eclipse](https://github.com/eclipse/corrosion) 34 | 35 | 36 | -------------------------------------------------------------------------------- /src/welcome.md: -------------------------------------------------------------------------------- 1 | # Welcome! 2 | 3 | **Nannou is an open-source, creative-coding toolkit for Rust.** 4 | 5 | The aim of this guide is to help you find the information you are looking for. 6 | Whether you are new to Nannou and are looking for a place to start, or you are 7 | an experienced Nannou user looking for more advanced tutorials, this book should 8 | have something for you! 9 | 10 | As excited as we are about developing tools for creative coding, we are equally 11 | excited about fostering a warm, welcoming and inclusive community. Please make 12 | yourself familiar with our [Code of Conduct](/code_of_conduct.md) and feel free 13 | to join us on [the Nannou 14 | Slack](https://communityinviter.com/apps/nannou/nannou-slack)! 15 | 16 | ### [Why Nannou?](/why_nannou.md) 17 | 18 | Here you can read about the motivations and philosophy behind Nannou. Why start 19 | Nannou? What drives forward progress? 20 | 21 | ### [Getting Started](/getting_started.md) 22 | 23 | Is this your first time using Nannou or Rust? This is the chapter for you. 24 | This chapter covers everything from installing Rust right through to starting 25 | your own Nannou project. 26 | 27 | ### [Tutorials](/tutorials.md) 28 | 29 | A suite of tutorials demonstrating how to do different things with Nannou. For 30 | example, "How do I output sounds?", "How do I draw shapes?", "How can I connect 31 | to my laser?" 32 | 33 | ### [Developer Reference](/developer_reference.md) 34 | 35 | Learn more about the design philosophy behind Nannou, how the project is 36 | architected and how you can contribute. 37 | 38 | ### [API Reference](https://docs.rs/nannou) 39 | 40 | If you are looking for the source code reference, check out 41 | [docs.rs/nannou](https://docs.rs/nannou). Here you can find documentation about 42 | the API generated from the code itself. 43 | 44 | ### [Showcases](/showcases.md) 45 | 46 | See what's possible with Nannou! A collection of projects made with Nannou. 47 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # NOTICE: the guide has been moved [here](https://github.com/nannou-org/nannou/tree/master/guide). 2 | 3 | --- 4 | 5 | # the nannou guide [![Build Status](https://travis-ci.org/nannou-org/guide.svg?branch=master)](https://travis-ci.org/nannou-org/guide) 6 | 7 | The one-stop-shop for everything someone might want to know about nannou! 8 | 9 | ## Working on the Book 10 | 11 | The easiest way to build, render and read the book is as follows: 12 | 13 | - Clone the repo. 14 | ```bash 15 | git clone https://github.com/nannou-org/guide 16 | cd guide 17 | ``` 18 | - Install the [Rust markdown book](https://github.com/rust-lang-nursery/mdBook) tool. 19 | ``` 20 | cargo install mdbook 21 | ``` 22 | - Make `mdbook` watch the repo, re-build on file changes and host at 23 | `localhost:3000`. 24 | ``` 25 | mdbook serve 26 | ``` 27 | - Open your browser and point it to `localhost:3000` to find the rendered 28 | markdown book. 29 | 30 | You should now have a hot-loading environment where you can edit the book 31 | markdown and see the results rendered in your browser each time you save a file. 32 | 33 | ## Running Tests 34 | 35 | To run the tests, do the following: 36 | 37 | ```bash 38 | cd book-tests 39 | cargo test 40 | ``` 41 | 42 | The `build.rs` will retrieve all `rust` code snippets from the markdown files 43 | and generate a test file so that they all may be tested during `cargo test`. 44 | 45 | We do this rather than using the `mdbook test` as `mdbook test` does not support 46 | including remote dependencies. 47 | 48 | ## License 49 | 50 | Licensed under either of 51 | 52 | * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0) 53 | * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT) 54 | 55 | at your option. 56 | 57 | **Contributions** 58 | 59 | Unless you explicitly state otherwise, any contribution intentionally submitted 60 | for inclusion in the work by you, as defined in the Apache-2.0 license, shall be 61 | dual licensed as above, without any additional terms or conditions. 62 | -------------------------------------------------------------------------------- /src/contributors.md: -------------------------------------------------------------------------------- 1 | # Contributors 2 | 3 | This project exists thanks to all the people who contribute. 4 | 5 | 6 | 7 | 8 | ## Backers 9 | 10 | Thank you to all our backers! 🙏 11 | 12 | 13 | 14 | 15 | ## Sponsors 16 | 17 | Support this project by becoming a sponsor. Your logo will show up here with a link to your website. 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | -------------------------------------------------------------------------------- /src/getting_started/running_examples.md: -------------------------------------------------------------------------------- 1 | # Running Examples 2 | 3 | The easiest way to get familiar with nannou is to explore the examples. 4 | 5 | Nannou provides three collections of examples: 6 | 7 | | **Path** | **Description** | 8 | | --- | --- | 9 | | [**`examples/`**](https://github.com/nannou-org/nannou/tree/master/examples) | A collection of examples with categorised demonstrations of nannou. | 10 | | [**`generative_design/`**](https://github.com/nannou-org/nannou/tree/master/generative_design) | Examples from [Generative Gestaltung](http://www.generative-gestaltung.de/), ported from p5.js to nannou. | 11 | | [**`nature_of_code/`**](https://github.com/nannou-org/nannou/tree/master/nature_of_code) | Examples from [Nature of Code](https://natureofcode.com/), ported from Processing to nannou. | 12 | 13 | To get the examples we can clone the nannou repository. 14 | 15 | ```bash 16 | git clone https://github.com/nannou-org/nannou 17 | ``` 18 | 19 | If you do not have `git` installed you can press the "Clone or download" button 20 | at the top of this page and then press "Download .zip". 21 | 22 | Now, change the current directory to `nannou`. 23 | 24 | ```bash 25 | cd nannou 26 | ``` 27 | 28 | Run the example using cargo! 29 | 30 | ```bash 31 | cargo run --release --example draw 32 | ``` 33 | 34 | The `--release` flag means we want to build with optimisations enabled. 35 | 36 | The value passed via the `--example` flag matches the `name` property of an 37 | entry within the `[[examples]]` table of the package's `Cargo.toml` file. The 38 | matched entry's `path` property points to the source file to build: 39 | 40 | ```toml 41 | # Draw 42 | [[example]] 43 | name = "draw" 44 | path = "draw/draw.rs" 45 | ``` 46 | 47 | If we were to look through the nature of code directory and decide we want to 48 | run the following example: 49 | 50 | ```toml 51 | # Chapter 1 Vectors 52 | [[example]] 53 | name = "1_1_bouncingball_novectors" 54 | path = "chp_01_vectors/1_1_bouncingball_novectors.rs" 55 | ``` 56 | 57 | We could do so with the following: 58 | 59 | ```bash 60 | cargo run --release --example 1_1_bouncingball_novectors 61 | ``` 62 | 63 | In general, the name of the example will almost always be the file name without 64 | the `.rs` extension. 65 | 66 | If you are compiling nannou for the first time you will see cargo download and 67 | build all the necessary dependencies. This might take a while! Luckily, we only 68 | have to wait for this the first time. 69 | 70 | ![cargo](https://i.imgur.com/5OBNqMB.gif) 71 | 72 | Once the example compiles you should see the following window appear. 73 | 74 | ![draw_HD](https://i.imgur.com/HVVamUI.gif) 75 | 76 | To run any of the other examples, replace `draw` with the name of the 77 | desired example. 78 | -------------------------------------------------------------------------------- /src/getting_started/create_a_project.md: -------------------------------------------------------------------------------- 1 | # Create A Project 2 | 3 | Whether we are creating an artwork, an app, a quick sketch or an installation, 4 | we want to begin by creating a new project. A new nannou project lets us build a 5 | nannou application the way that *we* want to use it. 6 | 7 | Eventually, the aim for Nannou is to provide a project generator tool which will 8 | allow us to do the following and much more in just a few clicks. For now, we can 9 | create a new project with just a few small steps: 10 | 11 | 1. Create the Rust project with the name of our project: 12 | 13 | ```bash 14 | cargo new my-project 15 | ``` 16 | 17 | 2. Change directory to the generated project. 18 | 19 | ```bash 20 | cd my-project 21 | ``` 22 | 23 | 3. Edit the `Cargo.toml` file and add the latest version of nannou to the bottom 24 | like so: 25 | 26 | ```toml 27 | [package] 28 | name = "my_project" 29 | version = "0.1.0" 30 | authors = ["mitchmindtree "] 31 | edition = "2018" 32 | 33 | [dependencies] 34 | nannou = "0.12" 35 | ``` 36 | 37 | Note that there is a chance the nannou version above might be out of date. 38 | You can check the latest version by typing `cargo search nannou` in your 39 | terminal. 40 | 41 | 4. Replace the code in `src/main.rs` with the following to setup our nannou 42 | application. 43 | 44 | ```rust,no_run 45 | # extern crate nannou; 46 | use nannou::prelude::*; 47 | 48 | fn main() { 49 | nannou::app(model) 50 | .update(update) 51 | .simple_window(view) 52 | .run(); 53 | } 54 | 55 | struct Model {} 56 | 57 | fn model(_app: &App) -> Model { 58 | Model {} 59 | } 60 | 61 | fn update(_app: &App, _model: &mut Model, _update: Update) { 62 | } 63 | 64 | fn view(_app: &App, _model: &Model, frame: Frame){ 65 | frame.clear(PURPLE); 66 | } 67 | ``` 68 | 69 | If you are new to Rust or simply do not understand the code above just yet, 70 | do not fear! In the first tutorial of the next chapter we will break down 71 | this code step-by-step. 72 | 73 | 5. Trigger the initial build and check that everything is working nicely by 74 | running our app! 75 | 76 | ```bash 77 | cargo run --release 78 | ``` 79 | 80 | The first build might take a while, as we must build nannou and all of its 81 | dependencies from scratch. The following times that we run our app should be 82 | much faster! 83 | 84 | Once the project has finished building, it will begin running and we should 85 | be able to see a purple window. 86 | 87 | 88 | **That's it!** If everything went as planned, you are now ready to start 89 | building your own nannou project. Of course, we probably want our application to 90 | be more than just a purple window. 91 | 92 | To find out how to add more features to our project like graphics, audio, 93 | multiple windows, laser output, projection mapping and much more, let's take a 94 | look at the next chapter. 95 | -------------------------------------------------------------------------------- /src/tutorials.md: -------------------------------------------------------------------------------- 1 | # Tutorials 2 | 3 | In the previous chapter we prepared everything needed to start our own Nannou 4 | project! In this chapter, we will take a more focused look at all of the 5 | different features we can add to our Nannou project. 6 | 7 | If you are new to Nannou or Rust we recommend starting with the first tutorial 8 | before going on. If you are feeling more confident, feel free to choose your own 9 | adventure through the following tutorials depending on what you want to add to 10 | your project! 11 | 12 | 13 | ## Basics 14 | 15 | A suite of tutorials for getting familiar with Rust and the Nannou environment. 16 | 17 | - [Drawing a sketch](/tutorials/basics/draw-a-sketch.md) 18 | - [Anatomy of a nannou app](/tutorials/basics/anatomy-of-a-nannou-app.md) 19 | - Nannou events 20 | - Rust variables 21 | - Rust conditions 22 | - Rust loops 23 | - Rust functions 24 | 25 | ## Drawing 26 | 27 | Working with Nannou's `Draw` API - a simple approach of coding graphics. 28 | 29 | - [Drawing 2D shapes](/tutorials/basics/drawing-2d-shapes.md) 30 | - Drawing 3D shapes 31 | - Drawing images 32 | - Drawing meshes 33 | 34 | ## Windowing 35 | 36 | Walk-throughs for creating and working with one or more windows. 37 | 38 | - Building a custom window 39 | - Creating multiple windows 40 | - Drawing to different windows 41 | - Fullscreen on startup 42 | - Automatically positioning windows 43 | 44 | ## GUI 45 | 46 | How to create a GUI (Graphical User Interface) for you Nannou project. 47 | 48 | - Creating a UI 49 | - Exploring available UI widgets 50 | - Multi-window UI 51 | 52 | ## Audio 53 | 54 | A suite of guides for working with audio in Nannou. 55 | 56 | - Setting up audio output 57 | - Setting up audio input 58 | - Selecting specific audio devices 59 | - Playing an audio file 60 | - Basic audio synthesis 61 | - Many channel audio streams 62 | - Feeding audio input to output 63 | - Visualising audio 64 | 65 | ## Video 66 | 67 | Loading, playing and recording video in Nannou. 68 | 69 | - Drawing video 70 | - Recording a window to video 71 | - Manipulating video playback 72 | 73 | ## Vulkan 74 | 75 | Understanding the lower level that underlies all graphics in Nannou. 76 | 77 | - What is Vulkan? 78 | - The graphics pipeline 79 | - Compute shaders 80 | - Fragment shaders 81 | - Vertex shaders 82 | 83 | ## Projection Mapping 84 | 85 | Getting started with using Nannou for projection mapping. 86 | 87 | - Basic quad-warping. 88 | 89 | ## LASERs 90 | 91 | Detecting and outputting to LASER DACs on a network. 92 | 93 | - Connecting to a LASER. 94 | - Detecting LASER DACs. 95 | - Tweaking LASER interpolation and optimisations. 96 | 97 | ## OSC 98 | 99 | - Setting up an OSC sender. 100 | - Setting up an OSC receiver. 101 | 102 | ## DMX 103 | 104 | Working with DMX over the network via sACN. 105 | 106 | - Working with the sacn crate. 107 | 108 | ## Serial over USB 109 | 110 | Working with Serial data in a cross-platform manner. 111 | 112 | - Reading USB serial data. 113 | - Writing USB serial data. 114 | 115 | 116 | If you were unable to find what you were looking for above, or if you have an 117 | idea for a tutorial not yet present, please feel free to create an issue or a 118 | pull request! 119 | -------------------------------------------------------------------------------- /src/tutorials/basics/draw-a-sketch.md: -------------------------------------------------------------------------------- 1 | # Draw a Nannou Sketch 2 | 3 | **Tutorial Info** 4 | 5 | - Author: tpltnt 6 | - Required Knowledge: [Getting Started](/getting_started.md) 7 | - Reading Time: 5 minutes 8 | 9 | --- 10 | 11 | 12 | **Nannou is a framework for creative coding in Rust.** A framework can be 13 | thought of as a collection of building blocks to help accomplish a goal. 14 | If you are not familiar with the programming language Rust, please work 15 | through some of [this material first](https://www.rust-lang.org/learn). 16 | 17 | A sketch is the smallest/fastest way to get results with nannou. 18 | Here is one example which just yields a blue window: 19 | 20 | ```rust,no_run 21 | # extern crate nannou; 22 | # 23 | // minimal example of a nannou sketch 24 | use nannou::prelude::*; 25 | 26 | fn main() { 27 | nannou::sketch(view).run(); 28 | } 29 | 30 | fn view(app: &App, frame: Frame) { 31 | // get canvas to draw on 32 | let draw = app.draw(); 33 | 34 | // set background to blue 35 | draw.background().color(BLUE); 36 | 37 | // put everything on the frame 38 | draw.to_frame(app, &frame).unwrap(); 39 | } 40 | ``` 41 | 42 | You can exit the sketch by pressing `ESC`. 43 | 44 | ## Sidenote: Sketches vs. Apps 45 | 46 | Nannou can be used to create many things with very different levels 47 | of complexity, similar to pen and paper. Sketches are more like 48 | squiggles on napkins while apps can be really elaborate drawings. 49 | Sketches offer a constrained space to work with, but a lot is taken 50 | care of behind the scenes. Apps allow for more fine grained control, 51 | but also require more (explicit) work on your part. The main difference 52 | is that an app provides a model for working with state, while a 53 | sketch provides a simpler API to get drawing quickly. A good 54 | overview of how apps work can be found in the chapter 55 | [Anatomy of a nannou app](/tutorials/basics/anatomy-of-a-nannou-app.md). 56 | 57 | 58 | ## Explaining the Code 59 | 60 | A sketch consists of at least two functions: `main()` and `view()`. 61 | First we import some building blocks: 62 | ```rust,no_run 63 | # #![allow(unused_imports)] 64 | use nannou::prelude::*; 65 | # fn main() {} 66 | ``` 67 | 68 | After this import the actual sketching code starts. The `main()` functions is where all your logic starts. The code 69 | ```rust,no_run 70 | # extern crate nannou; 71 | # use nannou::prelude::*; 72 | # 73 | # fn main() { 74 | nannou::sketch(view).run(); 75 | # } 76 | # fn view(_app: &App, _frame: Frame) {} 77 | ``` 78 | call a function to draw on the single window (`view()` in this case). This 79 | function has the signature `fn(_: &App, _: Frame);`. Don't worry if you 80 | don't know what a function signature is. Just copy the `main()` function 81 | and you will be fine. 82 | 83 | Within the view() function, what we draw to the Frame will be presented in our window. 84 | ```rust,no_run 85 | # #![allow(unused_imports)] 86 | # extern crate nannou; 87 | # 88 | # // minimal example of a nannou sketch 89 | # use nannou::prelude::*; 90 | # 91 | # fn main() { 92 | # nannou::sketch(view).run(); 93 | # } 94 | # 95 | fn view(app: &App, frame: Frame) { 96 | let draw = app.draw(); 97 | 98 | draw.background().color(BLUE); 99 | 100 | draw.to_frame(app, &frame).unwrap(); 101 | } 102 | ``` 103 | 104 | This function follows the same scheme. First some setup is done. The line 105 | ```rust,no_run 106 | # #![allow(unused_imports)] 107 | # #![allow(unused_variables)] 108 | # extern crate nannou; 109 | # 110 | # // minimal example of a nannou sketch 111 | # use nannou::prelude::*; 112 | # 113 | # fn main() { 114 | # nannou::sketch(view).run(); 115 | # } 116 | # 117 | # fn view(app: &App, _frame: Frame) { 118 | let draw = app.draw(); 119 | # } 120 | ``` 121 | lets us assign a canvas-like datatype to the variable `draw`. 122 | We can now paint on the this canvas by setting the background to blue. 123 | ```rust,no_run 124 | # #![allow(unused_imports)] 125 | # extern crate nannou; 126 | # 127 | # // minimal example of a nannou sketch 128 | # use nannou::prelude::*; 129 | # 130 | # fn main() { 131 | # nannou::sketch(view).run(); 132 | # } 133 | # 134 | # fn view(app: &App, _frame: Frame) { 135 | # let draw = app.draw(); 136 | draw.background().color(BLUE); 137 | # } 138 | ``` 139 | Now we have a canvas with only a blue background. We take this canvas and 140 | create a computer graphics frame from it to display in the main window. 141 | ```rust,no_run 142 | # #![allow(unused_imports)] 143 | # extern crate nannou; 144 | # 145 | # // minimal example of a nannou sketch 146 | # use nannou::prelude::*; 147 | # 148 | # fn main() { 149 | # nannou::sketch(view).run(); 150 | # } 151 | # 152 | # fn view(app: &App, frame: Frame) { 153 | # let draw = app.draw(); 154 | draw.to_frame(app, &frame).unwrap(); 155 | # } 156 | ``` 157 | 158 | Note that the `view()` function is called repeatedly, but not at a constant 159 | rate. This might be problematic if you use randomness to draw things. 160 | -------------------------------------------------------------------------------- /src/getting_started/platform-specific_setup.md: -------------------------------------------------------------------------------- 1 | # Platform-specific Setup 2 | 3 | Before we get started, let's make sure we have all the necessary ingredients for 4 | installing Rust and building nannou projects. 5 | 6 | Depending on what OS you are running, you might require an extra step or two. 7 | 8 | By the way, if you notice some steps are missing from this section of the guide, 9 | feel free to open an issue or PR at [the nannou guide 10 | repo](https://github.com/nannou-org/guide)! 11 | 12 | ## macOS 13 | 14 | Ensure that you have xcode-tools installed: 15 | 16 | ```bash 17 | xcode-select --install 18 | ``` 19 | 20 | This should provide all the developer tools needed for building nannou. 21 | 22 | ## Windows 23 | 24 | Rust requires the C++ build tools for Visual Studio. The Rust book has this to 25 | say: 26 | 27 | > On Windows, go to 28 | > [https://www.rust-lang.org/tools/install](https://www.rust-lang.org/tools/install) 29 | > and follow the instructions for installing Rust. At some point in the 30 | > installation, you’ll receive a message explaining that you’ll also need the 31 | > C++ build tools for Visual Studio 2013 or later. The easiest way to acquire 32 | > the build tools is to install [Build Tools for Visual Studio 33 | > 2019](https://www.visualstudio.com/downloads/#build-tools-for-visual-studio-2019). 34 | > The tools are in the Other Tools and Frameworks section. 35 | 36 | ## Linux 37 | 38 | Ensure you have the following system packages installed: 39 | 40 | - **Basic dev packages** 41 | 42 | First make sure the basic dev packages are installed. 43 | - `curl` will be required by `rustup` the rust toolchain manager. 44 | - `build-essential` will be required by `rustc` the rust compiler for linking. 45 | - `pkg-config` is used by some build scripts to source information about 46 | certain libraries. 47 | - `alsa` dev packages are required for `nannou_audio`. 48 | 49 | For Debian/Ubuntu users: 50 | ```bash 51 | sudo apt-get install curl build-essential python cmake pkg-config 52 | ``` 53 | 54 | - **alsa dev package** 55 | 56 | For Fedora users: 57 | ```bash 58 | sudo dnf install alsa-lib-devel 59 | ``` 60 | 61 | For Debian/Ubuntu users: 62 | ```bash 63 | sudo apt-get install libasound2-dev 64 | ``` 65 | 66 | For Arch users: 67 | ```bash 68 | sudo pacman -S alsa-lib 69 | ``` 70 | 71 | - **curl lib dev package** 72 | 73 | Nannou depends on the `curl-sys` crate. Some Linux distributions use 74 | LibreSSL instead of OpenSSL (such as AlpineLinux, Voidlinux, possibly 75 | [others](https://en.wikipedia.org/wiki/LibreSSL#Adoption) if manually 76 | installed). 77 | 78 | - **xcb** 79 | 80 | The XCB library provides inter-operability with Xlib. 81 | 82 | For Debian/Ubuntu users: 83 | ```bash 84 | sudo apt install libxcb-shape0-dev libxcb-xfixes0-dev 85 | ``` 86 | 87 | You might also need `python3` for the `xcb` crate's build script. 88 | 89 | - **vulkan** 90 | 91 | Installing Vulkan support on Linux is generally quite easy using your 92 | distro's package manager. That said, there may be different driver 93 | options to consider depending on your graphics card and tolerance for 94 | proprietary software. The following are rough guidelines on how to get 95 | going quickly, however if you are at all concerned with finding the 96 | approach that suits you best we recommend searching for vulkan driver 97 | installation for your graphics card on your distro. 98 | 99 | For Fedora with AMD graphic cards: 100 | ```bash 101 | sudo dnf install vulkan vulkan-info 102 | ``` 103 | 104 | For Fedora with NVIDIA graphic cards: 105 | Add the proprietary drivers 106 | ```bash 107 | sudo dnf install https://download1.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm https://download1.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm 108 | ``` 109 | and run 110 | ```bash 111 | sudo dnf install xorg-x11-drv-nvidia akmod-nvidia vulkan-tools 112 | ``` 113 | 114 | For Debian with AMD or Intel graphic cards: 115 | ```bash 116 | sudo apt-get install libvulkan1 mesa-vulkan-drivers vulkan-utils 117 | ``` 118 | 119 | For Debian with NVIDIA graphic cards: 120 | ```bash 121 | sudo apt-get install vulkan-utils 122 | ``` 123 | 124 | For Ubuntu users with AMD or Intel graphic cards: 125 | Add a PPA for the latest drivers 126 | ```bash 127 | sudo add-apt-repository ppa:oibaf/graphics-drivers 128 | sudo apt-get update 129 | sudo apt-get upgrade 130 | ``` 131 | and run 132 | ```bash 133 | sudo apt-get install libvulkan1 mesa-vulkan-drivers vulkan-utils 134 | ``` 135 | 136 | For Ubuntu users with NVIDIA graphic cards: 137 | Add a PPA for the latest drivers 138 | ```bash 139 | sudo add-apt-repository ppa:graphics-drivers/ppa 140 | sudo apt-get update 141 | sudo apt-get upgrade 142 | ``` 143 | and run 144 | ```bash 145 | sudo apt-get install nvidia-graphics-drivers-396 nvidia-settings vulkan vulkan-utils 146 | ``` 147 | 148 | For Arch with AMD graphic cards: 149 | ```bash 150 | sudo pacman -S vulkan-radeon lib32-vulkan-radeon 151 | ``` 152 | 153 | For Arch with Intel graphics card: 154 | ```bash 155 | sudo pacman -S vulkan-intel 156 | ``` 157 | 158 | For Arch with NVIDIA graphic cards: 159 | ```bash 160 | sudo pacman -S nvidia lib32-nvidia-utils 161 | ``` 162 | 163 | For Gentoo run: 164 | ```bash 165 | sudo emerge --ask --verbose dev-util/vulkan-tools dev-util/vulkan-headers 166 | ``` 167 | 168 | OK, we should now be ready to install Rust! 169 | -------------------------------------------------------------------------------- /src/code_of_conduct.md: -------------------------------------------------------------------------------- 1 | # Contributor Covenant Code of Conduct 2 | 3 | ## Our Pledge 4 | 5 | In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation. 6 | 7 | ## Conduct 8 | 9 | * We are committed to providing a friendly, safe and welcoming environment for all, regardless of level of experience, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, nationality, or other similar characteristic. 10 | * Please be kind and courteous. There’s no need to be mean or rude. 11 | * Respect that people have differences of opinion and that every design or implementation choice carries a trade-off and numerous costs. There is seldom a right answer. 12 | * Please keep unstructured critique to a minimum. If you have solid ideas you want to experiment with, make a fork and see how it works. 13 | * We will exclude you from interaction if you insult, demean or harass anyone. That is not welcome behavior. We interpret the term “harassment” as including the definition in the Citizen Code of Conduct; if you have any lack of clarity about what might be included in that concept, please read their definition. In particular, we don’t tolerate behavior that excludes people in socially marginalized groups. 14 | * Private harassment is also unacceptable. No matter who you are, if you feel you have been or are being harassed or made uncomfortable by a community member, please contact one of the channel ops or any of the Nannou moderation team immediately. Whether you’re a regular contributor or a newcomer, we care about making this community a safe place for you and we’ve got your back. 15 | * Likewise any spamming, trolling, flaming, baiting or other attention-stealing behavior is not welcome. 16 | 17 | ## Moderation 18 | 19 | These are the policies for upholding our community’s standards of conduct. If you feel that a thread needs moderation, please contact the [Nannou moderation team][email]: 20 | 21 | 1. Remarks that violate the Nannou standards of conduct, including hateful, hurtful, oppressive, or exclusionary remarks, are not allowed. (Cursing is allowed, but never targeting another user, and never in a hateful manner.) 22 | 2. Remarks that moderators find inappropriate, whether listed in the code of conduct or not, are also not allowed. 23 | 3. Moderators will first respond to such remarks with a warning. 24 | 4. If the warning is unheeded, the user will be “kicked,” i.e., kicked out of the communication channel to cool off. 25 | 5. If the user comes back and continues to make trouble, they will be banned, i.e., indefinitely excluded. 26 | 6. Moderators may choose at their discretion to un-ban the user if it was a first offense and they offer the offended party a genuine apology. 27 | 7. If a moderator bans someone and you think it was unjustified, please take it up with that moderator, or with a different moderator, in private. Complaints about bans in-channel are not allowed. 28 | 8. Moderators are held to a higher standard than other community members. If a moderator creates an inappropriate situation, they should expect less leeway than others. 29 | 30 | In the Nannou community we strive to go the extra step to look out for each other. Don’t just aim to be technically unimpeachable, try to be your best self. In particular, avoid flirting with offensive or sensitive issues, particularly if they’re off-topic; this all too often leads to unnecessary fights, hurt feelings, and damaged trust; worse, it can drive people away from the community entirely. 31 | 32 | And if someone takes issue with something you said or did, resist the urge to be defensive. Just stop doing what it was they complained about and apologize. Even if you feel you were misinterpreted or unfairly accused, chances are good there was something you could’ve communicated better — remember that it’s your responsibility to make your fellow members of the community comfortable. Everyone wants to get along and we are all here first and foremost because we want to talk about cool technology. You will find that people will be eager to assume good intent and forgive as long as you earn their trust. 33 | 34 | ## Our Responsibilities 35 | 36 | Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. 37 | 38 | Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. 39 | 40 | ## Scope 41 | 42 | This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers. 43 | 44 | ## Enforcement 45 | 46 | Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [**contact@nannou.cc**][email]. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. 47 | 48 | Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. 49 | 50 | ## Attribution 51 | 52 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version] as well as the [Node.js Policy on Trolling](http://blog.izs.me/post/30036893703/policy-on-trolling) and the [Rust Code of Conduct](https://www.rust-lang.org/en-US/conduct.html) 53 | 54 | [email]: mailto:contact@nannou.cc 55 | [homepage]: http://contributor-covenant.org 56 | [version]: http://contributor-covenant.org/version/1/4/ 57 | -------------------------------------------------------------------------------- /src/why_nannou.md: -------------------------------------------------------------------------------- 1 | # Why Nannou? 2 | 3 | **nannou** is a collection of code aimed at making it easy for artists to 4 | express themselves with simple, fast, reliable, portable code. Whether working 5 | on a 12-month installation or a 5 minute sketch, this framework aims to give 6 | artists easy access to the tools they need. 7 | 8 | The project was started out of a desire for a creative coding framework inspired 9 | by Processing, OpenFrameworks and Cinder, but for Rust. Named after 10 | [this](https://www.youtube.com/watch?v=A-Pkx37kYf4). 11 | 12 | ## Goals 13 | 14 | Nannou aims to provide easy, cross-platform access to the things that artists 15 | need: 16 | 17 | - [x] **Windowing & Events** via [winit](https://crates.io/crates/winit). 18 | - [x] **Audio** via [CPAL](https://crates.io/crates/cpal). *Input and 19 | output streams. Duplex are not yet supported.* 20 | - [ ] **Video** input, playback and processing (*would love suggestions and 21 | ideas*). 22 | - [x] **GUI** via [conrod](https://crates.io/crates/conrod). *May switch to a 23 | custom nannou solution in the future*. 24 | - **Geometry** with functions and iterators for producing vertices and indices: 25 | - [x] 1D - `Scalar`, `Range`. 26 | - [x] 2D - `Rect`, `Line`, `Ellipse`, `Polygon`, `Polyline`, `Quad`, 27 | `Tri`. 28 | - [x] 3D - `Cuboid`. 29 | - [ ] 3D TODO - `Ellipsoid`, `Cube`, Prisms, Pyramids, *Hedrons, etc. 30 | - [x] Vertex & index iterators. 31 | - [x] [Graph](https://docs.rs/nannou/latest/nannou/geom/graph/index.html) for 32 | composing geometry. 33 | - **Graphics** via Vulkan (via [vulkano](https://github.com/vulkano-rs/vulkano)): 34 | - [x] [Draw](https://docs.rs/nannou/latest/nannou/draw/index.html) API. E.g. 35 | `draw.ellipse().w_h(20.0, 20.0).color(RED)`. 36 | - [x] [Mesh](https://docs.rs/nannou/latest/nannou/mesh/index.html) API. 37 | - [ ] Image API (currently only supported via GUI). 38 | - [ ] Framebuffer object API. 39 | - **Protocols**: 40 | - [x] [OSC](https://docs.rs/nannou/latest/nannou/osc/index.html) - Open Sound 41 | Control. 42 | - [x] [CITP](https://github.com/nannou-org/citp) - Controller Interface 43 | Transport Protocol (network implementation is in progress). 44 | - [x] [Ether-Dream](https://github.com/nannou-org/ether-dream) Laser DAC 45 | protocol and network implementation. 46 | - [x] [DMX via sACN](https://github.com/lschmierer/sacn) - commonly used for 47 | lighting and effects. 48 | - [x] [Serial](https://crates.io/crates/serial) - commonly used for 49 | interfacing with LEDs and other hardware. 50 | - [x] [MIDI](https://crates.io/crates/midir) - Musical Instrument Digital 51 | Interface. 52 | - [x] [UDP](https://doc.rust-lang.org/std/net/struct.UdpSocket.html) via 53 | std. 54 | - [x] TCP 55 | [streams](https://doc.rust-lang.org/std/net/struct.TcpStream.html) and 56 | [listeners](https://doc.rust-lang.org/std/net/struct.TcpListener.html) 57 | via std. 58 | - **Device & I/O stream APIs**: 59 | - [x] [Audio](https://docs.rs/nannou/latest/nannou/app/struct.Audio.html). 60 | - [ ] Video. 61 | - [x] [Lasers](https://github.com/nannou-org/lasy). 62 | - [ ] Lights. 63 | - [ ] LEDs. 64 | - [ ] **Graphical Node Graph** via [gantz](https://github.com/nannou-org/gantz). 65 | - [ ] **GUI Editor**. 66 | 67 | Nannou aims to **use only pure-rust libraries**. As a new user you should 68 | require nothing more than `cargo build` to get going. Falling back to C-bindings 69 | will be considered as a temporary solution in the case that there are no Rust 70 | alternatives yet in development. We prefer to drive forward development of less 71 | mature rust-alternatives than depend on bindings to C code. This should make it 72 | easier for nannou *users* to become nannou *contributors* as they do not have to 73 | learn a second language in order to contribute upstream. 74 | 75 | Nannou **will not contain `unsafe` code** with the exception of bindings to 76 | operating systems or hardware APIs if necessary. 77 | 78 | Nannou wishes to **remove the need to decide between lots of different backends 79 | that provide access to the same hardware**. Instead, we want to focus on a 80 | specific set of backends and make sure that they work well. 81 | 82 | ## Why Rust? 83 | 84 | Rust is a language that is both highly expressive and blazingly fast. Here are 85 | some of the reasons why we choose to use it: 86 | 87 | - **Super fast**, as in [C and 88 | C++ fast](https://benchmarksgame.alioth.debian.org/u64q/compare.php?lang=rust&lang2=gpp). 89 | - [**A standard package manager**](https://crates.io/) that makes it very 90 | easy to handle dependencies and share your own projects in seconds. 91 | - **Highly portable.** Easily build for MacOS, Linux, Windows, Android, iOS and 92 | [so many others](https://forge.rust-lang.org/platform-support.html). 93 | - **No header files** (and no weird linking errors). 94 | - **Sum Types and Pattern Matching** (and no `NULL`). 95 | - **Local type inference**. Only write types where it matters, no need to repeat 96 | yourself. 97 | - A more modern, **ƒunctional and expressive style**. 98 | - **Memory safe and data-race-free!** Get your ideas down without the fear of 99 | creating pointer spaghetti or segfault time-sinks. 100 | - **Immutability by default.** Easily distinguish between variables that can 101 | change and those that can't at a glance. 102 | - **Module system** resulting in very clean and concise name spaces. 103 | - One of the kindest internet communities we've come across (please visit 104 | mozilla's #rust or /r/rust if you're starting out and need any pointers) 105 | 106 | ## Why the Apache/MIT dual licensing? 107 | 108 | For the most part, nannou is trying to maintain as much flexibility and compatibility 109 | with the licensing of Rust itself, which is also [dual licensed](https://www.rust-lang.org/policies/licenses). 110 | 111 | The Apache 2.0 and MIT license are very similar, but have a few key differences. 112 | Using the Apache 2.0 license for contributions triggers the Apache 2.0 patent grant. 113 | This grant is designed to protect against leveraging the patent law system to bypass 114 | (some) terms of the license. If the contribution is under the Apache 2.0 license, the 115 | contributor assures that they will not claim a violation of (their own) patents. If 116 | someone makes a work based on Apache 2.0 licensed code, they in turn also vow to 117 | not sue their users (for patent infringement). 118 | The MIT license provides compatibility with a lot of other FLOSS licenses. 119 | 120 | Further reading: 121 | 122 | * [Apache License, Version 2.0](https://opensource.org/licenses/Apache-2.0) 123 | * [MIT License](https://opensource.org/licenses/MIT) 124 | * [Please read: Rust license changing (very slightly)](https://mail.mozilla.org/pipermail/rust-dev/2012-November/002664.html) 125 | * [Rationale of Apache dual licensing](https://internals.rust-lang.org/t/rationale-of-apache-dual-licensing/8952) 126 | * [Against what does the Apache 2.0 patent clause protect?](https://opensource.stackexchange.com/questions/1881/against-what-does-the-apache-2-0-patent-clause-protect) 127 | * [GPLv2 Combination Exception for the Apache 2 License]https://blog.gerv.net/2016/09/gplv2-combination-exception-for-the-apache-2-license/) 128 | -------------------------------------------------------------------------------- /src/tutorials/basics/drawing-2d-shapes.md: -------------------------------------------------------------------------------- 1 | # Drawing 2D Shapes 2 | 3 | In this tutorial we explore drawing 2D shapes with nannou. We will cover drawing basic lines, simple polygons (e.g. ellipses, rectangles, etc.), and more complex polygons (where you can create whatever shape you'd like)! 4 | 5 | To begin with, we will need a nannou project file to work with. Copy the following into new file: 6 | 7 | ```rust,no_run 8 | use nannou::prelude::*; 9 | 10 | fn main() { 11 | nannou::sketch(view).run(); 12 | } 13 | 14 | fn view(app: &App, frame: Frame) { 15 | // Prepare to draw. 16 | let draw = app.draw(); 17 | 18 | // Clear the background to purple. 19 | draw.background().color(PLUM); 20 | 21 | // Draw a blue ellipse with default size and position. 22 | draw.ellipse().color(STEELBLUE); 23 | 24 | // Write to the window frame. 25 | draw.to_frame(app, &frame).unwrap(); 26 | } 27 | ``` 28 | 29 | You can also find this file, and other useful examples, in the [examples](https://github.com/nannou-org/nannou/tree/master/examples) directory of the nannou source repository. 30 | 31 | ## Drawing Simple Shapes 32 | 33 | Let's try running the file! (if you haven't already, you will need to add this file to your Cargo.toml file) 34 | 35 | You should a new window with something that looks like this: 36 | 37 | ![A simple circle](./images/2d-shape-circle.png) 38 | 39 | Already we are rendering a circle to our canvas. As you may have guessed, the line of code responsible for creating a circle is the call to the `ellipse` function: 40 | 41 | ``` 42 | draw.ellipse() 43 | .color(STEELBLUE); 44 | ``` 45 | 46 | There are many ways we can alter our circle here. Let's start with changing the size: 47 | 48 | ``` 49 | draw.ellipse() 50 | .color(STEELBLUE) 51 | .w(300.0) 52 | .h(200.0); 53 | ``` 54 | 55 | The `w` function here changes the width of the ellipse to 300 pixels, and the `h` function changes the height to 200.0 pixels. You should see what we would more colloquially refer to as an ellipse. 56 | 57 | We can also change the position of our ellipse with the `x_y` method: 58 | 59 | ``` 60 | draw.ellipse() 61 | .color(STEELBLUE) 62 | .w(300.0) 63 | .h(200.0) 64 | .x_y(200.0, -100.0); 65 | ``` 66 | 67 | ![An ellipse](./images/2d-shape-ellipse.png) 68 | 69 | As you can see, we edit our ellipse by chaining together different methods which will change one or more properties of our shape. This is called the **Builder** pattern. The call to `draw.ellipse()` returns an object of type `Drawing`. In turn, each call to a builder method, such as `w(300.0)` or `x_y(200.0, -100.0)`, returns the same instance of our shape. By chaining these function calls, we are able to build an ellipse with the attributes we want. 70 | 71 | There are several more methods we can use to build our ellipse. You can view the documentation for many of these methods [here](https://docs.rs/nannou/latest/nannou/draw/struct.Drawing.html). 72 | 73 | ### Drawing Rectangles and Quadrilaterals 74 | Drawing a square or rectangle uses the same builder pattern that drawing an ellipse does. In fact, it's similar enough that you can swap out `ellipse` with `rect` in the example above to get a working example: 75 | 76 | ``` 77 | draw.rect() 78 | .color(STEELBLUE) 79 | .w(300.0) 80 | .h(200.0); 81 | ``` 82 | 83 | You will see an image like this: 84 | 85 | ![A rectangle](./images/2d-shape-rect.png) 86 | 87 | In addition to `rect`, you can also use the `quad` method, which is for drawing quadrilaterals. This function is similar to `rect`, but you can also choose to supply your own coordinates for your shape. Try the following: 88 | 89 | ``` 90 | let point1 = pt2(-10.0, -20.0); 91 | let point2 = pt2(10.0, -30.0); 92 | let point3 = pt2(15.0, 40.0); 93 | let point4 = pt2(-20.0, 35.0); 94 | 95 | draw.quad() 96 | .color(STEELBLUE) 97 | .w(300.0) 98 | .h(200.0) 99 | .points(point1, point2, point3, point4); 100 | ``` 101 | 102 | You should see the following: 103 | 104 | ![A quadrilateral with custom defined points](./images/2d-shape-quad.png) 105 | 106 | The `pt2` method above will create a point object that represents a point in XY coordinate space, like a graph or a Cartesian plane. nannou's coordinate system places (0,0) at the center of the window. This is **not** like many other graphical creative coding frameworks, which place (0,0) at the upper-leftmost position of the window. 107 | 108 | Note that while the `Drawing` builder objects for different shapes share many of the same builder methods, they do not share all of them. Trying to use the method `points` on an instance of an `Drawing`, for example, will raise an error. 109 | 110 | ### Drawing a Triangle 111 | 112 | Additionally, there is one more simple shape method: `tri`, for drawing triangles. It behaves similarly to `quad`, where you can supply your own coordinates to decide how the shape looks. Try it out! 113 | 114 | ![A triangle](./images/2d-shape-tri.png) 115 | 116 | ## Drawing Lines 117 | 118 | The `line` function provides a simple way to draw a line: 119 | 120 | ``` 121 | let start_point = pt2(-30.0, -20.0); 122 | let end_point = pt2(40.0, 40.0); 123 | 124 | draw.line() 125 | .start(start_point) 126 | .end(end_point) 127 | .weight(4.0) 128 | .color(STEELBLUE); 129 | ``` 130 | 131 | ![A simple line](./images/2d-simple-line.png) 132 | 133 | Simply provide a starting point and an ending point, and you have your line. 134 | 135 | This is great for simpler drawings, but what if you want to draw something more complicated? A sine wave, for instance. 136 | 137 | To draw our sine wave, we will use the `polyline` function. To use this function, we will supply a collection (or array) of points that represent points on a sine wave. We can generate this array of points using—what else—the `sin` function! 138 | 139 | ``` 140 | let points = (0..50).map(|i| { 141 | let x = (i as f32 - 25.0); //subtract 25 to center the sine wave 142 | let point = pt2(x, x.sin()) * 20.0; //scale sine wave by 20.0 143 | (point, STEELBLUE) 144 | }); 145 | draw.polyline() 146 | .weight(3.0) 147 | .colored_points(points); 148 | ``` 149 | 150 | ![A sine wave polyline drawing](./images/2d-simple-polyline.png) 151 | 152 | As you can see, the power of `polyline` is the ability to draw a series of lines 153 | connecting and ordered array of points. With this, you can easily draw a 154 | variety of shapes or lines, so long as you can provide or generate the points 155 | you need to represent that shape. 156 | 157 | For example, a circle: 158 | 159 | ``` 160 | let radius = 150.0; // store the radius of the circle we want to make 161 | let points = (0..=360).map(|i| { // map over an array of integers from 0 to 360 to represent the degrees in a circle 162 | 163 | let radian = deg_to_rad(i as f32); // convert each degree to radians 164 | let x = radian.sin() * radius; // get the sine of the radian to find the x-co-ordinate of 165 | // this point of the circle, and multiply it by the radius 166 | let y = radian.cos() * radius; // do the same with cosine to find the y co-ordinate 167 | (pt2(x,y), STEELBLUE) // construct and return a point object with a color 168 | }); 169 | draw.polyline() // create a PathStroke Builder object 170 | .weight(3.0) 171 | .colored_points(points); // tell our PathStroke Builder to draw lines connecting our array of points 172 | ``` 173 | ![A custom circle](./images/2d-custom-circle-outline.png) 174 | 175 | A custom drawn circle! ...okay, perhaps this isn't too exciting, given that we 176 | already have an easy way of drawing circles with `ellipse`. But with a simple change to the above code we can generate an outline of a 177 | different shape. Let's try using the `step_by` function, which allows us to 178 | choose the interval at which we would like to step through a range or other iterator. So instead 179 | of calling `(0..=360).map`, we will call `(0..=360).step_by(45).map`: 180 | 181 | ``` 182 | let points = (0..=360).step_by(45).map(|i| { 183 | ``` 184 | 185 | The rest of our code will remain unchanged. 186 | 187 | Because 45 divides into 360 eight times, our code generated 8 points to represent a regular octagon. 188 | 189 | ![An octagon outline](./images/2d-complete-octogon-outline.png) 190 | 191 | An octagon! 192 | 193 | Try experimenting with different values to pass into `step_by` and see the 194 | different shapes you can create! 195 | 196 | As a side note, you may have noticed that we did not use a `color` function to set the drawing's 197 | color this time. Instead, `polyline` requires that each point be given a color. 198 | This means that you can change the color of the polyline point-by-point. Try 199 | experimenting with it! 200 | 201 | ## Drawing Custom Polygons 202 | 203 | To draw a custom filled-in polygon (and not just an outline), will we use code very similar to our custom circle or 204 | octagon code. The main difference is that instead of calling `polyline` to 205 | create a Builder, we call `polygon`: 206 | 207 | ``` 208 | let radius = 150.0; 209 | let points = (0..=360).step_by(45).map(|i| { 210 | let radian = deg_to_rad(i as f32); 211 | let x = radian.sin() * radius; 212 | let y = radian.cos() * radius; 213 | pt2(x,y) 214 | }); 215 | draw.polygon() 216 | .color(STEELBLUE) 217 | .points(points); 218 | ``` 219 | 220 | ![An octagon](./images/2d-custom-octogon-polygon.png) 221 | 222 | Notice how we are again using the `color` function to set the color of our 223 | polygon, similar to the basic polygon functions covered in the beginning of this 224 | tutorial. 225 | 226 | ## Concluding Remarks 227 | 228 | In this tutorial, we learned about most basic 2D drawing functions with nannou. 229 | 230 | You can view the documentation for the different `Drawing` objects these return here: 231 | 232 | * [Ellipse](https://docs.rs/nannou/latest/nannou/draw/primitive/ellipse/struct.Ellipse.html) 233 | * [Rect](https://docs.rs/nannou/latest/nannou/draw/primitive/rect/struct.Rect.html) 234 | * [Quad](https://docs.rs/nannou/latest/nannou/draw/primitive/quad/struct.Quad.html) 235 | * [Tri](https://docs.rs/nannou/latest/nannou/draw/primitive/tri/struct.Tri.html) 236 | * [Polyline (or PathStroke)](https://docs.rs/nannou/latest/nannou/draw/primitive/path/type.PathStroke.html) 237 | * [Polygon](https://docs.rs/nannou/latest/nannou/draw/primitive/polygon/struct.Polygon.html) 238 | 239 | These links provide more information about other functions you can use to change your drawings in a variety of ways. 240 | 241 | You have now learned about some of the most commonly used functions for 2D drawing with 242 | nannou. Of course, this is just scratching the surface of ways in which you can generate 243 | shapes or polygons with nannou, but it should serve as a solid starting point in 244 | creating your own drawings. 245 | 246 | Happy coding! 247 | -------------------------------------------------------------------------------- /src/tutorials/basics/anatomy-of-a-nannou-app.md: -------------------------------------------------------------------------------- 1 | # Anatomy of a Nannou App 2 | 3 | **Tutorial Info** 4 | 5 | - Author: tpltnt, mitchmindtree 6 | - Required Knowledge: [Getting Started](/getting_started.md) 7 | - Reading Time: 10 minutes 8 | 9 | --- 10 | 11 | 12 | **Nannou is a framework for creative coding in Rust.** A framework can be 13 | thought of as a collection of building blocks to help accomplish a goal. 14 | 15 | If romance stories were frameworks, then you might have the protagonist, their 16 | love interest, some struggles, and a happy ending as the building blocks. All of 17 | these need to be fleshed out by the author, but using clichés help to tell a 18 | story without having to introduce everyone and everything in excruciating 19 | detail. If the author wants to tell a horror story, then the clichés of a 20 | romance story aren't very helpful. 21 | 22 | In the same way you can use nannou to create programs for artistic expression, 23 | but you might find it hard to build an office suite. So let's take a look at the 24 | building blocks for creative coding together. 25 | 26 | Here's an example of a bare-bones nannou app that opens an empty window: 27 | 28 | ```rust,no_run 29 | # extern crate nannou; 30 | # 31 | use nannou::prelude::*; 32 | 33 | struct Model {} 34 | 35 | fn main() { 36 | nannou::app(model) 37 | .event(event) 38 | .simple_window(view) 39 | .run(); 40 | } 41 | 42 | fn model(_app: &App) -> Model { 43 | Model {} 44 | } 45 | 46 | fn event(_app: &App, _model: &mut Model, _event: Event) { 47 | } 48 | 49 | fn view(_app: &App, _model: &Model, _frame: Frame) { 50 | } 51 | ``` 52 | 53 | We will start from the top! 54 | 55 | ## Import Common Items 56 | 57 | ```rust,no_run 58 | # #![allow(unused_imports)] 59 | # extern crate nannou; 60 | use nannou::prelude::*; 61 | # fn main() {} 62 | ``` 63 | 64 | This line imports all of the commonly used items from nannou into scope. These 65 | include items such as `App`, `Frame`, and many more that we will learn about 66 | over time. To see the full list of items re-exported by the prelude, see 67 | [here](https://docs.rs/nannou/latest/nannou/prelude/index.html). 68 | 69 | > Note: Unlike some other languages, Rust does not automatically include 70 | > everything from the libraries added to the project. This approach results in 71 | > very clean namespaces and avoids conflicts between different items from 72 | > different crates. That said, it also means we need to manually import every 73 | > item we *do* want to use into scope. By providing a prelude nannou makes it a 74 | > little easier to access all of the commonly used items. 75 | 76 | ## **Model** - Our app state 77 | 78 | ```rust,no_run 79 | # #![allow(dead_code)] 80 | struct Model {} 81 | # fn main() {} 82 | ``` 83 | 84 | The **Model** is where we define the state of our application. We can think of 85 | the model as the representation of our program at any point in time. Throughout 86 | the life of our program, we can update the model as certain events occur such as 87 | mouse presses, key presses or timed updates. We can then present the model using 88 | some kind of output, e.g. by drawing to the screen or outputting to a laser. We 89 | will look at these input and output events in more detail in another tutorial! 90 | Our example is as simple as possible, and we have no state to track. Thus our 91 | model can stay empty. 92 | 93 | > Note: A `struct` describes a set of data. Our struct has no fields and thus is 94 | > empty. There is no state information to be tracked in this example. 95 | 96 | ## **main** - Where Rust programs begin and end 97 | 98 | ```rust,no_run 99 | # extern crate nannou; 100 | # use nannou::prelude::*; 101 | # struct Model {} 102 | fn main() { 103 | nannou::app(model) 104 | .event(event) 105 | .simple_window(view) 106 | .run(); 107 | } 108 | # fn model(_app: &App) -> Model { 109 | # Model {} 110 | # } 111 | # fn event(_app: &App, _model: &mut Model, _event: Event) { 112 | # } 113 | # fn view(_app: &App, _model: &Model, _frame: Frame) { 114 | # } 115 | ``` 116 | 117 | All Rust programs begin executing at the start of the `main` function and end 118 | when the `main` function ends. In most nannou programs, the main function is 119 | quite small. In short, we build a description of our app and then run it! 120 | 121 | ```rust,no_run 122 | # extern crate nannou; 123 | # use nannou::prelude::*; 124 | # struct Model {} 125 | # fn main() { 126 | nannou::app(model) // Start building the app and specify our `model` 127 | .event(event) // Specify that we want to handle app events with `event` 128 | .simple_window(view) // Request a simple window to which we'll draw with `view` 129 | .run(); // Run it! 130 | # } 131 | # fn model(_app: &App) -> Model { 132 | # Model {} 133 | # } 134 | # fn event(_app: &App, _model: &mut Model, _event: Event) { 135 | # } 136 | # fn view(_app: &App, _model: &Model, _frame: Frame) { 137 | # } 138 | ``` 139 | 140 | We will describe what these **model**, **event** and **view** functions do 141 | below! 142 | 143 | > Note: In this app building process we get a hint at the fundamental design 144 | > archetype of nannou apps. The approach is roughly based on the 145 | > [Model-View-Controller (MVC) 146 | > pattern](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller), 147 | > though equally inspired by [Functional Reactive Programming 148 | > (FRP)](https://en.wikipedia.org/wiki/Functional_reactive_programming). 149 | > 150 | > In general, these paradigms split a program into: 151 | > 152 | > - a **model** describing the internal state 153 | > - a **view** describing how to present the model and 154 | > - a **controller** describing how to update the model on certain events. 155 | > 156 | > If you zoom out a bit you can think of the computer as a model, the screen as 157 | > a view (the audio output could also be thought of as a view), and the keyboard 158 | > (or mouse) as the controller. A user looks at the view and can change the 159 | > state of the model using the controller. If a program does not require user 160 | > input, the controller might use an algorithm based on time or some other 161 | > application event to modify the model. 162 | 163 | ## **model** - initialise our Model 164 | 165 | ```rust,no_run 166 | # #![allow(dead_code)] 167 | # extern crate nannou; 168 | # use nannou::prelude::*; 169 | # struct Model {} 170 | fn model(_app: &App) -> Model { 171 | Model {} 172 | } 173 | # fn main() {} 174 | ``` 175 | 176 | The `model` function is run once at the beginning of the nannou app and produces 177 | a fresh, new instance of the **Model** that we declared previously, AKA the app 178 | state. This can be thought of as the "setup" stage of our application. Here, we 179 | might do things like create some windows, create a GUI, load some images or 180 | anything else that we want to happen once at the beginning of our program. We 181 | will learn how to do all of these things in future tutorials, but for now we 182 | will just return an instance of our empty **Model**. 183 | 184 | > Note: To assist with the creation of windows, GUIs, audio streams and other 185 | > kinds of I/O, access to the **App** is provided as an *input* to the function. 186 | > The **App** type can be thought of as a helper type that wraps up the finicky 187 | > details of the application (such as establishing event loops, spawning I/O 188 | > streams, etc) and provides an easy to use, high-level API on top. Providing 189 | > access to the **App** via a function's first argument is a common practice 190 | > throughout nannou's API. 191 | > 192 | > ```rust,no_run 193 | > # #![allow(dead_code)] 194 | > # extern crate nannou; 195 | > # use nannou::prelude::*; 196 | > # struct Model {} 197 | > // ----- Access to the `App` passed as an input to the function. 198 | > // / 199 | > // v 200 | > fn model(_app: &App) -> Model { 201 | > Model {} 202 | > } 203 | > # fn main() {} 204 | > ``` 205 | > 206 | > You can learn more about what the **App** is responsible for and capable of 207 | > [here](https://docs.rs/nannou/latest/nannou/app/struct.App.html). 208 | 209 | ## **event** - updating the Model on app events 210 | 211 | ```rust,no_run 212 | # #![allow(dead_code)] 213 | # extern crate nannou; 214 | # use nannou::prelude::*; 215 | # struct Model {} 216 | fn event(_app: &App, _model: &mut Model, _event: Event) { 217 | } 218 | # fn main() {} 219 | ``` 220 | 221 | The **event** function is some code that will run every time some kind of app 222 | event occurs. There are many different kinds of app events including mouse and 223 | keyboard presses, window resizes, timed updates and many more. Each of these are 224 | events during which we may wish to update our **Model** in some way. For 225 | example, we may wish to turn a camera when a mouse is moved, begin drawing a 226 | shape when a button is pressed, or step forward an animation on timed updates. 227 | 228 | All of these events are described within the **Event** type. One way to 229 | distinguish between which event is currently occurring is to ["pattern 230 | match"](https://doc.rust-lang.org/book/ch06-02-match.html) on the event and 231 | handle only those events that we care about, ignoring all the others. A simpler 232 | approach is to not register an **event** function while building the app at all, 233 | and instead only register more specific functions for those events that we care 234 | about. 235 | 236 | For example, if instead of handling *all* events we only want to handle timed 237 | updates (an event that by default occurs 60 times per second) we could change 238 | our app building code to this: 239 | 240 | ```rust,no_run 241 | # #![allow(dead_code)] 242 | # extern crate nannou; 243 | # use nannou::prelude::*; 244 | # struct Model {} 245 | fn main() { 246 | nannou::app(model) 247 | .update(update) // rather than `.event(event)`, now we only subscribe to updates 248 | .simple_window(view) 249 | .run(); 250 | } 251 | # fn model(_app: &App) -> Model { 252 | # Model {} 253 | # } 254 | # fn update(_app: &App, _model: &mut Model, _update: Update) { 255 | # } 256 | # fn view(_app: &App, _model: &Model, _frame: Frame) { 257 | # } 258 | ``` 259 | 260 | And remove our `event` function in favour of an `update` function: 261 | 262 | ```rust,no_run 263 | # #![allow(dead_code)] 264 | # extern crate nannou; 265 | # use nannou::prelude::*; 266 | # struct Model {} 267 | fn update(_app: &App, _model: &mut Model, _update: Update) { 268 | } 269 | # fn main() {} 270 | ``` 271 | 272 | Now, our new **update** function will only run each time a timed update 273 | occurs. 274 | 275 | > Note: Nannou provides a whole suite of different events that may be registered 276 | > while building an app or window in this way. See the [all_functions.rs 277 | > example](https://github.com/nannou-org/nannou/blob/master/examples/nannou_basics/all_functions.rs) 278 | > for a demonstration of most of the different kinds of events that are 279 | > available. 280 | 281 | ## **view** - presenting the Model to a window 282 | 283 | ```rust,no_run 284 | # #![allow(dead_code)] 285 | # extern crate nannou; 286 | # use nannou::prelude::*; 287 | # struct Model {} 288 | fn view(_app: &App, _model: &Model, _frame: Frame) { 289 | } 290 | # fn main() {} 291 | ``` 292 | 293 | Finally, the **view** allows us to present the state of the model to a window by 294 | drawing to its **Frame** and returning the frame at the end. Here we can change 295 | the background colour, use the **Draw** API to draw a scene, draw a GUI to the 296 | window or even use the wgpu API to draw to the frame using our own textures and 297 | render passes. All of this will be covered by future tutorials. 298 | 299 | ## Concluding Remarks 300 | 301 | Hopefully this has given you a rough idea of how nannou apps work! Do not stress 302 | if some of the syntax looks confusing or some of the specifics still seem 303 | unclear - we will aim to cover these and more in future tutorials :) 304 | --------------------------------------------------------------------------------