-
Notifications
You must be signed in to change notification settings - Fork 40
Canvas Shader Coding
To ensure maximum compatibility for multiple mods accessing the shader pipeline, Canvas provides a defined API and requires some conventions to be followed.
Mod authors can create vertex shaders, fragment shaders or both. When only one is present, an appropriate "default" shader is used.
Mod shaders do not contain a main method, and should not include attribute or uniform declarations. (Those are handled by Canvas.)
Instead, mod shaders implement one or more of the following methods:
void cv_startFragment(inout cv_FragmentData fragData)
void cv_startVertex(inout cv_VertexData data)
void cv_endVertex(inout cv_VertexData data)
The data structures and their usage within these methods are defined here:
Canvas includes several libraries that enable interaction with the world or player from within shaders. These are located here and include comments explaining usage.
Canvas also include some general library routines that have no dependency on game state. Those are located here.
Most public Canvas methods and declarations begin with a cv_ or CV_ prefix to distinguish them and prevent name conflicts with mods or OpenGl itself.
Canvas includes a crude preprocessor that can include shader sources files via an #include directive. It supports nesting and arbitrary namespaces paths. See canvas source files for examples of usage.
When the shader is compiled all included source is compounded into a single source file that is sent to the graphics driver. OpenGL is typically good about removing dead code, but it is advisable to keep libraries small and only include what you need.
All source located in /assets/canvas/shaders/internal is non-public API and should not be referenced outside of Canvas code. No effort will be made to support such usage nor to prevent breakage if it happens. Future versions of Canvas may detect and warn against such usage to prevent inadvertent dependencies.
- Canvas will define the GLSL version as 120 to ensure compatibility. Later versions are unsupported and conflicting declarations will fail.
- No extensions should activated or depended on except
GL_EXT_gpu_shader4