forge-steel/README.md

F.O.R.G.E. (Steel)

Fusion Of Real-time Generative Effects

Steel version (PC executable)

Discover an engine where user-defined fragment shaders collide to produce stunning visuals.

See Demo #1 - 1H and Demo #2 - Monitor View on YouTube.

Quick Start

FORGE default project is controlled with a KORG nanoKONTROL2.

Don't worry if you don't have one, the demo mode will still run great.

After you install the project, you can test run the following commands:

# demo mode, works out of the box
forge --demo
# see the monitor output
forge --demo --monitor-only
# open to another screen
forge --demo --screen=1
# open both output and monitor
forge --demo -screen=0 --monitor=1
# nanoKONTROL2 plugged, control the default project
forge
# nanoKONTROL2 plugged, add video devices
forge --video-in=/dev/video0 --video-in=/dev/video1
# run the sample projet and work on it
forge --project=./sample --hot-reload

What to do next

Here are some pointers if you want to customize your FORGE experience:

• Discover the hotkeys
• Familiarize with the CLI arguments
• Discover how to use the default project
• Make your own FORGE project

Table of Contents

• Quick Start
  • What to do next
• What is FORGE ?
• Install
  • Prerequisites
  • From release
  • From repository (PKGBUILD)
  • From repository (dev version)
• Usage
  • Runtime hotkeys
  • CLI arguments
• Default Project
  • Monitor and debug view
  • nanoKONTROL2 layout for the default project
  • Available sources and effects
• Making your own FORGE project
  • forge_project.cfg
  • Writing your fragment shaders
  • Working with #include
• Frequently Asked Questions
  • Why "steel"?
  • My nanoKontrol2 is acting strange
  • How do I report a bug?
  • Help I got low FPS on my video device
  • How do I change the default project built-in sentences?

What is FORGE ?

TODO

Install

Prerequisites

library	apt	pacman
libglfw	libglfw3-dev	extra/glfw
libGL	libgl-dev	extra/libglvnd
libasound	libasound2-dev	extra/alsa-lib
libv4l2	libv4l-dev	extra/v4l-utils
libbsd	libbsd-dev	extra/libbsd

From release

See Releases

tar xvzf forge-steel-x.y.z.tar.gz
cd forge-steel-x.y.z
./configure
make
make install

From repository (PKGBUILD)

git clone --recursive https://github.com/klemek/forge-steel
cd forge
makepkg -si

From repository (dev version)

git clone --recursive https://github.com/klemek/forge-steel
cd forge
aclocal
autoconf
automake --add-missing
./configure
make
make install

Usage

Runtime hotkeys

When running, the following hotkeys are available:

• Esc: Exit window
• R: Randomize shader state
• D: Demo mode On/Off
• A: Auto Random mode On/Off

CLI arguments

usage: forge [-h] [-v] [-p=PROJECT_PATH] [-c=CFG_FILE] [-hr] [-s=SCREEN] [-m=SCREEN] [-mo] [-w] [-t=TEMPO] [-d] [-ar / -nar] [-v=FILE] [-vs=SIZE] [-is=SIZE] [-sf=STATE_PATH] [-ls / -nls] [-ss / -nss] [-tm] [-tf] 

Fusion Of Real-time Generative Effects.

options:
  -h, --help                show this help message and exit
  -v, --version             print version
  -p, --project             forge project directory (default: /usr/share/forge/default)
  -c, --config              config file name (default: forge_project.cfg)
  -hr, --hot-reload         hot reload of shaders scripts
  -s, --screen              output screen number (default: primary)
  -m, --monitor             monitor screen number (default: none)
  -mo, --monitor-only       no output screen
  -w, --windowed            not fullscreen
  -t, --tempo               base tempo (default: 60)
  -d, --demo                demonstration mode (assume --no-save-state, --no-load-state, --auto-random)
  -ar, --auto-random        randomize state every 4 beats
  -nar, --no-auto-random    do not randomize state (default)
  -v, --video-in            path to video capture device (multiple allowed)
  -vs, --video-size         video capture desired height (default: internal texture height)
  -is, --internal-size      internal texture height (default: 720)
  -sf, --state-file         saved state file (default: forge_saved_state.txt)
  -ls, --load-state         load saved state (default)
  -nls, --no-load-state     do not load saved state
  -ss, --save-state         save state (default)
  -nss, --no-save-state     do not save state
  -tm, --trace-midi         print midi code and values
  -tf, --trace-fps          print fps status of subsystems

Default Project

A.K.A Kleπek's shaders

FORGE come pre-loaded with a default project, the following explains how to use it.

Monitor and debug view

When opening the monitor view, here's what to expect:

On the bottom left corner, here's how to read the internal state:

nanoKONTROL2 layout for the default project

In order to control the default project, you can expect it to work with this layout:

In blue is a sample "stage" as most sources/effects use a combination of 4 stages (see table below)

⚠️ you'll need to change your nanoKONTROL2 settings to remove the "toggle" behavior of the buttons and use "external" led control. (Use the KORG KONTROL Editor and the provided data file to setup your controller.)

Available sources and effects

Working with pages and items, you can use the following predefined sources and effects:

P	#	SRC	COL2	COL3	COL4	FX	COL6	COL7	COL8
1	0	Feedback + Thru	Hue	Saturation	Light	Thru	Hue	Saturation	_Light
	1	Lines	Thick. / Dezoom	Rotation	Distortion	Feedback + Shift	Zoom / Dezoom	X Shift	Y Shift
	2	Dots	Zoom	Rotation	Lens	Shift	Zoom / Dezoom	X Shift	Y Shift
	3	Waves	Spacing	Thickness	Vert. Scroll (R)	Colorize	Black Color	White Color	Shift
	4	Noise	Zoom	Voronoi dist.	Details	Quantize	Pixel Size	Bit Depth	Blur
2	5	Video In 1 + Thru	Hue	Saturation	Light	Dithering	Pixel Size	Bit Depth	Blur
	6	CP437	Zoom	Charset	Char. Delta	TV	Lens	Horz. Noise	Dezoom
	7	Sentences	Zoom	Sentence	Vertical repeat	Kaleidoscope	Axes	Rotation	Horz. Scroll
	8	Sentences repeat	X Shift	Sentence	Vertical repeat	CP437	Zoom	Charset	Char. Delta
	9	Isometric grid	Zoom	Scroll	Elevation	Lens	Lens limit	Lens power	Pre Zoom
3	A	Video In 2 + Thru	Hue	Saturation	Light	Spill	Bottom limit	Top Limit	Rotation
	B	Scales	Zoom	Shape	Ripples	Game Of Life	Pixel Size	Ruleset/Threshold	Feedback
	C	Credenza	Zoom	Shape	Ripples	Sobel Filter	Horz. filter	Vert. filter	Filter Size
	D	Cursor	Size	Pos X	Pos Y	Isometric	Zoom	Scroll	Rotate
	E	(Random source)	---	---	---	(Random effect)	---	---	---

Making your own FORGE project

TODO

forge_project.cfg

TODO

Writing your fragment shaders

TODO

Working with #include

TODO

Frequently Asked Questions

Why "steel"?

FORGE is a concept which is intended to be derived onto other forms (like Raspberry PI). In order to differentiate between them each would be name after a different alloy.

FORGE (steel) describe the linux version.

My nanoKontrol2 is acting strange

You may need to change your NanoKontrol2 settings to remove the "toggle" behavior of the buttons and use "external" led control.

Use the KORG KONTROL Editor and the provided data file to setup your controller.

How do I report a bug?

You're free to open a new issue in the Issues page.

Don't forget to add all information available to your bug (version, operating system, etc.).

Help I got low FPS on my video device

There's already an open issue on this subject.

How do I change the default project built-in sentences?

The sentences are defined in default/inc_sentences.glsl.

The script [scripts/sentences.py] can help you update them.