home *** CD-ROM | disk | FTP | other *** search
/ Amiga Elysian Archive / AmigaElysianArchive.iso / screen / hambench.arc / HamBench.doc < prev    next >
Text File  |  1989-06-11  |  19KB  |  379 lines
  1. =============================================================================
  2.  
  3.                                        
  4.                                             
  5.                               
  6.                                                
  7.                                          v. 1.0
  8.  
  9.                     (And all sorts of other display modes)
  10.  
  11.                              by David M. Pochron
  12.                    (a.k.a.  "The MCP" or "The MCP *sysop*")
  13.  
  14. =============================================================================
  15.  
  16. OVERVIEW
  17. --------
  18.    First off, the author assumes the user has a working knowledge of creating
  19. WorkBench icons and manipulating color palettes with HAM paint programs.  If
  20. not, you may want to get a friend to help you create your own icons for use
  21. with this program!
  22.    Also, I'll post here the standard lingo of "I assume no responsibility for
  23. lost work, trashed floppies, etc, etc.  if you use this program and the system
  24. crashes during a session."  (Since we are doing some pretty funny stuff with
  25. the system structures and all.)
  26.  
  27.    Now, on with the good stuff...
  28.  
  29.    This program is the culmination of my previous efforts - The KickStart mod
  30. which allowed you to change the # of bitplanes on the Workbench screen by
  31. patching KickStart 1.2; and my later effort, "Bitplanes" which changed the
  32. number of bitplanes on any screen on the fly.  Now, with HamBench, you can
  33. not only change the # of bitplanes, you can change resolutions and display
  34. modes on the fly as well - giving you the power of any type of Workbench
  35. screen mode you want - complete with icons!
  36.  
  37. USING HAMBENCH
  38. --------------
  39.    Although its main purpose for being created was to provide the capability
  40. of HAM mode with the Workbench screen, HamBench goes far beyond that.  You
  41. may also select to use a regular lo-resolution screen with any number of
  42. bitplanes, or you can also use the EXTRA_HALFBRITE mode with Workbench! 
  43. Plus, it allows you to load your own color palette from a data file each time
  44. you invoke the HamBench program.
  45.  
  46. HamBench should be used from CLI.  The arguments it understands are as
  47. follows:  {All must be in *lower case*, however, they can be on the command
  48. line in any order you wish (Except the <Palette, as it is a redirection
  49. argument.) }
  50.  
  51. HamBench [ < Filename ] [?] [r] [ham] [hb] [c] [n] [depth]
  52.  
  53. [ < Filename ]
  54. This is where you specify the filename of the color palette data file for
  55. loading your own custom color palette.  Replace "Filename" with the name of
  56. the data file with the raw palette data.  Note that You must also give it the
  57. [c] switch (load color palette) in order for HamBench to read in this file.
  58.    The palette file included with this ARC file is named "palette.dat".
  59.  
  60. [?]
  61. Helpful info display of HamBench parameters.
  62.  
  63. [r]
  64. Toggle between lo-res/hi res mode.  This effectively changes the horizontal
  65. resolution of the screen on the fly.  Necessary when using the [ham] or [hb]
  66. (halfbright) switches.
  67.  
  68. [ham]
  69. Toggle on/toggle off HAM mode.  Pretty straighforward.  You MUST be "toggling
  70. on" -OR- already be in lo-res mode or else HAM mode will not work.  (Unless
  71. there are Amiga's out there (A3000?) with hi-res HAM mode!)
  72.    Also, read about the [depth] argument for some special notes on the [ham]
  73. switch.
  74.  
  75. [hb]
  76. Works exactly like the [ham] switch, except give you EXTRA_HALFBRITE instead
  77. of HAM mode!  Same deal with lo-res mode too.  Again, read under [depth] arg.
  78. for special notes and how [hb] and [ham] affect changing the screen depth.
  79.  
  80. [c]
  81. Color switch.  Tells HamBench to look for a color palette file named in the
  82. redirection argument, load it, and set the screen colors to that new palette. 
  83.    The palette file itself must a raw color palette file converted from an IFF
  84. brush or picture CMAP chunk by the "ConvCMAP" program.
  85.    Note that HamBench can handle palette files with differing numbers of
  86. colors.  If your palette file you created has only, let's say, 16 colors in
  87. it, (because the screen or brush you extracted the color palette data from
  88. only had 16 colors in it) and you wish to create a Workbench screen with a 32-
  89. color palette, then only the first 16 colors will be changed, since that is
  90. all that was in your data file.
  91.  
  92. [n]
  93. No fixing of the right-hand border.  Normally, when you do not specify this
  94. option, whenever (and only when) the HamBench program is toggling down into
  95. lo-res mode, (from the [r] option) the Workbench screen's border is fixed so
  96. it looks like a normal, lo-res screen.  However, this also makes several
  97. programs un-executable in lo-res mode, since when the border is in place,
  98. Intuition will NOT open a window that would cross this border, causing the
  99. program to "hang."  The [n] option tells HamBench not to re-adjust the border
  100. when in lo-res, but it doesn't look as "tidy" since the right hand side of
  101. the screen will be in "full-video land."
  102.  
  103. [depth]
  104. Well, I saved the hardest to explain for last - changing the number of planes
  105. on the screen.  In short, when you pass in a number (1 - 8) in this argument,
  106. the plane depth will be set to this number.  The baffling part is when you
  107. ignore this parameter -  it has differing results, depending on whether you
  108. also used the [ham] or [hb] options.  Hopefully, I can try to explain the
  109. results, case-by-case, as follows:
  110.    1. If you specified neither [ham] nor [hb] mode as an option, then the
  111. Workbench screen will be forced to 2 bitplanes. (Std. WB depth)
  112.    2. If either HAM or HB mode is being toggled ON, then the program will
  113. set the # of bitplanes of the screen to 6.
  114.    3. If either HAM or HB mode is going to be toggled OFF, then the # of
  115. bitplanes on the screen will be set to 2. (standard WB depth)
  116.  
  117.    To understand it best, try experimenting.
  118.    PS. There are no checks for currently "illegal" values ( > 6 ) so you
  119. could end up crashing the system.
  120.  
  121.  
  122.  
  123. JUST TO GET THINGS GOING...
  124. ---------------------------
  125.    If the above has completely baffled you, here are some examples and what
  126. they do:
  127.  
  128. 1. IF YOU ARE CURRENTLY DISPLAYING A STD. WORKBENCH SCREEN:
  129. "HamBench r ham"                ; Turns on lo-res mode & HAM mode. Depth set
  130.                                   to 6 planes deep.
  131. "HamBench r hb"                 ; Turns on HALF_BRITE mode.  Same deal.
  132. "HamBench <palette.dat c r ham" ; Does same as above, but loads in your own
  133.                                   custom color palette.
  134. "HamBench <palette.dat c r hb"  ; Same deal. HB mode.
  135. "HamBench ham r n"              ; HAM mode - but don't fix rt. border.
  136. "HamBench 5 r"                  ; Turn on lo-res, but no HAM or HB.  Sets
  137.                                   screen depth to 5 for 32 colors at once.
  138. "HamBench 1"                    ; Don't even change resolutions. Just set
  139.                                   screen depth to 1.
  140. "HamBench 4 r ham"              ; Specify a 4-bitplane HAM mode screen!?!
  141.                                  (Well, it's pretty useless, but interesting.)
  142. 2. IF YOU ARE ALREADY IN HAM MODE AND DO THE FOLLOWING:
  143. "HamBench r ham"                ; Toggle HAM mode off, toggle resolution back
  144.                                   to hi-res, set depth back to 2.
  145. "HamBench ham"                  ; Only toggle off HAM mode - screen stays in
  146.                                   lo-res.
  147.  
  148. Similarly, HALFBRITE works the same way.
  149. You could also go directly from HAM mode into HALFBRIGHT by the following:
  150.  
  151. "HamBench ham hb"
  152.  
  153. This toggles off HAM mode, and toggles on HB mode.  The toggle ON has
  154. priority so the screen depth is set to 6.
  155.    Note: You should really only use any of the lo-resolution modes for DEMO
  156. purposes only, such as for disks with music or sound files, picture disks,
  157. animation disks, and also with disk magazines!  Plus, it's always nice to
  158. insert a disk and have a full-color, digitized image of your face pop up on
  159. the screen, perhaps making a funny expression when you click on it!
  160. (Impress your Mac II,IBM PS/2 and Atari ST friends!!!)
  161.  
  162.  
  163. USING HAMBENCH AS A WORKBENCH ICON
  164. ----------------------------------
  165.    You can use HamBench from a Workbench icon as well.  There is an icon in
  166. this ARC file called "HamBench.WB".  This icon is used with IconX which is on
  167. the Workbench 1.3 disk.  The script this icon accompanies can be modified
  168. with ED so you can have any screen mode just by clicking the icon.  You will
  169. notice this file reads:
  170.  
  171. HamBench <palette.dat c r ham
  172.  
  173. This has the effect of toggling on/off HAM mode and lo/hi res each time to
  174. click the icon and also loading in the custom palette.  You can change this to
  175. whatever modes you want to toggle on or off.
  176.  
  177.  
  178. CREATING CUSTOM ICONS
  179. ---------------------
  180.    Creating a digitized icon in HAM mode is much more tricky than creating a
  181. standard icons.  First of all, the color palettes must be identical,
  182. regardless of which mode you are in.  Therefore you must "lock" the color
  183. palette in the paint program you will be creating the icon with.  The
  184. standard steps for creating a digitized icon are as follows:
  185.  
  186. 1. Digitize something!
  187. 2. Load your favorite HAM paint program, and load some image with the palette
  188.    your Workbench screen is going to use.  It is important to decide on a
  189.    palette for all your images before you load the image you just digitized.
  190.    Note some paint programs may require you to "lock" the palette first.
  191. 3. Load the image you digitized as a brush, you will probably need at least 1
  192.    meg of memory to do this, unless the image you digitized is small.
  193. 4. Shrink the image to the size you want.
  194. 5. Do a "Remap" of the digitized image which will fix it so it has the same
  195.    palette as the main screen image you loaded with the palette you want to
  196.    use.  (Note: some paint programs may do a "remap" of the brush as soon as
  197.    you load it into the paint program, thus this step may not be necessary.)
  198. 6. Re-save the brush to disk.
  199. 7. Use the MAKEICON program found in the ARC file to convert it to an .info
  200.    file.  It is now an icon you can display on the Workbench screen!
  201.  
  202.  
  203. SPECIAL BONUS
  204. -------------
  205.    (Exciting, isn't it??)  Although this program had made references to the
  206. Workbench screen, in truth you can change any screen of any program you
  207. desire.  All that needs to be done is to put the screen you wish to be changed
  208. in front of all other screens, dragging it to the bottom of the display if
  209. you still need access to the Workbench screen, and HamBench will modify that
  210. screen instead of the Workbench screen!  This opens up some very interesting
  211. possibilities with Dpaint III and HAM mode, though I can't try it out at this
  212. time since I don't have Dpaint III yet...
  213.  
  214.  
  215. USING THE OTHER PROGRAMS
  216. ------------------------
  217.    Although I've mentioned in passing the utility programs in other places in
  218. this ReadMe file, I'll mention them all here so you know how to use them.
  219.  
  220. ConvCMAP < {IFFfile} > {ColorPaletteFile}
  221.   -- Extracts color palette chunk from IFF file and saves it to a raw palette
  222. file on disk. (BTW: Those are redirection < > symbols; they must be included
  223. on the command line!)
  224.  
  225. FixIcon {IconName} {depth}
  226.   -- Change the depth of the icon you specify in {IconName} to the depth you
  227. want.  Simply adds or subtracts bitplanes in the <icon>.info file.  Do not
  228. add the ".info" to the iconname - it gets added internally.
  229.  
  230. MakeIcon {icontemplate} {brushname}
  231.   -- Replace the image structure of the icon specified in {icontemplate} with
  232. the IFF image in {brushname}.  Note that you should not include the ".info"
  233. extension with the icon filename - it gets added internally.
  234.    This program effectively lets you create custom icons from brushes with
  235. any icon type! (disk, garbage, tool,etc.)
  236.  
  237. ShrinkWindows
  238.   -- This program duplicates the ShrinkWindows() function internal to the
  239. HamBench program.  If you use the [n] option in HamBench, there is a good
  240. chance that you will move windows offscreen or open new windows so that you
  241. cannot get to their control gadgets.  This program (runnable from BOTH
  242. WorkBench and CLI) goes through all the windows on the front-most screen and
  243. fits them into a lo-res display.  Very useful!
  244.  
  245.  
  246. ABOUT THE ICONS...
  247. ------------------
  248.    There are several icons which I have included with this ARC file.  Most of
  249. them are in HAM mode - I wanted to create Extra-HalfBright icons also but I
  250. do not have a paint program which supports EHB yet.  Anyway, here is a little
  251. bit on how each was created:
  252.  
  253. MARBLE.INFO
  254.  - Rendered with SA-4D - Not digitized!  Meant for MarbleMadness, but could
  255. be used for many other programs.
  256.  
  257. PREFERENCES.INFO
  258.  - Drawn using Dpaint II and converted to HAM mode for compatability with the
  259. rest of the icons.  Use it with the Preferences program, of course!
  260.  
  261. HAMBENCH-WB.INFO
  262.  - Drawn using the Photon Paint tools & palette requester in HAM mode.  Used
  263. with this program!
  264.  
  265. SCULPT.INFO
  266.  - Rendered with SA-4D, for SA-4D!  Simple as that.
  267.  
  268. LAUREN.INFO
  269.  - The famous "Lauren" pic, courtesy of Digi-View!  You could have your face
  270. plastered on WB too, folks!
  271.  
  272. DISK.INFO
  273.  - A HAM disk icon, demonstrating animated icons work as well in HAM mode. 
  274. Hand drawn, of course, but a real digitized diskette as an icon could be
  275. reather nifty!
  276.  
  277. BRISBY.INFO
  278.  - This icon is not HAM mode, but simply a 16-color lo-res drawn icon.  (It
  279. uses the 16-color base palette.)  This demonstrates that you can use different
  280. screen mode icons as long as the depth and palettes match!  I have included
  281. the original IFF file with this icon in case you want to use the same palette
  282. with your own custom icons.  All the icons here use this same palette!
  283.    Mrs. Brisby is a character from the Don Bluth film, "The Secret of NIMH",
  284. a motion picture which is a personal favorite of mine.  If you haven't seen
  285. it, you should!
  286.  
  287. The "ShrinkWindows" program has its own icon too, but it is simply an 8-color
  288. icon made with Dpaint II and MakeIcon.  Both ShrinkWindows.info and
  289. Brisby.info have been run through "FixIcon" so you should have no problems
  290. with these icons in any screen mode.
  291.    There are other 8- and 16-color icons in the ARC file of my previous effort,
  292. BITPLANES.  If you only want to use the 8/16 color screen modes, then you
  293. should seek the ARC file out for more icons.
  294.  
  295.  
  296. CAVEAT EMPTOR  (Oh no! The bad news!!)
  297. -------------
  298.    Needless to say, you can run into a few problems using HamBench, most
  299. obvious is most programs will not run with a low resolution workbench,
  300. because they open up a window larger than the display area. 
  301.    Additionally, you may have noticed if you ran the program already that the
  302. window and screen gadgets do not change size to fit the new resolution - thus
  303. they may look larger or smaller than normal or perhaps are being rendered over
  304. by other gadgets when the screen is set to an alternate resolution.  This
  305. problably could be fixed, but at the expense of making this program Kickstart-
  306. version dependant.  In any case, it doesn't seem to harm anything.
  307.    Another problem is much more serious and is due to a bug in the WorkBench
  308. part of the operating system itself!  It appears that Workbench does not like
  309. it when you try to display icons with more than a 2-bitplane deficit on a
  310. customized Workbench screen.  So if you have a 2-bitplane icon and you try to
  311. display it on a screen with 4 or more bitplanes, you will most certainly meet
  312. Mr. GURU.  In short, it makes it pretty much impossible to stick in any
  313. existing disk with normal icons without having the system crash.  (Actually,
  314. the system doesn't crash immediately; all the CHIP memory vanishes (yet it
  315. isn't reported as so on the memory meter) and after that, the GURU won't be
  316. long in comming...)  Unfortunately, I see no fix for this in the immediate
  317. future, until either Commodore brings out a Workbench that actually works
  318. 100%, or perhaps Charlie Heath of MicroSmiths, who created the ARP project,
  319. will eventually release the ARP WorkBench project, which should fix the bugs.
  320. (I hope!)
  321.    To help alleviate this serious bug, there is a program included with this
  322. ARC file called "FixIcon."  This program simply changes the depth of the
  323. .info file you specify as an argument, such as:
  324.  
  325. FixIcon disk 6                 ;note no ".info" after icon name!
  326.  
  327. will fix the disk.info file so it has 6 bitplanes on it instead of 2.  You can
  328. specify any number 1-8 in the second argument field and the icon will be
  329. changed to that depth.  You should do this to all your disks if you expect to
  330. use a Workbench with more than 3 bitplanes.
  331.    Actually, I shouldn't be too hard on Commodore, since the WorkBench was
  332. never meant to have the depth & screen resolution be changed on the fly.  In
  333. fact, I'm pleasantly surprised that this program works at all - try to do
  334. this on some other PC's and the OS crashes with a brilliant blazing inferno!
  335. It just seems that this bug is one that should not happen.  In any case,
  336. KickStart 1.4 (whenever it comes out) should not have this problem, since it
  337. is supposed to support "foreign graphic modes" on the Workbench screen, which
  338. will mean a variable amount of bitplanes depending on the graphics card you
  339. happen to have inserted into the machine.
  340.  
  341.  
  342. RULES
  343. -----
  344.    Okay, this program is pretty much pure PD.  You can use it for whatever you
  345. like, and you can even sell it yourself or even use it with disk magazines as
  346. long as I get proper credit.  If you sell it on your local user group PD disks
  347. or upload it to BBSes, please, keep this ARC file intact!
  348.    Also, I'd like for it to be "SpreadWare", if you use it regularly, it'd be
  349. nice if you gave a copy of the ARC file to a friend also.
  350.  
  351.  
  352. CONCLUSION
  353. ----------
  354.    Hopefully, I will have time to continue to add improvemts to the HamBench
  355. program; next on the list is fine-scrolling the WorkBench screen when in lo-
  356. res mode so you can see everything.  I wish I had more info on the internal
  357. workings of Workbench and how it displays its icons, as I would patch the
  358. forementioned icon display bug in a moments notice.  If anyone has any info,
  359. please feel free to contact me.  Also, if you have any bug reports or things
  360. you would like to see added, tell me about them!  I can usually be reached on
  361. the following BBSes:
  362.  
  363. The Daily Planet  608-873-4700  1200/2400       Leave mail to: "The MCP"
  364. A.S.I.M BBS       305-271-0688  1200/2400/9600  Leave mail to: "The MCP"
  365.  
  366. I have sysop status (for now at least) on the ASIM BBS, so you can also leave
  367. [F]eedback to the sysop and point out that the mail is for THE MCP somewhere
  368. in your message.  If you live (or visit often) the Madison WI area, drop by
  369. the CAMEO user's group meetings and seek me out (by my real name, David
  370. Pochron); I usually attend every meeting whenever possible.
  371.    You can also contect me if you want to hire a good Amiga programmer who
  372. knows "C" but prefers Assembly language.  (College is so expensive, and to
  373. actually have a hard drive might be nice someday... :-)
  374.  
  375.    That's all for now; hope you like the program.  It was fun to make.
  376.  
  377.                                                -- David M. Pochron
  378.                                                            6/10/89
  379.