home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 542.lha / Convert_v2.7 / convert.doc.pp / convert.doc
Text File  |  1991-08-10  |  14KB  |  328 lines
  1. ===========================================================
  2.    Convert.doc - for v2r7 - last updated July 25th, 1991
  3. ===========================================================
  4.  
  5. Credits:
  6. --------
  7. Software created by Pete Patterson for Black Belt Systems
  8. Additional coding by Ben Williams
  9. Documentation written by Ben Williams
  10. Funding by Black Belt Systems
  11. Project: HAM-E hardware support
  12.  
  13. Introduction:
  14. -------------
  15. The convert tool was created to fill a specific need of the Black Belt
  16. Systems HAM-E product customer base. The HAM-E is a graphics device
  17. which can display color information far more accurately than the Amigas
  18. built in graphics capabilities allow. As such, the HAM-E display
  19. formatting software takes as input CBM standard 24 bit IFF files, the
  20. format defined by CBM specifically for this type of use.
  21.  
  22. Unfortunately, many otherwise powerful Amiga products such as Impulses
  23. Turbo Silver, Byte by Bytes Sculpt series and some of the PD ray trace
  24. products don't save standard files; instead, they save raw files,
  25. or partially (sometimes totally!) non-conformant "other" formats, some
  26. of which they consider proprietary.
  27.  
  28. Certain other software products often save image formats that are
  29. designed to take advantage of various features in the Amiga's graphics
  30. system that allow enhancement of certain image modes. HAM-E, SHAM and
  31. Dynamic HiRes are examples of this type of image file. ASDGs "The Art
  32. Department" saves 24 bit files with special chunks in them called
  33. "CLUT" chunks that modify the 24 bit data in various ways. All of these
  34. differing image file formats bring chaos to our supposedly orderly
  35. "standard image format" environment.
  36.  
  37. The convert tool is able to read many of these file formats, optionally
  38. scale the input file to a new size for output, and write it out as a
  39. completely standard, "100% vanilla" 24 bit IFF file as per the CBM
  40. specification. Once this is done, the resulting file can be sent to the
  41. HAM-E Image Professional software, or any other Amiga tool that can
  42. read 24 bit IFF.
  43.  
  44. The convert tool has been made available free of charge to our
  45. customers as a service to them. Use by other parties is allowable as
  46. well - note that this is not the same as "public domain" release.
  47.  
  48. Use of Convert:
  49. ---------------
  50. There are basically two types of image files that convert supports.
  51. First, we have "unified" image files. These are files where all of the
  52. iamge information is contained in one file, with enough other
  53. information to allow the convert tool to identify the file type and
  54. then act accordingly. The other is "raw" individual RGB files, where
  55. three individual files make up the complete image; and there is no
  56. information in these files to help the tool know what the file type is,
  57. or what its resolution is, and so on.
  58.  
  59. If you use convert from the CLI or shell, then you will use the command
  60. switches, documented below.
  61.  
  62. If you use convert from the workbench, or if you type "convert" without
  63. any command line switches, then you are presented with a user interface
  64. that consists of control panels and buttons. This mode is better suited
  65. for interactive operations. The mouse interface is essentially self-
  66. explanatory.
  67.  
  68. The command line mode is better suited for script-based operations.
  69.  
  70. Unified Image File Use:
  71. -----------------------
  72. This consists of simply specifying an input and an output file:
  73.  
  74.     1> convert -i input_file -o output_file
  75.  
  76. This will take the input file and create a 24 bit IFF output file of
  77. the same resolution. The filenames may be presented in any order, as
  78. long as they are preceeded by the "-i" and "-o" switches. Note that for
  79. Targa format files, you must specify the -t flag anywhere on the command
  80. line. The width and height of the image is stored within the Targa file,
  81. but there is nothing in a Targa format file which identifies it as such.
  82.  
  83. Raw Image File Use:
  84. -------------------
  85. For any raw RGB file triplet, the "-i" option is not used. Instead,
  86. there are five (5) required command line switches that tell the convert
  87. software how to deal with this image. You must provide the names of
  88. each of the three raw files, as well as the horizontal and vertical
  89. resolution of the image contained in these files. Here is an example:
  90.  
  91.     1> convert -r file1 -g file2 -b file3 -x 320 -y 400 -o output_file
  92.  
  93. The parameters may be presented in any order, as long as all five of
  94. the -o, -r, -g, -b, -x, and -y switches are present.
  95.  
  96. You can also use the raw 24 bit input capability to read raw 8 bit
  97. black and white files, and then change these to 24 bit IFF. It's just a
  98. simple little trick, really - just specify the 8 bit raw input file
  99. three times. Lets say that the file is named "satpic". Here is the
  100. command line for reading it in:
  101.  
  102.     1> convert -r satpic -g satpic -b satpic -x 320 -y 400 -o output_file
  103.  
  104. This "fools" convert into thinking that the RGB values are all the
  105. same, and the result is a B&W 24 bit file.
  106.  
  107. Optional Output Scaling:
  108. ------------------------
  109. For either unified file types or raw RGB files, you have the option to
  110. scale the output file. You can do this as a percentage of input size,
  111. or to specific X:Y output requirements, or a mixture of both
  112. techniques. For the examples we'll use the unified form of the command
  113. since it's shorter and a little easier to understand; but these scaling
  114. options may also be applied in exactly the same way to raw RGB file
  115. conversion operations. Here are some examples:
  116.  
  117.     1> convert -i infile -o outfile -%x 50
  118.  
  119. This will scale the X axis to 50% of the original size. Since there is
  120. no scale specification for the Y axis, it will remain the original
  121. size.
  122.  
  123. If you need to scale both axis to 50%, then you specify that for both:
  124.  
  125.     1> convert -i infile -o outfile -%x 50 -%y 50
  126.  
  127. You can specify the output size directly in pixels, as well. The
  128. following example will create a 320x400 output, regardless of the size
  129. of the input file:
  130.  
  131.     1> convert -i infile -o outfile -px 320 -py 400
  132.  
  133. And this will scale the x axis to 50% of it's original size while
  134. ensuring a 200 line vertical size:
  135.  
  136.     1> convert -i infile -o outfile -%x 50 -py 200
  137.  
  138. You can mix and match percent and specific X and Y options as needed;
  139. don't use a percentage and a specific pixel specification for the same
  140. axis.
  141.  
  142. The scaling options also allow enlargement. For percentages, just
  143. specify values greater than 100; for pixel sizes, if the output size is
  144. larger than the input file size, then the output file will be enlarged
  145. in that dimension or dimensions. Here's an example:
  146.  
  147.     1> convert -i infile -o outfile -%x 200 -%y 200
  148.  
  149. Unified Image File Formats Supported:
  150. -------------------------------------
  151.  1 - 2 color IFF images
  152.  2 - 4 color IFF images
  153.  3 - 8 color IFF images
  154.  4 - 16 color IFF images
  155.  5 - 32 color IFF images
  156.  6 - 64 color "half-bright" IFF images
  157.  7 - 64 color HAM-E register mode single field images
  158.  8 - 64 color HAM-E register mode dual field images
  159.  9 - 128 color HAM-E register mode single field images
  160. 10 - 128 color HAM-E register mode dual field images
  161. 11 - 128 color IFF images
  162. 12 - 192 color HAM-E register mode single field images
  163. 13 - 192 color HAM-E register mode dual field images
  164. 14 - 256 color IFF images
  165. 15 - 256 color GIF images
  166. 16 - 256 color HAM-E register mode single field images
  167. 17 - 256 color HAM-E UPB8 brushes
  168. 18 - 512 color HAM-E register mode dual field images
  169. 19 - 4096 color photon paint IFF images
  170. 20 - 4096 color photon paint IFF brushes
  171. 21 - 4096 color DigiPaint IFF images
  172. 22 - 4096 color DigiPaint IFF brushes
  173. 23 - 4096 color Dynamic HiRes images
  174. 24 - 4096 color ARZ0 images ("TAD")
  175. 25 - 4096 color ARZ1 images ("TAD")
  176. 26 - 4096 color AHAM images ("TAD")
  177. 27 - 4096 color SHAM images ("info")
  178. 28 - 4096 color RGBN images ("Silver")
  179. 29 - 262144 color HAM-E ham mode single field images
  180. 30 - 262144 color HAM-E ham mode single field, multi-bank images
  181. 31 - 262144 color HAM-E ham mode dual field images
  182. 32 - 262144 color HAM-E ham mode dual field, multi-bank images
  183. 33 - 262144 color "ScanLab" 18 bit IFF files
  184. 34 - 16 million color RGB8 ("Silver")
  185. 35 - 16 million color 24-bit IFF images with CLUT chunks ("TAD")
  186. 36 - 16 million color 24-bit IFF images
  187. 37 - 16 million color QRT Trace files
  188. 38 - 16 million color DKB Trace files
  189. 39 - Targa Type  1 - Colormapped uncompressed images (maps up to 256)
  190. 40 - Targa Type  2 - Non-Colormapped uncompressed images
  191. 41 - Targa Type  9 - Colormapped RLE compressed images (maps up to 256)
  192. 42 - Targa Type 10 - Non-Colormapped RLE compressed images
  193. 43 - 16 million color TARGA files (Opticks)
  194.  
  195. RAW file formats supported:
  196. ===========================
  197. 44 - R, G, B files
  198. 45 - B&W, B&W, B&W files
  199.  
  200. Available Command Line Switches:
  201. ================================
  202.  
  203. For Help
  204. --------
  205. ?                 ...for list of options
  206. h                 ...for list of options
  207. -h                ...for list of options
  208. help              ...for list of options
  209.  
  210. For Specifying a Unified Input File:
  211. ------------------------------------
  212. -i [dev:dir/file]     ...unified input file (may include path)
  213.  
  214. For Specifying Targa Input:
  215. ---------------------------
  216. -t                    ...use -i for Targa file name
  217.  
  218. For Specifying raw RGB Input Files (All these switches are required):
  219. ---------------------------------------------------------------------
  220. -r [dev:dir/file]     ...raw red file (may include path)
  221. -g [dev:dir/file]     ...raw green file (may include path)
  222. -b [dev:dir/file]     ...raw blue file (may include path)
  223. -x [width]            ...raw source width
  224. -y [height]           ...raw source height
  225.  
  226. For Specifying the Output File (Required):
  227. ------------------------------------------
  228. -o [dev:dir/file]     ...24 bit output file (may include path)
  229.  
  230. For Scaling the output file to a percentage of the input file:
  231. --------------------------------------------------------------
  232. -%x [% value]         ...destination image width
  233. -%y [% value]         ...destination image height
  234.  
  235. For Scaling the output file to a specific Pixel Width:
  236. ------------------------------------------------------
  237. -px [pixel value]     ...destination image width
  238. -py [pixel value]     ...destination image height
  239.  
  240. To change an "over-under" X_Spex image to "Interleaved":
  241. --------------------------------------------------------
  242. -3d                   ...takes over-under, makes interleaved
  243.  
  244. To change an "Interleaved" X_Spex image to "over-under":
  245. --------------------------------------------------------
  246. -2d                   ...takes interleaved, makes over-under
  247.  
  248. Program revisions from version 1.0 to date:
  249. ===========================================
  250. v2r7 - No longer opens VBARs when invoked from the shell or CLI
  251.  
  252. v2r6 - Fixed bug present in 24 bit save since v2r3. This bug would nuke the
  253.        lower two bits of each of the red, green and blue buffers causing the
  254.        resultant file to be only eighteen bits. Nobody noticed.....
  255.        It was spotted because a user noticed that convert's 24 bit output
  256.        files were a good bit smaller than the input 24 bit files form ADPro.
  257.        He complemented us on our "good compression", which got us wondering.
  258.        Oooops. :^)
  259.        
  260. v2r5 - Sped up scaling by:
  261.        1. rearranging x and y expansion code for 3 or 4 to 1 speed 
  262.           improvement
  263.        2. recoded x and y compression code for 6 to 1 speed 
  264.           improvement
  265.      - Sped up targa 16 bit load by 20% or so
  266.  
  267. v2r4 - If the user interface is used, the program will loop until the Abort
  268.        gadget is selected.
  269.      - Assemblerized and optimized most of the rgb conversions including:
  270.             GIF
  271.             IFF 1 through 8 bitplanes
  272.             IFF HAM
  273.             IFF Halfbrite
  274.             Dynamic Hires
  275.             Sliced Ham
  276.        many others (so many I forgot 'em all)
  277.        Performance increases range from 200% to 600% (maybe even more)
  278.      - Fixed several unreported bugs relating to fixed buffer sizes. Most
  279.        (I would say all, but that kind of statement tends to come back and
  280.        haunt you) routines dynamically allocate line buffers according to
  281.        the actual picture width.
  282.      - Reworked Targa load routines using TrueVision Targa spec
  283.        Convert now supports the following Targa image types
  284.          : Type 1 - Colormapped uncompressed images (maps up to 256 entries)
  285.          : Type 2 - Non-Colormapped uncompressed images
  286.          : Type 9 - Colormapped RLE compressed images (maps up to 256 entries)
  287.          : Type 10- Non-Colormapped RLE compressed images
  288.      - Fixed Targa bug causing red and blue data to be swapped on Targa 16
  289.        images
  290.  
  291. v2r3 - Fixed bug causing crashes on unknown type Targa images
  292.      - Fixed bug in scaling affecting widths > 2048 pixels
  293.      - Implemented part of 24 bit save in assembler for 400% speed improvement
  294.      - Implemented part of 24 bit load as assembler for 600% speed improvement
  295.      
  296. v2r2 - Fixed bug in 24 bit save routine with widths > 800
  297.      - Fixed bug in scaling which affected brightness
  298.  
  299. v2r1 - Fixed bug in RAW RGB load (and maybe elsewhere)... if you accepted
  300.        either of the default width or height, the program would quit
  301.      - 32 bit Targa file support
  302.      - 16 bit Targa file support
  303.  
  304. v2r0 - Fixed bug in Targa conversions
  305.      - Added mouse interface
  306.  
  307. v1r6 - Fixed bug causing crashes if memory allocation failed
  308.      - Intergerized scaling for approximately 7x speed improvement
  309.  
  310. v1r5 - Fixed bug in loading 24 bit files that appeared in v1r4
  311.      - Added load of IBM (yech!) Dpaint "LBM" files
  312.      - Added load of IBM DPaint non-LBM files (recent DPaint versions)
  313.      - Added "shuffle" features to convert from and to X-Spex
  314.        compatible 3-d interleaved images
  315.  
  316. v1r4 - Added support for 18 bit IFF "ScanLab" files
  317.      - Added Support for Black Belt paint UPB8 (UnPackedBrush-8) brushes
  318.  
  319. v1r3 - Added HAM-E ham and reg mode single and multi field loaders
  320.  
  321. v1r2 - Added ability to read one type of targa file ("Opticks" generated)
  322.  
  323. v1r1 - Fixed bug in loading RGB8 and RGN files in v1r0
  324.      - Added scaling options (-px, -py, -%x, -%y)
  325.  
  326. v1r0 - Initial release version.
  327.  
  328.