doc: some initial howtos

doc/howto/draw-masks/readme.md

@@ -0,0 +1,33 @@
+# how to draw masks
+
+also see the faq entry how to compile vkdt such that you can
+use your pentablet as pressure-sensitive input:
+
+you need a specific version of glfw to support it.
+you can for instance clone `https://github.com/hanatos/glfw`,
+for instance to `/home/you/vc/glfw`, and then put the
+following in your custom `bin/config.mk`:  
+```
+VKDT_GLFW_CFLAGS=-I/home/you/vc/glfw/include/
+VKDT_GLFW_LDFLAGS=/home/you/vc/glfw/build/src/libglfw3.a
+VKDT_USE_PENTABLET=1
+export VKDT_USE_PENTABLET
+```
+
+of course you can also just use your mouse to draw masks.
+
+for a description how to draw and how the strokes are adapted to the image,
+see [the `draw` module documentation](../../../src/pipe/modules/draw/readme.md).
+to quickly add a `draw` module and the wiring around it to your image graph,
+insert the `draw` block (e.g. by pressing `ctrl-b` in darkroom mode and select
+the `draw` block, then insert it before a certain module in the graph).
+
+drawn masks are especially useful in conjunction with
+[retouching](../../../src/pipe/modules/wavelet/readme.md) and
+[inpainting](../../../src/pipe/modules/inpaint/readme.md).
+it can also be required to not only change the exposure of a masked region, but
+also [grade it differently](../../../src/pipe/modules/grade/readme.md) to match
+the surroundings when removing a shadow, for instance.
+
+also see the (simpler) [graduated density](../../../src/pipe/modules/grad/readme.md)
+module which can create a simple linear gradient mask without brush strokes.

doc/howto/gamepad/readme.md

@@ -0,0 +1,17 @@
+# how to use your gamepad
+
+currently, best tested is a sony dualshock controller.
+
+to avoid side effects especially with certain mouse pads being detected as joysticks,
+the use of joysticks is switched off by default. to enable it, make sure your
+`~/.config/vkdt/config.rc` contains a line:
+
+```
+intgui/disable_joystick:0
+```
+
+in general, `x` selects (enters lighttable/darkroom) and `o` aborts (goes back
+to lighttable/files view).
+
+to bring up context sensitive help overlaid on your screen, press the
+playstation button in the center.

doc/howto/gui-basics/readme.md

@@ -0,0 +1,35 @@
+# how to do basic things in the gui
+
+## views
+
+basic cascade of ui views is:
+
+files <-> lighttable <-> darkroom
+
+you can usually walk the arrows by key accel (enter/escape) or gamepad (`x`/`o`).
+
+you can export your work but don't have to save it.
+
+`.cfg` is saved when you exit darkroom mode or switch to the next image
+(backspace/space or L1/R1).
+
+`vkdt.db` (labels and ratings) is saved when you switch folder or exit vkdt.
+
+
+## rate and label
+
+colour labels `f1`-`f5`
+
+star ratings `1`-`5`
+
+these key accels work in both lighttable mode (on the whole selection) and in
+darkroom mode (only on the single edited image).
+
+## hotkeys
+
+can be customised for each view separately in the gui via `settings` ->
+`hotkeys`. some keys are special and not in the hotkey system.
+
+`f11` goes full screen
+
+`ctrl+q` quits the application

doc/howto/howto.md

@@ -0,0 +1,21 @@
+# howto
+
+this folder lists quick instructions on a few special topics:
+
+* [how to do basic things in the gui](./gui-basics/readme.md)
+* [how to draw masks](./draw-masks/readme.md)
+* [how to use your gamepad](./gamepad/readme.md)
+* [how to customise metadata display](./metadata/readme.md)
+
+-- these following topics do not exist yet --
+
+* [display colour management](./colour-display/readme.md)
+* [how to characterise the colour response of your camera](./colour-input/readme.md)
+* [how to reduce image noise](./noise-profiling/readme.md)
+* [how to do timelapses and keyframes](./timelapse/readme.md)
+* [how to manage presets](./presets/readme.md)
+* [how to use and create custom blocks](./blocks/readme.md)
+* [how to use feedback connectors](./feedback/readme.md)
+* [how to create a css/html website gallery](./gallery/readme.md)
+* [how to customise the favourites ui in darkroom mode](./favs/readme.md)
+* [how to fit parameters automatically](./fit/readme.md)

doc/howto/metadata/readme.md

@@ -0,0 +1,13 @@
+# how to customise metadata display
+
+the metadata is sourced externally via the `exiftool` command.
+so first make sure you installed it on your system. the exact
+command that is executed to create the view in the `metadata` expander
+in lighttable mode is defined in the `~/.config/vkdt/config.rc` file:
+
+```
+strgui/metadata/command:/usr/bin/exiftool -l -createdate -aperture -shutterspeed -iso
+```
+
+this default command will print in two line format (`-l`) the information
+that follows after it. consult `man exiftool` for more options.

readme.md

@@ -18,7 +18,6 @@ targets, such as the main view and histograms.
 
 ## features
 
-* [image operation modules documentation](src/pipe/modules/readme.md)
 * [very fast GPU only processing](src/qvk/readme.md)
 * [general DAG of processing operations](src/pipe/readme.md), featuring multiple inputs and outputs and
   feedback connectors for animation/iteration
@@ -32,6 +31,11 @@ targets, such as the main view and histograms.
 * [automatic parameter optimisation](src/fit/readme.md), for instance to fit vignetting
 * [heavy handed processing](src/pipe/modules/cnn/readme.md) at almost realistic speeds
 
+## documentation
+
+* [image operation modules documentation](src/pipe/modules/readme.md)
+* [how to do selected things](doc/howto/howto.md)
+
 ## packages
 
 there are up-to-date packages (deb/rpm/pkgbuild) in the
@@ -54,10 +58,12 @@ vulkan validation layers, so you need to have them installed), try
   make debug -j12
 ```
 
-simply run `make` without the `debug` for a release build. `make sanitize` is
-supported to switch on the address sanitizer. changes to the compile time
-configuration as well as the compiler toolchain can be set in `config.mk`. if
-you don't have that file yet, you can copy it from `config.mk.defaults`.
+simply run `make` without the `debug` for a release build. note that the debug
+build includes some extra memory overhead and performs expensive checks and can
+thus be much slower. `make sanitize` is supported to switch on the address
+sanitizer. changes to the compile time configuration as well as the compiler
+toolchain can be set in `config.mk`. if you don't have that file yet, you can
+copy it from `config.mk.defaults`.
 
 ## running
 
@@ -69,7 +75,7 @@ anywhere, create a symlink such as `/usr/local/bin/vkdt -> ~/vc/vkdt/bin/vkdt`.
 ```
 raw files will be assigned the `bin/default-darkroom.i-raw` processing graph.
 if you run the command line interface `vkdt-cli`, it will replace all `display`
-nodes by `export` nodes.
+nodes by export nodes.
 there are also a few example config files in `bin/examples/`. note that you
 have to edit the filename in the example cfg to point to a file that actually
 exists on your system.
@@ -174,3 +180,8 @@ also, `vkdt` requires 4GB video ram (it may run with less, but this seems to be
 number that is fun to work with). a fast ssd is desirable since disk io is often times
 a limiting factor, especially during thumbnail creation.
 
+* **can i speed up rendering on my 2012 on-board GPU?**  
+you can set the level of detail (LOD) parameter in your
+`~/.config/vkdt/config.rc` file: `intgui/lod:1`. set it to `2` to only render
+exactly at the resolution of your screen (will slow down when you zoom in), or
+to `3` and more to brute force downsample.

release.md

@@ -0,0 +1,67 @@
+# release procedure
+
+this document lists relevant steps in the release procedure.
+
+## release branch
+
+use semantic versioning and make a branch `release-0.5` to
+contain tags for point releases `0.5.0` and `0.5.1` etc.
+the `master` branch will carry on with new features and eventually become the
+next release branch.
+
+## submodules
+
+will be exported by `make release`.
+
+`ext/imgui` is relatively recent
+
+`ext/rawspeed` is a merge with the cr3 support branch
+
+## version.h
+
+`src/core/version.h` depends on `.git/FETCH_HEAD` if present.
+
+to generate it for local testing purposes without pushing the tag
+to the public repository,
+```
+git tag -a '0.5.0'
+git push dreggn 0.5.0
+git fetch --all
+```
+
+and for paranoia:
+
+```
+make src/core/version.h
+cat src/core/version.h
+```
+
+## create tarball
+
+`make release` and test in `/tmp`
+
+## upload
+
+* changelog
+* acks
+* checksum
+* sign the tag
+
+# changelog
+
+this is the first release of `vkdt`. the project has been under development for
+quite some years and so this is by no means a 'release early' kind of release.
+
+since there is no previous version, here are a few noteworthy features of this release:
+
+* very fast processing (gui and export use equivalent code path, no preview)
+* video support (both ldr `.mov` and raw `.mlv`)
+* timelapse support
+* keyframe support for majority of parameters
+* 3d rendering (quake!)
+* support spectral input profiles
+* drawn masks with pentablet support
+* flexible metadata display
+* script to create css/html only web gallery
+* cr3 support via rawspeed
+* multi-frame image alignment

src/pipe/modules/grad/readme.md

@@ -1,4 +1,4 @@
-# graduated density filter
+# grad: graduated density filter
 
 colour your landscape skies.