CS 4391 Spring '97 - Project 0

Due: Monday, April 14, 1997, 2:00 PM

Objective

Warm-up exercise: to demonstrate understanding of the simple command language interface and basic matrix operations.

Introduction to CLI

Instead of building specific scenes into our rendering code, we are going to put scene descriptions in data files separate from the program files. In this way, we don't need to change the program files and re-compile when we need to change the scene -- only the scene data file need to be modified. To implement this, we will use a simple command language interface (CLI) library to read in and interpret scene data files.

Although in this assignment you will not build nor render any scene, it will get you started on using CLI. You need to copy all the files in

	~cs4391/cli

to one of your directories. The files are:

	cli.h		-	Header file of CLI
	cli.c		-	C code file of CLI
	makefile	-	Makefile to build the library and test program
	testcli.c	-	Test program
	example.cli	-	Example input file

You can compile everything by typing make. When you run the test program testcli you will see a prompt:

	testcli>

You can then type in commands it understands at that prompt. For example, ? lists all the commands; add takes two integer parameters and adds them together; repeat takes an integer parameter n and a word, then prints out the word n-times; and finally read takes a file name and executes every command in that file as if they were typed in.

The main function in a program using CLI usually looks like the following:

Initialize CLI, for example:
```
	START_CLI("testcli", "cli")
  
```
Here "testcli" becomes the prompt string, and "cli" becomes the data file extension.
Define an application specific command, for example:
```
	COMMAND("add  num1 num2") {
	    float           a, b;

	    get_real(&a);
	    get_real(&b);
	    printf("%g + %g = %g\n", a, b, a + b);
	}
  
```
Here "add num1 num2" is the command description. The first word is the command name. The rest of them are dummy names for command parameters. When CLI gets a matching input, it executes code in the definition block. get_real is a CLI function that parses a parameter on the command line and saves it in a float variable. You can see uses of other CLI routines in the test program.
A typical use of a command is to get the necessary parameters, then invoke an application defined function in the place of the printf; the application define function may be in some other file(s) that will be linked in during the make process.
Finalize CLI, for example:
```
	END_CLI("Pardon?", "Bye-bye.")
  
```
Here "Pardon?" becomes the error prompt string, and "Bye-bye." becomes the log-out confirmation string.

Note that there's no ``;'' after any of the START_CLI, COMMAND, or END_CLI block.

Assignment

Extend the test program so it can calculate multiplication of a 4 by 4 matrix and a 4 by 1 vector. I.e. add:

A command matrix that takes 16 float parameters and saves them in a 4 by 4 matrix in row order. Let's call the matrix M.
A command vector that takes 3 float parameters and saves them in a 4 by 1 column vector (the last value in the vector is always set to 1.0). Let's call the vector V. The program prints out the result of M multiplies V.

Your program should handle series of vector commands (with possibly different values) and calculate multiplication results against the set matrix. It should also allow reseting the matrix with new sets of values.

Hints: Use input data files to help testing your program. Use an ANSI C compiler, for example in the College of Computing:

	/usr/local/lang/acc		-	on SunOS 4 machines
	/opt/SUNWspro/bin/cc		-	on Solaris 2 machines
	/usr/bin/cc			-	on SGI IRIX machines

You don't have to use the SGI machines to finish this project, but it's a good idea to test your program on them (because your friendly TA will grade your project on those machines, and any compilation error or core-dumping behavior can drive him really mad ;-).

Submission

Put your project files in a directory on a College of Computing UNIX machine, then execute the following command in that directory:

	shar *.c *.h makefile | elm -s "proj0" cs4391@cc.gatech.edu

The programs shar and elm are in the /usr/local/bin directory. Note that you are not allowed to modify the CLI library files; and the cs4391 email address is only for turning in your project files (mails to that account are saved automatically for grading).

Last modified: 04-Apr-97