GLSL Porting Guide for GL3

Updating GLSL Shaders for GL3

If you have written custom shaders for Jitter, you will likely want to start updating your shaders for use with the new GL3 engine. For convenience, Jitter attempts to load and convert legacy GLSL shaders. In many cases, you’ll find that no changes are necessary and your shaders will work without issue. However, there may be some limitations to this conversion, in which case you will need to update your JXS file. If you find such a case, or get errors on loading shaders that worked in the classic GL2 engine, please let us know.

JXS checklist:

  • In the language tag, change “version” value from “1.0” to “1.5”
  • Determine which vertex attributes your vertex shader needs (typically POSITION, TEXCOORD, and NORMAL) and add the appropriate param tags as follows:
    <param name="jit_position" type="vec3" state="POSITION" />
    <param name="jit_texcoord" type="vec2" state="TEXCOORD" />
    <param name="jit_normal" type="vec3" state="NORMAL" />
    The currently supported vertex attribute state accessors are
    • POSITION (vec3)
    • TEXCOORD (vec2)
    • NORMAL (vec3)
    • TANGENT (vec3)
    • BITANGENT (vec3)
    • VERTEX_ATTR
    • VERTEX_ATTR0
    • VERTEX_ATTR1
    • VERTEX_ATTR2
    • VERTEX_ATTR3
  • Add the appropriate bind tags to the JXS as follows:
    <bind param="jit_position" program="vp" />
    <bind param="jit_texcoord" program="vp" />
    <bind param="jit_normal" program="vp" />
  • Determine which built-in uniforms your shader uses and add the appropriate param and bind tags:
    <param name="textureMatrix0" type="mat4" state="TEXTURE0_MATRIX" />
    <param name="modelViewProjectionMatrix" type="mat4" state="MODELVIEW_PROJECTION_MATRIX" />
    <bind param="textureMatrix0" program="vp" />
    <bind param="modelViewProjectionMatrix" program="vp" />
  • The gl3 engine provides an additional state uniform, CAM_PROJECTION_MATRIX. This uniform accesses the current camera projection matrix. In most cases this will be the same as PROJECTION_MATRIX except when drawing in a jit.gl.slab or jit.gl.pass. An example of usage is the pass.ssao.gl3 patch.
  • Once these are added, your shader will have access to standard built-in variables, but you will also need to change a few items in the GLSL code itself.

Vertex Program Checklist:

  • Add the appropriate #version directives at the start of each shader program, e.g.: “#version 330 core”
  • Add the vertex attributes as inputs at the top of the vertex shader:
    in vec3 jit_position;
    in vec2 jit_texcoord;
    in vec3 jit_normal;
  • Add declarations for the uniform variables we created previously:
    uniform mat4 textureMatrix0;
    uniform mat4 modelViewProjectionMatrix;
  • In the code itself, replace any instance of built-in “gl_” variables with their equivalent:
    • Replace gl_Vertex with jit_position
    • Replace gl_MultiTexCoord0 with jit_texcoord
    • Replace gl_Normal with jit_normal
    • Replace gl_ModelViewProjectionMatrix with modelViewProjectionMatrix
    • Replace gl_TextureMatrix[0] with textureMatrix0
  • Replace varying variables and any vertex attributes you wish to pass along with an appropriate out struct, removing any built-in “gl_” :
    // vertex outputs
    out jit_PerVertex {
    vec4 jit_texcoord0;
    vec3 myPos;
    vec3 myOtherVar;
    } jit_out;

Fragment Shader Checklist:

  • Replace varying variables with an in struct that matches the out struct created in the vertex shader:
    in jit_PerVertex {
    vec4 jit_texcoord0;
    vec3 myPos;
    vec3 myOtherVar;
    } jit_in;
  • Add a layout directive for your fragment program output:
    layout (location = 0) out vec4 outColor;
  • Replace gl_FragColor with this output variable, for example:
    outColor = vec4(input.rgb, 1)
    

To get a functioning example of a new GLSL shader, simply double-click on a jit.gl.shader object with no shader file loaded. This is often a good first step in updating your shaders.

Referencing Other Files Using #include

GL3 supports the use of include to reference other shader files in the main jxs as long as those files are in the Max search path. These should be added after your bind tags and before your vertex program declaration.

bind param="FrontMaterialParameters" program="vp" />
bind param="LightingParameters" program="vp" />

include source="diffuse.glsl" program="vp" />
include source="specular.glsl" program="vp" />

program name="vp" type="vertex">

For practical examples, see the patches in ~/Documents/Max 8/Packages/gl3/patchers.

See Also

Name Description
GL3 Package Topics GL3 Package Topics