Library files

Viewpoint draws the world with a library of GLSL files. A Shaderpack changes the look by replacing some of them.

Replace a file

A file in the shaders/ folder of your pack replaces the file of the same path in the library.

The library is in Viewpoint’s source repository, in src/main/resources/viewpoint/shaders/.
Files in lib/ can also be replaced. Each program that includes the file gets your version.
A file that you do not replace comes from your base, then from the library. A pack holds only what it changes.
constants.glsl cannot be replaced. Viewpoint makes it. Any file can #include "constants.glsl".
Every stage starts with #version 330. Viewpoint adds the defines of the options and the pipeline after this line. See Format.

An include is a line of this form. Viewpoint expands it before it compiles the file, and it adds #line directives so that an error names the file and the line.

#include "lib/sun.glsl"

An include path is relative to the shaders/ folder. Viewpoint reads ./ and // in it as plain. It refuses a file whose include path holds .., an absolute path or \.

Files that are easy to replace

A shared file in lib/ is the cheapest file to replace. One change then applies to the near world and the far world.

File	Controls
`lib/shade.glsl`	The lighting model. The deferred, forward and far passes all call it.
`lib/fog.glsl`	The colour of the fog: what the world fades into at the end of the fog.
`lib/fog_amount.glsl`	How much fog a point gets. Keep the end of the fog where the range puts it: past it nothing is drawn.
`lib/distance.glsl`	What the distance does to a colour.
`lib/sun_filter.glsl`	The filter of the sun’s shadows.
`lib/cloud_shadow.glsl`	The shadow of the clouds on the sun’s light.
`lib/precip_look.glsl`	The look of rain, snow and splashes.
`post.frag`	The composite: the fog, the tone curve and the grade.
`sky.frag`	The sky.

The weather is Viewpoint’s. How it looks is the pack’s. Two files are always the library’s, and a copy in your pack is not used: lib/weather.glsl and precip.vert. The console names the copy when the pack loads.

Rules for some files

Some files must follow a rule, or the picture breaks.

Models of packs. A replaced mesh.vert or shadow.vert must include lib/pack_model.glsl. While uModels is set, it must take its vertex from modelVertex(aPos, aUv, aNormal), as the library files do. A program without uModels draws no models of packs.
Dead bodies. A replaced mesh.vert or shadow.vert must include lib/corpse_card.glsl. While uCards is set, it must take its vertex from cardVertex().
Characters and items. A replaced model_gbuffer.frag, model_shadow.frag or model_outline.frag reads uTextures[vTexture], not uTexture. It needs #extension GL_ARB_gpu_shader5 : enable.
The far shell. A replaced far_shell.frag, gbuffer_shell.frag or far_shadow_shell.frag reads uAtlases[vAtlas].
Glass. Keep the rule of the library in gbuffer.frag and forward.frag. Glass for which glassSolid is true is solid in the G-buffer. It is not in the translucent pass. Otherwise a window shows the empty rooms behind it.
Translucent texels. A replaced forward.frag or vehicle_glass.frag writes each texel through translucent(colour, alpha, fromEye). Do not declare an output of your own.
The sun’s light. The direct light of the sun must fall to none as uSunStrength falls, at dusk and at dawn. Follow uSunStrength, as the library does. Otherwise the light drops in one frame.
Includes of options. A library file that reads an option gives it a default with #ifndef.

The markers for snippets

Addons can add snippets of GLSL to your shaders. Most points work with any file. They are the start and the end of a vertex or fragment stage. You do not have to do anything for them. Declare each colour output of a fragment stage with its location, layout(location = N).

A few points are inside a shader. The library marks them with comments:

// @viewpoint point surface

If you replace a library file that has a marker, keep the marker line in the same place in your file. If you drop a marker, the snippets of that point do not run in your pack. A message on the Addons page says “the shaderpack X has no point Y”. See Shader snippets.

Made for a version

Set library= in your descriptor to the Viewpoint version that you made your pack for. Some library files that your pack replaces can change after that version. Then the card says “made for <version>: N of the files it replaces have changed since”. This is a notice for the player. It does not stop the pack.

This notice is planned. It can come after API 1.0.