1.0 Introduction Welcome to the animation programming manual. All the animation 'c'functions are detailed so that you can dictate and change the behaviour of the animation systems five user modules. To program your own algorithms you 1). Include the source (including the animation functions) in one of the user#.c modules 2). Compile Project 3). Run Compiled Program 1.1 Labelling Line Numbers All the animation functions start with an 'a_' and have an integer parameter (the last one). This parameter indicates to the player which line of code the function is referring too. I call this parameter the highlight reference (HLF). In the process of altering an algorithm, it is useful to label the line numbers with their reference number (starting at 0), this will help you to give the correct HLF. E.g. #include #include /* 000 */ void sel_control(void); /* 001 */ void selection(int [],int); /* 002 */ void sel_control(void){ /* 003 */ int b[7]={ 12, 13, 11, 9, 14, 15, 16}; a_func("sel_control",2); a_irayini(b,"b",7,3); a_callfunc("selection",4); /* 004 */ selection(b,7); a_endfunc("sel_control",5); /* 005 */ } NB. Only the algorithm operations want line numbers, NOT the animation functions or the #includes. 1.2 User Entry Points You can alter the five user modules (user1.c-user5.c). When Calgor is asked to run a user module, it starts at user#-control(); (where # is the number of the module you are playing). It is VERY important that your program should start at this point and not a point like main(). E.g. /* 001 */ void user1_control(){ /* 002 */ int d[10] = {-1,8,7,6,5,4,3,2,1,0}; /* 003 */ int parts = 10; a_func("user1_control",1); a_irayini(d,"d",parts,2); a_intini(parts,"parts",3); a_show(4); /* 004 */ quicksortb(d,0,parts-1); a_endfunc("user1_control",5); /* 005 */ } 1.3 Compiling The Project The Calgor.dice file has been included to help you in compiling the project (calgor.dice is just a make file). If you are using DICE, all you have to do is double click on this icon. This will pass the Calgor.dice file to Vmake, just specify your target machine, and where the code is going to be compiled (these are first set to RAM:) and then compile as normal. Calgor is set up to be compiled with Workbench 2.0 includes, if you want to compile under WB 3.0 then define V3, in the hold/extra.h file (this is presently commented out). 2.0 Animation Functions To program an algorithm, so that it can be used by the animation system is analogous to sequentially describing events taken by the algorithm. So with this in mind here are the functions, their parameters and examples of their operations. 2.1 void a_func(char *,int) char * Function Name int HLF This function is used to signal to the animation system that a function is starting. E.g. /* Line 000 */ void sel_control(void); /* Line 001 */ void sel_control(void){ a_func("sel_control",1); /* Line 002 */ } It displays the function name in the title bar. Calling this function repeatedly with the same function name causes the function index to increase by one. Caution must be taken if declarations are given after the function. E.g. /* Line 000 */ void sel_control(void); /* Line 001 */ void sel_control(void){ a_func("sel_control",1); /* Line 002 */ int a = 1; /* Line 003 */ } This would probably produce a compiler error due to the function 'a_func' being in front of the declaration 'int a=1'. To correct, specify a_func (or for that any animation function) after declarations, so the correct method would be. /* Line 000 */ void sel_control(void); /* Line 001 */ void sel_control(void){ /* Line 002 */ int a = 1; a_func("sel_control",1); /* Line 003 */ } 2.2 void a_irayini(int [],char *,int,int) int [] Array char * Array Name int Number Of Elements int HLF a_irayini will show the animation sequences to initialise an integer array. E.g. /* Line 000 */ void sel_control(void); /* Line 001 */ void sel_control(void){ /* Line 002 */ int b[7]={ 12, 13, 11, 9, 14, 15, 16}; a_irayini(b,"b",7,2); /* Line 003 */ } An important restriction is that there is only one integer array allowed per program, with a maximum of 10 elements. If the elements of the array have not be initialised first before calling this function, the contents of the elements may contain junk values, which will be displayed. 2.3 void a_iraypas(char *,int) char * Array Name int HLF Use this function when passing an array to a function. a_iraypas needs to be located in the receiving function. The function has similar animation sequences to the a_irayini. E.g. /* Line 000 */ void sel_control(void); /* Line 001 */ void selection(int [],int); /* Line 002 */ void sel_control(void){ /* Line 003 */ int b[7]={ 12, 13, 11, 9, 14, 15, 16}; a_irayini(b,"b",7,3); /* Line 004 */ selection(b,7); /* Line 005 */ } /* Line 006 */ void selection(int a[], int N){ /* Line 007 */ int i, j, min, t; a_iraypas("a",6); /* Line 008 */ } 2.4 void a_endfunc(char *,int) char * Function Name int HLF This function is used to denote that a function is about to end. There are presently no animations (except for highlighting) that go with this function. It allows the animation system to keep track of the current function . E.g. /* Line 000 */ void sel_control(void); /* Line 001 */ void sel_control(void){ /* Line 002 */ int b[7]={ 12, 13, 11, 9, 14, 15, 16}; a_endfunc("sel_control",3); /* Line 003 */ } 2.5 void a_intini(int, char *,int) int Integer value char * Integer Name int HLF The function a_intini causes the animation which shows the variables initial value. The function takes the integer value, name and HLF. E.g. /* Line 000 */ void sel_control(void); /* Line 001 */ void sel_control(void){ /* Line 002 */ int anumber=1; a_intini(anumber,"anumber",2); /* Line 003 */ } If a variable has not been initialised then a junk value could be shown. This should only be used once usually at the beginning of the function. When assigning a new value to a variable use the a_intass function. 2.6 void a_intass(int, char *, char *,int) int Value To Assign, char * Destination Value, char * Source Value, int HLF. When assigning values to integer variables use a_intass. The source value can be arithmetic sum (9+1*2+a[9]-v), absolute value (10), variable (v), array with an integer index(a[10]), array with a variable (a[v]), array with variable with integer offset (a[v*1]). Limitations: 1). Full evaluation of the arithmetic expression in the array delimeters is not made so (a[v+1*2]) would not be evaluated properly, also (a[1+v]) would be evaluated incorrectly. 2). Only *, -, / and + operations are evaluated. 3). There is no precedence ordering so the sum (9+1*2) would equal 20 and not 18. 4). a_intass cannot handle bracketed expressions such as (8+9)*7 . 5). The maximum number of components in a sum is 10. The destination value can either be an integer variable (v), integer array indexed by an integer (v[10]) or an integer array indexed by a integer variable (v[v]). /* Line 000 */ void sel_control(void); /* Line 001 */ void sel_control(void){ /* Line 002 */ int anum=1; /* Line 003 */ int morn=9; a_intini(anum,"anum",2); a_intini(morn,"morn",3); /* Line 004 */ anum = 4 + morn* 5; a_intass("anum","4+morn+5",4); /* Line 005 */ } a_intass should usually be placed after the sum has been executed in the algorithm, however the animation player does keep an internal representation of values. It is possible therefore to place the a_intass before the actual sum has been executed and have the animation system display the correct answer according to the sum E.g. /* Line 000 */ void sel_control(void); /* Line 001 */ void sel_control(void){ /* Line 002 */ int anum=1; /* Line 003 */ int morn=9; a_intini(anum,"anum",2); a_intini(morn,"morn",3); a_intass("anum","4*morn+5",4); /* Line 004 */ anum = 4 + morn * 5; /* Line 005 */ } /* This example would start the assignment animation sequences with anumber being assigned the value of 41 */ 2.7 void a_intcomp(char *,int) char * Evaluation expression int HLF This function will start the animation sequences for comparing two integer expressions. The function cannot handle more than two expressions but can handle the following operators: >, <, <=, >=, == , !=, as well as the unary test i.e. (expression). The two expressions can either be an arithmetic sum (9+1*2+a[9]-v), an absolute value (10), a variable (v), an array with an integer index(a[10]), array with a variable (a[v]), or array with variable with integer offset (a[v*1]). E.g. /* Line 000 */ void sel_control(void); /* Line 001 */ void sel_control(void){ /* Line 002 */ int anum=1; /* Line 003 */ int morn=9; a_intini(anum,"anum",2); a_intini(morn,"morn",3); a_intcomp("morn > anum",4); /* Line 004 */ if (morn > anum) /* Line 005 */ anum =0 ; /* Line 006 */ } Notice that a_intcomp is called before the actual comparison is made in the algorithm, it is legal to do this as a_intcomp relies on the internal values of variables for its operation. 2.8 void a_show(int) int HLF This function is simply used to highlight a line, used so you can monitor program steps. E.g. /* Line 000 */ void sel_control(void); /* Line 001 */ void selection(int [],int); /* Line 002 */ void sel_control(void){ /* Line 003 */ int b = 0; a_show(4); /* Line 004 */ selection(b,7); /* Line 005 */ } Note that the function is called before the calling of selection(b,7), if it was placed after, the highlight would not represent the correct program sequence. 3.0 Loops Just a few pointers, when executing a for loop an assignment is made once only in the first part of the loop, a comparison is made before the loop is entered and a value is changed. To observe these effects call a_intass and a_intcomp (respectively) before entering the loop. When inside the loop call the a_intass routine and then call a_intcomp E.g. /* Line 000 */ void sel_control(void); /* Line 001 */ void selection(int [],int); /* Line 002 */ void sel_control(void){ /* Line 003 */ int b = 0; /* Line 004 */ int a = 9; a_intini(b,"b",3); a_intini(a,"a",4); a_intass("b","0",5); a_intcomp("b < a",5); /* Line 005 */ for(b=0;b < a; b++){ a_intass("b","b + 1",5); a_intcomp("b < a",5); /* Line 006 */ } /* Line 007 */ selection(b,7); /* Line 008 */ } Happy Programming