1. Install all system requirements.
2. Download the JPot package and extract it to a directory. There is the program names trigger(.exe) that needs to be copied to a directory that declared in the PATH environment variable. If you are running Windows environment, it is suggested that you copy the trigger.exe program to C:\Windows. If you are running UNIX, you could copy it to $HOME/bin or /usr/local/bin and make sure that your PATH variable contains the path to that directory.
3. You can download the whole package of JPot or several pieces. The only different between Windows package and UNIX package is the OpenGL illustrated example programs in ogl sub-directory. There are either pre-compiled OpenGL examples for both Windows and Linux, or source file package that you can download and compile by yourself. If you are going to download the source files and compile them by yourself, make sure that the executable programs are stored in ogl sub-directory to be accessible when running the tutorial.

1. To run the tutorial, go to the directory that you install the software package and run the command java JPot <Enter>
2. The content of the tutorial will be on the left of the application's window. Click on chapter name to open its lessons, and click on the lesson to view its lecture note on the right window. There will be a link to the illustrated example of each lesson. Click on that link will invoke the example program.
3. Each example program lets you interact to practice the concept you have learned from the lecture. The interaction is done by changing sliders' value, choosing different active values from the radio buttons, etc. After setting interactive values, click on Execute button will update the viewing source code (new values appear in red color) and also the object rendering screen. The viewing source code window shows you the exact OpenGL program to obtain the result in the object rendering window on the left hand side.
4. Click on Reset button will set all parameters back to the default values.

Create input file for the generator

Generally, all declarations are started by the string "/*$$$" and ended by "$$$*/". Depending on what kind of interaction is required in the lesson, syntax will be applied appropriately to it. There are two major kinds of interactions available in JPot: sliders and code-swapping radio buttons. There are three different types of sliders, but they are declared by the same syntax, and different types of sliders can be specified in the same statement. Declaration of each slider is quoted between "[" and "]", and separated by a comma. The generator will determine the type of sliders during the process automatically to create the appropriate one for the lesson. Code swapping and slider declarations can be mixed together as a useful feature of the tutorial. Details of how to obtain this is described below.

The format of a declaration for numeric sliders is:

/*$$$[label, data type, default value, min value, max value, alignment],[…]$$$*/

Where:

[…]	Contains the declaration of each parameter. Note that different types of sliders can be declared in the same section that ranges by /*$$$ and $$$*/, including slider of integer, slider of floating point number, and slider of string constant.
Label	A string to specify the label of the slider, it will appear on the interactive window.
Data type	A character to specify the type of numeric value applied to the slider. We use character "f" to specify floating values, and character "i" to specify integer values.
Default value	A value that will be applied to the slider when the program first runs, and when the user resets all the values.
min value	Minimum value that the user can set with the slider.
max value	Maximum value that the user can set with the slider.
Alignment	A character to specify whether the slider will be drawn consecutively with the previous slider, or start at the new line. If it is "c", then the slider will be drawn consecutively, if it is "n", then it will be started at the new line.

The format of a declaration for constant-value sliders is:

/*$$$[label, data type, default string, [string constant, constant value],…,alignment],[…]$$$*/

Where:

[…]	Contains the declaration of each parameter. Note that different types of sliders can be declared in the same section that ranges by /*$$$ and $$$*/, including slider of integer, slider of floating point number, and slider of string constant.
Label	A string to specify the label of the slider, it will appear on the interactive window.
data type	The character "s" to specify that this type of slider is a constant string value slider.
default string	The string constant that will be applied to the slider when the program first runs, and when user reset all the values.
string constant	The string defined in header files that represents the constant value.
constant value	Constant value that is represented by the string constant.
Alignment	A character to specify whether the slider will be drawn consecutively with the previous slider, or start on a new line. If it is "c", then the slider will be drawn consecutively. If it is "n", then it will be started at the new line.

Below is an example of how to declare parameters of the glTranslatef function to match with three consecutive sliders in the interaction window. It also shows all three parameters of the glTranslatef function that are changed to be JPOT$1, JPOT$2, and JPOT$3 as required for the generation process.

/*$$$ [X, f, 0.0, -5.0, 5.0, c], [Y, f, 0.0, -5.0, 5.0, c], [Z, f, 0.0, -5.0, 5.0, c]$$$*/

glTranslatef(JPOT$1, JPOT$2, JPOT$3);

Below is an example of how to declare parameters for the glBegin function to get different constant values from the slider during the running time. These differ from numeric sliders where users can select different numeric value, with this kind of slider they will see and select constant string instead.

/*$$$

[Line Mode, s, GL_LINES, GL_LINES 1 GL_LINE_LOOP 2 GL_LINE_STRIP 3, c]

$$$*/

glBegin(JPOT$1);

In this example, note that GL_LINES, GL_LINE_LOOP and GL_LINE_STRIP are three constant values that users will see and select from the slider, and 1, 2, 3 are real values that those constants are represented by. Similar to the previous example, the only one parameter of glBegin function is set as JPOT$1.

The format of a declaration for code swapping processes has two parts: One for the portion of codes that will be active by default, and the other one is the portion that will be inactive at the first time running. During the running time, users can set the active part by selecting the appropriate radio button on the interactive window. The syntax to declare these portions is below:

/*$$$swap-flip label$$$*/

the active portion of code by default

/*$$$swap-end$$$*/

/*$$$swap-flop label$$$*/

the inactive portion of code by default

/*$$$swap-end$$$*/

where label is the label of the corresponding radio button on the interactive window.

Code swapping and sliders can be merged together to handle the situation where interaction with sliders are required in both parts of the swapping codes. To do that, declare parameters for sliders only at one part of the code, and repeat the variable names of sliders' parameters (JPOT$1, JPOT$2, etc…) in the other part.

A comprehensive example below shows how to combine the declaration of sliders and code swapping together to enhance the usefulness of the declaration languages and the generator. In the example, two radio buttons will be created on the screen with the title "Translate then Rotate" and "Rotate then Translate" respectively. Seven sliders will be created in three rows: One with X1, Y1 and Z1 values for the translation's parameters, the other for setting the angle of the rotation, and the last row for the three parameters X2, Y2 and Z2 of the rotation function.

/*$$$swap-flip Translate then Rotate$$$*/

/*$$$

[X1, f, 0.0, -5.0, 5.0, c],

[Y1, f, 0.0, -5.0, 5.0, c],

[Z1, f, 0.0, -5.0, 5.0, c],

$$$*/

glTranslatef(JPOT$1, JPOT$2, JPOT$3);

/*$$$

[Angle, f, 0.0, -90.0, 90.0, n],

[X2, f, 0.0, -5.0, 5.0, n],

[Y2, f, 0.0, -5.0, 5.0, c],

[Z2, f, 0.0, -5.0, 5.0, c]

$$$*/

glRotatef(JPOT$4, JPOT$5, JPOT$6, JPOT$7);

/*$$$swap-end$$$*/

/*$$$swap-flop Rotate then Translate$$$*/

glRotatef(JPOT$4, JPOT$5, JPOT$6, JPOT$7);

glTranslatef(JPOT$1, JPOT$2, JPOT$3);

/*$$$swap-end$$$*/

The File Parser program is used to generate files for new lessons. The program receives the original OpenGL file with embedded descriptions for the interaction, and a string specifies the output name as the input. For each time running with an input file, it generates three files as output: a Java program for the interaction interface, the viewing source code under HTML format and the OpenGL C program. These three files are placed into the appropriate directories by the generator: the Java program in the current directory, the HTML document in the html directory and the OpenGL C program in the ogl directory.

Users need to compile the new files to have them worked on. To compile the Java program, use the command

javac <java program with extension> <enter>

To compile the OpenGL C program, there maybe several ways depending on what kind of C compiler they have in the system with the same name as the base name of the input file.

A lecture note of the new created lesson needs to be created under HTML format, with hyperlink to the corresponding Java class of the lesson that has just been created. For example, if the name of the new lesson is "NewLesson", the hyperlink will be as follows: <a href="NewLesson.class">Click here to run the example</a>.

New lessons need to be declared in the Configure file before it is active in JPot. To define either a new chapter or lesson for JPot, a line must be added with the following format to the Configure file:

<Chapter name> <Lesson Name> <Lecture file name>

where:

Note that position of this string in the Configure file effects the order of its appearance in the tutorial.