Admin: Remove internal source-code reference (bot)

2026-08-08T14:37:41Z

Remove internal source-code reference (bot)

← Older revision		Revision as of 16:37, 8 August 2026
Line 1:		Line 1:
	{{TOCright}}		{{TOCright}}
	This is the normative reference for MXWendler's FXPack shader interface — the exact tables and naming rules the loader implements ~~(see <code>mxw_effect.cpp</code>, <code>mxw_effectbase::setSource()</code>)~~. For a step-by-step, task-oriented guide (minimal shader, worked example, packaging, writing effects with Claude) see [[Writing FXPack Shaders]].		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]]		See also: [[Effects]] · [[Tutorial Coupling Video with Effects and Audio Signals]]

Admin: Create FXPack Shader Reference (split from howto); no inline bold (bot)

2026-08-08T14:31:17Z

Create FXPack Shader Reference (split from howto); no inline bold (bot)

New page

{{TOCright}}
This is the normative reference for MXWendler's FXPack shader interface — the exact tables and naming rules the loader implements (see <code>mxw_effect.cpp</code>, <code>mxw_effectbase::setSource()</code>). 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]]

<div class="noprint">
==Overview==
</div>
An FXPack is MXWendler's shader-effect container format: 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 interface works by naming convention: MXWendler scans your shader source for <code>uniform</code> declarations whose names start with <code>mxw_</code> and contain <code>_mxw</code>. 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.

<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>.

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">
==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]]

FXPack Shader Reference - Revision history

Admin: Escape angle-bracket placeholders in code lines (fixes stray HTML bolding rest of page)

Admin: Remove internal source-code reference (bot)

Admin: Create FXPack Shader Reference (split from howto); no inline bold (bot)

← Older revision		Revision as of 16:39, 8 August 2026
Line 163:		Line 163:
	A <code>float</code> uniform with six underscores becomes an operator-facing, automatable slider:		A <code>float</code> uniform with six underscores becomes an operator-facing, automatable slider:

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

	* <code>vertslider</code> — the widget type (currently the only slider type)		* <code>vertslider</code> — the widget type (currently the only slider type)
Line 193:		Line 193:
	A <code>vec4</code> uniform with seven underscores becomes a color picker (RGBA):		A <code>vec4</code> uniform with seven underscores becomes a color picker (RGBA):

	uniform vec4 mxw_colorcontrol_<Label>_<r>_<g>_<b>_<a>_mxw;		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:		Each component is an encoded number in 0…1. Example — a tint control defaulting to opaque dark blue: