README.md 8.83 KB
Newer Older
Gargaj's avatar
Gargaj committed
1 2
# Bonzomatic

Gargaj's avatar
Gargaj committed
3
[![GitHub Workflow Status](https://img.shields.io/github/workflow/status/Gargaj/Bonzomatic/build-on-push?logo=github)](https://github.com/Gargaj/Bonzomatic/actions)
Gargaj's avatar
Gargaj committed
4 5 6
[![Appveyor build status](https://ci.appveyor.com/api/projects/status/ix6fwi6nym1tu4e7?svg=true)](https://ci.appveyor.com/project/Gargaj/bonzomatic)
[![Travis build status](https://img.shields.io/travis/Gargaj/Bonzomatic?logo=travis)](https://travis-ci.org/Gargaj/Bonzomatic)
[![Gitter chat](https://badges.gitter.im/Gargaj/Bonzomatic.svg)](https://gitter.im/Gargaj/Bonzomatic?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
Gargaj's avatar
Gargaj committed
7 8 9 10

## What's this?
This is a live-coding tool, where you can write a 2D fragment/pixel shader while it is running in the background.

Dmitry Teplov's avatar
Dmitry Teplov committed
11
![Screenshot](https://i.imgur.com/8K8IztLl.jpg)
Gargaj's avatar
Gargaj committed
12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28

The tool was originally conceived and implemented after the Revision 2014 demoscene party's live coding competition where two contestants improv-code an effect in 25 minutes head-to-head. Wanna see how it looks in action? Check https://www.youtube.com/watch?v=KG_2q4OEhKc

## Keys
- F2: toggle texture preview
- F5 or Ctrl-R: recompile shader
- F11 or Ctrl/Cmd-f: hide shader overlay
- Alt-F4 or Shift+Escape: exbobolate your planet

## Requirements
On Windows, both DirectX 9 and 11 are supported.

For the OpenGL version (for any platform), at least OpenGL 4.1 is required.

On recent macOS, to allow sound input to be captured (for FFT textures to be generated), you need to: Open up System Preferences, click on Security & Privacy, click on the Privacy tab then click on the Microphone menu item. Make sure Bonzomatic.app is in the list and ticked.

## Configuration
Gargaj's avatar
Gargaj committed
29
You can configure Bonzomatic by creating a `config.json` and placing it next to the binary executable you're planning to run in the working directory for the binary; Bonzomatic will helpfully print this directory out for you when you run it, and you can also pass a file (with absolute or relative path, whichever you want) as parameter to the executable to load any other file as `config.json`. This allows you to have multiple configurations for multiple situations.
30 31

The file can have the following contents: (all fields are optional)
Gargaj's avatar
Gargaj committed
32 33
``` javascript
{
Gargaj's avatar
Gargaj committed
34
  "window":{ // default window size / state; if there's a setup dialog, it will override it
Gargaj's avatar
Gargaj committed
35 36 37 38
    "width":1920,
    "height":1080,
    "fullscreen":true,
  },
Gargaj's avatar
Gargaj committed
39 40 41
  "audio":{ // default audio device settings; if there's a setup dialog, it will override it
    "useInput":false, // if true, use line-in/mic/...; if false, attempt to create a loopback device and use stereo out
  },
42
  "font":{ // all paths in the file are also relative to the binary, but again, can be absolute paths if that's more convenient
Gargaj's avatar
Gargaj committed
43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62
    "file":"Input-Regular_(InputMono-Medium).ttf",
    "size":16,
  },
  "rendering":{
    "fftSmoothFactor": 0.9, // 0.0 means there's no smoothing at all, 1.0 means the FFT is completely smoothed flat
    "fftAmplification": 1.0, // 1.0 means no change, larger values will result in brighter/stronger bands, smaller values in darker/weaker ones
  },
  "textures":{ // the keys below will become the shader variable names
    "texChecker":"textures/checker.png",
    "texNoise":"textures/noise.png",
    "texTex1":"textures/tex1.jpg",
  },
  "gui":{
    "outputHeight": 200,
    "opacity": 192, // 255 means the editor occludes the effect completely, 0 means the editor is fully transparent
    "texturePreviewWidth": 64,
    "spacesForTabs": false,
    "tabSize": 8,
    "visibleWhitespace": true,
    "autoIndent": "smart", // can be "none", "preserve" or "smart"
63 64
    "scrollXFactor": 1.0, // if horizontal scrolling is too slow you can speed it up here (or change direction)
    "scrollYFactor": 1.0, // if vertical scrolling is too slow you can speed it up here (or change direction)
Gargaj's avatar
Gargaj committed
65 66 67 68 69 70 71 72
  },
  "midi":{ // the keys below will become the shader variable names, the values are the CC numbers
    "fMidiKnob": 16, // e.g. this would be CC#16, i.e. by default the leftmost knob on a nanoKONTROL 2
  },
  // this section is if you want to enable NDI streaming; otherwise just ignore it
  "ndi":{
    "enabled": true,
    "connectionString": "<ndi_product something=\"123\"/>", // metadata sent to the receiver; completely optional
73
    "identifier": "hello!", // device identifier; must be unique, also helps source discovery/identification in the receiver if there are multiple sources on the network
Gargaj's avatar
Gargaj committed
74 75 76
    "frameRate": 60.0, // frames per second
    "progressive": true, // progressive or interleaved?
  },
77 78 79 80 81 82 83 84 85 86 87
  // this section is if you want to customise colors to your liking
  "theme":{
    "text": "FFFFFF", // color format is "RRGGBB" or "AARRGGBB" in hexadecimal
    "comment": "00FF00",
    "number": "FF8000",
    "op": "FFCC00",
    "keyword": "FF6600",
    "type": "00FFFF",
    "builtin": "44FF88",
    "preprocessor": "C0C0C0",
    "selection": "C06699CC", // background color when selecting text
Gargaj's avatar
Gargaj committed
88
    "charBackground": "C0000000", // if set, this value will be used (instead of gui opacity) behind characters
89
  },
Gargaj's avatar
Gargaj committed
90 91 92 93 94 95 96 97 98 99 100
  "postExitCmd":"copy_to_dropbox.bat" // this command gets ran when you quit Bonzomatic, and the shader filename gets passed to it as first parameter. Use this to take regular backups.
}
```
### Automatic shader backup
If you want the shader to be backed up once you quit Bonzomatic, you can use the above `postExitCmd` parameter in the config, and use a batch file like this:
```
@echo off
REM ### cf. https://stackoverflow.com/a/23476347
for /f "tokens=2 delims==" %%a in ('wmic OS Get localdatetime /value') do set "dt=%%a"
set "YY=%dt:~2,2%" & set "YYYY=%dt:~0,4%" & set "MM=%dt:~4,2%" & set "DD=%dt:~6,2%"
set "HH=%dt:~8,2%" & set "Min=%dt:~10,2%" & set "Sec=%dt:~12,2%"
Gargaj's avatar
Gargaj committed
101
copy %1 X:\MyShaderBackups\%YYYY%%MM%%DD%-%HH%%Min%%Sec%.glsl
Gargaj's avatar
Gargaj committed
102 103 104 105 106 107 108
```
This will copy the shader timestamped into a specified folder.

## Building
As you can see you're gonna need [CMAKE](https://cmake.org/) for this, but don't worry, a lot of it is automated at this point.

### Windows
Cate Acher's avatar
Cate Acher committed
109
Use at least [Visual C++ 2010](https://support.microsoft.com/ru-ru/help/2977003/the-latest-supported-visual-c-downloads). For the DX9/DX11 builds, obviously you'll be needing a [DirectX SDK](https://www.microsoft.com/en-us/download/details.aspx?id=6812), though a lot of it is already in the Windows 8.1 SDK as well.
Gargaj's avatar
Gargaj committed
110 111 112 113

### OSX/macOS
```cmake``` should take care of everything:
```
114 115 116
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ../
cmake --build .
Gargaj's avatar
Gargaj committed
117
```
118 119
The Bonzomatic.app bundle, resulting from the compilation, should be found in `./build/Bonzomatic.app`. You can place it anywhere.
We do NOT recommend putting it in /Applications. Bonzomatic is looking for config.json files and resources living at the same level of the app.
Gargaj's avatar
Gargaj committed
120 121

### Linux
122
You'll need ```xorg-dev```, `libasound2-dev` and ```libglu1-mesa-dev```; after that ```cmake``` should take care of the rest:
Gargaj's avatar
Gargaj committed
123
```
124
apt install xorg-dev libglu1-mesa-dev libasound2-dev cmake
Gargaj's avatar
Gargaj committed
125 126 127 128 129 130
cd Bonzomatic
cmake .
make
make install
```

131 132 133 134 135 136 137 138 139 140 141 142 143
### OpenBSD
[Xenocara](https://xenocara.org) contains all required components.  Hack away with
```
cmake .
make
```
or use the port
```
cd /usr/ports/graphics/bonzomatic
make install
```


Gargaj's avatar
Gargaj committed
144 145 146 147 148 149 150
## Organizing a competition
If you want to organize a competition using Bonzomatic at your party, here's a handy-dandy guide on how to get started:
https://github.com/Gargaj/Bonzomatic/wiki/How-to-set-up-a-Live-Coding-compo

## Credits and acknowledgements
### Original / parent project authors
- "ScintillaGL" project by Mykhailo Parfeniuk (https://github.com/sopyer/ScintillaGL)
Gargaj's avatar
Gargaj committed
151
- Riverwash LiveCoding Tool by Michał Staniszewski and Michal Szymczyk (http://www.plastic-demo.org)
Gargaj's avatar
Gargaj committed
152 153

### Libraries and other included software
Dmitry Teplov's avatar
Dmitry Teplov committed
154
- Scintilla editing component by the Scintilla Dev Team (https://www.scintilla.org)
Gargaj's avatar
Gargaj committed
155
- OpenGL Extension Wrangler Library by Nigel Stewart (http://glew.sourceforge.net)
Gargaj's avatar
Gargaj committed
156
- mini_al by David Reid (https://github.com/dr-soft/mini_al)
Gargaj's avatar
Gargaj committed
157
- KISSFFT by Mark Borgerding (https://github.com/mborgerding/kissfft)
Dmitry Teplov's avatar
Dmitry Teplov committed
158 159
- STB Image and Truetype libraries by Sean Barrett (https://nothings.org)
- GLFW by whoever made GLFW (https://www.glfw.org/faq.html)
Gargaj's avatar
Gargaj committed
160
- JSON++ by Hong Jiang (https://github.com/hjiang/jsonxx)
Dmitry Teplov's avatar
Dmitry Teplov committed
161
- NDI(tm) SDK by NewTek(tm) (https://www.newtek.com/ndi.html)
Gargaj's avatar
Gargaj committed
162 163 164

These software are available under their respective licenses.

Gargaj's avatar
Gargaj committed
165 166
The remainder of this project code was (mostly, I guess) written by Gargaj / Conspiracy and is public domain.
OSX / macOS maintenance and ports by Alkama / Tpolm + Calodox; Linux maintenance by PoroCYon / K2.
Gargaj's avatar
Gargaj committed
167 168

## Contact / discussion forum
Dmitry Teplov's avatar
Dmitry Teplov committed
169
If you have anything to say, do it at https://www.pouet.net/topic.php?which=9881 or [![Join the chat at https://gitter.im/Gargaj/Bonzomatic](https://badges.gitter.im/Gargaj/Bonzomatic.svg)](https://gitter.im/Gargaj/Bonzomatic?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)