home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d7xx / d762 / plotmap.lha / PlotMap / Plotmap.doc < prev    next >
Text File  |  1992-11-21  |  16KB  |  480 lines
  1.  
  2.                                PlotMap V0.85
  3.                                *************
  4.  
  5.                       Documentation by Thies Wellpott
  6.                       (excuse my bad English, please)
  7.  
  8.  
  9. 1. Copyright
  10. ************
  11.  
  12. PlotMap is FreeWare (c) 1992 Thies Wellpott. You may copy it for free
  13. provided that
  14.         - no profit is made with it
  15.         - PlotMap is not included with commercial software without
  16.           written agreement from the owner of the copyright
  17.         - no file is missing (six map files, "PlotMap", "PlotMap.doc")
  18.         - PlotMap is distributed with this documentation file,
  19.           "PlotMap.doc" and both files are unmodified
  20.  
  21. The source code is for personal use only. It need not to be distributed
  22. along with the program, but if it is the whole source code must be kept
  23. with it.
  24.  
  25.  
  26. 1.1. Warrenty
  27. *************
  28.  
  29. YOU USE THIS PROGRAM COMPLETELY ON YOUR OWN RISK! If you destroy any file,
  30. your computer, your car or even the whole universe or any part of it while
  31. using it, do not blame me, it is not my fault!
  32.  
  33.  
  34. 2. Introduction
  35. ***************
  36.  
  37. Perhaps you know DrawMap by Bryan Brown. I got this nice program and used
  38. it a short while when I noticed that there is missing a lot and that it is
  39. ugly slow (sorry, Bryan). It needs over one minute to load the map files
  40. (not directly Bryan`s fault, fread() needs that long time), PlotMap needs
  41. just about 3 seconds (68000, ALF-2, Quantum-HD) !
  42. PlotMap uses exactly the same map files like DrawMap 4.0/4.1.
  43.  
  44. PlotMap has the following improvements towards DrawMap 4.0:
  45.  
  46.  - drawing speed up by a factor of round about 2 (see table below)
  47.  - runs on 512 KB Amigas (perhaps also on a 256 KB machine)
  48.  - runs with one floppy drive
  49.  - more edit commands
  50.  - zoom a box from a box
  51.  - definable screen mode (PAL/NTSC, number of colors, lace or not, etc.)
  52.  - OS 2.0 look
  53.  - more configurable
  54.  - WHOLE configuration saveable
  55.  - auto detail level
  56.  - abort function for drawing (ever accidentaly drawn a full map with highest
  57.    detail level?)
  58.  - some more I forgot
  59.  
  60. This version requires OS 2.04!
  61.  
  62. PlotMap only exists because Bryan included the source code with his
  63. distribution. Thanks a lot Bryan!! I used it as a kind of reference to
  64. learn the structure of the map files and the way the maps are displayed. I
  65. did not copy or even steal his source code but some parts may look similar
  66. because the basic idea of the drawing algorithms does not differ. So
  67. PlotMap is no copy of DrawMap with some improvements, it is a new program
  68. with similarities to DrawMap.
  69.  
  70. Here are some interesting information I collected through the development:
  71.  
  72. times (V0.50/V0.51) (all maps, flat map, Hires/Lace/PAL/16 colors):
  73. DrawMap4.0 (NTSC) needs (low) 14-15s and (medium) 59s.
  74.  
  75. detail level | algorithm    | normal | draw.c optimized (-O)
  76. -------------+--------------+--------+----------------------
  77. low          | FFP-math     | 19s    |  9s
  78.              | Lattice-math | 21-22s | 11s
  79.              | integer      | 17-18s |  7-8s
  80. -------------+--------------+--------+----------------------
  81. medium       | FFP-math     | 47s    | 36s
  82.              | Lattice-math | 61s    | 49s
  83.              | integer      | 39s    | 27-28s
  84.  
  85.  
  86. memory usage (OS 2.04, PAL display):
  87.  
  88. no map loaded, flood fill disabled, screen: Hires/Lace/16 colors,
  89. coord. window on (all display types)
  90. chip: 172720   other: 135344   total: 308064
  91.  
  92. some as above, but only 8 colors
  93. total: 264920
  94.  
  95. no map loaded, flood fill disabled, screen: Hires/NoLace/4 colors,
  96. no coord. window
  97. chip: 43504   other: 133976  total: 177480
  98.  
  99. all maps loaded, flood fill enabled, screen: Hires/Lace/16 colors/overscan,
  100. coord. window on (all display types)
  101. chip: 269816   other: 1164560   total: 1434376
  102.  
  103.  
  104. 3. Installation
  105. ***************
  106.  
  107. For the installation you need LhA by Stefan Boberg.
  108.  
  109. 3.1. On a harddisk
  110. ******************
  111.  
  112. You need at least 1.2 MB free space on your hard disk. The destination
  113. directory in this example is called "DH0:Utilities/PlotMap". You may give
  114. it a name of your choice.
  115.  
  116. Copy the files "PlotMap", "PlotMap.info", "PlotMap.doc",
  117. "PlotMap.doc.info" and "PlotMap.config" to your destination directory.
  118.  
  119. 1> Copy PlotMap(%|.info|.doc|.doc.info|.config) DH0:Utilities/PlotMap
  120.  
  121. Unarchive the archive "maps.lha" with the following line:
  122.  
  123. 1> LhA x -ab64 maps.lha DH0:Utilities/PlotMap/
  124.  
  125. If you want to have the source code then unarchive the archive "source.lha":
  126.  
  127. 1> LhA x -ab64 source.lha DH0:Utilities/PlotMap/source/
  128.  
  129.  
  130. 3.2. On a floppy based system
  131. *****************************
  132.  
  133. You need two empty, formatted disks. The first that will contain the
  134. program may have a name of your choice (I use "PM_1" in this example), the
  135. second MUST have the name "PM_DATA". You must boot from the Workbench or
  136. you must install all necessary files on disk 1 (libs, handler, etc.) and
  137. boot from it then.
  138.  
  139. 1> Format DRIVE df0: NAME PM_1 NOICONS
  140.  
  141. 1> Format DRIVE df0: NAME PM_DATA NOICONS
  142.  
  143. Copy the files "PlotMap", "PlotMap.info", "PlotMap.doc",
  144. "PlotMap.doc.info" and "PlotMap.config" to the first disk.
  145.  
  146. 1> Copy PlotMap(%|.info|.doc|.doc.info|.config) PM_1:
  147.  
  148. Execute the following lines:
  149.  
  150. 1> LhA x -ab64 maps.lha map.limits.bin coast.pnt island.pnt PM_1:
  151.  
  152. 1> LhA x -ab64 maps.lha country.pnt state.pnt river.pnt lake.pnt PM_DATA:
  153.  
  154.  
  155. 4. Getting started
  156. ******************
  157.  
  158. Start PlotMap either by double clicking its icon or by typing "PlotMap"
  159. in the Shell. If PM cannot load the configuration file "PlotMap.config" it
  160. will beep the screen. Afterwards the configuration window will pop up.
  161.  
  162.  
  163. 4.1. The configuration window
  164. *****************************
  165.  
  166. Here you may define the screen mode either my selecting/toggling the
  167. gadgets or by pressing the underlined keys (e. g. "h" for SuperHires). The
  168. screen size and the used memory are displayed below. Note: In SuperHires
  169. mode you can use a maximum of 4 colors (but you can select more, this will
  170. be fixed in later versions). Overscan toggles between text overscan
  171. (defined with Preferences) and maximum overscan (Intuition hard coded). The
  172. six gadgets below "Load map" define which maps should be loaded completely.
  173. The numbers behind the names show the memory used by each map. Maps which
  174. are not loaded completely will be loaded part by part when they are drawn.
  175. This slows down the drawing but saves memory (the only way for users with
  176. less then 1.5 MB of memory). The last checkbox is another memory saving
  177. option. If disabled you cannot use flood fill or fill oceans but you save
  178. one bitplane (40 KB with 640 x 512) of chip memory. "Save" saves the
  179. options and starts PM (you have the possibility to save them later, too)
  180. and "Use" starts PM.
  181.  
  182. You will find yourself on an empty screen with the defined resolution.
  183. The only way to control PM is via menus (and their shortcuts, of course).
  184.  
  185.  
  186. 4.2. The menus
  187. **************
  188.  
  189. The description of each menu follows (items with no description are not
  190. implemented yet):
  191.  
  192. 4.2.1. Project
  193. **************
  194.  
  195. ** Help
  196.  
  197. ** Save map
  198. Please use a screen grabber like GrabIFF, Snap, etc.
  199.  
  200. ** Save configuration
  201. Saves the configuration file to the current directory. The following things
  202. will be saved (items marked with a * are definable in the config window at
  203. startup):
  204.  
  205.  - * superhires yes/no
  206.  - * interlace yes/no
  207.  - * overscan yes/no
  208.  - * mode (PAL/NTSC)
  209.  - * number of bitplanes (number of colors)
  210.  - * which maps should be completely loaded
  211.  - * flood fill option yes/no
  212.  - default vert. factor
  213.  - status of "Cls before draw"
  214.  - status of "Coord. window", "Coord. mouse-X/Y", "Coord. degrees"
  215.  - position of the coord. window
  216.  - which maps should be plot
  217.  - current detail level
  218.  - color palette
  219.  - all definable colors (background, oceans, maps, grid, grid highlight,
  220.    shadow, line, box, text, flood fill)
  221.  
  222. ** Print map
  223. You may use GraphicDump for this (do not forget to switch off the title
  224. bar, via Amiga-t).
  225.  
  226. ** About
  227. Displays programm information.
  228.  
  229. ** Quit
  230. Cuts the power cable of your computer :-)
  231.  
  232.  
  233. 4.2.2. Preferences
  234. ******************
  235.  
  236. ** Vert. factor
  237. With this option you can adjust the plot to your screen. The current
  238. vfactor is displayed in this item-title. The subitem "Use default" sets the
  239. vfactor to that displayed in the subitem-title. With "Set" you can change
  240. the vfactor. A requester pops up where you can enter a number. The input is
  241. limited to four chars. "Cancel" cancelles the operation, nothing is
  242. changed, "Ok" accepts the entered value and "Use as default" sets the
  243. default vfactor to the enter value.
  244.  
  245. ** Cls before draw
  246. If enabled, the screen will be cleared before a map is drawn.
  247.  
  248. ** Coord. window
  249. If enabled, the coordinate window is displayed. You close the window by
  250. disabling this item or by clicking the close gadget of the coord. window.
  251. You may move the coord. window around, but it is impossible to activate it
  252. (I hope!) so do not try it (and waste hours with it).
  253.  
  254. ** Coord. mouse-X/Y
  255. Display the mouse coordinates in the coord. window.
  256.  
  257. ** Coord. degrees
  258. Display the lattitude and longitude in the coord. window.
  259.  
  260. ** Coastlines, Islands, Countries, States, Rivers, Lakes
  261. Specifies which maps should be drawn.
  262.  
  263. ** Detail level
  264. Specifies the detail level the maps are drawn with. "High" till "Low"
  265. directly specify one of the five levels. "Auto high" .. "Auto low"
  266. automatically selects a detail level depending on the size of the part
  267. currently displayed.
  268.  
  269.  
  270. 4.2.3. Colors
  271. *************
  272.  
  273. ** Palette
  274.  
  275. ** Background
  276. Specifies the background color of the map
  277.  
  278. ** Oceans
  279. Color of the oceans (for "Fill oceans")
  280.  
  281. ** Coastlines, Islands, Countries, States, Rivers, Lakes
  282. Color of each map.
  283.  
  284. ** Grid
  285. Color of the grid ("Grid")
  286.  
  287. ** Grid highlight
  288. Color of the longitude 0° and the lattitude 0° ("Grid")
  289.  
  290. ** Shadow
  291. Color of the shadow (not implemented yet)
  292.  
  293. ** Line, Box, Text, Flood fill
  294. Color for the edit commands. If you draw a line the line color will be
  295. used, difficult to understand?
  296.  
  297.  
  298. 4.2.4. Maps
  299. ***********
  300.  
  301. ** Plane
  302. "Flat" draws a flat map like DrawMap 4.0.
  303. "Mercator" draws the same map as DrawMap 4.0.
  304. The drawing is interruptable by pressing the right mouse button. It is
  305. possible that PM needs a bit to react on your mouse click so do not panic
  306. if the drawing does not interrupt immediately.
  307.  
  308. ** Box
  309. With "Select box1" you may specify a box of the currently displayed map to
  310. be drawn. A distortion is impossible because the height of the box is
  311. calculated from the width which you may specify.
  312. "Select box2" works like "Select box1" but you can specify the width and
  313. the height.
  314. If you select "Select box" the mouse pointer becomes a cross hair and the
  315. title bar displayes a short description what to do. Press and hold the left
  316. mouse button, the first point is set, move the mouse and a box appears
  317. that indicates which part of the map will be drawn. Release the left mouse
  318. button if you found your box; the map will be drawn. Press the right mouse
  319. button to abort this operation.
  320. "Zoom in" and "Zoom out" are not implemented yet.
  321.  
  322. ** Sphere
  323.  
  324. ** Redraw
  325. Redraws the current map with the selected colors and detail level.
  326.  
  327.  
  328. 4.2.5. Edit
  329. ***********
  330.  
  331. ** Clear screen
  332. Clears the screen with the current background color.
  333.  
  334. ** Fill oceans
  335. This item will fill all oceans oceans with the ocean color if it differs
  336. from the background color. This may take a while (Flood() needs a bit
  337. during intensive DMA-usage) !
  338. Why did I implement this function you may think perhaps? Ok, I tell you the
  339. secret. (You must use the default configuration, delete or rename your
  340. config-file if you have changed colors.) Try the following: Set the
  341. background color to light green (color no. 8), leave all other colors at
  342. their current setting! Now draw a flat map and then select "Fill oceans".
  343. Now you have filled continents! It is possible that some parts of the
  344. continents are filled with the ocean color. Select a higher detail level or
  345. use "Draw line" to repair "damaged coastlines".
  346. At the moment this function is in its test phase, I just fill a few
  347. oceans. If you fill oceans of a part of a map (menu Maps->Box) you will
  348. realize it. I will improve it in the next versions.
  349.  
  350. ** Grid
  351. A requester with two sliders pops up. Via the two sliders you can specify
  352. the distance between the grid lines in degrees. (Hint: The key "x"
  353. increases the "X step" value and "Shift x" decreases it. Commo-guidelines
  354. for sliders). "Ok" draws the grid and "Cancel", well, I forgot its function
  355. perhaps you will figure out :-).
  356.  
  357. ** Shadow
  358.  
  359. ** Toggle title
  360. Toggle the status of the screen`s title bar.
  361.  
  362. ** Draw line
  363. This item allows you to draw a line with the current line color. The
  364. specification of the start and the end point works similar to the
  365. specification of Maps->Box->Select box.
  366.  
  367. ** Draw box
  368. Like "Draw line", but draws a rectangle/box.
  369.  
  370. ** Draw filled box
  371. Draws a filled box.
  372.  
  373. ** Text
  374. A requester pops up where you can enter a text. "Cancel" cancelles the
  375. operation. If you select "Ok" the entered text follows the movement of your
  376. mouse pointer. The RMB aborts the operation, the LMB puts the text to its
  377. current position.
  378.  
  379. ** Flood fill
  380. Fills all adjacent pixels that have same pen number/color as the one at the
  381. mouse click position. This may take a while if your screen needs a lot of
  382. DMA time (hires-interlace-16 colors/superhires-4 colors).
  383.  
  384.  
  385. 5. What else?
  386. *************
  387.  
  388. Enjoy the program and wait for new versions. I released this version
  389. because it is possible to work with it and solves a lot of problems DrawMap
  390. 4.0 has (memory usage, HD required, speed).
  391.  
  392. Perhaps I will program a version for Kick 1.2/1.3. A version for
  393. 68020/30/40 and 68881/2 will follow!
  394.  
  395.  
  396. 6. History
  397. **********
  398.  
  399. V0.10  19.06.92
  400.    first code
  401. V0.20  24.06.92
  402.    draw_fullmap, some menus and some routines finished
  403. V0.30  01.07.92
  404.    config window finished; draw_fullmap improved
  405. V0.40  07.07.92
  406.    color menus corrected, manually (bug in OS!);
  407.    start of draw box map coding (not working)
  408. V0.41  07.07.92
  409.    draw (filled) box feature added
  410. V0.50  09.07.92
  411.    use of FFP, it is faster (see above)
  412. V0.51  10.07.92
  413.    draw-algorithms improved, I use integer-operations now (where possible)
  414. V0.60  11.07.92
  415.    part-wise loading of maps added (for users with few memory)
  416. V0.61  14.07.92
  417.    handling of MOUSEMOVE (draw line/box) improved, during the inner loop
  418.    I set only a flag, the drawing is performed outside
  419. V0.62  14.07.92
  420.    I use the OS 2.04 screen and window routines (open, get size,
  421.    overscan, etc.) now
  422. V0.70  16.07.92
  423.    changes in gadget alloc. (internal); background color changeable;
  424.    draw_boxmap completely new coded; draw routines changed (no continue;
  425.    anymore), you can read them better now; Move() only after WritePixel()
  426.    not after Draw(); key shortcuts for config-wd gadgets; some minor
  427.    improvements
  428. V0.71  16.07.92
  429.    select box coord corrected; coordinate display window added
  430. V0.72  17.07.92
  431.    coordinate display during draw line/box; coordinates are now correct
  432.    for a box map, too
  433. V0.73  19.07.92
  434.    INTUITICKS instead of MOUSEMOVE for draw_line/box (because of coord
  435.    window which needs time); errors with draw_boxmap corrected
  436. V0.74  19.07.92
  437.    bug fixed! I got a Intui-message, afterwards I checked for ende; the
  438.    message could be left unreplied (on exit of function)
  439. V0.80  19.07.92
  440.    ocean color, fill oceans, clear screen, clear screen before draw
  441.    menuitems added; minor improvements in draw line/box (avoid flicker)
  442. V0.81  20.07.92
  443.    coord. window routines put into their own module; coord display
  444.    during text and flood fill; a bit more rounding (coords, etc.);
  445.    code added which feigns a faster reaction during mouse movement (draw
  446.    box/line, text); OS 2.0 like waiting pointer; menu data put into
  447.    their own module
  448. V0.82  20.07.92
  449.    bug in calc_box_coord fixed, select box from box now works
  450. V0.83  22.07.92
  451.    vfactor changable during execution; edit routines put into their own
  452.    module; minor bugs fixed; minor internal changes
  453. V0.84  23.07.92
  454.    set vfactor/enter text requester added; coord. calc rounding improved;
  455.    auto detail level added
  456. V0.85  23.07.92
  457.    grid, shadow color menuitems added; fill oceans implemented; color menu
  458.    correction changed; draw grid implemented; minor internal changes
  459.  
  460.  
  461. TODO
  462.  
  463. - support of packed data files (powerpacker, lh, ...)
  464. - more screen modes (productivy, lores, A2024)
  465. - more speed, of course :-)
  466. - more display types (like DrawMap 4.1 ??)
  467. - ARexx-port (?)
  468.  
  469.  
  470.  
  471. Send bug reports, hints, ideas and 68040-cards :-) to (sorry, no e-mail
  472. available):
  473.  
  474.         Thies Wellpott
  475.         Moorhauser Weg 14
  476.         2948 Schortens 1
  477.  
  478.         Germany
  479.  
  480.