Passes & inputs

A Shaderpack can add full-screen passes. A pass is a fragment shader of your own. Viewpoint draws it over the whole frame at one stage. It reads what you name, and it writes the image of the stage or a target of your pack. Use a pass for an effect that the renderer does not have: motion blur, depth of field, a lens flare, reflections.

pack.properties

targets=focus
target.focus=r16f 1x1 history

passes=focus dof
pass.focus.stage=final
pass.focus.fragment=focus.frag
pass.focus.inputs=depth focus.previous
pass.focus.target=focus

pass.dof.stage=final
pass.dof.fragment=dof.frag
pass.dof.inputs=color depth focus
pass.dof.when=depthOfField

Key	Meaning
passes	The ids of your passes. Within a stage they run in this order.
pass.<id>.stage	translucent, composite or final. Required.
pass.<id>.fragment	Its fragment shader: a path in shaders/. Required.
pass.<id>.vertex	Its vertex shader. The default is screen.vert: one triangle over the screen, with vUv from 0 to 1.
pass.<id>.inputs	What it reads, with spaces between the names. Use at most 12.
pass.<id>.target	What it writes: color (the image of the stage, the default) or one of your targets.
pass.<id>.when	A toggle option of your pack. The pass runs only while it is on.
targets	The names of your targets. Use at most 8.
target.<name>	<format> <size> [history].

Format is rgba8, rgba16f, rg16f, r16f or r32f.

Size is a share of the frame (1, 0.5, 0.25; up to 1) or a number of texels (1x1, 256x256; up to 4096).

history keeps the copy of the target from the end of the last frame.

The stages

Stage	When it runs	What color is
translucent	After the glass. Before the bounce light, the weather and the air.	The lit HDR image, with the depth of the scene drawn.
composite	After the air and the bloom. Before post.frag.	The HDR image that post.frag is about to read.
final	After anti-aliasing. Before the rain over the image.	The finished image, after the tone curve.

• What a pass writes at translucent or composite goes into the history of anti-aliasing. This is what reflections want, because anti-aliasing smooths their noise.
• The history of anti-aliasing is taken before final. A blur at final never smears into the next frames.
• At final, the image can be at the size of the screen while the other inputs are at the size of the frame. Read the other inputs by their UV.
• Without a pass at final, the frame is drawn as without passes. A pack with no passes pays nothing.

The inputs

An input goes on a sampler. Its name is u and the input name with a capital letter: color is uColor, farDepth is uFarDepth, focus.previous is uFocusPrevious.

Input	Holds	At which stages
color	The image of the stage, as the previous pass left it.	All
depth	The depth of the scene. lib/camera.glsl turns it into a position.	All
albedo, normal, light	The G-buffer: colour and material, normal, and the light of the game’s grids.	All
velocity	How far the models moved on screen since the last frame, in UV. w is 1 where it is set.	All
farDepth	The depth of the far world, on its own range (uFarRange). Set only where the far world drew.	All
occlusion	The ambient occlusion: the bent normal and the visibility.	All
volume	The light in the air, at half size.	composite, final
bloom	The first level of the bloom. The bloom of the pack must be on.	composite, final
<target>	A target of your pack: what a pass before this pass wrote in this frame.	All
<target>.previous	A target with history: what it held at the end of the last frame. Zeros in the first frame.	All

A pass cannot read the target that it writes. Read <target>.previous for the last frame.

Note

Each pass is one full-screen draw. Your targets use video memory. Viewpoint makes them when your pack comes into use, and lets them go when another pack comes into use. A pass that does not compile does not replace the pack on screen. The Graphics page shows the errors.

The values of the frame

Viewpoint sets these uniforms once each frame, on every pass that declares them. Declare only the ones that you use.

Uniform	Holds
uResolution, uTexel (vec2)	The size of what the pass writes, and one over it.
uView, uProjection (mat4)	The camera’s view and projection.
uViewProjection, uInvViewProjection (mat4)	From scene space to clip space and back.
uPrevious (mat4)	From this frame’s scene position to the clip position of the last frame.
uCamera (vec4), uEye (vec3)	The near and far planes and the tangents of the half-angles. The eye in scene space.
uSunDir, uSunColor (vec3), uSunStrength (float)	The direction, colour and strength of the sun, or of the moon at night.
uFogColor (vec3), uFogRange (vec2)	The colour of the fog, and where it starts and ends, in squares.
uTime, uFrameSeconds, uExposure (float), uFrame (int)	Real seconds. How long the last frame took. The exposure. The number of frames drawn.
uRain, uSnow (float)	How hard it rains and snows, 0 to 1.
uWind (vec2)	The wind at the ground, in squares each second.
uCloudCover (float)	How much of the sky over the eye is cloud, 0 to 1.
uSceneOrigin (vec3)	Where the origin of the scene is in the world.

Scene space has x to the west, y up and z to the north, relative to the character. One storey is the side of a square multiplied by √6.

Fix things to the world

Anything that is fixed to the world needs uSceneOrigin added back. Without it, patterns crawl and shadows slide when the player walks.

Do not use uTime for the weather. The weather follows the game’s clock, so a paused game stills the clouds. Use the values of the weather that lib/weather.glsl declares.

Event values

Viewpoint sets a value for each event of the fight: a muzzle flash, a shot, a hit on a zombie, and damage that the player takes. The names start with uEvent. Each value tells how long ago the last event happened, and how strong it was. Declare the uniform to read it.

Uniform	Event
uniform vec2 uEventFlash;	A muzzle flash: 1 for your own gun, less for a gun further away, 0 at 30 squares or more
uniform vec2 uEventShot;	A shot that you fire
uniform vec2 uEventHit;	A zombie that you hit: 1, or 0.5 for a blow that does no damage
uniform vec2 uEventDamage;	Damage that you take: 1 for a quarter of your health or more

x is the seconds since the last event, and y is its strength, from 0 to 1. Before the first event, x is 1000000.

Use these values for an effect that you tie to the fight, for example a short vignette. Do not use them to copy a cue that the game does not give.

Values of addons

An addon can give a value to your shaders. See Shader values. Declare the uniform with the encoded id of the addon in its name:

uniform float uAddon_example_lean_angle;

For the addon example.lean and the value angle, the name is uAddon_example_lean_angle. The name of a value has no _ in it, so the name has one reading. If the addon is off, Viewpoint does not set the uniform. Make your shader work with a value of 0. Add the addon to requires if your pack is not useful without it.