WIP: Write a Preset Authoring Guide

Author: kblaschke

bun.lock

@@ -0,0 +1 @@
+title: Preset Authoring Guide

content/1.docs/3.preset-authoring/.navigation.yml

@@ -0,0 +1,21 @@
+---
+title: Introduction
+description: A comprehensive guide to Milkdrop presets.
+---
+
+## A Comprehensive Guide to Authoring Milkdrop Presets
+
+This section contains all information required to create new and edit existing Milkdrop presets.
+
+Starting with a general overview on the file format and general rendering process, the guide also covers each built-in
+effect, syntax and usage of the Milkdrop-specific expressions and making use of HLSL shaders to further improve the
+resulting visuals.
+
+### Available Editors
+
+The original Milkdrop plug-in for WinAmp<span>&reg;</span> has a built-in editor which allows editing all parameters
+and code blocks. While not being overly user-friendly, it is the editor which was used to create basically all presets
+available in the wild.
+
+Recently, more community projects have started implementing their own, improved editors, including projectM. As of now,
+none of these editors are released publicly. Once they become available, we'll add links here. 

content/1.docs/3.preset-authoring/1.index.md

@@ -0,0 +1,42 @@
+---
+title: Preset Files (.milk)
+description: An overview of the format of Milkdrop presets.
+---
+
+## General File Syntax
+
+Since Milkdrop has been around since the late 1990's, the choice for the file format was based on best practices in
+Windows development during that era. XML, JSON and other modern structural formats weren't a thing then, so the NullSoft
+developers decided to use readily-available functions in the Win32 API to save and load presets and thus chose the
+Windows INI file format.
+
+A preset file consists of only a single INI section, `[preset00]`, which contains all parameters, expressions and shader
+code blocks. Presets since Milkdrop 2 also use a few additional keys in the global section to enable use of HLSL pixel
+shaders.
+
+Each setting in the preset file follows the `key=value` scheme. If a key is present multiple times, the _first_ value
+found in the file is being used.
+
+## Default Parameters
+
+Many default preset parameters follow a certain syntax, determining the data type expected as the value:
+
+- Keys starting with `b` are considered boolean values, e.g. `0` means false/off and any non-zero value is considered
+  true/on.
+- Keys starting with `i` are parsed as integer values without decimals.
+- Keys starting with `f` are floating-point numbers.
+
+The values of default parameters can be changed within expressions in most, but not all cases. For example, the `enabled`
+values of custom waves and shapes cannot be set in expressions, as well as the `shapecode_#_num_inst` value.
+
+## Code Blocks
+
+Milkdrop presets can contain expression code and HLSL shaders with more than a single line. Each code block has its own
+key prefix (e.g. `per_frame_`), followed by a 1-based line number without leading zeroes. A code block is read in by
+incrementing the line number by one each and then checking if the key exists. Once a key isn't found, the code block is
+considered finished. A maximum of 99999 lines per code block are allowed.
+
+Shader code blocks (with the `warp_` and `comp_` prefixes) start with an additional `` ` `` after the `=`, which is
+discarded automatically when reading in the preset. Using the backtick is fully optional, e.g. shader code will parse
+properly without it and expression code will be parsed correctly if there is a backtick at the beginning of each line's
+value.

content/1.docs/3.preset-authoring/2.preset-files.md

@@ -0,0 +1,132 @@
+---
+title: Rendering Process
+description: All built-in effects and their rendering order.
+---
+
+## Preset Versions
+
+Before listing all effects, it's important to know the differences between preset versions.
+
+In general, presets are different between Milkdrop 1.x and Milkdrop 2.x. This is because Milkdrop 1 did not support
+using pixel shaders, they only supported a fixed set of effects which could be controlled using certain predefined
+parameters.
+
+Milkdrop 2.0 introduced shader support and since Milkdrop 2.0.1, preset authors could choose to use different shader
+versions for both warp and composite shaders (or disable them individually).
+
+As a rule of thumb, all Milkdrop 1 post-processing effects listed below will be disabled if a user-defined composite
+shader is enabled.
+
+## Preset Loading
+
+When loading a preset, all `init` expression code blocks will be executed _once_, in this order:
+
+- `per_frame_init`
+- `wave_0_init`
+- `wave_1_init`
+- `wave_2_init`
+- `wave_3_init`
+- `shape_0_init`
+- `shape_1_init`
+- `shape_2_init`
+- `shape_3_init`
+
+## Rendering Order
+
+The following sections lists all Milkdrop built-in effects in the order they're being rendered. The rendering order is
+important to achieve certain effects.
+
+Each effect is described in more detail in the [following chapter](effects).
+
+### Frame Setup
+
+This step doesn't render anything, but executes the `per_frame_` code block.
+
+### Motion Vector Grid
+
+Draws a grid of colored dots or lines on top of the previous frame's image. The lines represent the apparent motion (
+speed and direction) of the warp effect.
+
+Not that this is the only effect which is drawn _before_ warping the image.
+
+### Image Warp
+
+A full-screen effect which allows to transform the previous frame's image in many different ways. This effect consists
+of multiple steps:
+
+1. For each intersection in the user-defined warp mesh grid, the "per-vertex" or "per-pixel" expression code is
+   executed.
+2. If the preset version is less than `200` or the warp pixel shader version less than `2`, a simple default warp shader
+   will be used. This shader also applies the `decay` value by multiplying the resulting color with the set value.
+3. Otherwise, the warp shader contained in the preset will be executed and rendered. It may or may not use the warp grid
+   U/V coordinates. The `decay` value will not be applied automatically.
+
+### Custom Shapes
+
+A preset may use up to 4 sets of custom shapes, each with 1 to 1024 instances. Shapes 1 to 4 are rendered in order and
+thus on top of each other.
+
+Each shape instance can have a colored or textured interior, and also an optional colored border around it.
+
+### Custom Waveforms
+
+Custom waveforms, of which up to 4 can be used, render lines or dots and can use audio or spectrum data to animate the
+waveform.
+
+The coordinates and color of each individual point which makes up the waveform can be scripted using expression code.
+This allows to draw arbitrary shapes.
+
+### Default Waveform
+
+A single waveform with eight predefined drawing modes. The mode, color, position and scaling of the waveform can be
+customized.
+
+### Darken Center
+
+A simple effect which draws a diamond-shaped area in the center of the screen which darkens pixels more the closer they
+are to the center.
+
+### Image Borders
+
+Two configurable borders around the whole screen, one inner and one outer border. Each can have individual color and
+width.
+
+### Post-Processing / Composite Effect(s)
+
+Before any post-processing effects are applied, the current preset image is stored and passed on to the next frame. This
+means any of the effects described in this section are only display to the viewer and the image will then be discarded.
+
+If the preset version is at least `200` (Milkdrop 2.0) and a pixel shader version >= 2 is set for the composite shader,
+only the "Composite Shader" effect is drawn and the other effects below are skipped.
+
+If no composite shader is enabled as stated above, the five "classic" post-processing filters are drawn if enabled
+individually.
+
+#### Composite Shader
+
+The composite shader can contain arbitrary HLSL code.
+
+If the preset contains composite shader code, the shader is executed to draw the final image. none of the following
+effects will be applied in this case.
+
+#### Video Echo
+
+Renders a copy of the current preset image ofer the existing one. The image can be flipped on the X and Y axis and
+zoomed in or out. The opacity of the effect can also be specified from 0% (effect disabled) to 100% (only rendering the
+echo).
+
+#### Brighten Image
+
+Brightens the whole image using a square filter.
+
+#### Darken Image
+
+Darkens the whole image using a square filter.
+
+#### Solarize
+
+Emphasizes medium-bright colors of the image.
+
+#### Gamma Adjustment
+
+Applies a gamma filter, eventually multiple times, to adjust the overall image brightness.

content/1.docs/3.preset-authoring/3.preset-rendering-process.md

@@ -0,0 +1 @@
+title: Built-In Effects

content/1.docs/3.preset-authoring/4.effects/.navigation.yml

@@ -0,0 +1,9 @@
+---
+title: Effects Reference
+description: A detailed description of all available built-in effects.
+---
+
+This chapter contains a reference of all available visual effects. They are ordered in the same
+way [as effects are drawn](preset-rendering-process).
+
+For each effect, available parameters are explained in detail, with screenshots to provide examples.

content/1.docs/3.preset-authoring/4.effects/1.index.md

@@ -0,0 +1,60 @@
+---
+title: Motion-Vector Grid
+description: A configurable grid with dots or lines following the warp motion.
+---
+
+![Motion Vectors Effect](/content/preset-guide/effect-motion-vectors.jpg){style="width: 50%;"}
+
+The Motion Vector Grid is the very first effect being drawn, even before the [Warp effect](image-warp) is applied.
+
+The effect draws a grid of lines (or dots, if length is set to minimum). The lines resemble the reverse-propagated
+motion vectors of the Warp effect as drawn in the _previous_ frame, pointing into the direction of movement, with the
+line length representing the movement speed.
+
+## Default Settings
+
+In the preset file, the following settings configure the default values for the Motion Vector Grid effect:
+
+| .milk Setting Key | Type  | Range       | Description                                                              |
+|-------------------|-------|-------------|--------------------------------------------------------------------------|
+| nMotionVectorsX   | INT   | 0 .. 64     | The number of motion vectors in the X direction                          |
+| nMotionVectorsY   | INT   | 0 .. 48     | The number of motion vectors in the Y direction                          |
+| mv_dx             | FLOAT | -1.0 .. 1.0 | Horizontal placement offset of the motion vectors                        |
+| mv_dy             | FLOAT | -1.0 .. 1.0 | Vertical placement offset of the motion vectors                          |
+| mv_l              | FLOAT | 0.0 .. 5.0  | The length of the motion vectors (0=dot/no trail, 1=normal, 2=double...) |
+| mv_r              | FLOAT | 0.0 .. 1.0  | The red color value of the motion vector grid                            |
+| mv_g              | FLOAT | 0.0 .. 1.0  | The green color value of the motion vector grid                          |
+| mv_b              | FLOAT | 0.0 .. 1.0  | The blue color value of the motion vector grid                           |
+| mv_a              | FLOAT | 0.0 .. 1.0  | The opacity of the motion vector grid                                    |
+
+## Expression Code Usage
+
+All settings of the Motion Vector Grid can be manipulated using Milkdrop expression code using the variables described
+below in one of the following blocks:
+
+- `per_frame_init_`
+- `per_frame_`
+
+| .milk Setting Key | Expression Variable | Writeable |
+|-------------------|---------------------|-----------|
+| nMotionVectorsX   | mv_x                | YES       |
+| nMotionVectorsY   | mx_y                | YES       |
+| mv_dx             | mv_dx               | YES       |
+| mv_dy             | mv_dy               | YES       |
+| mv_l              | mv_l                | YES       |
+| mv_r              | mv_r                | YES       |
+| mv_g              | mv_g                | YES       |
+| mv_b              | mv_b                | YES       |
+| mv_a              | mv_a                | YES       | 
+
+**Notes:**
+
+- Values are not retained across frames, they're only used to draw the current frame and then discarded.
+- Each value will be set to the default value assigned in the .milk file at the start of each of the above code blocks.
+- Any changes made to the variables in the `per_frame_init_` code are discarded and reset to defaults in the
+  `per_frame_` block.
+
+This means:
+
+- Only read the values in the `per_frame_init_` bock, e.g. to init user-defined or global variables.
+- An expression like `mv_dx += 0.01;` will not animate the value, it'll instead add a constant value to the default one.