ObEd V1.02 - The Ultimate Object Editor for Demos and Simulators CREDITS Design Per Christian Odegard Programming Per Christian Odegard Graphics Per Christian Odegard Documentation Per Christian Odegard ReqToolsLibrary Nico François Per Christian Odegard works for Quark Grafix. Contacts: Snail mail: Per Christian Odegard Djupdalsfaret 7 N-2200 KONGSVINGER NORWAY Internet: perod@ifi.uio.no IRC: Viol8r, CoolHand or Quark --------------- --- GENERAL --- --------------- ABOUT OBED ObEd is a general purpose 3D model designer, programmed for the author's own use, but released as Public Domain software as a result of public request. The editor does only support 16 colour, simple, and relatively small objects, and is NOT intended to be used as an editor for use with ray tracing programs. The current limits are: Colours: 16 Points: 999 Surfaces: 999 Objects: 999 Coord. values: -9999 to +9999 These limits will probably change, as the author is planning an A1200 version of ObEd. However, he doesn't own one yet, so all offers are welcome :-) HISTORY The work on ObEd started when the author needed a tool for creating models for a flight simulator he was working on. Writing dc.w lines in the source code got a bit boring after the sqillionth line, so he decided that something had to be done. The actual coding started one hot summer afternoon in the year of 1992, and he has added new stuff when he had time for such pleasures, which wasn't very often, as he had to do his military duties this year. However, on his leaves, he sat up all night getting red-eyed programming new bits on ObEd. By Chistmas 1992 the program version 1.0 was finished. Still, the docs had to be written, and here it is - in January 1993 - ObEd V1.0. The author really hopes you enjoy this piece of Amiga software. DISCLAIMER The author is not responsible for any damage this piece of software may cause the user (or any other being or corporation). Use at own risk, in other words. LIBRARIES ObEd will only work on Amigas with Kickstart 2.04 ROMs. You'll also need these libraries: diskfont.library V37 dos.library V37.44 exec.library V37.132 gadtools.library V37 graphics.library V37.35 intuition.library V37.318 reqtools.library V37 REQUESTERS From time to time, you will be asked to verify your actions (a chance to chicken out), in other words, a requester will pop up on the screen, asking you a 'yes or no' question. Pressing Y, V or ENTER will activate the 'Yep' gadget, while N or B will activate the 'Nope' gadget. You may also use the mouse to select your reply. WARNINGS Sometimes, ObEd opens a window displaying a warning or a piece of information. Just press SPACE (or click on the gadget) to continue after you've read the message. RELEASES V1.01 - Late January 1993: - CloseWindow() bug fixed. This caused crashes on 'lesser' machines ;-) - Now uses topaz 8 everywhere, not the default font as in V1.00 - Minor bug fixed in Undo routine - Buffers now contain '---', not 000 as in V1.0 V1.02 - Early February 1993: - Unused now searches midpoint list too - Unused searches FROM current point. This enables the user to find all unused points before deleting any - More warnings and info messages added - Both PAL and NTSC versions available - Easier colour selection (see Using the mouse...) - SHIFT-K will swap front and back colour of a surface KNOWN BUGS The screen flickers somewhat on slower machines. This is because the blitter is unable to transfer 4 bitplanes in one frame. STRUCTURE --------- Points: Coorinates in 3-space consists of X, Y and Z values. The coordinates may be in the range -9999 to 9999. The maximum number of points is currently set to 999. Surfaces: Each surface consists of four points. In order to make a triangle, make the last two point numbers the same. For a line, make the last three point numbers the same etc. The colour of a surface is defined by four digits. The fourth digit is the surface's main colour, the third is its shade colour. The first and second digits work in the same way, only for the back side of the surface. Examples follow: 0003 - Surface colour is 3 040b - Front colour is $b and back col. is 4 0062 - Surface is shaded using cols 6 and 2 Note: A surface value of 0 makes it invisible (hidden). Each surface has a 'wireframe flag', which indicates whether the surface should be drawn in wireframe or filled mode. You may not have more than 999 surfaces. Objects: Several surfaces make up objects. You set the start- surface and the number of surfaces for every object. In order to sort the objects, a so-called 'midpoint' exists for each object. This point may be any point in the point list and may be manipulated in order to make the object look right. Take a look at the demo objects to see how this works. The upper limit for the number of objects is 999. Models: Models contain one or many objects. NOTE: In the following text, <type> will be used to indicate Point, Surface or Object, depending on which panel that is highlighted. THE DEFAULT COLOURS The colours 0 to 15 are used in the model, and may be changed any way you want them to. However, the colours 16 to 31 are special colours used in the panels and windows. If you wish to alter the look of these, used the table below. The colour table looks a bit confusing, because sprite colours and colours used for special effects must be stored at certain locations in the table. However, here it comes in all it so-called glory: Table entry Describtion Default colour 16 Panel data text Black 17 Menu colour 1 White 18 Main panel colour Grey 19 Panel selected Red 20 Bright edge White 21 Shadow edge Black 22 Headlines Black 23 Panel not selected Black 24 Number (#) text Blue 25 SPRITE COLOUR!!! Variable 26 Panel data text 2 White 27 Menu colour 2 Yellow 28 Menu colour 3 Red 29 SPRITE COLOUR!!! Variable 30 Menu colour 4 Green 31 Menu colour 5 Orange NOTE: The entries marked 'SPRITE COLOUR!!!' may not be changed. Of course course, you could always try, but the program will change them back at some time (when cycling sprite colours). THE SOURCE AND WHAT IT MEANS Consider the following example file of a cube with a line on top of it. Comments will not appear in the saved file. *** THE COMMON DATA SHARED BY ALL MODELS OF THE SAME TYPE *** DefOb: dc.w 009 ;number of points - 1 dc.w 001 ;number of objects - 1 dc.l PTX ;address of points dc.l XOAddr ;pointers to objs' 1st surf dc.l XOS ;pointer to list of ;objects' # of surfaces dc.l XOMid ;pointer to list of ;objects' midpoints *** THE MODEL STRUCTURE *** XO: dc.l DefOb ;pointer to common data dc.w 0 ;the following dc.s lines dc.l 0 ;work as data storage in dc.l 0 ;the author's filght sim dc.l 0 ;system, and may be removed dc.l 0 ;or used to whatever you dc.l 0 ;find useful dc.l 0 dc.w 0*16 ;X-, Y- and Z-rotation dc.w 0*16 ;of the model dc.w 0*16 PTX: dc.w 0100, 0100, 0100 ;the X, Y and Z values of dc.w -0100, 0100, 0100 ;the point dc.w -0100,-0100, 0100 dc.w 0100,-0100, 0100 dc.w 0100, 0100,-0100 dc.w -0100, 0100,-0100 dc.w -0100,-0100,-0100 dc.w 0100,-0100,-0100 dc.w 0000, 0100, 0000 dc.w 0000, 0500, 0000 XO000: Surf 000,003,002,001,$0006,0 ;the 1st, 2nd, 3rd and 4th Surf 004,005,006,007,$0002,0 ;point, the colour value, Surf 001,002,006,005,$0062,0 ;and the wireframe flag Surf 000,004,007,003,$002E,0 Surf 000,001,005,004,$000F,0 Surf 003,007,006,002,$000D,0 XO006: Surf 008,009,009,009,$0009,1 ;the line XOMid: dc.w 000*6,009*6 ;the midpoints of the objs XOAddr: dc.l XO000,XO006 ;the addresses of the first ;surfaces of the object XOS: dc.w 005,000 ;the number of surfaces of ;objects Surf is a macro defined like this: Surf: macro dc.w \1*6,\2*6,\3*6,\4*6,\5,\6 endm HOW THE BINARY FILE IS STORED This info may be useful if you want to write a program that converts ObEd files into files that other 3D programs can understand. Consider the same example model as above. The binary file will contain the following datas: (all values in hexadecimal) HEX VALUES COMMENTS ---------- -------- 4f 62 45 64 ;'ObEd'. ID text 0009 ;number of points - 1 0001 ;number of objects - 1 0006 ;number of surfaces - 1 0064 0064 0064 ;x,y,z values of the points ff9c 0064 0064 ff9c ff9c 0064 0064 ff9c 0064 0064 0064 ff9c ff9c 0064 ff9c ff9c ff9c ff9c 0064 ff9c ff9c 0000 0064 0000 0000 01f4 0000 0000 0012 000c 0006 0006 0000 ;surface points, colours and wf-mode 0018 001e 0024 002a 0002 0000 0006 000c 0024 001e 0062 0000 0000 0018 002a 0012 002e 0000 0000 0006 001e 0018 000f 0000 0012 002a 0024 000c 000d 0000 0030 0036 0036 0036 0009 0001 ;the line 0000 0036 ;midpoints (*6) 0000 0000 0000 0048 ;1st surface start (relative offset) 0005 0000 ;objects' number of surfaces ------------------------- --- THE CONTROL PANEL --- ------------------------- The 'current' point, surface and object is the topmost entry of respective panels. The selected panel has a highlighted title. THE POINTS PANEL This panel contains (left to right) the point number (#), the x-coordinate (X), the y-coordinate (Y), and the z-coordinate (Z). THE SURFACES PANEL This panel contains (left to right) the surface number (#), the first point of the surface (POINTS), the second, the third, the fourth, the colour code (COL), and finally the wireframe flag (WF). THE OBJECTS PANEL This panel contains (left to right) the first surface of the object (SU), the number of surfaces it contains in addition to the first (i.e. number of surfaces - 1) (#) and the midpoint of the object (MID). THE ROTation DATA The number of degrees the model is rotated about the X-, Y- and Z- axis (respectively) is displayed here. THE NUMber DATA The number of points, surfaces and objects (respectively) is displayed here. THE BUFfer DATA The buffered point, surface and object (respectively) is displayed here. THE DATa DATA The top row contains the WAS-flags' status (1=on). W=WireFrame Mode On, A=AllMode On, S=SpriteOff Mode On. The second and third row show which two points that are found to be equal. They contain '---' if none are found. THE OTHER DATA Below these datas you will find the model's current position in 3-space. At the very bottom, a colour reference list is displayed in all its colourfulness. --------------------- --- THE MAIN VIEW --- --------------------- MOVING AND ROTATING THE OBJECT You may move the object in 3-space using the keys described in the key overview file. Moving and rotating is useful for seeing how it looks from different ranges and angles. Speaking of angles, the entire object may be rotated using the numerical keypad. Note that Shifts speeds up these operations. EDITING THE OBJECT: Using edit windows -------------------------------------- EDITING THE POINTS In order to edit the points, use the cursor keys to scroll the point list until the point you want to modify tops the point panel. You may now press 'ESC' (of the point panel is highlighted) or 'F1'. A window will open, displaying the current values of the point. Pressing 'X' will allow you to change the values of the x-coordinate (Similar keypresses for the other coordinates). Press 'ENTER' if you're satisfied, or 'TAB' to cycle to the next coordinate. Press 'A' for accept if you're pleased with the new values, or 'R' for regret if you're not. ESCape also works as an 'ooops' key on all the edit windows. EDITING THE SURFACES Editing the surfaces works in the same way as with the points. Fill in the point values and colour code as explained above. You can also select whether the surface should be drawn in wireframe mode or not here. Note the hotkeys on this screen too. Press 'F2' at any time, or 'ESC' when the 'Surfaces' panel is hightlighted to enter this window. EDITING THE OBJECTS This works as with the two above, and hotkeys are available on this screen as well. Press 'F3' or 'ESC' when the 'Objects' panel is highlighted. EDITING THE MODEL: Using special keys -------------------------------------- EDITING THE POINTS The coordinate values may be changed using the keys surrounding the numerical keypad. Normal step value is 1, but using SHIFTed keys, a step value of 10 will be used. EDITING THE SURFACES Using the keys '4', '5', '6' and '7', you may insert the current point at position 1, 2, 3 and 4 respectively. Pressing '8' will change the surfaces's wireframe flag. EDITING THE OBJECTS You may change the number of surfaces in the current object by using the keys '>' (for more) and '<' (for less). Pressing '9' on the main keypad will use the current surface as the object's first surface. Using the current point as the object's 'midpoint' can be done by pressing '0' on the main keypad. FILE OPERATIONS --------------- DELETING ALL (NEW) Pressing 'O' will delete everything currently stored in the computer memory, and leave you with a blank model. Make sure you save your model before pressing this key. However, you can always get your old model back by pressing the UNDO key. This key is described elsewhere in this documentation. LOADING A MODEL Loading a model will delete all your previous work, so make sure you've saved it. A new model will be loaded, and it will appear at the same positions and using the same rotations as the previous ones. Press 'Amiga-L' to do this. LOADING A PALETTE You may load a previously saved palette (range of colours) by pressing 'Amiga-]'. SAVING A MODEL AS BINARY When you are plased with your work, save it by pressing 'Amiga-B'. This should be done frequently, and you should make backups of your work. SAVING A MODEL AS ASSEMBLY SOURCE This is the single most useful feature of the editor. The file created may be added to a demo or flight simulator for instant use. You'd just have to change the label names slightly. The source is in MC68000 assembly format, so don't try it in your C source ;) Press 'Amiga-T' to achieve this little miracle. SAVING A PALETTE If you've created a palette that pleases your eyes (or otherwise, as the case might be), simply press 'Amiga-[' to save it. If you save it as 'StdPalette', this file will be loaded at the beginning of the program, thus making it the default palette. IMPORTING A MODEL You may wish to import a previously done work into your current model. This routine makes your dreams come true. Very useful, and very easy to use. The imported data is added at the end of the lists. To execute, press 'Amiga-I'. GETTING VERSION NUMBER Clicking in the data panel area will display a little info about ObEd. QUITTING THE PROGRAM When you are pleased with your model (AND IT IS SAVED), you may quit ObEd by pressing the 'Amiga-ESC' key combination. ADDITIONAL EDIT OPERATIONS -------------------------- NEW <TYPE> Pressing 'N' will add a single <type> at the end of the <type> list. This will only contain zeros, and whould be edited before used in other <type>s. INSERTING You may insert a new point anywhere in the point list by pressing 'J'. Inserting surfaces in the surface list is a bit more complictated. The only place you may insert new surfaces, is before the first surface of any object. For example, if your model contains two objects (00 05 17 and 07 03 32) you may insert surfaces at positions 00 or 07. COPYING You may copy the contents of one <type> into another, by first BUFFERING the source <type>, then selecting the destination <type> and finally pressing 'C' to do the copying. EXCHANGING Exchanging the contents of two <type>s, works like this: BUFFER the first <type>, select the other <type> and press 'E' to exchange these two <type>s. DELETING Deleting <types> doesn't require much brainwork. Simply select the <type> you want to delete and press 'D'. If the <type> is used in another type (e.g. a point is used in a surface), you won't be able to delete it. If you press 'Amiga-1' you will delete the first point, surface, and object. This is particulary useful when a new object is CREATEd and you want to delete the dummy object, surface, and point (all containing 0 as default). MOVING Pressing the 'M' key, a window will open, asking you to input the X, Y, and Z movement. If <type> is a surface, it will move all the points in the surface, and if it is an object, it will move all the points contained by its surfaces. Note that if any of the points are used by other surfaces or objects, these will change as well, causing often unwanted results. ROTATING If you press 'R', you will be asked for rotation angle about the X-, Y-, and Z-axis, respectively. This angle must be in the range 0-359 degrees. Please note that different objects and surfaces may use the same points, and will thus change as well. Only objects and models may be rotated. If you wish to rotate a model, set the AllMode flag. CLONING Selecting a <type> and pressing 'Y', will clone this <type>, i.e. creating a new <type> looking exactly like the current one, and placing it at the end of the <type> list. BUFFERING Before you can use the COPY or EXCHANGE functions, you have to use this function. What it does, is to select the first <type> that will take part in the operation. For exapmle, if you were to exchange the points #2 and #9, you should select point #2, buffer it, select point #9 and execute EXCHANGE. As for COPY, the BUFFERed <type> is the source in the operation. Press 'SPACE' in order to buffer a <type>. UNDOING CHANGES With all the functions and operations available to the user of ObEd, you're bound to do a mistake sooner or later. Or maybe you just want to try out an idea to see how it looks, but want to be able to get the old model back. Help is literally at hand. Pressing the 'HELP' key will undo the very last changes on your model. VIEWING THE MODEL ----------------- Six preset views are available to the user. These are: View Key Top 'T' Underside 'U' Front 'F' Behind 'B' Left 'L' Right 'R' SPECIAL OPERATIONS ------------------ SUBSTITUTING (GLUING) If you dicovered that two of your points share the same coordinate values, you may want to remove one of them. This is done by first searching for equal points (as described above), and then pressing the 'G' key. Note that gluing when two equal points do not exist, is no good. FLIPPING A SURFACE Being able to flip a surface can be useful many a time. Exchanging the front and back colours of a surface can be done with this function, but the main reason for incorporating it is this: Say that you create a new surface, only to find that you inserted the points in anti-clockwise order, thus making it hidden at the wrong angles. One solution could be to edit the colour codes (exchange the first and last bytes), but a far cleaner approach would be to execute a flip. What this does, is simply to put the points in an anti- clockwise order (relative to the input order). Press 'K' for this handy function. CHANGING THE ORDER OF THE POINTS IN THE SURFACE Not satisfied with the order at which the points appear in the surface? Consider your problems solved! Just press 'V' and hey presto! It has changed! Do you need this function? Probably not. But life as a programmer sure isn't easy. Just imagine having to put a function on every key on a large, never-ending keyboard. Functions like this simply have to turn up once in a while. MIRRORING Any <type> can be 'mirrored', i.e. changing the sign of the specified coordinate(s) used by the <type>. Mirroring 'About X' will change the sign of the x-coordinates, while the Y- and Z- coordinated stay intact. Example: You are creating a model of a fighter aircraft, and have created the left wing. It would be a boring task to create the right wing from scratch, so what you do is simply to CLONE the wing, and then MIRROR it 'About X'. Note that 'About Z' is not a mathematically correct expression. 'About the XY-plane' would be far better, but I find 'About Z' more intuitive, in that you see which coordinate that will be changed without any harmful brainwork. Press 'F6', 'F7' and 'F8' for X-, Y- and Z-mirroring respectively. SCALING Say you want to create St. Paul's Cathedral. That would fill quite a few screens, wouldn't it? A 3D insect would also be nice to be able to create. But the Cathedral wouldn't be very surveyable at all, and the insect would be very hard to edit because of its less than impressing size. Problems. What problems? You just have to make the Cathedral small and the insect large and scale them up or down when you are pleased with their looks. Some frequently used scaling percentages are available on various F-keys (see key overview), and you can input any (within certain limits) percentage yourself by pressing 'Amiga-P'. CREATING MODELS Pressing the '~' key at the main keyboard will give you an option to create any of four 'predefined' models. You will be asked for a few parameters, and ObEd will create the models for you, complete with points, surfaces and objects. The objects available are: BOX You will be prompted for X-, Y- and Z-length from the centre of the box. Simple, clean fun. Adds: Box Rectangle Points 8 4 Surfaces 6 1 Objects 1 1 PYRAMID Enter X- and Y-length from the centre of the bottom surface as well as the height of the pyramid. Adds: Pyramid Triangle Points 5 3 Surfaces 5 1 Objects 1 1 PYRRAD A PyrRad object a pyramid where all the surfaces are identical as far as size is concerned. You siply have to enter the radius of the object, i.e. the length from its centre to its corners. Adds: PyrRad Points 4 Surfaces 4 Objects 1 CYLINDER This is one handy object. Entering the height, radius and step value, a cylinder will be created. The step value is the number of 'pie parts' the circle at the top and bottom will be divided into. 4 parts will result in a box, and 10 will result in something that may be mistaken for a cylinder. Adds: Cylinder Disc Points 2+2*STEPS 1+STEPS Surfaces 3*STEPS STEPS Objects 1 1 NOTE: STEPS is the step value as described above. MISC OPERATIONS --------------- FINDING POINT It is often useful to find the first surface to include the current point. Pressing '/' will put this surface at the top of the surface display (making it 'current'). Repeatedly pressing this key, will find all occurences of the point in the surface list. CHECKING FOR UNUSED POINTS It isn't too hard to imagine why unused points are unwanted in the point list. By pressing the '\' key, the first of these will become current. The search starts at the current point. FINDING EQUAL POINTS As the reader may understand, having stored two points with exactly the same coordinates, is highly undesirable. Pressing the '=' key, the two equal points (if any) will be stored in a special buffer, and their point numbers will be displayed at the screen. You may then use the GLUE command to delete one of the points without destroying the object. CHANGING THE PALETTE The author is the first to admit that the default colours make the expression 'tasteless' fit quite perfectly. Therefore, a little utility to change the palette is included. This works the same way as any other palette modifier the user may have experienced, so no detailed explantion should be needed. Your new palette may be saved for later use. The 'P' key opens the palette window. RESETTING THE PALETTE If your choise of colours wasn't a lucky one, simply press 'SHIFT-P' for getting the default colours instead. CHANGING SPRITE COLOUR Sometimes, seeing the sprites is difficult because they are displayed in the same (or similar) colour as the background image. This problem is easily avoided by changing the colour of the sprites. Use the '.' key on the numerical keyboard for this operation. ----------------- --- THE FLAGS --- ----------------- THE ALLMODE FLAG When this flag is set, some operations work on the enire model. These are: Scale, Move and Rotate. Press 'Amiga-M' to turn this flag on and off. THE SPITESOFF FLAG Setting this flag turns the sprites off. Press '0' on the numeric keypad to turn this flag on and off. THE WIREFRAME FLAG Setting this flag puts the editor in wireframe mode, i.e. everything will be displayed in wireframe. Press 'DEL' to turn this flag on and off. THE SPITENUMBER OFF FLAG If you set this flag, the spites will not display the pointnubmer, i.e. you will only see the crosshairs. 'BACKSPACE' will set or clear this flag. ------------------------------- --- USING THE MOUSE IN OBED --- ------------------------------- Using the mouse, you can select most of the operations that are available from the keyboard. For a menu overview, see below. Other mouse operations: * Clicking on the 'quit' icon will exit the program after a request * Clicking in the graphics window will select the point closest to the cursor * Clicking in the <type> panels will select <type> * Clicking in the data panel will display an 'About' window * Clicking on a colour will make it the surface's main colour * A SHIFTed click on a colour will make it the surface's 'shade' colour -------------------- --- THE MENU BAR --- -------------------- Remebering all the keys is something of a nightmare. Therefore, menus are available at the top of the screen to let you choose some of the most frequently used commands easily. The menu strip is divided into 5 parts: Menu Submenu Submenu Comment FILE New New model Load Load Object Load Palette Save Save Object Save Source Save Palette Import Import binary About Quit EDIT New New <type> Edit Edit <type> Insert Copy Exchange Delete Move Rotate Object or Model (AllMode on) Clone Buffer Undo Undo last changes VIEW Top Underside Front Behind Left Right Reset SPECIAL Glue Two equal points->one point Flip Turn surface upside-down Mirror About X About Y About Z Scale 0.50 0.66 0.75 0.90 1.10 1.25 1.50 2.00 Input Input scale percentage Create Create new object MISC Find Point Unused Find Equal WireFrame Flags AllMode Sprites Palette Edit Reset -------------------------------- -- THE UNAVOIDABLE GREETINGS --- -------------------------------- This is no fancy hardware-bashing euro demo. In fact, it's just a boring system-friendly utility. Still, where would the Amiga be today without the greetings that pop up on every single piece of software these days? So here's my little, no-scrolling list: (Appearing in alphabetical order) Dag Lem (_Hot_ in Spain, eh? Nudge, nudge) Lars Haugseth (The Gandalf of Amiga programming) Morten Amundsen (Gives the expression Party Animal a new meaning) Paal Johansen (Soon getting an A4000, you workaholic?) Stian W Arnesen (Deeply in love with the Amiga) Stig A Olsen (Intel inside, but still a cool dude) Svein A Johansen(Nothing beats his party moonwalkings) Tommy Rivrud (Get rid of that 'beard', eh?) And lots of greetings to everybody at the University of Oslo.