The OpenGL Matrix Format Building Standalone Applications with Jitter Jitter Tutorials

Appendix C: The JXS File Format

The Jitter Shader Description File

Jitter provides a means of encapsulating shader parameters and programs through an XML based shader description file (JXS). This JXS file offers an easy way of setting up any required OpenGL state to achieve a particular effect, without any additional patcher related work.

The JXS file may contain a list of parameters and textures, followed by a set of language dependent implementations for the shader's vertex and fragment programs.

Each language implementation must specify both a vertex and a fragment program. These programs may either reference external files, or be stored inline within a CDATA section or an XML comment. Programs for each language implementation will be loaded and bound in the order that they are listed in the JXS file. If a particular language implementation fails to compile, the next implementation will be used, until a successful candidate is found.

Inside of the language implementation declaration, any shader parameter previously specified must be identified with a bind tag that indicates which shader program should receive the parameter's values.

The following listing outlines the format of a typical JXS file:

<jittershader name="myshader">
  <!-- optional description -->
  <description>This is my shader</description>

  <!-- optional list of texture objects to bind -->
  <texture file="mytexture.jpg"/>

  <!-- optional list of shader parameters -->
  <param name="myparam" type="vec3" default="3.0 4.0 5.0">
    <description>This is my parameter</description>
  </param>

  <!-- list of language implementations -->
  <language type="glsl" version="1.0">

    <!-- list of binding targets for shader parameters -->
    <bind param="myparam" program="vp"/>

    <!-- vertex and fragment programs -->
    <program name="vp" type="vertex" source="sh.passthru.xform.vp.glsl"/>
    <program name="fp" type="fragment">
      <![CDATA[

        // entry point
        void main()
        {
          gl_FragColor=vec4(0.5, 0.5, 0.5, 1.0);
        }
      ]]>
    </program>
  </language>
</jittershader>

Note that the XML document must be well-formed with matching opening/closing tags.

JXS Shader State Variables

Jitter provides several built in uniform variables that expose OpenGL state to JXS shader programs. These can be accessed by specifying the variable name in the state attribute of the XML param tag

For exmaple:

<param name="itvmat" type="mat3" state="NORMAL_MATRIX" />

Available shader parameter state bindings are listed below.

Model View and Projection Matrices

WORLD_MATRIX (mat4)
VIEW_MATRIX (mat4)
MODELVIEW_MATRIX (mat4)
PROJECTION_MATRIX (mat4)
VIEW_PROJECTION_MATRIX (mat4)
MODELVIEW_PROJECTION_MATRIX (mat4)
PREV_MODELVIEW_PROJECTION_MATRIX (mat4)
NORMAL_MATRIX (mat3)

Camera

CAMERA_POSITION (vec3)
CAMERA_DIRECTION (vec3)
VIEWPORT (vec2)
INVERSE_VIEWPORT (vec2)
NEAR_CLIP (float)
FAR_CLIP (float)
FAR_CORNER (vec3)

Light

LIGHT_VIEWPROJ_MATRIX0-7 (mat4)
LIGHT_RANGE0-7 (float)
LIGHT0-7_POSITION (vec3)
LIGHT0-7_DIRECTION (vec3)
LIGHT0-7_AMBIENT (vec4)
LIGHT0-7_DIFFUSE (vec4)
LIGHT0-7_SPECULAR (vec4)
LIGHT0-7_CUTOFF (float)
LIGHT0-7_EXPONENT (float)

Material

AMBIENT (vec4)
DIFFUSE (vec4)
SPECULAR (vec4)
EMISSION (vec4)

Texture

TEXTURE0-7_MATRIX (mat4)
TEXDIM0-7 (vec2)

Matrix Transformations

Matrix variables (mat3 and mat4 type variables) can be transformed in specified ways using the transform attribute of the XML param tag:

<param name="itvmat" type="mat4" state="VIEW_MATRIX" transform="INVERSE_TRANSPOSE" />

Available matrix transformations include:

IDENTITY
TRANSPOSE
INVERSE
INVERSE_TRANSPOSE

Vertex Attributes

Jitter JXS shader programs are able to access custom vertex attributes via the VERTEX_ATTR state tag:

<param name="pvel" type="vec4" state="VERTEX_ATTR" />

and in the vertex program:

attribute vec4 pvel;

To set the values of custom vertex attributes from the patch, send jit.gl.mesh the vertex_attr_matrix message followed by the name of a jit.matrix containing the attribute values. The example patch custom.vertex.attribute demonstrates this.

Additionally there are several built in vertex attributes available via the following state tags:

POSITION (vec3)
NORMAL (vec3)
TANGENT (vec3)
BITANGENT (vec3)