klemek/forge-steel
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

docs: more docs

Browse Source
This commit is contained in:
klemek
2025-11-05 22:41:20 +01:00
parent 8cc934db5d
commit eca95d5f18
6 changed files with 325 additions and 88 deletions
Download Patch File Download Diff File Expand all files Collapse all files
DEVELOPMENT.md
+98
View File
@@ -0,0 +1,98 @@
# Working on this project
## Makefile.dev targets
```text
clean remove build folder
build build project into build/forge
run run project with test args
demo run project with demo mode
valgrind valgrind analysis
clean-release remove autoconf/automake files
test-release try to build release
release-% make full release of version %
release-arch make arch-linux release package
```
## Release guide
```shell
# make full build
make -f Makefile.dev release-1.0.0
# push release
git push origin master --tags
# create release from tag on github
# attach .tar.gz to the github release
make -f Makefile.dev release-arch
# attach .pkg.tar.zst to the github release
```
## Roadmap
- [x] Basics
- [x] Create GLSL Window
- [x] Load static fragment shader into GLSL
- [x] Add default uniforms
- [x] Read fragment shader from file
- [x] Handle compilation errors
- [x] Minimal working fragment sample
- [x] Hot-reload fragment shader (with arg)
- [x] Specify fragment shader path
- [x] Force fullscreen
- [x] Select screen as argument / config
- [x] fps in window title
- [x] Clean code
- [x] Multi-stage shaders
- [x] Test 2 stages with render to texture
- [x] 2 in 2 fx 1 mix 1 fx layout
- [x] Include common code
- [x] 16 input + 16 fx definition and selection (with const param)
- [x] Feedback texture
- [x] Shaders config file
- [x] uniform config
- [x] fragment config
- [x] subroutines config
- [x] demo mode
- [x] random seed injected into shaders
- [x] internal texture size for speed
- [x] pass state as uniform
- [x] debug shader (and in monitor)
- [x] random mode / demo mode with R/D key
- [x] Clean code and fix things
- [x] Midi
- [x] Read Midi events
- [x] Read midi mapping config file
- [x] Write Midi events
- [x] Send midi data to shaders
- [x] Save midi state
- [x] Load midi state from last save
- [x] State machine with A/B switch
- [x] Tap-tempo feature
- [x] Clean code and fix things
- [x] Video input
- [x] Fixed camera video
- [x] Pass video info to shaders
- [x] Sub process video reading
- [x] Shader based format mapping
- [x] Video mapping config file
- [x] Get first video size matching internal size
- [x] Other internal size for video
- [x] Pass input fps into shaders for debug
- [x] Clean code and fix things
- [x] Monitor screen
- [x] 2nd window
- [x] Use buffers as panels (INA A FXA / DEBUG A+B FXA+B / INB B FXB)
- [x] Clean code and fix things
- [x] Share openGL state between monitor and screen
- [ ] Other
- [ ] Update readme with usage documentation
- [ ] Documentation in default config file
- [x] Clone "shaders" and config in system path at setup
- [ ] Minimal sample shaders
- [ ] Find and fix opengl errors 0500 ?
- [ ] Investigate video device fps loss (bad unregister ?)
- explore libv4l directly [github](https://github.com/philips/libv4l) (with `-lv4l2`)
- [ ] Bonus
- [ ] Record show as text files
- [ ] Play from record text file
- [ ] Try to write NanoKontrol config
Makefile.dev
-4
View File
@@ -31,10 +31,6 @@ run: build
demo: build
./build/$(TARGET) $(TEST_ARGS) --demo
.PHONY: install
install: build
cp -f build/$(TARGET) $(INSTALL_DIR)/$(TARGET)
.PHONY: valgrind
valgrind: build
valgrind \
PKGBUILD
+1 -1
View File
@@ -3,7 +3,7 @@ pkgver=0.0.0
pkgrel=1
pkgdesc="Fusion Of Real Time Generative Effects"
arch=('i686' 'pentium4' 'x86_64' 'arm' 'armv7h' 'armv6h' 'aarch64' 'riscv64')
depends=('glfw>=1:3.0', 'v4l-utils>=1.30', 'alsa-lib>=1.2.14')
depends=('glfw>=1:3', 'v4l-utils>=1.32', 'alsa-lib>=1.2', 'libglvnd>=1.7')
url="https://github.com/klemek/forge-steel"
source=("${pkgname}-steel-${pkgver}.tar.gz::https://github.com/klemek/forge-steel/releases/download/steel-v${pkgver}/${pkgname}-steel-${pkgver}.tar.gz")
sha256sums=('71e2db98e1346b101d175535c30875f28eb21432f4147ecc2b40c9da3973f5fb')
README.md
+60 -83
View File
@@ -4,7 +4,33 @@
> **F**usion **O**f **R**eal **T**ime **G**enerative **E**ffects
*Steel version (linux executable)*
*Steel version (PC executable)*
TODO cool image and youtube link
## Table of Contents
- [F.O.R.G.E. (Steel)](#forge-steel)
- [Table of Contents](#table-of-contents)
- [What is FORGE ?](#what-is-forge-)
- [Install](#install)
- [Prerequisites](#prerequisites)
- [From release](#from-release)
- [From repository (PKGBUILD)](#from-repository-pkgbuild)
- [From repository (dev version)](#from-repository-dev-version)
- [Usage](#usage)
- [CLI arguments](#cli-arguments)
- [Included Shaders and Config](#included-shaders-and-config)
- [Making your own FORGE config](#making-your-own-forge-config)
- [Working with `frag0.glsl`](#working-with-frag0glsl)
- [Frequently Asked Questions](#frequently-asked-questions)
- [Why "steel"?](#why-steel)
- [How do I report a bug?](#how-do-i-report-a-bug)
- [Help I got low FPS on my video device](#help-i-got-low-fps-on-my-video-device)
## What is FORGE ?
![](images/forge.drawio.png)
TODO
@@ -12,10 +38,12 @@ TODO
### Prerequisites
* libglfw
* libGL
* libasound2
* libv4l
| 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 |
### From release
@@ -51,7 +79,9 @@ make
make install
```
## CLI arguments
## Usage
### CLI arguments
```txt
usage: forge [-h] [-v] [-hr] [-s=SCREEN] [-m=SCREEN] [-mo] [-f=DIR_PATH] [-c=CFG_PATH] [-sf=STATE_PATH] [-ls / -nls] [-ss / -nss] [-is=SIZE] [-v=FILE] [-vs=SIZE] [-t=TEMPO] [--demo] [-w]
@@ -82,83 +112,30 @@ options:
--trace-fps print fps status of subsystems
```
## Release guide
### Included Shaders and Config
```shell
# make full build
make -f Makefile.dev release-1.0.0
# push release
git push origin master --tags
# create release from tag on github
# attach .tar.gz to the github release
make -f Makefile.dev release-arch
# attach .pkg.tar.zst to the github release
```
TODO
## Roadmap
### Making your own FORGE config
- [x] Basics
- [x] Create GLSL Window
- [x] Load static fragment shader into GLSL
- [x] Add default uniforms
- [x] Read fragment shader from file
- [x] Handle compilation errors
- [x] Minimal working fragment sample
- [x] Hot-reload fragment shader (with arg)
- [x] Specify fragment shader path
- [x] Force fullscreen
- [x] Select screen as argument / config
- [x] fps in window title
- [x] Clean code
- [x] Multi-stage shaders
- [x] Test 2 stages with render to texture
- [x] 2 in 2 fx 1 mix 1 fx layout
- [x] Include common code
- [x] 16 input + 16 fx definition and selection (with const param)
- [x] Feedback texture
- [x] Shaders config file
- [x] uniform config
- [x] fragment config
- [x] subroutines config
- [x] demo mode
- [x] random seed injected into shaders
- [x] internal texture size for speed
- [x] pass state as uniform
- [x] debug shader (and in monitor)
- [x] random mode / demo mode with R/D key
- [x] Clean code and fix things
- [x] Midi
- [x] Read Midi events
- [x] Read midi mapping config file
- [x] Write Midi events
- [x] Send midi data to shaders
- [x] Save midi state
- [x] Load midi state from last save
- [x] State machine with A/B switch
- [x] Tap-tempo feature
- [x] Clean code and fix things
- [x] Video input
- [x] Fixed camera video
- [x] Pass video info to shaders
- [x] Sub process video reading
- [x] Shader based format mapping
- [x] Video mapping config file
- [x] Get first video size matching internal size
- [x] Other internal size for video
- [x] Pass input fps into shaders for debug
- [x] Clean code and fix things
- [x] Monitor screen
- [x] 2nd window
- [x] Use buffers as panels (INA A FXA / DEBUG A+B FXA+B / INB B FXB)
- [x] Clean code and fix things
- [x] Share openGL state between monitor and screen
- [ ] Other
- [ ] Update readme with usage documentation
- [ ] Documentation in default config file
- [x] Clone "shaders" and config in system path at setup
- [ ] Find and fix opengl errors 0500 ?
- [ ] Investigate video device fps loss (bad unregister ?)
- [ ] Bonus
- [ ] Record show as text files
- [ ] Play from record text file
- [ ] Try to write NanoKontrol config
TODO
### Working with `frag0.glsl`
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.
### How do I report a bug?
TODO
### Help I got low FPS on my video device
TODO
images/forge.drawio
+166
View File
@@ -0,0 +1,166 @@
<mxfile host="Electron" agent="Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/28.2.8 Chrome/140.0.7339.249 Electron/38.5.0 Safari/537.36" version="28.2.8">
<diagram name="Page-1" id="uAijJZJkDDyZqolEMDYd">
<mxGraphModel dx="1848" dy="672" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
<root>
<mxCell id="0" />
<mxCell id="1" parent="0" />
<mxCell id="3Uv0AfHo8SbA6Qcxonjd-1" value="F.O.R.G.E." style="rounded=0;whiteSpace=wrap;html=1;verticalAlign=top;" vertex="1" parent="1">
<mxGeometry x="154" y="210" width="546" height="350" as="geometry" />
</mxCell>
<mxCell id="3Uv0AfHo8SbA6Qcxonjd-2" value="TEXTURE" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
<mxGeometry x="270" y="250" width="120" height="60" as="geometry" />
</mxCell>
<mxCell id="3Uv0AfHo8SbA6Qcxonjd-3" value="SHADER" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
<mxGeometry x="274" y="410" width="120" height="60" as="geometry" />
</mxCell>
<mxCell id="3Uv0AfHo8SbA6Qcxonjd-4" value="TEXTURE" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
<mxGeometry x="280" y="260" width="120" height="60" as="geometry" />
</mxCell>
<mxCell id="3Uv0AfHo8SbA6Qcxonjd-5" value="TEXTURE&lt;br&gt;1...N" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
<mxGeometry x="290" y="270" width="120" height="60" as="geometry" />
</mxCell>
<mxCell id="3Uv0AfHo8SbA6Qcxonjd-6" value="SHADER" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
<mxGeometry x="284" y="420" width="120" height="60" as="geometry" />
</mxCell>
<mxCell id="3Uv0AfHo8SbA6Qcxonjd-7" value="SHADER&lt;br&gt;1...N" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
<mxGeometry x="294" y="430" width="120" height="60" as="geometry" />
</mxCell>
<mxCell id="3Uv0AfHo8SbA6Qcxonjd-9" value="" style="shape=flexArrow;endArrow=classic;html=1;rounded=0;" edge="1" parent="1">
<mxGeometry width="50" height="50" relative="1" as="geometry">
<mxPoint x="333.5" y="340" as="sourcePoint" />
<mxPoint x="333.5" y="400.5" as="targetPoint" />
</mxGeometry>
</mxCell>
<mxCell id="3Uv0AfHo8SbA6Qcxonjd-11" value="UNIFORM&lt;br&gt;SAMPLERS" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="3Uv0AfHo8SbA6Qcxonjd-9">
<mxGeometry x="0.1111" relative="1" as="geometry">
<mxPoint x="-40" y="-13" as="offset" />
</mxGeometry>
</mxCell>
<mxCell id="3Uv0AfHo8SbA6Qcxonjd-10" value="" style="shape=flexArrow;endArrow=classic;html=1;rounded=0;" edge="1" parent="1">
<mxGeometry width="50" height="50" relative="1" as="geometry">
<mxPoint x="370" y="400" as="sourcePoint" />
<mxPoint x="370" y="340" as="targetPoint" />
</mxGeometry>
</mxCell>
<mxCell id="3Uv0AfHo8SbA6Qcxonjd-12" value="RENDERS TO&lt;br&gt;FRAMEBUFFERS" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="3Uv0AfHo8SbA6Qcxonjd-10">
<mxGeometry x="-0.3556" y="2" relative="1" as="geometry">
<mxPoint x="62" y="-1" as="offset" />
</mxGeometry>
</mxCell>
<mxCell id="3Uv0AfHo8SbA6Qcxonjd-13" value="" style="shape=flexArrow;endArrow=classic;html=1;rounded=0;" edge="1" parent="1">
<mxGeometry width="50" height="50" relative="1" as="geometry">
<mxPoint x="140" y="300" as="sourcePoint" />
<mxPoint x="260" y="299.5" as="targetPoint" />
</mxGeometry>
</mxCell>
<mxCell id="3Uv0AfHo8SbA6Qcxonjd-14" value="DMA&lt;div&gt;BUFFERS&lt;/div&gt;" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="3Uv0AfHo8SbA6Qcxonjd-13">
<mxGeometry x="0.1111" relative="1" as="geometry">
<mxPoint x="-10" y="-19" as="offset" />
</mxGeometry>
</mxCell>
<mxCell id="3Uv0AfHo8SbA6Qcxonjd-15" value="" style="shape=flexArrow;endArrow=classic;html=1;rounded=0;" edge="1" parent="1">
<mxGeometry width="50" height="50" relative="1" as="geometry">
<mxPoint x="140" y="450.5" as="sourcePoint" />
<mxPoint x="260" y="450" as="targetPoint" />
</mxGeometry>
</mxCell>
<mxCell id="3Uv0AfHo8SbA6Qcxonjd-16" value="UNIFORMS" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="3Uv0AfHo8SbA6Qcxonjd-15">
<mxGeometry x="0.1111" relative="1" as="geometry">
<mxPoint x="-10" y="-19" as="offset" />
</mxGeometry>
</mxCell>
<mxCell id="3Uv0AfHo8SbA6Qcxonjd-19" value="OUTPUT&lt;br&gt;SHADER" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
<mxGeometry x="530" y="270" width="120" height="60" as="geometry" />
</mxCell>
<mxCell id="3Uv0AfHo8SbA6Qcxonjd-23" value="MONITOR&lt;br&gt;SHADER" style="rounded=0;whiteSpace=wrap;html=1;dashed=1;" vertex="1" parent="1">
<mxGeometry x="530" y="360" width="120" height="60" as="geometry" />
</mxCell>
<mxCell id="3Uv0AfHo8SbA6Qcxonjd-24" value="" style="shape=flexArrow;endArrow=classic;html=1;rounded=0;dashed=1;" edge="1" parent="1">
<mxGeometry width="50" height="50" relative="1" as="geometry">
<mxPoint x="420" y="320" as="sourcePoint" />
<mxPoint x="520" y="360" as="targetPoint" />
</mxGeometry>
</mxCell>
<mxCell id="3Uv0AfHo8SbA6Qcxonjd-25" value="" style="shape=flexArrow;endArrow=classic;html=1;rounded=0;" edge="1" parent="1">
<mxGeometry width="50" height="50" relative="1" as="geometry">
<mxPoint x="420" y="290" as="sourcePoint" />
<mxPoint x="520" y="290" as="targetPoint" />
</mxGeometry>
</mxCell>
<mxCell id="3Uv0AfHo8SbA6Qcxonjd-26" value="" style="shape=flexArrow;endArrow=classic;html=1;rounded=0;" edge="1" parent="1">
<mxGeometry width="50" height="50" relative="1" as="geometry">
<mxPoint x="349.5" y="585" as="sourcePoint" />
<mxPoint x="349.5" y="495" as="targetPoint" />
</mxGeometry>
</mxCell>
<mxCell id="3Uv0AfHo8SbA6Qcxonjd-27" value="COMPILES&lt;br&gt;TO" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="3Uv0AfHo8SbA6Qcxonjd-26">
<mxGeometry x="0.1111" relative="1" as="geometry">
<mxPoint x="-55" y="-15" as="offset" />
</mxGeometry>
</mxCell>
<mxCell id="3Uv0AfHo8SbA6Qcxonjd-28" value="SHADER" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
<mxGeometry x="274" y="590" width="120" height="60" as="geometry" />
</mxCell>
<mxCell id="3Uv0AfHo8SbA6Qcxonjd-29" value="SHADER" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
<mxGeometry x="284" y="600" width="120" height="60" as="geometry" />
</mxCell>
<mxCell id="3Uv0AfHo8SbA6Qcxonjd-30" value="GLSL FILE&lt;br&gt;1...N" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
<mxGeometry x="294" y="610" width="120" height="60" as="geometry" />
</mxCell>
<mxCell id="3Uv0AfHo8SbA6Qcxonjd-31" value="MIDI INPUT" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
<mxGeometry x="10" y="420" width="120" height="60" as="geometry" />
</mxCell>
<mxCell id="3Uv0AfHo8SbA6Qcxonjd-36" value="TEXTURE" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
<mxGeometry x="-10" y="250" width="120" height="60" as="geometry" />
</mxCell>
<mxCell id="3Uv0AfHo8SbA6Qcxonjd-37" value="TEXTURE" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
<mxGeometry y="260" width="120" height="60" as="geometry" />
</mxCell>
<mxCell id="3Uv0AfHo8SbA6Qcxonjd-38" value="VIDEO DEVICE&lt;br&gt;1...N" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
<mxGeometry x="10" y="270" width="120" height="60" as="geometry" />
</mxCell>
<mxCell id="3Uv0AfHo8SbA6Qcxonjd-39" value="" style="shape=flexArrow;endArrow=classic;html=1;rounded=0;" edge="1" parent="1">
<mxGeometry width="50" height="50" relative="1" as="geometry">
<mxPoint x="660" y="299.5" as="sourcePoint" />
<mxPoint x="760" y="299.5" as="targetPoint" />
</mxGeometry>
</mxCell>
<mxCell id="3Uv0AfHo8SbA6Qcxonjd-40" value="OUTPUT&lt;br&gt;WINDOW" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
<mxGeometry x="770" y="270" width="120" height="60" as="geometry" />
</mxCell>
<mxCell id="3Uv0AfHo8SbA6Qcxonjd-41" value="" style="shape=flexArrow;endArrow=classic;html=1;rounded=0;dashed=1;" edge="1" parent="1">
<mxGeometry width="50" height="50" relative="1" as="geometry">
<mxPoint x="660" y="389.5" as="sourcePoint" />
<mxPoint x="760" y="389.5" as="targetPoint" />
</mxGeometry>
</mxCell>
<mxCell id="3Uv0AfHo8SbA6Qcxonjd-42" value="MONITOR&lt;br&gt;WINDOW" style="rounded=0;whiteSpace=wrap;html=1;dashed=1;" vertex="1" parent="1">
<mxGeometry x="770" y="360" width="120" height="60" as="geometry" />
</mxCell>
<mxCell id="3Uv0AfHo8SbA6Qcxonjd-43" value="CONTEXT" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
<mxGeometry x="530" y="460" width="120" height="60" as="geometry" />
</mxCell>
<mxCell id="3Uv0AfHo8SbA6Qcxonjd-46" value="" style="shape=flexArrow;endArrow=classic;html=1;rounded=0;" edge="1" parent="1">
<mxGeometry width="50" height="50" relative="1" as="geometry">
<mxPoint x="510" y="490" as="sourcePoint" />
<mxPoint x="430" y="450" as="targetPoint" />
</mxGeometry>
</mxCell>
<mxCell id="3Uv0AfHo8SbA6Qcxonjd-47" value="UNIFORMS" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="3Uv0AfHo8SbA6Qcxonjd-46">
<mxGeometry x="0.1111" relative="1" as="geometry">
<mxPoint x="25" y="-18" as="offset" />
</mxGeometry>
</mxCell>
<mxCell id="3Uv0AfHo8SbA6Qcxonjd-52" value="MIDI OUTPUT" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
<mxGeometry x="770" y="460" width="120" height="60" as="geometry" />
</mxCell>
<mxCell id="3Uv0AfHo8SbA6Qcxonjd-55" value="" style="shape=flexArrow;endArrow=classic;html=1;rounded=0;" edge="1" parent="1">
<mxGeometry width="50" height="50" relative="1" as="geometry">
<mxPoint x="660" y="490" as="sourcePoint" />
<mxPoint x="760" y="490" as="targetPoint" />
</mxGeometry>
</mxCell>
</root>
</mxGraphModel>
</diagram>
</mxfile>
images/forge.drawio.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 64 KiB