Updating Legacy GLSL Shaders for glcore

If you have written custom shaders for Jitter, you will likely want to start updating your shaders for use with the new glcore 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.

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 glcore 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.
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

JXS shader files support including external GLSL source files as long as those external files are in the Max search path. The include tags 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">

GLSL Porting Guide

Updating Legacy GLSL Shaders for glcore

JXS checklist:

Vertex Program Checklist:

Fragment Shader Checklist:

Referencing Other Files Using #include

See Also