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 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)
See Also
Name | Description |
---|---|
Working with OpenGL | Working with OpenGL |