FXPack Shader Reference

Template:TOCright This is the normative reference for MXWendler's FXPack shader interface — the exact tables and naming rules the effect loader implements. For a step-by-step, task-oriented guide (minimal shader, worked example, packaging, writing effects with Claude) see Writing FXPack Shaders.

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

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

The interface works by naming convention: MXWendler scans your shader source for uniform declarations whose names start with mxw_ and contain _mxw. Those 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. Every other uniform is a normal private uniform you set yourself inside the shader.

An .fxpack 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 .fxpack file name, not from the file inside.
• Inside effects/ 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 .mxf fragment shader.
• Auxiliary textures live in a textures/ sub-folder and are wired up through sampler uniforms (see Auxiliary textures).

Each GLSL pipeline stage is a separate file, identified by extension:

Extension	Stage	Required
.mxv	Vertex shader	no
.mxf	Fragment shader	yes (the workhorse)
.mxg	Geometry shader	no
.mxtc	Tessellation control shader	no
.mxte	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 GL_PATCHES automatically.

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

The loader tokenises your source, strips comments, and inspects every uniform declaration. A uniform participates in the MXWendler interface only if its name starts with mxw_ and contains _mxw.

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

Type	Underscore count	Meaning
sampler2D	–	Input texture (video frame, feedback, or aux image)
float	2	A live engine value (time, resolution …)
float	6	A slider UI control
vec4	7	A color picker UI control

Number encoding

Because GLSL identifiers cannot contain . or -, numeric values baked into uniform names are encoded:

• x stands for the decimal point → 0x5 = 0.5, 100x0 = 100.0
• a leading n means negative → n0x5 = -0.5 (slider ranges only)

Declare a float uniform named mxw_<value>_mxw and MXWendler updates it every frame:

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

Declaring an unknown mxw_..._mxw 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 gl_TexCoord[0].xy 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:

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);
}

Video input arrives through sampler2D uniforms. The name selects which frame:

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

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

Sliders

A float uniform with six underscores becomes an operator-facing, automatable slider:

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

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

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

uniform float mxw_vertslider_Resolution_0x1_10x0_0x5_mxw;

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:

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

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

Color pickers

A vec4 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:

uniform vec4 mxw_colorcontrol_Tint_0x0_0x1_0x25_1x0_mxw;  // rgba = (0.0, 0.1, 0.25, 1.0)

To ship a fixed lookup image (gradient, mask, logo, LUT strip …) with your effect, place the file in the textures/ folder of the ZIP and reference it with a sampler whose name encodes the file name. The last underscore before _mxw 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: mxw_tex_<basename>_<ext>_mxw maps to textures/<basename>.<ext>.
• The base name must not start with plus, minus, render or accum — those prefixes are reserved for the frame samplers above.
• A missing texture file makes the effect fail to load.

• 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 <Label>.
• Encode decimals with x and negatives with a leading n. -0.5 → n0x5.
• Do not declare the same interface uniform in two stages of one effect (e.g. mxw_millis_mxw 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 // or /* */.
• Texture coordinates are in pixels, not 0..1 — normalise with mxw_reciprocalU/V_mxw and un-normalise before every texture2D lookup.
• Target #version 120 for portability.