Crawly Crypt Collection 1

home *** CD-ROM | disk | FTP | other *** search

/ Crawly Crypt Collection 1 / crawlyvol1.bin / graphics / polyfilm / manual.doc < prev next >

Wrap

Text File | 1993-06-01 | 81KB | 2,311 lines

Polyfilm User Manual Martin Brownlow 1. Alert boxes The user will not get very far in Polyfilm without being able to use an alert box. An alert box is formed by a dou- ble edged box containing text and between one and three (inclusive!) buttons, one of which will have an edge twice as thick as the others. They appear usually when the user has done something unwise, but also when there is a choice of options, for instance, the Polyfilm title screen is an alert box with three items. They function in exactly the same manner as GEM's alert boxes. Pressing a button (by clicking on it with either button) will select the relevant option, informing the pro- gram of your choice. Pressing return counts as selecting the button with the double thick edge. While an alert box is present on screen, nothing else will work, since the pro- gram is waiting for your input. 2. The fileselector Any functions which involve the selection of a filename will at some time call the fileselector. It is invaluable that the user knows how to correctly manipulate this form, or else correct usage of Polyfilm will be impossible. It is similar in many ways to the GEM fileselector of TOS 1.4 up, with buttons for each drive present to allow easy swapping between drives. The drive buttons are located down the left hand side of the form, and each can be one of three colours; white for present but not selected, green for not present or red to indicate the currently selected drive. Clicking on a white drive button will change to that drive and read files from there. Clicking on a green or red drive button has no effect. Dominating the middle of the form is the file-list win- dow. Contained in this window are all the files in the current directory which match the current file mask (shown in the top-right of this window) along with all the sub- June 1, 1993 - 2 - directories present. Selectable files are show in black text, with directories written in red. To select a file, click on it in the window, and it will turn black and its name will appear in the selected box to the right of the file window. Clicking on the name again, or clicking on the OK button will use this file as the filename wanted by the function. Click on cancel (or OK with no file selected) to cancel the function. To change to a sub-directory, simply click once on the directory name in the file window. To regress back through the subdirectories (ie go back a direc- tory), click on the black square in the top left of the win- dow. The final function available in the file window is the ability to scroll through all the files present if there are more than eleven. To do this, simply click on the up or down buttons at the top and bottom right of the window. One final feature is the ability to edit the filename to, for instance, create a new file. This is done in the selected box of the fileselector. Pressing either the left or right arrow keys will move a green cursor through the filename, and typing while the cursor is visible will insert text into the cursor position, moving the cursor on after each character. The backspace key will delete the character to the left of the cursor, and the delete key will delete the character under the cursor. Finally, pressing the escape key will clear the filename and put the cursor to the beginning of the filename. 3. The editor 3.1 Introduction The editor is where the user will create all of the objects for use in a film, as well as the preferences file for the film (the file which holds all the palettes, patterns and lightsource shadings). The editor screen consists of four windows in the left two-thirds of the screen, and a menu of options and three bars in the right third of the screen. The windows each hold a projection of the current object; the top left window holds the front projection of the object, the top right win- dow holds the end projection of the object, the bottom left window holds the plan projection of the object, and finally the bottom right window holds a three dimensional wireframe projection of the object, whose orientation is described by the three bars in the lower right corner of the screen. Each window consists of the main image, two scroll bars (to the right and bottom sides of the window) and a zoom box (in the bottom right corner of the window) which controls the magnification of the image in the window. Clicking with June 1, 1993 - 3 - the mouse on a scroll bar will centre the window at the corresponding point in space. Clicking on the zoom box will either increase the magnification of the image in the window (ie zoom-in) or reduce it, depending on whether the left or right button is pressed. Clicking in the body of the window has no effect unless you are adding shapes to the object. The three bars in the bottom right portion of the screen control the orientation of the object in the three dimensional projection window. Clicking on the arrows with the left button will change the corresponding angle by 1 degree, using the right will change it by 15 degrees. Finally, clicking directly on the bar will immediately change the angle to the corresponding amount. The final element of the editor is the menu. Clicking on a menu item (or pressing the indicated key) will do the corresponding function. Many menu items bring up further menus to control the action of the function. For instance, the first menu item, add, brings up a further menu whose items consist of Point, Line, Triangle, Quad, Sphere, Detail, Colour and Menu. Choosing Point or Line from here will immediately put you into creation mode, in which you can create new shapes inside the object's definition. As stated earlier, the editor uses four windows to display the object being edited, each one having individual zoom and location settings. Contained in these windows are the wireframe views of the object; three orthographic pro- jections and a configurable three dimensional projection. The three dimensional projection can have its Euler angles (Euler angles are the three angles which define an object's attitude) changed by means of the three bars in the bottom right of the screen. It should be noted that the Euler angles defined by the bars describe the object's attitude, not the camera's, so Euler angles of [0,0,0] do not give the front projection, since this faces into the screen. Instead [180,0,0] should be used, or, for use in the interpreter, [180*16,0,0] (the interpreter uses 360*16 divisions for its angle measurements to give increased accuracy). The atti- tude of the three dimensional image is important in several functions, for example the view functions and the orienta- tion function. See later for descriptions of their usage. The editor can be exited at any time while the main menu is showing, either by clicking on the Quit button, or by pressing the escape key. If there are objects that have changed since they were last saved then the user is given the chance to abort quitting the editor. When the editor is exited, all banks and preferences which have not been saved are lost forever. June 1, 1993 - 4 - 3.2 Adding a shape The first thing the user will want to do is add a shape. This is a quite simple activity, and forms the core of the editor; you can't do very much without adding a shape at some time or another... In order to add a shape, you must first enter the Add menu by either clicking on the add button, or pressing A (on all functions which have a keyboard shortcut, the key to press is indicated in squared parentheses after the button name). After selecting the add button, the menu will change to one offering a choice of different shapes for use in the image, along with options for colour, detail and going back to the main menu. Clicking on point or line (or pressing P or L) will immediately take you into the windows to enter the defining points of the shape (see below), whereas selecting triangle, quad or sphere will bring up another menu for further defining the properties of the shape. 3.2.1 Further shape options If you chose triangle or quad, you will encounter two main groups of buttons; single sided or double sided. Double sided means that the surface is visible from both sides. Although this makes the entering of the shape slightly fas- ter, it slows down calculation and drawing of the shape by the renderer, so it should only be used if both sides can be seen. Single sided shapes can only be viewed from one side. When entering a single sided shape, the points should be entered so that when looking from the direction you wish the shape to be visible from, the points go in a clockwise direction. If you get this wrong, the shape will only be visible from the other side. However, this can be remedied using the flip normal function in the edit menu. Choosing a sphere, however, only gives you one set of options, since spheres are automatically visible from all directions. The options for a shape not only define which direction it is visible from, but also what it will look like. Choos- ing outline will make the shape be drawn in outline only, with any shapes behind being visible through its body. Choosing solid will make the shape a solid region of colour. Finally, choosing both will make the shape be drawn in solid colour with an outline, too (preferably, the user will define the two colours to be different!). After choosing which type of shape you want, the editor will throw you into the windows to enter the points consti- tuting the shape. June 1, 1993 - 5 - 3.2.2 Entering a point When entering a point, the mouse pointer disappears, to be replaced by three red crosshairs, one in each projection window, the menu is replaced by some information about what you are doing and the keys which will have an effect, and finally, the orientation bars disappear to be replaced by three co-ordinate counters which tell you where in space the crosshairs are. Moving the mouse without the right button pressed will affect the position of the crosshairs directly in the front projection window, ie moving the mouse up will move the crosshairs in the front window up (and as a side effect, it will move the crosshairs in the end projection window up, too) and moving the mouse right will move the crosshairs in the front projection window right (and the crosshairs in the plan projection window right, too). Hold- ing the right mouse button while moving the mouse will directly affect the position of the crosshairs in the plan projection window (ie you have no control over the y posi- tion of the crosshairs). The speed of the crosshair movement on-screen is depen- dent on the magnification of the window, since for a given mouse movement, the crosshairs will move by a certain co- ordinate displacement, not pixel displacement. This means that the user can get perfect positioning at any magnifica- tion using the co-ordinate counter in the bottom right corner of the screen. Problems can arise in two ways using this graphical method of input. The first kind of problem occurs because a mouse isn't the easiest thing to use with perfect accuracy. For instance, if the user wants to put a point at [50,0,0], starting with the mouse at [0,0,0], then all that is needed is to move the mouse right until the x counter reads 50. This sounds very easy, but in practice it is all too easy to let the mouse drift upwards while moving across, and then to let it drift across while correcting the vertical drift, making the entering of a point take up to twice as long as it should. To counter this, the editor supports three lock-out keys, which each lock the co-ordinates on one of the axes. The three keys are control, left shift and alter- nate which lock the x, y and z co-ordinates, respectively. Now in our example, the user just needs to press and hold the left shift key and move the mouse right until the co- ordinates read [50,0,0]. The second type of problem occurs when the user needs to place a point at exactly the same place as another point. This should occur often, since most objects designed should be closed. Points positioned at the same place are detected by Polyfilm, and are only counted as one point, which both saves on memory, allowing larger objects, and speeds up pro- cessing time, since it is one less point to calculate. If June 1, 1993 - 6 - the object has not been designed on paper first, it is easy to forget where exactly each point is. The different window magnifications do not help solve this problem, since at the lower magnifications, many pixels are represented by just one pixel, so it is impossible to tell exactly which pixel the point the user wants occupies. Polyfilm overcomes this problem using two keys, which are active nearly all of the time during the entering of a point. These keys are S and K, which snap the crosshairs to the nearest predefined point. The difference between the keys is that K also enters the point as if the left mouse button had been pressed. If the keys are active, then it will say so in the right panel. Other keys which are active during the entering of a point are Z, which returns the crosshairs to [0,0,0] and centres the windows on that point, and C which simply cen- tres the windows on the crosshairs. Finally, pressing the escape key will quit from the entering of the point, losing any shapes which are partly defined. 3.2.3 Entering a shape; multiple points If a shape other than point is chosen from the add menu, then the user will need to define more than one point to enter the shape. When this is the case, after the input of a point, the editor will show an elasticated view of the shape so far, which changes as the user moves the crosshairs. As the user enters more points, the shape will be formed by the elastic lines, showing what the finished shape will look like in the image. Pressing the escape key during the entering of multiple points will lose all the points defined in the current elastic shape defined so far. There is a special case when entering a point which requires the use of more keys, and that is the entering of the last point on a quadrilateral. Since the finished qua- drilateral must be planar (ie two-dimensional), the last point cannot just be positioned anywhere, so Polyfilm will try to make the shape planar by projecting the point into a window until it forms a planar shape with the rest of the shape. Projecting into a window means that in the chosen window, the co-ordinates remain the same, but the point is moved along the axis which goes into the window until it is in the correct place. This means that the user can position the point in the correct place visibly in one window and then tell Polyfilm to find the correct place in the other windows. Although Polyfilm makes an informed choice as to which window to project into, it would be useful to know which window this would be, or more precisely, to be able to tell Polyfilm which window to project into. Six keys control June 1, 1993 - 7 - which window to project into, F, E and P project into front, end and plan windows respectively, but do not enter the point (like the S key), while 1, 2 and 3 project into the same windows, but enter the point (like the K key). Alter- natively, pressing the left mouse button tells Polyfilm to choose the best window to project into. A reminder of these keys is printed in the right panel when they become active. Another restraint on the last point of a quadrilateral is that it must make a convex shape when projected. A con- vex shape is one which doesn't turn back on itself, one which, when walking clockwise around the outside lines, only turns to the right from one line to the next. If the shape is not convex then Polyfilm will not allow the user to enter it. 3.2.4 Colour Choosing the colour option from the add menu brings up a low resolution screen which enables you to choose the colour of the next and subsequent shapes. Dominating the centre of the screen is a display of all the colours and patterns available for use. Clicking here with the left button will change the first colour, clicking with the right will change the second colour. The first and second colours are displayed just above the colours and patterns. It should be noted that the second colour can only be selected from the top row (the colours in the palette, not patterns or light source shadings (see below)). Finally, there are three but- tons on the periphery of the screen. Selecting the Done button will return to the editor with the current colour selection. Selecting the Choose palette button will enable the user to change the current palette via the palette selection screen (see later). Although the palette can be changed on this screen, this does not mean that an object can have more than one palette in it. In fact, the palettes have no effect on the object, they only select which set of sixteen colours is to be used in the rendering. The Select LSS button replaces the colour selection screen with the light source selection screen, which enables the user to define a shape's first colour to be an LSS (see the section on defining preferences, below). The light source selection screen has, in place of the colours and patterns, two of the possible thirty two light source shad- ings displayed. To display the rest, the UP and DOWN but- tons should be used. Only a shape's first colour can be an LSS. The difference between the first colour and second colour of a shape is simple. The first colour is the colour of the shape when it is drawn, be it outline or solid. The second colour is only used when the shape is both solid and June 1, 1993 - 8 - outlined, and it is used to draw the outline of the shape, after the first colour has been used to draw the solid. It is possible to define a line or point to be an LSS or a pattern in colour. In this case, the user should be aware that, in the case of a pattern, the colour directly above the pattern on-screen will be used, not the pattern, or, in the case of an LSS, it is the LSS number minus one in modulo 16 which is used for the colour number. Defining lines and points to be LSS's or patterns is only used in conjunction with the rotation function (see below) to allow easy definition of patterned or light source shaded surfaces of revolution. 3.2.5 Surface detail Surface detail can be used to enhance the final appearance of an object, and also to overcome certain shortcomings in the rendering routines. A piece of surface detail is a shape which is inscribed on the surface of another shape, and which, therefore, is visible only when the parent sur- face (the surface which it rests on) is visible. From the definition above, it can be seen that surface detail must be two-dimensional, and it must also rest on a planar shape. Thus this prohibits points, lines and spheres from being parent surfaces, and it also prohibits spheres as a form of surface detail. To add a piece of surface detail, click on the Detail button in the add menu (or press D). You are now presented with a menu which enables you to select which surface to put the detail on. To cycle through the applicable surfaces, use the buttons marked Next, Previous, Forward 10 and Back 10. The surface which is currently selected will be highlighted in green. To select the surface to add detail to, simply click on the Select button. To return to the add menu, select the Cancel button. Once you have selected the surface you want to put the detail on, the menu will change to a list of valid shape types, similar to the add menu, except with sphere and detail missing. This menu functions in exactly the same way as the add menu, as do the shape type sub-menus. One small difference is that surface detail cannot be single or double sided by choice, it inherits its sidedness from its parent shape. When defining the points constituting a piece of sur- face detail, it should be noticed that the usual add point keys and functions do not work. Instead, since the detail actually needs to be on the surface, each point defined is snapped to the parent shape's plane. To see how to do this, June 1, 1993 - 9 - refer to section 3.2.3, Entering a shape; multiple points, above. 3.3 Editing and deleting a shape If an error is made during the entering of a shape, then it is useful to be able to either edit the shape or delete it. This is done by the second and third items in the main menu, respectively. Choosing either one brings up a sub-menu with three buttons which enable you to choose to edit/delete either a normal shape (polygon) or a piece of surface detail, or to go back to the main menu. Choosing either polygon or detail then brings up a further sub-menu which allows the user to choose which shape/detail to edit/delete. This functions in exactly the same way as the sub-menu described in the addition on surface detail, above, except that when choosing a piece of detail to edit, the currently selected detail is highlighted in red. Choosing select from this menu has a different effect depending on whether you chose edit or delete from the main menu. If you chose delete, an alert box will appear, asking whether or not the user is sure about deleting the shape. Clicking on OK will proceed with the delete, while clicking on ABORT stops the deletion. Both buttons return the user to the surface selection menu. If the user chose edit, however, a further sub-menu is produced, allowing three different editing functions. If a function is unavailable on the current shape, then there will not be a box around it, and the user will be unable to select that function. The first of the three functions allows the shape's colour to be altered. This function is always available. The next of the three functions allows the changing of the type of shape (in this context, type of shape refers to either outline, solid, both, single sided or double sided, not triangle, quad etc). This function is only available for editing triangles, quadrilaterals and spheres. Finally, a single sided, planar shape's normal can be flipped, allowing it to be viewed from the other side. 3.4 The extra sub-menu The fourth option on the main menu, Extra, brings up a further menu of useful functions. These are; Paste, Rota- tion, Orientation, View and Info. Choosing info brings up an alert box which informs you how many points, normals, surfaces and surface details are used by the current object. June 1, 1993 - 10 - 3.4.1 Paste The Paste option allows the user to add objects together to form larger objects. This is particularly useful when cou- pled with the rotation function (see below), since the rota- tion function will only rotate about [0,0,0] using the whole object. So, for example, the rotation function could be used to create a wheel, which could then be pasted onto another bank four times to create the four wheels of a car or truck (see below for an explanation of banks). When paste is selected, the extra sub-menu is replaced with a bank selection menu, with which you choose which bank to paste the current bank onto. Clicking on a bank button will display the current contents of that bank, and clicking on select will choose the currently displayed bank to paste onto. Clicking on cancel will abort the paste operation and leave all banks unchanged. The bank which is the source for the paste is the one which was displayed when the paste option was selected. After selection of which bank to paste onto, you must then position the object to be pasted inside the current object's space. This is done in exactly the same way as adding a point, above. Every time the mouse is moved, the whole object and paste object must be redrawn in the win- dows. This means that when you are pasting a complex object onto a complex object, things can slow down alot. To get around this, Polyfilm supports two extra keys during the pasting of an object. The f2 key will stop Polyfilm drawing the paste object, leaving just the red crosshairs to mark the position of the cursor; this speeds things up, and it is recommended that you do this to position your object in roughly the right place before using f1 to redisplay the paste object for fine positioning. Pressing the left mouse button will paste the object into the current bank at the current co-ordinates. Alternatively, pressing the escape key will abort the operation. 3.4.2 Orientation The orientation function is used to rotate the current shape if, for instance, you suddenly find out that you've entered the object the wrong way around. When the orientation but- ton is pressed, the object is rotated to the same Euler angles as the three dimensional projection window and then displayed in its rotated form. Choosing Keep from the new menu will keep the rotated shape, whereas choosing Cancel will return the shape to its original form. June 1, 1993 - 11 - 3.4.3 Rotation The rotation function is the editor's most powerful func- tion. The power of it is reflected in the number of parame- ters the user must set before there is any effect on the object. Rotation of objects is restricted to objects con- taining only points and lines. Upon rotation, points become lines, and lines become quadrilaterals, since new points created are automatically joined to the points they were rotated from. When the rotate function is first selected, the user must decide which window Polyfilm is to rotate the current shape in, or, if it is preferred, which axis to rotate the shape about. Rotation in a window will rotate the shape around [0,0] in the given window, whereas rotation about an axis will rotate the shape around a line, for example around z=0 is a rotation around the z-axis. This is exactly the same as a rotation in the front projection window. The next thing that must be selected is the angle through which the object is to be rotated. This can be one of seven predefined values; 30, 45, 60, 90, 180, 270 or 360 degrees. After this selection, the user must enter the number of steps in the rotation; ie how many different shapes are to be created for each shape already declared. To do this, press backspace until the number displayed reads zero, and then type your new number, followed by the return key. Choosing Cancel here will abort the rotation. The constraints on the number of steps are that it must be between three and sixty steps, inclusive (this is reiterated on-screen), and that it must divide the total rotation angle multiplied by sixteen exactly, ie there must be no remainder. If these constraints are not met then the rota- tion will not proceed. The final thing that needs selecting is the type of quadrilateral or triangle that lines will become. This selection is exactly the same as that given in Further shape options, above. It should be noted that if you are using lines changing into single sided shapes, then all lines defined in you image should be defined in a clockwise direc- tion in the right hand half of the window at 90o to the one that you'll be rotating in, and in an anticlockwise direc- tion in the left hand half... in short, define all lines in the right half of a window for a rotation. As an example of rotation, put a single point at [0,50,0] (ie 50 pixels up in the front window) with the default colour (this should be light source shading number 1) in an empty bank (see below for how to change banks). Now choose to rotate the image in the front window by 180 degrees in 12 steps. Since the Polyfilm editor is a bit silly, it'll ask what lines should be made into, but there June 1, 1993 - 12 - are no lines, so just click on anything. After a very short delay (less than a quarter of a second), the windows should be redrawn with a semicircle in the front view and a line in each of the other two projection windows. The reason we only rotated the point by 180 degrees is that if we had done the full 360 degrees then the left hand half of the front view would be going clockwise, producing a sphere which would have only half of its outer edge looking outwards when single sided is chosen later. The final thing to do in our example is to perform another rotation, this time about the plan view, by 360 degrees in 24 steps, with lines turning into single sided solid type shapes. After entering all that, the editor should go to sleep for a short while (less than 5 seconds for such a small rotation), with the legend Working displayed in the menu area. When the windows are redrawn, they will contain a full sphere, ready to be light source shaded (this light source shading is the reason we did not simply use the in-built sphere shape type). To view your creation in all its glory, see the instructions on viewing an object, below. 3.4.4 View Clicking on the view object button from the extra menu will bring up a new menu containing the view options available to the user. Most of these new buttons control the rotational movement of the object. All view modes take the current orientation of the three dimensional projection window to be the starting orientation of the object. Stationary simply draws the object and waits for a keypress. This is useful for checking an object from an exact angle. The next three buttons rotate the object around each of the three principle axes. The Alpha button is the same as the first angle specified by the first orien- tation bar, Beta is the same as the second orientation bar, and Gamma is the same as the third orientation bar. While viewing in this mode, the plus and minus keys on the keypad affect rotation speed (which can be either positive or nega- tive), and the S key stops the rotation. Finally, pressing the escape key will exit the rotation and return the user to the view sub-menu. The final button which views the object is the Free move button. In this mode, all three angular velocities can be altered, resulting in impressive, somewhat chaotic, rota- tion patterns. The keys which affect the angular velocities are; Q, W and E to speed up the rotation about the alpha, beta and gamma angles, respectively, Z, X and C to slow down the rotation, and A, S and D to stop each of the three rota- tions. Finally, F will stop the whole rotation, and the escape key will leave the view mode. June 1, 1993 - 13 - The last option on the menu (apart from the cancel but- ton), is the palette button. This allows you to change which palette to use for the low resolution mode viewings. See the section on preferences for how to select a palette. 3.5 Banks One powerful feature of Polyfilm is its ability to create more than one object at a time by its use of banks. A bank is simply a place in memory which can hold an object. Poly- film supports five independent banks, each of which can be edited, viewed, deleted, copied, pasted, etc. To be able to perform certain bank operations, it is necessary to be in the banks sub-menu. Access to this is gained by clicking on the Bank button from the main menu. Changing bank can be achieved with the use of the first five buttons, or by pressing one of the first five function keys (these keys are indicated on the bank buttons). Chang- ing banks with the function keys works on nearly every menu, whether indicated or not. The exception to this is when deciding whether or not to keep an object which has just had its orientation changed (see orientation, above). When the bank has been changed, the windows will be cleared and the new bank drawn in, and then all subsequent operations will be applied to the new bank. Deletion of a bank is performed using the Delete but- ton. Pressing this button will cause the current bank to be deleted, except if the bank has changed since it was last saved. In this case, an alert box appears asking whether or not to proceed with the deletion. If the user clicks on the OK button, then the deletion will proceed. Finally, a bank can be copied onto another bank (this obviously results in the loss of the target bank) via the Copy button. Whichever bank is active when the copy button is selected will become the source bank, that is, the bank which is to be copied. The user must then choose the desti- nation bank, in exactly the same way as for the paste opera- tion (see above). When this has been done, the source bank will be copied over the target bank. If the target bank has changed since it was last saved, then an alert box will appear asking for confirmation before the copy operation takes place. 3.6 Loading and saving an object Loading and saving objects are essential functions, since it isn't possible to send files from the editor directly to the interpreter, and it is desirable to be able to save your work, anyway. The Load and Save buttons work in much the June 1, 1993 - 14 - same way, each one calling up the fileselector for the user to choose which file to load/save. If either of these func- tions have been used on the bank before, and the bank has not been deleted since, then the default fileselector choice is the same as the filename last used by the bank. To select the same filename, just press return, or click on the OK button. After filename selection, the load/save opera- tion will then take place. If the user selects the load option on a bank which has changed since it was last saved, then an alert box appears asking for confirmation of the load. Loading will only proceed if confirmation is given. 3.7 Preferences The preferences section of the Polyfilm editor allows the user to set all of the patterns, palettes and light source shadings used in the rendering process. Each of the previ- ously mentioned categories can be selected via the button with the same name from the preferences menu. Complete preferences files can also be saved and loaded from here. It should be noted that a preferences file consists of five palettes, thirty two light source shadings and forty eight patterns, and that only one preferences file can be loaded into the editor at any one time. 3.7.1 Editing the palette When the palette option is chosen from the preferences menu, the screen will change to one containing four buttons, three colour bars and a bank of sixteen colours. The buttons allow the user to change which palette is being edited, to save or load a single palette, or to exit the palette edi- tor. The changing of the palette is done via the palette selection screen as defined above. Clicking on one of the colours in the bank of sixteen colours will make that colour the current colour and move its RGB values into the bars. Clicking on one of the arrows above or below a bar will change the corresponding value by one either up or down (depending on which arrow was pressed). Actually clicking inside the bar will move the corresponding slider to the value clicked on. As the colour values change, so does the colour selected in the bank, and the colour of the sliders on the bars. The current colour components displayed in the bars are written below them, along with which colour the bar represents, either red, green or blue. 3.7.2 Editing the patterns The pattern editing screen consists of two large windows in June 1, 1993 - 15 - the upper left portion of the screen, the larger of which displays a magnification of the pattern, the smaller displays a magnification of the pattern mask, a bank of six- teen colours in the top right of the screen, below which are five buttons. To the left of the buttons, under the smaller window are four small images. The upper two contain the regular size versions of the pattern and mask, the lower two contain the colours which the left and right mouse buttons lay down, respectively. Finally, at the bottom of the screen is a bank containing all 48 patterns. To change a pattern, the user must press the left or right buttons in either of the two large windows. Pressing them in the leftmost of the two windows lays down a pixel of the appropriate colour, and changes the mask and both of the regular sized views of the pattern. Clicking in the mask window will alter the mask, either laying down a piece of white or a piece of black, depending on which button was pressed. The significance of the mask colours is simple to understand; if a part of the mask is white, then whatever if behind the pattern is seen behind the shape, but black prohibits vision through the pattern. Some strange effects can be achieved by altering the mask so that pieces of the background are visible through a part of the pattern which contains colour. In short, the mask should not be altered unless you know what you are doing, or are experimenting. To change which colour each button lays down, simply click the button whose colour you want to change over the colour you want to change it to, and it changes. A pattern is not included in the bank of patterns until it is put there by the user. This is done by clicking the right button over the space that you want it to occupy. The pattern will then be placed in that position, completely erasing the previous occupant. Similarly, to retrieve a pattern for editing, press the left button on the desired pattern. The final thing to describe is the function of the but- tons beneath the colour bank. Most of these are self- explanatory; clear clears the current pattern, load and save cover disk operations (although they only work on the pat- tern being edited, not the whole bank), and exit exits the pattern editor. However, the stipple operation is a useful and interesting button. Clicking on this button will turn the pattern being edited into a checkerboard pattern using the left and right button colours as the black and white squares. In this way, effective mid-way colours can be easily made to increase the effectiveness of a light source shading. June 1, 1993 - 16 - 3.7.3 Editing the lightsource shadings Before describing how to edit the LSS's, it is perhaps a good idea to say exactly what an LSS is. In short, an LSS is a list of the series of colours that a shape will go through as its angle to the lightsource increases. When a shape which is defined to be a lightsource shading is to be printed, then its angle to the lightsource is found, and then this (along with the backlit flag) is used to determine where in the list the correct colour for the surface is. The backlit flag determines whether or not the list will be consulted when the lightsource is on the other side of the shape. If the LSS is defined to not be backlit then the reverse side colour is used when the lightsource is behind the shape, if the backlit flag is set then the posi- tion in the LSS is calculated differently, taking into account the back of the object. The LSS editing screen consists of three main rows of icons and buttons. The top row contains a list of all the colours and patterns. The middle row contains a representa- tion of the current LSS, and the bottom row holds eight but- tons. Examining the middle row, you will see that there is an arrow above the first square in the LSS definition. This arrow shows where a colour will be placed if one is selected. The middle row itself consists of two rows of sixteen icons, slightly displaced to the left of centre, and one icon on its own on the right of the screen. The two rows of sixteen icons represent the list of colours, the order going along the top row, then down to the next row as you would when reading. If one of theses icons is a cross, then that colour is not used, since a lightsource has the number of colours it uses defined. The icon on its own represents the back colour of the shape, and only comes into effect when the backlit button reads No. Clicking with the left button anywhere on the middle row will move the arrow over the corresponding icon. Clicking with the right button on an icon will delete the icon, moving the rest up to fill the gap. Clicking in the top row with the left button will put the colour or pattern clicked on into the space in the LSS pointed to by the arrow. Clicking with the right, however, will insert the colour into the LSS at the arrow's position, moving colours further down the LSS to make room. The buttons in the left hand half of the bottom row control which lightsource is being edited, the number of colours it contains and whether or not it is backlit. Clicking on one of these buttons with the left button will decrease the corresponding value, the right increasing it. June 1, 1993 - 17 - The exception is the backlit button, which toggles when clicked on. The right hand half of the bottom row contains buttons which are self explanatory, allowing changing of palette, saving and loading of the current LSS, clearing of the current LSS and exiting back to the preferences menu. 4. The Polyfilm Motion Control Language In order to create a film, it is necessary to be able to tell Polyfilm what each entity, be it a camera, object or lightsource, has to do during each and every frame. This is achieved using the Polyfilm Motion Control Language, which is a programming language unique to Polyfilm designed espe- cially to allow easy manipulation of objects in three dimen- sional space. Programs are written in this language (hereafter referred to as MCL) using a text editor (unfor- tunately, a text editor was beyond the scope of this pro- ject), and then saved to disk as a text file with the exten- sion .MCL. This file will contain commands defining each entity in the film, its initial position and attitude, and its motions during the film. The language was designed to be as much like C as pos- sible for a language of this type. This means that the language is not interpreted like a standard BASIC, which is interpreted dependent on line numbers. Instead the inter- preter goes through the program from line to line down the file. It should also be noted that there is no GOTO state- ment. If you are unfamiliar with this type of language, then you are referred to any good C text book. 4.1 Interpreting Modes The interpreter itself has three modes, and it is vital that the user understands the use of each mode and its limits on commands. The first mode, called mode 0 in the following documentation, is the first pass mode. It is in this mode that the interpreter first looks through the program, find- ing out which objects, cameras etc have been declared, and initialising them. In this mode, the interpreter also finds each entity's main function (the point where an entity's program running is to start from) and loads any object types (three dimensional shapes defined using the editor) and preferences set by the program. Finally, any commands out- side of any functions are done as the interpreter encounters them. After the first pass has been completed, the data structures which have been created are checked for complete- ness; every entity must have a main function and every June 1, 1993 - 18 - object must have a type. If the first pass is completed successfully and the entities created are correct, the interpreter enters mode 1 and the film proper is begun. In mode 1, the interpreter goes through each entity's program, entity by entity, until either an endsim command is encountered, a wait condition fails or a frame command is found. Upon the first of these events, the film is ended, but the other two events tell the interpreter that this entity's program has finished for this frame, and then the interpreter starts on the next entity's program. Mode 2, the last mode, is the mode in which the inter- preter processes any keypresses for which commands have been defined (this, too, is determined in mode 0). Mode 2 is entered every frame, before processing of entities' programs has begun. In each mode, there are limits on which commands are allowed, and also the mode they must take. A complete list of commands, and which modes they are allowed in is given later. In mode 0, all objects, cameras and lightsources which are to be used in the film must be defined, along with all types of objects, all entity main functions, any functions which are to be used in the film and all simkey programs. Entities may only be defined in mode 0. This is enforced by simply not allowing the definition commands in any other mode. In addition to these constraints, no function calls of any type are allowed, any commands given in this mode must be object-referenced (see command list, below) and any variables accessed must be object referenced (see variables, below). Similarly, in mode 2, all variables and commands must be object-referenced and no function calls are allowed. However, in mode 1, object-referencing is optional, and function calls are allowed. The only restriction on mode 1 is that object definition commands are not allowed. 4.2 Expressions An expression is merely a series of variables, numbers and operators which evaluates to a certain value. Usually, expressions are enclosed in square brackets, [], since whi- tespace and round brackets, (), can be used within the expression itself. However, in many cases, when co- ordinates and Euler angles are being defined, three expres- sions are gathered together, limited with square brackets, but separated by commas; eg [16,32,48]. Unfortunately, the interpreter's expression evaluater June 1, 1993 - 19 - does not work as expected by the newcomer to Polyfilm. Instead of working the expression out from the left, taking certain operators over others, Polyfilm works out expres- sions from the right, giving all operators equal priority, so, for instance, 5 * 8 + 4 evaluates to 60 in Polyfilm, not to 44 as expected. To counter this, brackets should be used, so ( 5 * 8 ) + 4 should be used instead to achieve the required result. Polyfilm supports many operators, most of which are self explanatory, for instance, the function of *, /, +, -, <, >, <=, >=, ( and ) should be obvious. ! is used to logi- cally negate the following value, & is used for a logical and, and | is used for the logical or. The MCL logical values are quite simple; anything over 0 gets thought of as 1, or true, and anything less than or equal to 0 is thought of as 0, or false. It should be noted that although != could be used for an inequality check, <> is quicker, since it is already programmed as a check, whereas != is the con- catanation of two operators. 4.3 Variables and identifiers Variables (or identifiers) are strings of up to 32 charac- ters which represent either a value, entity, function or object type. An identifier's type is defined by the way in which it is declared. For example, when an identifier is declared in a type command, then the identifier is of type type, but if it is defined in an object command, it is of type object. However, if it is defined on the left hand side of an arithmetic equation, it is a variable, whose parent object is either given by the variable prefix (eg st.arc, is a variable called arc, belonging to the object st) or, if no prefix is given, its parent object is the object which is currently being interpreted (obviously, this only applies in mode 1). To access a variable, simply include its name in an expression, for instance the expression [arc*16] returns the value of arc multiplied by 16 as its answer. The value of the variable arc is taken from the currently active object. If this is not the desired case of the variable, simply object-reference the name by putting the object whose vari- able you want to access as a prefix to the variable name, for instance, [st.arc*16] will use the object st's variable arc, even if st is not the current object. It should be noted that each entity has its own vari- able space, and that any variables defined by one object can be defined by another, with no confusion, since they are totally independent. In order to define a variable, simply use it as the left hand side of an equation, as in most languages, for example June 1, 1993 - 20 - centre_x = x - 800; would define a variable called centre_x for the current object and give it the value x - 800. It is perfectly pos- sible to define a variable for a different object. This would be achieved by prefixing centre_x with the desired object's name, as stated above. Each entity has twelve reserved variables. These are given to allow easy access to the current position, atti- tude, speed and angular velocity of the entity. The reserved variables are called; x, y, z, xs, ys, zs, a, b, c, as, bs and cs. These represent the x, y and z position of the object, the x, y and z velocity components of the object, the alpha, beta and gamma Euler angles of the object and the three angular velocities, respectively. Reserved variables may be accessed and set at any time, but remember that changing them is like doing a move command or a rotate command. 4.4 Main functions As stated above, every entity must have a main function, since this is where processing of the entity's program begins. The syntax for defining a main function is simple; first the object's name is given followed by .main[] (with no space), and finally the actual function itself, enclosed within {}. For example, a simple main function would be; st.main[] { rotate speed [16,0,0]; wait; } This main function is defined for an object called st, which must have been previously declared. If it has not been declared when the interpreter comes across this main function, then an error is given. It is important to real- ise that when an object has finished executing its main function (provided it hasn't called it; see below) then exe- cution will restart from the beginning of the main function. If an object finishes executing a called main function, then control returns to just after the point where the function was called, exactly as for a normal function call. Main functions can also be called, just like normal functions (see below). In order to do this, simply use the following command; st.main[]; June 1, 1993 - 21 - The above line would make the current object call the main function of object st. When used in this way, the main function must be object-referenced to avoid an error, even if an object is calling its own main function. 4.5 Functions and function calls As in most C type languages, PMCL supports function calls. However, function usage is different to normal C use. Unlike C, during a function, all of an object's variables are still accessible; there is no notion of local and global variables. This means that parameter passing is more or less pointless. However, PMCL allows functions to have one parameter passed to them. Only one parameter may be passed (although this is optional), and this must be defined at definition. When the function is called, the value given will be loaded into the variable named in the function header. To define a function, simply include the function's name in a line in the root program (ie not inside any entity's program). The function name should be followed by the parameter name, if any, enclosed in square brackets, followed by the function body enclosed in {}. If the func- tion has no parameters, the square brackets must still be used. An example of a simple function follows; x_move [x_dest] { speed=10; if [x>x_dest]{ speed=speed*-1; } while [x<>x_dest] { move by [10,0,0]; frame; } } This function takes a single parameter, called x_dest. It should be simple to see that the function moves the entity along in the x direction until the destination point is reached. Functions like this can greatly improve program legibility and size, since a piece of code which is often repeated can be used as a function. To call a function, it a simply a matter of using its name as a command, with and parameter value needed enclosed in square brackets (again, the square brackets must be included even if there is no parameter). After the function has finished, interpretation continues from after the June 1, 1993 - 22 - function call as if the function call were a simple command. It should be noted that functions do not belong to any entity, and should not be object-referenced. 4.6 Simkeys Simkeys are defined by the simkey command, and, put simply, are blocks of code which are executed when the relevant key is pressed. A block of simkey code cannot contain function calls, frame or wait commands, and all commands and vari- ables must be object-referenced. For more information on defining a simkey block of code, see the command list, below. 4.7 Commands and keywords A command is a word which the interpreter recognises and which tells it to do a certain operation. A keyword, how- ever, is a word which elaborates on what the user wants the command to do. A keyword is usually followed by an expres- sion telling it how much to do something, for instance, how far to move. Often, a command will perform no function unless a keyword is given. A command may also have more than one keyword. In this case, the keywords are inter- preted sequentially. For some commands, it is possible to tell Polyfilm which object you want it to affect. This is stated where it is possible. To tell the command to work on an object other than the current object, put the object's name directly after the command. For instance, rotate st to [0,0,0]; will rotate the object called st to face in the direc- tion [0,0,0], no matter which object is the current object. Some commands are restricted in certain modes. For instance, it is impossible to declare an object in any mode but mode 0, the initial mode. There follows a complete list of all the commands, the keywords which are applicable to them, a description of their effects and an example of their use. 4.7.1 type The type command is used to load in a file containing an object definition. This file can then be referred to by the name given. The type command must be followed by two June 1, 1993 - 23 - parameters. The first is the name which the type is to be called, the second is the name of the file which is to be loaded. The filename should include the pathname, ideally starting with a drive name in usual ST fashion, but failing that, starting with a backslash, \, to indicate that the path starts in the root directory. The type command is res- tricted to mode 0. Example of use; type st "\data\st.3d"; 4.7.2 prefs The prefs command is used to load in a preferences file. It should be followed by the full filename of the preferences file to load, as for type. Prefs is restricted to mode 0 only. Example of use; prefs "\data\prefs_1.prf"; 4.7.3 object The object command is used to declare objects. Every object must have a type and a main function declared by the end of the initial pass. The type of an object can be declared with the keyword type. The word directly following an object command is taken to be the name the user wishes the object to be called. An object is not called into existence until it is declared by the object command, so any refer- ences made to the object must be done so only after it has been declared. The object command is only allowed in mode 0. The following keywords are applicable to the object command. type The type keyword must be followed by the name of the type which the user wants the object to be. This key- word must be included in the definition of an object to avoid an error. at The at keyword declares the starting position of the object. It must be followed by a co-ordinate triplet. If the at keyword is omitted, the object will be con- sidered to be positioned at [0,0,0]. looking June 1, 1993 - 24 - The keyword looking declares the starting attitude of the object. It must be followed by an attitude tri- plet. If the looking keyword is omitted, an attitude of [0,0,0] is assumed. hiddenThe hidden keyword declares the object to be hidden at the start of the film. It may be omitted. visible Visible declares the object to be visible. The default state of an object when declared is visible. Example of use; object obj_1 type st at [0,0,256] looking [0,0,180*16] visible; 4.7.4 camera The camera command is used to declare a camera. Every film must have at least one camera declared. The first camera to be declared is automatically thought of as the active camera unless the program is told otherwise. As for object, the camera must be followed by the camera's name, and every cam- era must have a main function. The use of camera is res- tricted to mode 0. The following keywords are applicable to the camera command. at The at keyword declares the starting position of the camera. It must be followed by a co-ordinate triplet. If the at keyword is omitted, the camera will be con- sidered to be positioned at [0,0,0]. looking The keyword looking declares the starting attitude of the camera. It must be followed by an attitude tri- plet. If the looking keyword is omitted, an attitude of [0,0,0] is assumed. activeThe active keyword tells the program that this is the camera which should be considered to be on. Example of use; camera cam_1 at [0,0,-256] looking [0,0,0] active; 4.7.5 lightsource The lightsource command is used to define a lightsource. June 1, 1993 - 25 - Directly following this command should be the name of the lightsource being defined. Lightsources may be of two types; parallel and point. Parallel lightsources give parallel rays of light, like from an far away lightsource. When declaring a parallel lightsource, an illumination vec- tor must be given. This vector represents the direction of the light. Parallel lightsources may not have their system variables altered and may not be moved using a move command. Point lightsources behave as any other entity. They give light off from their current location in every direction. This command is restricted to mode 0. The following keywords are applicable to the light- source command. at The at keyword declares the starting position of the lightsource. It must be followed by a co-ordinate tri- plet. It also defines the lightsource to be a point lightsource, and from this point on, no parallel light- source commands will work on it. vectorThe vector keyword declares the illumination vector of the lightsource. The desired vector must be declared after the keyword as a triplet. The magnitude of this vector does not matter, since it is made to equal unity when it is interpreted. It also defines the light- source to be a parallel lightsource. From this point on, move commands will not work on this entity, and its system variables will be inaccessible. lit The lit keyword tells the interpreter that this light- source should be the one being used. Example of use; lightsource lig_1 vector [1,0,0]; 4.7.6 palette The palette command tells the interpreter which palette to use. It must be followed by a number between 1 and 5 inclusive. It can be used in any mode. Example of use; palette 2; 4.7.7 simkey The simkey command defines a block of code which will be June 1, 1993 - 26 - executed upon a certain keypress. The key in question must be placed in quotes after the simkey command. Following the key comes the block of code to be executed, contained within {}. Within a simkey block of code there can be no function calls, and all variables and commands must be object- referenced. The simkey command itself is restricted to mode 0. The case of the key (upper or lower) does not matter. Example of use; simkey "a" { kick obj_1; kick obj_2; } 4.7.8 rotate The rotate command instructs the interpreter that a rotation is to be performed. This command can be object referenced and can be called from any mode. The following keywords are applicable to the rotate command. by The keyword by tells the interpreter that the following rotation is to be done relative to the current attitude of the object. The keyword must be followed by an attitude triplet. This triplet is then added to the current attitude of the entity. to This tells the interpreter to rotate the entity directly to the given angle. Following this keyword must be an attitude triplet. speedThis keyword sets the angular velocities of the given entity. The new values must be given in triplet form. Example of use; rotate st speed [80,0,0]; 4.7.9 move The move command instructs the interpreter that a movement is to be performed. This command can be object referenced and can be called from any mode. The following keywords are applicable to the move com- mand. June 1, 1993 - 27 - by The keyword by tells the interpreter that the following movement is to be done relative to the current position of the object. The keyword must be followed by a co- ordinate triplet. This triplet is then added to the current position of the entity. to This tells the interpreter to move the entity directly to the given position. Following this keyword must be a co-ordinate triplet. speedThis keyword sets the component velocities of the given entity. The new values must be given in triplet form. forward This tells the interpreter to move the given object forward by a given amount. The distance to move must be given in square brackets directly after the keyword, and must be one value, not a triplet. backward This tells the interpreter to move the given object backwards by a given amount. The distance to move must be given in square brackets directly after the keyword, and must be one value, not a triplet. forwardspeed This keyword sets the components velocities of the entity. Following this keyword must be a single value enclosed in square brackets. This value is then rotated to find the speeds to move the object to make it go forward by this amount. It should be noted that if the entity is rotated afterwards, the entity will no longer be moving forward, and this command must be done again. backwardspeed This keyword sets the components velocities of the entity. Following this keyword must be a single value enclosed in square brackets. This value is then rotated to find the speeds to move the object to make it go backwards by this amount. It should be noted that if the entity is rotated afterwards, the entity will no longer be moving backwards, and this command must be done again. Example of use; move to [0,0,256] forwardspeed [50]; 4.7.10 face This is similar to rotate, except that it tells the current June 1, 1993 - 28 - object to face a given direction. It may not be object- referenced, and therefore it is only available in mode 1. It must be followed by an attitude triplet. Example of use; face [0,0,0]; 4.7.11 endsim The endsim command ends the simulation when it is encoun- tered. It takes no parameters and may be used in any mode. Example of use; endsim; 4.7.12 frame The frame command tells an entity to finish its program for this frame. It can only be used in mode 1, and cannot be object-referenced. Example of use; frame; 4.7.13 wait The wait command is a powerful conditional command. It instructs the entity to wait, acting as if it had encoun- tered a frame command. It is followed by an optional expression which is enclosed in square brackets. If this expression is not present, then the entity waits for ever. However, if the expression is present, then the entity waits until the expression works out to be true (the wait condi- tions are checked at the beginning of every frame). This command is restricted to mode 1. Example of use; wait [x=5]; or wait; June 1, 1993 - 29 - 4.7.14 kick The kick command is the only command in Polyfilm which must be object-referenced. It instructs the named object to stop its wait at the start of the next frame, whether the condi- tion evaluates or not. It has no effect if the given object is not waiting. Example of use; kick obj_1; 4.7.15 show This command tells the given object to show itself, negating the effect of a hide command. This command may be object- referenced and used in any mode, however, the entity it is referenced to must be an object, not a camera or light- source. Example of use; show obj_1; 4.7.16 hide This command tells the given object to hide itself, negating the effect of a show command. This command may be object- referenced and used in any mode, however, the entity it is referenced to must be an object, not a camera or light- source. Example of use; hide obj_1; 4.7.17 activate The activate command tells the interpreter to change the camera in use to the given camera. This command may be object-referenced and used in any mode, however, the entity it is referenced to must be a camera, not an object or lightsource. Example of use; activate cam_1; June 1, 1993 - 30 - 4.7.18 light The light command tells the interpreter to change the light- source in use to the given lightsource. This command may be object-referenced and used in any mode, however, the entity it is referenced to must be a lightsource, not an object or camera. Example of use; light lig_1; 4.7.19 revector This command changes the vector of a parallel lightsource. It must be followed by the new vector. It may be object- referenced and used in any mode, but the object it is refer- enced to must be a parallel lightsource. Example of use; revector lig_1 [0,1,0]; 4.7.20 changetype This command allows the changing of an object's type. It may be object-referenced and so used in any mode, but it must be referenced to an object, not a camera or light- source. The command must be followed by the name of the new type for the object, preceeded by the keyword to. This key- word differs from others in that it is not optional. Example of use; changetype to sphere; 4.7.21 stop The stop command is rather special. Used on its own, it stops all movement and rotation for the given object. How- ever, keywords may be used to limit its effect to movement or rotation. The command may be object-referenced and used in any mode. The following keywords are applicable to the stop com- mand. movement June 1, 1993 - 31 - This limits the effect of the command to stopping the movement of the entity. rotation This limits the effect of the command to stopping the rotation of the entity. Example of use; stop st movement; 4.7.22 colour This command changes one of the colours in the palette. It must be followed by two values, separated by a comma and enclosed in square brackets. The first value is the colour index, and should be between 0 and 15 inclusive. The second value is the new RGB value. The value of this is derived from the decimal value expression. For instance, a value of 342 would give a red value of 3, a blue value of 4 and a green value of 2. This value should not exceed 777, and the separate digits should each not exceed 7. Also, this value should not be negative. The colour command may be used in any mode. Example of use; colour [15, new_colour*111]; 4.7.23 while The while command works exactly the same as the one in C and in most other languages. It is followed first by an expres- sion in square brackets, and then by a block of code enclosed in {}. If the expression evaluates to true, then the block of code is executed, if not it is skipped. When the end of the block of code is used, then the condition is tested again. If it is still false, then the block is repeated, else it is exited. This command is restricted to modes 1 and 2. Example of use; while [a<>180*16] { rotate by [16,0,0]; frame; } June 1, 1993 - 32 - 4.7.24 if and else The following two commands should be familiar to every pro- grammer of any degree of competence. The if command is fol- lowed by an expression in square brackets and a block of code in {}. If the expression in the brackets is true, then the block of code is executed once, else it is skipped. Following the block of code for the if statement, it is pos- sible to have an else command, followed by another block of code in {}. Then, if the if expression fails, this block of code is done once. If the if expression evaluated to true, then after the if code is done, the else code is skipped. Else is entirely optional. These commands are restricted to modes one and two. Example of use; if [a=180*16] { move forwardspeed [50]; } else { rotate to [180*16,0,0]; } 5 The Film Control Program and CFF viewer The film control program and CFF viewer enable the user to watch a film. The programs each operate from a form. The film control program form has three toggle buttons, three normal buttons and two filename buttons. The toggle buttons are labelled View frame build-up, Single-step and Make CFF. Clicking on these will change their settings. Single step forces the film to be viewed frame by frame, waiting for a mouse button to be pressed between each frame. View frame build-up makes the frame be drawn to the visible screen, rather than to an invisible one. This has the effect of letting the user see how the frame was constructed. Make CFF tells the computer to make the film that is about to be viewed into a CFF, whose filename is given in the CFF filename box. The filename buttons are green boxes which show the current filename in them. Initially, no filenames are shown in these boxes. To change the filename in the box, click on the box and choose the new filename from the fileselector. The three buttons at the bottom of the form allow the view CFF form to be entered, the film to be viewed (and hence a CFF made if the Make CFF button is enabled), and the film control program to be quit. When viewing a film, pressing escape ends the film and returns to the film control program form. June 1, 1993 - 33 - The view CFF form allows a CFF to be chosen via a filename box. When this is done, two values may be changed. These are the playback speed of the film and whether or not the film should be repeated. The playback speed is altered by clicking on it. Using the left button increases the speed (the lower the number, the higher the speed), and using the right decreases the speed. A speed of 0 is spe- cial; it makes the viewer wait for a keypress between frames. Finally, two buttons at the bottom of the form allow the quitting of the CFF viewer and the playing of the CFF. When viewing a CFF, pressing escape will quit and return the program to the CFF viewer. The function keys, f1-f10, alter the playback speed of the film during play. F1 corresponds to a speed of 0, and f10 to a speed of 9. June 1, 1993 - 34 - Appendix A Example MCL Program The following example program shows how an MCL program may be written. Line numbers have been added along the left hand side of each listing to aid explanation. If the list- ing is to be typed in, then the line numbers should be omit- ted. Simple Object Rotation 1 % Two flying saucers rotating on screen 2 % uses point light source 3 4 type saucer "\data\saucer.3d"; 5 6 prefs "\data\prefs.prf"; 7 palette 1; 8 9 object obj1 type saucer at [200,0,500]; 10 object obj2 type saucer at [-200,0,500]; 11 camera cam1; 12 lightsource lig1 at [0,0,250]; 13 14 obj1.main[]{ 15 rotate speed [16,24,32]; 16 wait; 17 } 18 obj2.main[]{ 19 rotate speed [-16,-24,-32]; 20 wait; 21 } 22 23 cam1.main[]{ wait; } 24 lig1.main[]{ wait; } The first two lines of the above program are comments and are ignored by the interpreter. Line 4 defines an object type called saucer and loads the object definition whose filename is given. Line 6 loads in the preferences file and line 7 defines which palette we want to use. Lines 9-12 declare all the entities which are to be used during the film. Lines 14, 18, 23 and 24 define the main functions of the entities. All of this information is extracted during mode 0. June 1, 1993 - 35 - In mode 1, each object's program is run until either a wait condition fails or a frame command is reached. This means that obj1 and obj2 both do their rotate commands, set- ting themselves rotating, and then hit the wait command, which makes them stop executing the program and wait for- ever. However, they will still rotate, since we set the rotation speed. cam1 and lig1 both immediately hit a wait command, forcing them to wait forever. The result of this film is two saucers revolving con- stantly. The only way the film will finish is if the user presses escape while viewing it. June 1, 1993