Triton offers a “user shader” framework that allows you to extend Triton’s shaders, while keeping your integration code separate from ours. This can be incredibly useful if you need to integrate Triton with a proprietary lighting algorithm or deferred rendering system.
It can be tempting to try to use some of Triton’s internal shader uniforms inside your user shaders. Why bother maintaining your own uniform for the modelview matrix, when there’s a “trit_modelview” uniform defined in our projgrid_ellipsoid_common.glsl shader file?
Well, it *is* possible to do that, but it’s kind of fraught with peril. Let’s cover a couple of things you need to be aware of before attempting to use Triton’s internal uniforms in your user shaders.
You can’t just declare a uniform that’s in a UBO somewhere else.
Triton uses uniform buffer objects internally, which means it’s not as simple as just declaring the uniform you want to use at the top of your user shaders. But, we know some customers really want to do this, so we’ve provided a way.
Inside the resources/Triton.config file, look for this setting:
gl-uniforms-available-in-usershaders = no
If you set that to “yes”, then we will expose our uniforms to the user shaders. They won’t work at all unless you change this setting, so that’s step one no matter what!
Not every uniform is linked into every shader program.
The other problem you’re likely to encounter is that your user shader will be linked into every shader program Triton creates, including the ones used to draw the ocean, spray particles, “god rays,” and decals. But not every uniform is declared within every shader internally. So, if you include a uniform that’s defined for the ocean (projgrid*) shaders but not also in every other shader, you’ll get a shader compilation error on your user shaders.
You can get around this by using some preprocessor definitions within your shader: OCEAN_SHADER, DECAL_SHADER, GODRAYS_SHADER, and PARTICLE_SHADER. If you wrap any references to our internal uniforms with #ifdef’s that check for these definitions, you can ensure that you are only referencing those uniforms within the shaders they exist in.
Even better: don’t do this!
As you can see there’s a lot that can go wrong when you try to re-use our internal uniforms in your user shaders, including the possibility that we’ll remove or rename them in later releases of Triton. While you *can* do it if you follow the guidance above, it’s going to be safer in the long term to manage your own uniforms within the user shaders if at all possible. Triton::Ocean::GetShaderObject() will return the underlying program objects for each of Triton’s internal shaders, allowing you to set and maintain your own uniforms on them.
