Writing FXPack Shaders - Revision history

Admin: Split into howto + reference; move tables to FXPack Shader Reference; no inline bold (bot)

2026-08-08T14:31:19Z

Split into howto + reference; move tables to FXPack Shader Reference; no inline bold (bot)

Admin: Add section: writing a shader with Claude (bot)

2026-08-08T13:23:38Z

Add section: writing a shader with Claude (bot)

@@ Line 298: / Line 298: @@
 * Texture coordinates are in '''pixels''', not 0..1 — normalise with <code>mxw_reciprocalU/V_mxw</code> and un-normalise before every <code>texture2D</code> lookup.
 * Target <code>#version 120</code> for portability.
 [[Category:Effects]]
 [[Category:Reference]]

Admin: Create developer guide: how to write FXPack shaders (bot)

2026-08-08T13:12:27Z

Create developer guide: how to write FXPack shaders (bot)

New page

<div class="noprint">
==Introduction==
</div>
An '''FXPack''' is MXWendler's shader-effect container format. It is a plain ZIP archive with the extension <code>.fxpack</code> that bundles one or more GLSL shader stages together with any auxiliary textures and a readme. Dropping an <code>.fxpack</code> file into the <code>effects/</code> folder makes a new effect available in Preload Preview, the Live Editor and on the Render Output — no recompilation of MXWendler is required.

The clever part of the format is the '''interface''': MXWendler scans your shader source for specially-named <code>uniform</code> declarations. Uniforms whose names start with <code>mxw_</code> and end with <code>_mxw</code> are recognised automatically and are either fed a live engine value every frame (time, resolution, input frames …) or turned into a '''UI control''' (a slider or a color picker) that the operator can automate. You never write any C++ or edit MXWendler itself — the shader ''is'' the plugin.

This page documents that interface exactly as the loader implements it (see <code>mxw_effect.cpp</code>, <code>mxw_effectbase::setSource()</code>).

See also: [[Effects]] · [[Tutorial Coupling Video with Effects and Audio Signals]]

<div class="noprint">
==Package structure==
</div>
An <code>.fxpack</code> is a ZIP file with this internal layout:

MyEffect.fxpack (a ZIP archive)
├── effects/
│ └── MyEffect.mxf ← fragment shader (required)
│ └── MyEffect.mxv ← vertex shader (optional)
│ └── MyEffect.mxg ← geometry shader (optional)
│ └── MyEffect.mxtc ← tessellation control (optional)
│ └── MyEffect.mxte ← tessellation eval (optional)
├── textures/
│ └── myLookup.bmp ← auxiliary textures (optional)
└── readme.txt ← human description (recommended)

Notes:
* The effect '''name''' shown in the MXWendler UI is taken from the <code>.fxpack</code> file name, not from the file inside.
* Inside <code>effects/</code> the loader picks the '''first''' file matching each stage extension, so the base name is free — but matching it to the pack name keeps things tidy.
* At most '''one file per shader stage'''. A minimal effect is just a single <code>.mxf</code> fragment shader.
* Auxiliary textures live in a <code>textures/</code> sub-folder and are wired up through sampler uniforms (see [[#Auxiliary textures|Auxiliary textures]]).

<div class="noprint">
==Shader stages and file extensions==
</div>
Each GLSL pipeline stage is a separate file, identified by extension:

{| class="wikitable"
! Extension !! Stage !! Required
|-
| <code>.mxv</code> || Vertex shader || no
|-
| <code>.mxf</code> || '''Fragment shader''' || '''yes''' (the workhorse)
|-
| <code>.mxg</code> || Geometry shader || no
|-
| <code>.mxtc</code> || Tessellation control shader || no
|-
| <code>.mxte</code> || Tessellation evaluation shader || no
|}

Most effects are pure image processing and only need the fragment shader. If a tessellation stage is present, MXWendler switches the geometry to <code>GL_PATCHES</code> automatically.

Target GLSL version is '''120''' (<code>#version 120</code>) for maximum cross-platform / macOS compatibility. Higher versions work on desktop GL but may be skipped on older macOS.

<div class="noprint">
==The interface: mxw_..._mxw uniforms==
</div>
The loader tokenises your source, strips comments, and inspects every <code>uniform</code> declaration. A uniform participates in the MXWendler interface only if its name '''starts with <code>mxw_</code> and contains <code>_mxw</code>'''. Everything else is a normal private uniform you set yourself inside the shader.

Which kind of interface a uniform becomes is decided by its GLSL '''type''' and by how many underscores its name contains:

{| class="wikitable"
! Type !! Underscore count !! Meaning
|-
| <code>sampler2D</code> || – || Input texture (video frame, feedback, or aux image)
|-
| <code>float</code> || 2 || A live engine value (time, resolution …)
|-
| <code>float</code> || 6 || A '''slider''' UI control
|-
| <code>vec4</code> || 7 || A '''color picker''' UI control
|}

;Number encoding
Because GLSL identifiers cannot contain <code>.</code> or <code>-</code>, numeric values baked into uniform names are encoded:
* <code>x</code> stands for the decimal point → <code>0x5</code> = <code>0.5</code>, <code>100x0</code> = <code>100.0</code>
* a leading <code>n</code> means negative → <code>n0x5</code> = <code>-0.5</code> (slider ranges only)

<div class="noprint">
==Live engine values (global uniforms)==
</div>
Declare a <code>float</code> uniform named <code>mxw_<value>_mxw</code> and MXWendler updates it every frame:

{| class="wikitable"
! Uniform !! Value supplied each frame
|-
| <code>mxw_millis_mxw</code> || Wall-clock time in milliseconds — use for animation
|-
| <code>mxw_maxU_mxw</code> || Input texture width in pixels
|-
| <code>mxw_maxV_mxw</code> || Input texture height in pixels
|-
| <code>mxw_reciprocalU_mxw</code> || 1 / width (multiply texcoords by this to normalise to 0..1)
|-
| <code>mxw_reciprocalV_mxw</code> || 1 / height
|-
| <code>mxw_viewportsizeX_mxw</code> || Render viewport width in pixels
|-
| <code>mxw_viewportsizeY_mxw</code> || Render viewport height in pixels
|-
| <code>mxw_footagesizeX_mxw</code> || Source footage width in pixels
|-
| <code>mxw_footagesizeY_mxw</code> || Source footage height in pixels
|-
| <code>mxw_footageframelength_mxw</code> || Number of frames in the source footage
|-
| <code>mxw_framenumber_mxw</code> || Current footage frame number
|-
| <code>mxw_framecounterenvironment_mxw</code> || Global engine frame counter
|-
| <code>mxw_outputLuminance1x1_mxw</code> || Average luminance of the output (1×1 reduction)
|}

Declaring an unknown <code>mxw_..._mxw</code> float with two underscores is an error and the shader will fail to load.

;Coordinate system — important
MXWendler binds video frames as '''rectangle textures''', so <code>gl_TexCoord[0].xy</code> arrives in '''pixels''' (0…width, 0…height), '''not''' normalised 0…1. Use the reciprocal/max uniforms to convert. The standard helpers used throughout the stock effects are:

<syntaxhighlight lang="glsl">
uniform float mxw_reciprocalU_mxw;
uniform float mxw_reciprocalV_mxw;
uniform float mxw_maxU_mxw;
uniform float mxw_maxV_mxw;

// pixel coords -> 0..1
vec2 normalizedTc(vec2 tc) {
return tc * vec2(mxw_reciprocalU_mxw, mxw_reciprocalV_mxw);
}
// 0..1 -> pixel coords (needed before texture2D lookups)
vec2 unNormalizedTc(vec2 tc) {
return tc * vec2(mxw_maxU_mxw, mxw_maxV_mxw);
}
</syntaxhighlight>

<div class="noprint">
==Input textures (samplers)==
</div>
Video input arrives through <code>sampler2D</code> uniforms. The name selects ''which'' frame:

{| class="wikitable"
! Uniform pattern !! Delivers
|-
| <code>mxw_tex_plus_0_mxw</code> || The '''current''' input frame (the normal case)
|-
| <code>mxw_tex_plus_N_mxw</code> || The frame N steps in the '''future''' (look-ahead)
|-
| <code>mxw_tex_minus_N_mxw</code> || The frame N steps in the '''past''' — enables trails / motion blur / temporal feedback
|-
| <code>mxw_tex_render_prefinalfx_minus_N_mxw</code> || Feedback of the render output (before final FX), N frames back
|-
| <code>mxw_accum_buffer_N_mxw</code> || Multi-Render-Target accumulation buffer N (advanced ping-pong)
|}

Sample any of them with <code>texture2D(sampler, pixelCoords)</code> where the coordinates are in ''pixels'' (use <code>unNormalizedTc()</code> if you computed a 0..1 coordinate). Requesting past/future frames (<code>minus</code>/<code>plus</code> with N>0) tells the engine to keep a rolling history of frames for this effect.

<div class="noprint">
==UI controls==
</div>
===Sliders===
A <code>float</code> uniform with '''six''' underscores becomes an operator-facing, automatable slider:

uniform float mxw_vertslider_<Label>_<lo>_<hi>_<default>_mxw;

* <code>vertslider</code> — the widget type (currently the only slider type)
* <code><Label></code> — a '''single-token''' name shown in the UI (no spaces/underscores; use CamelCase)
* <code><lo> <hi></code> — slider range (encoded numbers, may be negative with <code>n</code>)
* <code><default></code> — start value

Example — a "Resolution" knob from 0.1 to 10.0 starting at 0.5:

<syntaxhighlight lang="glsl">
uniform float mxw_vertslider_Resolution_0x1_10x0_0x5_mxw;
</syntaxhighlight>

;The Master convention
By convention almost every stock effect exposes a '''Master''' slider (0…1, default 1) and uses it to cross-fade between the untouched input and the processed result, so the effect can be dialled in smoothly and automated:

<syntaxhighlight lang="glsl">
uniform float mxw_vertslider_Master_0x0_1x0_1x0_mxw;
...
gl_FragColor = mix(
texture2D(mxw_tex_plus_0_mxw, gl_TexCoord[0].xy), // original
processedColor, // your result
mxw_vertslider_Master_0x0_1x0_1x0_mxw); // dry/wet
</syntaxhighlight>

Following this convention is strongly recommended — it makes your effect behave like the built-ins.

===Color pickers===
A <code>vec4</code> uniform with '''seven''' underscores becomes a color picker (RGBA):

uniform vec4 mxw_colorcontrol_<Label>_<r>_<g>_<b>_<a>_mxw;

Each component is an encoded number in 0…1. Example — a tint control defaulting to opaque dark blue:

<syntaxhighlight lang="glsl">
uniform vec4 mxw_colorcontrol_Tint_0x0_0x1_0x25_1x0_mxw; // rgba = (0.0, 0.1, 0.25, 1.0)
</syntaxhighlight>

<div class="noprint">
==Auxiliary textures==
</div>
To ship a fixed lookup image (gradient, mask, logo, LUT strip …) with your effect, place the file in the <code>textures/</code> folder of the ZIP and reference it with a sampler whose name encodes the file name. The '''last''' underscore before <code>_mxw</code> separates the extension:

textures/myGradient.bmp ⇄ uniform sampler2D mxw_tex_myGradient_bmp_mxw;
textures/mixred.bmp ⇄ uniform sampler2D mxw_tex_mixred_bmp_mxw;

Rules:
* Pattern: <code>mxw_tex_<basename>_<ext>_mxw</code> maps to <code>textures/<basename>.<ext></code>.
* The base name must '''not''' start with <code>plus</code>, <code>minus</code>, <code>render</code> or <code>accum</code> — those prefixes are reserved for the frame samplers above.
* A missing texture file makes the effect fail to load.

<div class="noprint">
==A minimal fragment shader==
</div>
The smallest useful effect — a brightness knob that fades to the original via Master:

<syntaxhighlight lang="glsl">
#version 120

// input frame
uniform sampler2D mxw_tex_plus_0_mxw;

// dry/wet
uniform float mxw_vertslider_Master_0x0_1x0_1x0_mxw;

// user control: brightness 0..2, default 1
uniform float mxw_vertslider_Brightness_0x0_2x0_1x0_mxw;

void main(void)
{
vec2 tc = gl_TexCoord[0].xy; // pixel coordinates
vec4 src = texture2D(mxw_tex_plus_0_mxw, tc);

vec4 processed = vec4(src.rgb * mxw_vertslider_Brightness_0x0_2x0_1x0_mxw, src.a);

gl_FragColor = mix(src, processed, mxw_vertslider_Master_0x0_1x0_1x0_mxw);
}
</syntaxhighlight>

<div class="noprint">
==Worked example: a time-animated distortion==
</div>
This annotated version of the stock ''ag_Sine'' effect shows the coordinate helpers, a user slider and the Master mix working together:

<syntaxhighlight lang="glsl">
#version 120

uniform sampler2D mxw_tex_plus_0_mxw; // current frame
uniform float mxw_vertslider_Master_0x0_1x0_1x0_mxw; // dry/wet
uniform float mxw_vertslider_Resolution_0x1_10x0_0x5_mxw; // user knob

uniform float mxw_reciprocalU_mxw;
uniform float mxw_reciprocalV_mxw;
uniform float mxw_maxU_mxw;
uniform float mxw_maxV_mxw;

vec2 normalizedTc(vec2 tc) { return tc * vec2(mxw_reciprocalU_mxw, mxw_reciprocalV_mxw); }
vec2 unNormalizedTc(vec2 tc) { return tc * vec2(mxw_maxU_mxw, mxw_maxV_mxw); }

void main(void)
{
vec2 tc = normalizedTc(gl_TexCoord[0].xy); // -> 0..1
tc = tc * 2.0 - 1.0; // -> -1..1

vec2 xy = abs(tc) * mxw_vertslider_Resolution_0x1_10x0_0x5_mxw;
vec2 val = fract(vec2(xy.x + sin(xy.y), xy.y + sin(xy.x)));

vec4 processed = texture2D(mxw_tex_plus_0_mxw, unNormalizedTc(val));

gl_FragColor = mix(texture2D(mxw_tex_plus_0_mxw, gl_TexCoord[0].xy),
processed,
mxw_vertslider_Master_0x0_1x0_1x0_mxw);
}
</syntaxhighlight>

<div class="noprint">
==Packaging and installing==
</div>
# Put your shader(s) in an <code>effects/</code> folder and any images in a <code>textures/</code> folder.
# Add a <code>readme.txt</code> describing what the effect does.
# ZIP those folders together (the folders must be at the root of the archive).
# Rename the resulting archive to <code>YourEffectName.fxpack</code>.
# Copy it into MXWendler's <code>effects/</code> directory. It appears in the effect list on next start.

Because an <code>.fxpack</code> is just a ZIP, you can inspect or fork any of the 130+ bundled effects: copy one, rename to <code>.zip</code>, unzip, edit the <code>.mxf</code>, re-zip. The bundled <code>ag_*</code> effects are an excellent library of worked examples.

<div class="noprint">
==Rules and gotchas==
</div>
* Interface uniforms are matched by name, so '''spelling and underscore count matter'''. A slider needs exactly 6 underscores; a color picker exactly 7; a live value exactly 2.
* Labels are single tokens — no spaces or underscores inside <code><Label></code>.
* Encode decimals with <code>x</code> and negatives with a leading <code>n</code>. <code>-0.5</code> → <code>n0x5</code>.
* '''Do not''' declare the same interface uniform in two stages of one effect (e.g. <code>mxw_millis_mxw</code> in both the vertex and fragment shader). Declare it in one stage and pass the value on — this is also faster.
* Commented-out uniforms are ignored (comments are stripped before scanning), so you can safely park declarations behind <code>//</code> or <code>/* */</code>.
* Texture coordinates are in '''pixels''', not 0..1 — normalise with <code>mxw_reciprocalU/V_mxw</code> and un-normalise before every <code>texture2D</code> lookup.
* Target <code>#version 120</code> for portability.

[[Category:Effects]]
[[Category:Reference]]