home *** CD-ROM | disk | FTP | other *** search
/ Mega Top 1 / os2_top1.zip / os2_top1 / APPS / RAYTRACE / RT / GBM.TXT < prev    next >
Text File  |  1994-07-31  |  35KB  |  736 lines
  1. Generalised Bitmap Module
  2. =========================
  3.  
  4.  
  5. Supported File Formats
  6. ----------------------
  7.  
  8. Short name : Long name : File extensions
  9.     Comments
  10.  
  11. Bitmap : OS/2 1.1, 1.2, 2.0 / Windows 3.0 bitmap : .BMP .VGA .BGA .RLE .DIB .RL4 .RL8
  12.     Reads any of the above if uncompressed or run-length compressed.
  13.     Will not read CCITT G3 MH Fax compressed files.
  14.     Will not read 24 bit RLE files.
  15.     If input is an OS/2 bitmaparray file then which bitmap can be specified.
  16.         Input options: index=# (default: 0)
  17.     Can be made to write OS/2 1.1 or Windows 3.0 / OS/2 2.0 bitmaps
  18.         Output options: 1.1,win,2.0 (default: 2.0, note win=2.0)
  19.     The handling of 1bpp bitmaps is a little complicated.
  20.     When reading 1bpp bitmaps, the palette is ignored.
  21.     1's are considered foreground, and they are considered black.
  22.     0's are considered background, and they are considered white.
  23.     This agrees with WorkPlace Shell WPFolder background mode, and most PM
  24.     programs, but notably disagrees with Windows PBrush.
  25.     When writing 1bpp bitmaps, the actual 2 colours in the palette are
  26.     ignored, and a fixed palette is written. This is so that the resulting
  27.     bitmap will display black on white when displayed by WPFolder etc..
  28.     Foreground and background colours in palette can be inverted on input.
  29.         Input options: inv
  30.     Foreground and background colours in palette can be inverted on output.
  31.         Output options: inv
  32.     Foreground and background colours in bits can be inverted on input.
  33.         Input options: invb
  34.     Foreground and background colours in bits can be inverted on output.
  35.         Output options: invb
  36.  
  37. GIF : CompuServe Graphics Interchange Format : .GIF
  38.     Reads 1, bit data files.
  39.     Reads 2, 3 and 4 bit data files and presents them as 4 bit.
  40.     Reads 5, 6, 7 and 8 bit data files and presents them as 8 bit.
  41.     Writes 1, 4 and 8 bit data files.
  42.     Reads "GIF87a" and "GIF89a" style files.
  43.     Writes "GIF87a" style files.
  44.     Should correctly handle deferred clear-code in LZW data stream.
  45.     Will not generate output with deferred clear-code.
  46.     ie: should not break older GIF readers.
  47.     Can specify index of image within file on read.
  48.         Input option: index=# (default 0)
  49.     Can specify to return decoded data so far rather than error if corrupt.
  50.         Input option: errok
  51.     Can specify screen size to write in output screen descriptor.
  52.         Output options: xscreen=#,yscreen=# (defaults: image size).
  53.     Can specify background colour index to write in file BMHD header.
  54.         Output option: background=# (default: 0)
  55.     Can specify position information in output image descriptor.
  56.         Output options: xpos=#,ypos=# (defaults: 0,0).
  57.     Extensively test on GIF files from a wide variety of sources.
  58.     Compatibility tested with xloadimage and xv.
  59.  
  60. PCX : ZSoft PC Paintbrush Image format : .PCX
  61.     Reads and writes 1,4,8 and 24 bit colour files.
  62.     Subset of plane/bits-per-plane combinations supported.
  63.     Files are read and written using a run-length coding scheme.
  64.     Tested using Zsoft originated .PCX files.
  65.     Compressed runs of pixels are not supposed to straddle scan lines.
  66.     GBM never does this, but some other applications violate this rule.
  67.     By default, if GBM finds that a run of pixels is longer than the scan
  68.     line, it will use the leftover pixels on the next scan line.
  69.     Some images will not load properly, as they require the loading
  70.     program to discard those pixels in the run that extend beyond the end
  71.     of the scan line. This behaviour can be enabled in GBM.
  72.         Input option: trunc
  73.  
  74. TIFF : Microsoft/Aldus Tagged Image File Format support : .TIF .TIFF
  75.     Reads and writes 1,4,8 and 24 bit colour files.
  76.     Can almost read all TIFF 6.0 Baseline compliant files.
  77.       Can read uncompressed and Packbits images.
  78.       CCITT Modified huffman compression is the missing peice.
  79.     Can read some files with extensions to Baseline.
  80.       Can read 1bpp greyscale and palettised files.
  81.       Can read Orientation==4 files.
  82.       Can read PlanarConfiguration==2 files for RGB image data.
  83.       Can read LZW compressed files too.
  84.       Can also read CMYK 4 colour seperation files.
  85.       No JPEG or Y-Cb-Cr support.
  86.     Writes files that comply with TIFF 6.0 Baseline.
  87.       Usually writes uncompressed files only.
  88.       Data is written out as a single large strip.
  89.     Can specify image within TIFF file with many images
  90.         Input option: index=# (default: 0)
  91.     Can write 1bpp as non-Baseline file preserving fg/bg cols
  92.         Output option: pal1bpp
  93.     Can ask for LZW compression.
  94.         Output option: lzw
  95.     Can specify informational tags to append on output.
  96.         Output options: artist=,software=,make=,model=,host=,documentname=,pagename=,imagedescription=
  97.  
  98. Targa : Truevision Targa/Vista bitmap : .TGA .VST .AFI
  99.     Reads any uncompressed/run-length-compressed files.
  100.     Reads 8 bit and 24 bit files.
  101.     Can read 8 bit greyscale and 8 bit colour mapped files.
  102.     Reads both yup and ydown files.
  103.     Writes out as uncompressed 8 bit or 16,24,32 bit.
  104.         Output options: 16,24,32 (default 24)
  105.     8 bit data is always written out as a colour mapped file.
  106.     Can be made to write yup and ydown files.
  107.         Output options: ydown,yup (default: yup)
  108.  
  109. ILBM : Amiga IFF / ILBM Interleaved bitmap format : .IFF .LBM
  110.     Reads 1 bit palettised files.
  111.     Reads 2,3 and 4 bit palettised files, returning them as 4 bit.
  112.     Reads 5,6,7 and 8 bit palettised files, returning them as 8 bit.
  113.     Reads HAM6, HAM8, SHAM and Extra-Halfbrite images.
  114.     HAM6, HAM8 and SHAM returned as 24 bit data.
  115.     Writes 1,4 and 8 bit palettised colour files.
  116.     Writes 24 bit files by performing simple conversion to HAM6 first.
  117.     This loses quality but results are still better than 8 bit.
  118.     Understands the RLE compression scheme used.
  119.     Uses BMHD, CMAP, CAMG and BODY sections of file only.
  120.     Only writes BMHD, CMAP, CAMG and BODY sections in output files.
  121.     Can specify position information in file BHMD header.
  122.         Output options: xpos=#,ypos=# (defaults: 0,0).
  123.     Can specify transparent colour to write in file BMHD header.
  124.         Output option: transcol=# (default: 0)
  125.     Can specify aspect ratio to write in file BMHD header.
  126.         Output options: xaspect=#,yaspect=# (defaults: 1,1).
  127.     Can specify screen size to write in output BMHD header.
  128.         Output options: xscreen=#,yscreen=# (defaults: image size).
  129.     Note that when DeluxePaint etc. try to load an 8 bit IFF file, they
  130.     switch to a 32 colour (5 bit mode) and only read the 5 least
  131.     significant planes of the file - this generally looks yukky!
  132.     Tested using DeluxePaint sample bitmaps.
  133.  
  134. YUV12C : YUV12C M-Motion Frame Buffer : .VID
  135.     Reads files and presents data as 24 bit data.
  136.     Writes 24 bit data files by converting them into 12 bit YUV.
  137.     VID files MUST be a multiple of 4 pixels wide.
  138.     When writing a non-multiple of 4, the last 1, 2 or 3 pixels are lost.
  139.     Can specify image origin information in YUV12C header.
  140.         Output options: xpos=#,ypos=# (defaults: 0,0).
  141.     Tested using M-Control Program 2.0, Browser sample application.
  142.  
  143. Greymap : Portable Greyscale-map (binary P5 type) : .PGM
  144.     Credit for file format to Jef Poskancer.
  145.     No palette present in file format.
  146.     Reads 8 bit grey scale files.
  147.     Writes red, green, blue plane or greyscale equivelent of 8 bit image.
  148.         Output options: r,g,b,k (default: k)
  149.  
  150. Pixmap : Portable Pixel-map (binary P6 type) : .PPM
  151.     Credit for file format to Jef Poskancer.
  152.     Reads and writes 24 bit unpalettised RGB data files.
  153.  
  154. KIPS : IBM KIPS : .KPS
  155.     Reads 8 bit palettised files.
  156.     Will look for palette in .PAL file unless .KPL file specified.
  157.         Input options: pal,kpl (default: pal)
  158.     Writes 8 bit palettised files.
  159.     Will write palette in .PAL file unless .KPL file specified.
  160.         Output options: pal,kpl (default: pal)
  161.  
  162. IAX : IBM Image Access eXecutive : .IAX
  163.     Reads array as 8 bit greyscale.
  164.     File format does not hold image dimensions.
  165.     Hence code assumes width is 512 pixels unless overridden.
  166.         Input options: width=# (default: 512)
  167.     File format does not include palette.
  168.     Writes red, green, blue plane or greyscale equivelent of 8 bit image.
  169.         Output options: r,g,b,k (default: k)
  170.  
  171. XBitmap : X Windows bitmap : .XBM
  172.     Reads 1bpp X bitmaps, presenting 1's as black, 0's as white.
  173.     Writes 1bpp X bitmaps, darkest colours as 1's, brightest colour as 0's.
  174.     Tested upon some sample .XBM files.
  175.  
  176. Sprite : Archimedes Sprite format from RiscOS : .SPR .SPRITE
  177.     Technically sprite files have no extension.
  178.     But GBM recognises .SPR and .SPRITE for convenience.
  179.     Reads 1,4 and 8 bit sprites.
  180.     'First bit' value in header must be a multiple of 8 (v.likely).
  181.     Will only read image plane, will ignore any mask plane.
  182.     Will handle case when no palette present in file.
  183.     Will default to the default Wimp palette in this case.
  184.     If input contains more than one sprite then which can be specified.
  185.         Input options: index=# (default: 0)
  186.     Will output 1,4 and 8 bit files.
  187.     Will write a palette in the file.
  188.     Will only write an image plane, ie: no mask plane.
  189.     Will write a 16 entry palette for 8 bit data (not 64 entry).
  190.     Will map to wierd archmedes palette when writing 8 bit data.
  191.     Tested reading 4bpp sprites with no palette.
  192.     Tested reading 8bpp sprites with no palette and with 64 entry palette.
  193.     Sprites generated by GBM have been loaded on RiscOS.
  194.     Remember: Use SetType to change type of file from PC-file to Sprite,
  195.     by SetType option of filer menu or "*SetType <filename> Sprite".
  196.  
  197. PSEG : IBM Printer Page Segment : .PSE .PSEG .PSEG38PP .PSEG3820
  198.     This is a file format used by IBM document/printing systems.
  199.     It is used to represent a bi-level image to be used in a document.
  200.     Reads data and presents a 1bpp bitmap.
  201.     Image is presented 1's as black on 0's as white background.
  202.     PSEG files should be downloaded from a VM host in binary mode.
  203.     Some PSEG files have a corrupt record structure.
  204.     This doesn't cause a problem on VM but can confuse a non-VM reader.
  205.     GBM can be made to attempt to handle these files.
  206.         Input option: fixrec
  207.     Will output 1bpp file.
  208.     Can specify 2x scale factor.
  209.         Output option: double
  210.     Palette in 1bpp data is lost when written to file.
  211.     The resulting non-VM file has no record structure.
  212.     So when it is uploaded it must be fixed using FIXL3820 EXEC or similar.
  213.     Image width is rounded up to next multiple of 8 when written.
  214.  
  215.  
  216. Sample Applications
  217. -------------------
  218.  
  219. GBMHDR - Display header information from bitmap files
  220.  
  221. usage: gbmhdr [-g] [-s] {fn.ext{,opt}}
  222.        -g            don't guess bitmap format, try each type
  223.        -s            be silent about errors
  224.        fn.ext{,opt}  input filenames (with any format specific options)
  225.                      Bitmap when ext in [BMP VGA BGA RLE DIB RL4 RL8]
  226.                      GIF when ext in [GIF]
  227.                      PCX when ext in [PCX]
  228.                      TIFF when ext in [TIF]
  229.                      Targa when ext in [TGA VST AFI]
  230.                      ILBM when ext in [IFF LBM]
  231.                      YUV12C when ext in [VID]
  232.                      Greymap when ext in [PGM]
  233.                      Pixmap when ext in [PPM]
  234.                      KIPS when ext in [KPS]
  235.                      IAX when ext in [IAX]
  236.                      XBitmap when ext in [XBM]
  237.                      Sprite when ext in [SPR]
  238.        opt           bitmap format specific option to pass to bitmap reader
  239.  
  240.     Note that the GBM module only ever surfaces the size and bits per pixel
  241.     of images (regardless of the other information present in the header).
  242.     All GBM programs have access to the bitmap file formats documented
  243.     above, although this list is omitted in subsequent documentation.
  244.  
  245.     GBMHDR displays output in the following style :-
  246.  
  247.          384x768   8bpp    51Kb  17% GIF        aab.gif
  248.          227x254   8bpp    58Kb 102% Bitmap     andy.bmp
  249.          256x256  24bpp    84Kb  43% TIFF       bardot.tif
  250.  
  251.     Listed is the size, bits per pixel, Kb size of the file, a percentage
  252.     value, the file format, and the file name. The percentage is calculated
  253.     as (filesize*100/datasize) and effectively gives the compression ratio.
  254.     For example aab.gif is well compressed (to 17% of the theoretical
  255.     size). andy.bmp gives a >100% value because of the file header.
  256.  
  257. GBMREF - Reflect in horizontal and/or vertical directions
  258.  
  259. usage: gbmref [-h] [-v] [-t] fn1.ext{,opt} [fn2.ext{,opt}]
  260. flags: -h             reflect horizontally
  261.        -v             reflect vertically
  262.        -t             transpose x for y
  263.        fn1.ext{,opt}  input filename (with any format specific options)
  264.        fn2.ext{,opt}  optional output filename (or will use fn1 if not present)
  265.                       bitmap formats and options as before
  266.  
  267.     Certain non-obvious combinations of -h, -v and -t can be very usefull.
  268.     None of them    can be used for just file format translation.
  269.     -h -v        reflect both, equivelent to 180 degree turn
  270.     -h -t        equivelent to 90 degree turn clockwise
  271.     -v -t        equivelent to 90 degree turn anti-clockwise.
  272.  
  273. GBMSUB - Extract a subrectangle of a bitmap
  274.  
  275. usage: gbmsub [-x x] [-y y] [-w w] [-h h] fn1.ext{,opt} [fn2.ext{,opt}]
  276. flags: -x x           left edge of rectangle (default 0)
  277.        -y y           bottom edge of rectangle (default 0)
  278.        -w w           width of rectangle (default width of image - x)
  279.        -h h           height of rectangle (default height of image - y)
  280.        fn1.ext{,opt}  input filename (with any format specific options)
  281.        fn2.ext{,opt}  optional output filename (or will use fn1 if not present)
  282.                       bitmap formats and options as before
  283.  
  284.     If none of the -x,-y,-w and -h options are supplied the defaults
  285.     cover the whole of the input file. Hence this program will just read
  286.     one file and write the data as another. Great for format conversion.
  287.  
  288. GBMSIZE - Change the size of a bitmap
  289.  
  290. usage: gbmsize [-w w] [-h h] fn1.ext{,opt} [fn2.ext{,opt}]
  291. flags: -w w           new width of bitmap (default width of bitmap)
  292.        -h h           new height of bitmap (default height of bitmap)
  293.        fn1.ext{,opt}  input filename (with any format specific options)
  294.        fn2.ext{,opt}  optional output filename (or will use fn1 if not present)
  295.                       bitmap formats and options as before
  296.  
  297.     If none of the -w or -h options are supplied, the defaults will be
  298.     the input image size. Hence this program will just read one file and
  299.     write the data as another. Great for format conversion.
  300.  
  301. GBMBPP - Do various bits per pixel conversions
  302.  
  303. usage: gbmbpp [-m map] [-e] [-hN] fn1.ext{,opt} [fn2.ext{,opt}]
  304. flags: -m map         mapping to perform (default 7x8x4)
  305.                       bw           black and white
  306.                       vga          16 colour VGA
  307.                       8            8 colour (in 4 bit file)
  308.                       4g           4 bit greyscale
  309.                       7x8x4        7 levels red, 8 green, 4 blue 8514/A
  310.                       6x6x6        6 levels red, 6 green, 6 blue
  311.                       8g           8 bit greyscale
  312.                       tripel       64 reds, 64 greens, 64 blues tripel
  313.                       freqR:G:B:N  keep R red, G green, b blue bits, and map to
  314.                                    N most used colours in 8 bit palette
  315.                       mcutN        median cut to N colours
  316.                       R:G:B        keep R red, G green, B blue bits (eg: 8:8:8)
  317.        -e             enable error-diffusion (default is to truncate)
  318.                       -e only with -m bw, vga, 4g, 7x8x4, 6x6x6 with no -h
  319.        -h             enable halftoning (default is to truncate)
  320.                       -h only with -m 7x8x4, 6x6x6, 8, vga or R:G:B, with no -e
  321.                       N is a halftoning algorithm number (default 0)
  322.        fn1.ext{,opt}  input filename (with any format specific options)
  323.        fn2.ext{,opt}  optional output filename (or will use fn1 if not present)
  324.                       bitmap formats and options as before
  325.  
  326.     This program reads the input bitmap. If it is not 24 bit, then it is
  327.     expanded to 24 bit per pixel. The data is then processed using the
  328.     supplied mapping giving a 24,8,4 or 1 bit per pixel image, which is
  329.     then written to the output bitmap file. The bw mapping produces a 1
  330.     bpp output file, vga and 4g gives 4 bit output files, 7x8x4, 6x6x6, 8g,
  331.     freq and tripel give 8 bit output files. R:G:B (where R,G and B are
  332.     numbers in the range 0 to 8), gives a 24 bit output file where only
  333.     the top R bits of red are non-zero, the top G of green and B of blue.
  334.     The normal way to map is simply to map each colour in the source
  335.     bitmap to the closest one in the destination bitmap. However if -e
  336.     is supplied, error diffusion is used to get a smoother result. Also, if
  337.     -h is supplied halftoning may be used instead. -e and -h are not valid
  338.     together, and are only valid with certain mappings.
  339.  
  340. GBMGAMMA - Convert between various colour spaces
  341.  
  342. usage: gbmgamma [-m map] [-g gamma] [-s shelf] fn1.ext{,opt} [fn2.ext{,opt}]
  343. flags: -m map         mapping in the form ?_to_? (default: i_to_l), where ? is
  344.                       i  physical intensitys (eg: raytracer output)
  345.                       p  gamma corrected for a specific monitor
  346.                       l  L* cyclometric linear perceived intensitys (as in PM)
  347.        -g gamma       set monitor gamma (default 2.1)
  348.        -s shelf       set monitor shelf (default 0.0)
  349.                       gamma and shelf only used for mapping to or from p
  350.                       for 8514 monitor gamma=2.3,shelf=0.136
  351.                       for 8515 monitor gamma=2.1,shelf=0.0
  352.        fn1.ext{,opt}  input filename (with any format specific options)
  353.        fn2.ext{,opt}  optional output filename (or will use fn1 if not present)
  354.                       bitmap formats and options as before
  355.  
  356.     This program reads a bitmap and assumes the pixel values in it are
  357.     in the input colour space. If the bitmap has a palette it maps each
  358.     palette entry according to the supplied mapping, otherwise it maps
  359.     each individual 24 bit pixel. For example, if you get a 24 bit per
  360.     pixel image from a Windows video capture program, the odds are in may
  361.     be in a gamma corrected colour space with a gamma of 2.2. You can
  362.     convert this to the L* cyclometric colour space used by PM by typing
  363.     "gbmgamma -m p_to_l -g 2.2 captured.bmp nicepm.bmp". The shelf option
  364.     is primarily for when converting to a gamma corrected colour space for
  365.     a specific monitor (when you aren't going to use PM to display the
  366.     bitmap, and the display program doesn't do any correction). Some
  367.     monitors don't actually start to light up pixels until the pixel
  368.     values are a certain value. Normally "-s shelf" will not be used.
  369.  
  370. GBMCPAL - Map to Common Palette
  371.  
  372. usage: gbmcpal [-m map] [-v] n1 n2 n3 ifspec{,opt} ofspec{,opt}
  373. flags: -m map         mapping to perform (default freq6:6:6:256)
  374.                       freqR:G:B:N       map all bitmaps to same palette, worked
  375.                                         out using frequency of use histogram
  376.                       mcutN             map all bitmaps to same palette, worked
  377.                                         out using median cut algorithm
  378.                       rofreqR:G:B:N:N2  map each bitmap to frequency palette,
  379.                                         reordered to minimise differences
  380.                                         between successive bitmaps
  381.                       romcutN:N2        map each bitmap to median cut palette,
  382.                                         reordered to minimise differences
  383.                                         between successive bitmaps
  384.                                         R,G,B are bits of red, green and blue
  385.                                         to keep, N is number of unique colours,
  386.                                         N2 is extra palette entries
  387.        -v             verbose mode
  388.        n1 n2 n3       for ( f=n1; f<n2; f+=n3 )
  389.        ifspec           printf(ifspec, f);
  390.        ofspec           printf(ofspec, f);
  391.                       filespecs are of the form fn.ext
  392.                       ext's are used to deduce desired bitmap file formats
  393.                       bitmap formats and options as before
  394.  
  395.     Given a set of bitmaps, it is possible to examine them all and compute
  396.     a common palette for holding them, and then generated new bitmaps
  397.     mapped to that palette. The mappings available are frequency based
  398.     and median-cut based. Alternatively, it is possible to generate the
  399.     most suitable palette for each frame, and then reorder the palettes
  400.     of each bitmap so as to be as close as possible to its predecessor.
  401.  
  402.     By reordering palettes (using rofreq/romcut) it is possible to remove
  403.     almost all flicker on playback. From frame to frame, almost all palette
  404.     entries in a given frame, have close entries in the previous frame.
  405.     However for a few, this is not true, and flicker may be seen. The N2
  406.     parameter is designed to alleviate this. The process will handle the
  407.     N2 worst palette changes using N2 extra palette entries. Thus the N2
  408.     worst causes of flicker can be eliminated. A typical use might be :-
  409.  
  410.         gbmcpal -m romcut240:16 0 100 1 in%02d.bmp out%02d.bmp
  411.  
  412.     This means map each frame to a palette with 240 unique colours in.
  413.     Any given frame only uses 240 colours at most. But the palette is
  414.     acutally 240+16 colours in length, and the additional 16 are used to
  415.     eliminate flicker caused by the 16 worst matches.
  416.  
  417. GBMVFSA - View Full Screen Animation
  418.  
  419. usage: gbmvfsa [-l] [-p] [-s] [-t] [-P] n1 n2 n3 fspec{,opt}
  420. flags: -l             loop indefinately
  421.        -p             set palette only once, assume same
  422.        -s             single step the frames
  423.        -t             annotate each frame with its title
  424.        -P             display palette bar
  425.        n1 n2 n3       for ( f=n1; f<n2; f+=n3 )
  426.        fspec            printf(fspec, f);
  427.                       filespecs are of the form fn.ext
  428.                       bitmap formats and options as before
  429.  
  430.     This program can be used display an animation consisting of a
  431.     collection of individual bitmap frames. It displays the animation
  432.     to the OS/2 Full Screen 320x200 at 8bpp VGA screen mode. Because of
  433.     this, gbmvfsa is limited to displaying bitmaps of 320x200 or less, and
  434.     they must be 8bpp. Also, all the bitmaps must be the same size.
  435.  
  436.     If all the bitmaps share the same palette (presumably enforced by
  437.     using gbmcpal above), then specify the -p option.
  438.  
  439.     If the bitmaps have different palettes then visual artifacts can be
  440.     produced. This is because for each new frame, the palette is changed,
  441.     and then the screen bitmap bits are changed. Thus there is a small
  442.     window in which the old bits are displayed with the new palette.
  443.     At this time I know of no architected way to synchronise the changes
  444.     to occur with the vertical retrace, using the OS/2 Vio API.
  445.  
  446.     One way to avoid the problem is to have each bitmap use 128 colours.
  447.     Even bitmaps would use palette entrys 0 - 127, and palette entries
  448.     128 - 255 would contain the previous pictures palette. Similarly in
  449.     reverse for odd bitmaps.
  450.  
  451.     gbmcpal provides an attempt at solving the problem. Its rofreq and
  452.     romcut options reorder palette entries to try to minimise changes
  453.     between successive frames. This significantly reduces flicker.
  454.     In most cases, flicker can be totally eliminated.
  455.  
  456.     The important thing to note is that it is not gbmvfsa's job to solve
  457.     this problem, it is the job of the bitmap generating program.
  458.  
  459.     As the program runs, certain keys can be used :-
  460.  
  461.         Space    advances a single frame
  462.         -    steps back one frame
  463.         0 .. 9    moves to 0/10 .. 9/10 of the way through
  464.         s    enters single step mode
  465.         g    resumes continuous play
  466.         t    toggles titleing on/off
  467.         p    toggles palette display on/off
  468.         Esc,q,x    quits
  469.  
  470. GBMV - GBM Viewer
  471.  
  472. usage: gbmv [-e] [-h] fn.ext{,opt}
  473. flags: -e             error diffuse
  474.        -h             halftone
  475.                       -e and -h not allowed together
  476.        fn.ext{,opt}   input filename (with any format specific options)
  477.                       bitmap formats and options as before
  478.  
  479.     This program is a minimal image viewer for OS/2 + PM.
  480.     It simply pops up the image in a window.
  481.  
  482. GBMV2 - GBM Viewer 2
  483.  
  484. usage: gbmv2 [fn.ext{,opt}]
  485.        fn.ext{,opt}   input filename (with any format specific options)
  486.                       bitmap formats and options as before
  487.  
  488.     This program is a full featured PM application with full context
  489.     sensitive help. Virtually any function of the command line GBM tools
  490.     can be done interactively, with Undo capability. Interaction with
  491.     the PM printer and clipboard is possible also. The PM Desktop may
  492.     also be snapshotted. Functions pertaining to multiple bitmaps are
  493.     not available here. Try it.
  494.  
  495.  
  496. Colour spaces
  497. -------------
  498.  
  499. If a light is physically twice as bright, the eye does not necessarily see it
  500. as twice as bright. Also, if a pixel is written onto a monitor screen with
  501. twice the value, the physical intensity of the pixel is not necessarily double.
  502.  
  503. How exactly should numbers inside a bitmap file relate to physical or
  504. perceived intensitys when displayed on the screen?
  505.  
  506. In OS/2 PM perceived intensitys are proportional to the values in the bitmap
  507. file. Pixels in such a bitmap are in the 'L* cyclometric' colour space.
  508.  
  509. Ray Tracers often write pixel values in the bitmap proportional to the physical
  510. intensity computed for that ray. Such data is in the 'intensity' colour space.
  511.  
  512. Finally, if a bitmap holds values computed in such a way as to compensate for
  513. the gamma of the monitor (ie: intensitys transformed to cancel out the gamma
  514. of the monitor), then the data is in a 'gamma corrected' colour space.
  515.  
  516. So, if you have some Ray Tracer output, and you wish to display on an 8514
  517. monitor WITHOUT using OS/2 PM, then to get a decent colour rendition, you must
  518. map the bitmap from the 'intensity' to a 'gamma corrected' colour space.
  519. To do this you must know the gamma of the 8514 monitor (which is about 2.1).
  520.  
  521. Also, if you have some Ray Tracer output, and you wish to display on OS/2 PM,
  522. then to get a decent rendition you must map the bitmap from the 'intensity' to
  523. the 'L* cyclometric' colour space.
  524.  
  525. GBMGAMMA is a colour mapping program capable of performing mappings between
  526. any 2 of the 3 colour spaces above.
  527.  
  528. Mapping of this sort should really be done on 24 bit data, before
  529. error-diffusion or halftoning takes place.
  530.  
  531.  
  532. Making bitmap animations
  533. ------------------------
  534.  
  535. GBM was originally written as the bitmap handling portion of my homebrew
  536. Ray Tracer, RT. RT was originally written to allow me to trace snazzy
  537. animations. For example, here is what I did to make a spinning globe animation.
  538.  
  539. First I traced a largish number of individual bitmap frames using RT. I wrote
  540. these out under the names globeNNN.tif where NNN is 000, 010, 020, ... 350 (ie:
  541. the angle of rotation in degrees). I used the ",lzw" option to get the files
  542. written LZW encoded to reduce the disk space requirements.
  543.  
  544. Then to map the data to a common palette, I used :-
  545.  
  546.     gbmcpal -m freq6:6:6:256 0 360 10 globe%03d.tif globe%03d.bmp
  547.  
  548. To display the animation under OS/2, using fullscreen VGA, I use :-
  549.  
  550.     gbmvfsa -l -p 0 360 10 globe%03d.bmp
  551.  
  552. Obviously there are file formats specifically for holding animations, and
  553. algorithms for having animations where palette entries vary from frame to
  554. frame, but the simple example above is ok for many purposes.
  555.  
  556.  
  557. Some examples
  558. -------------
  559.  
  560. gbmhdr *.bmp *.tif
  561.     Displays the headers of all the bitmaps and TIFF files
  562.  
  563. gbmref file.bmp file.tga
  564.     Perform no reflection (no -h, -v or -t).
  565.     Hence simply converts file from Bitmap to Targa format!
  566.  
  567. gbmref -h larrow.tga rarrow.tga
  568.     Reflects larrow.tga to make rarrow.tga
  569.  
  570. gbmref -h -t profit.gif loss.gif
  571.     The combination of a horizontal flip with a transpose gives a 90
  572.     degree rotation clockwise. Thus a graph going up from bottom left
  573.     to top right, ends up going from top left to bottom right!
  574.  
  575. gbmref -v uarrow.pcx "darrow.lbm,xaspect=5,yaspect=6,xscreen=320,yscreen=200"
  576.     Reflects uarrow.pcx to make darrow.lbm
  577.     Output options defined for ILBM files used to write to aspect ratio
  578.     and screen size fields in output .lbm file.
  579.     Note: some command processors (such as OS/2 CMD.EXE) will split command
  580.     line arguments at spaces and commas, so we quote second argument.
  581.  
  582. gbmsub -x 100 -y 50 page.bmp
  583.     Trims 100 pixels off the left, and 50 off of the bottom
  584.     Note: no second filename given, so output overwrites page.bmp
  585.  
  586. gbmsize -w 1024 -h 768 strangesize.bmp screensized.bmp
  587.     Takes any bitmap and scales it to a typical SVGA screen size.
  588.  
  589. gbmbpp -m 7x8x4 24bit.tga 8bit.bpp
  590.     Maps a 24 RGB image to the 8514/A PM palette
  591.     Note: Source image format (Targa) not same as output format (Bitmap)
  592.  
  593. gbmbpp -m 7x8x4 -h 24bit.bmp nice8bit.bmp
  594.     As above but with halftoning
  595.  
  596. gbmbpp -m 7x8x4 -e 24bit.bmp nice8bit.bmp
  597.     As above, but with error diffusion
  598.  
  599. gbmbpp -m vga -e 24bit.bmp nice4bit.bmp
  600.     As above, but suitable for VGA display
  601.  
  602. gbmbpp -m 5:5:5 -e 8r8g8b.tga "5r5g5b.tga,16"
  603.     Error diffuse from 24 bit RGB to 15 bit RGB
  604.     (bottom 3 bits of each of R,G and B become zero)
  605.     Output option ",16" ensures data written in Targa-16 form
  606.     This reduces wasted disk space.
  607.  
  608. gbmbpp -m freq8:8:8:240 24bit.bmp 8bit.bmp
  609.     Finds 240 most frequently used colours.
  610.     For other colours finds closest match in most common 240 colours.
  611.     Maps colours in 24bit.bmp to give 8 bit output file.
  612.     If excessively large number of colours in original, may truncate bits.
  613.  
  614. gbmgamma -m i_to_l raytrace.bmp pmsuited.bmp
  615.     raytrace.bmp has pixels values proportional to physical intensity.
  616.     pmsuited.bmp is made with pixels proportional to perceived intensity.
  617.  
  618. gbmcpal -m freq6:6:6:256 0 360 10 globe%03d.bmp cpal%03d.bmp
  619.     Read globe000.bmp, globe010.bmp, ... globe350.bmp.
  620.     Compute a common shared palette.
  621.     Map each globeXXX.bmp file to a cpalXXX.bmp file.
  622.  
  623. gbmvfsa -p 0 100 1 frame%03d.bmp
  624.     Display frame000.bmp, frame001.bmp, ... frame099.bmp in a full screen
  625.     OS/2 Session using the 320x200 8bpp VGA screen mode.
  626.     The -p says to gbmvfsa that all the bitmaps share a common palette,
  627.     and so it only needs to set the palette when the first bitmap is loaded.
  628.  
  629.  
  630. Source code
  631. -----------
  632.  
  633. The main part of GBM is highly portable 32 bit C, and has been compiled on
  634. OS/2 2.x, AIX 3.2.5 and other systems. Certain associated parts, notably GBMV,
  635. GBMV2 and GBMVFSA programs are OS/2 dependant. Full source to these should
  636. be available where you obtained this package.
  637.  
  638. Before compiling on OS/2, copy the os2 subdirectory to its parent. Similarly
  639. for any other operating system.
  640.  
  641. The source code is folded, and was written using Andys Source Code Folding
  642. Editor, which is also public domain, and should hopefully be available where
  643. you obtained GBM.
  644.  
  645.  
  646. Public domain declaration
  647. -------------------------
  648.  
  649. I wrote all this code in my own time on my own equiptment.
  650. I used public non-confidential information to do so.
  651. I hereby place all this code into the public domain.
  652. Feel free to do whatever you like with it.
  653. No copyright / no royalties / no guarantees / no problem.
  654. Caveat Emptor!
  655.  
  656.  
  657. Obtaining this code
  658. -------------------
  659.  
  660. Internet: ftp.cdrom.com:    /pub/os2/2_x/graphics/gbm.zip
  661.           ftp.cdrom.com:    /pub/os2/2_x/graphics/gbmsrc.zip
  662.           ftp-os2.nmsu.edu: /pub/os2/2_x/graphics/gbm.zip
  663.           ftp-os2.nmsu.edu: /pub/os2/2_x/graphics/gbmsrc.zip
  664. IBM-VNET: REQUEST GBM    FROM AKEY AT HVTVM5
  665.           REQUEST GBMSRC FROM AKEY AT HVTVM5
  666. Earlier releases have been on the IBM OS/2 Developer Connection CD-ROMs 2 & 3.
  667. Also found on the Hobbes OS/2 Shareware CD-ROM.
  668. This code may also be found on some BBSs, although I don't know which ones.
  669.  
  670.  
  671. Change Log
  672. ----------
  673.  
  674. 11/5/92        Initial general release.
  675.  
  676. Various dates    Fixed assorted bugs in, and speeded up, various parts of GBM.
  677.         Dropped support for 16 bit systems.
  678.         Changed all code to now be compiled multithreaded.
  679.         Changed GBM library to a DLL under OS/2, saved at least 500Kb.
  680.         /NOI now required when linking with GBM.LIB.
  681.         Added textual error messages.
  682.         Added GIF, X Bitmap and RiscOS Sprite support.
  683.         Extensively improved TIFF file support (now almost Baseline).
  684.         Extensively improved IFF support (HAM6, HAM8 etc.).
  685.         GBM structure enlarged => PLEASE RECOMPILE
  686.         Addition of bitmap transpose (and hence rotate) capability.
  687.         Added GBMV2.EXE, the flagship OS/2+PM program to show off GBM.
  688.         Handling of 1bpp data has changed - now honors colours.
  689.         Windows / (OS/2 2.0 subset) not OS/2 1.1 bitmaps now default.
  690.         Improved error checking some file readers.
  691.         Addition of -s and -g options to GBMHDR.EXE.
  692.         Added GBMWPOBJ.CMD to set up Workplace Shell Objects.
  693.  
  694. 29/11/93    Sanitised documentation
  695.         Copy supplied to IBM OS/2 Developer Connection.
  696.  
  697. 6/2/94        Removed max number of strips limitation in TIFF reader.
  698.         Added TIFF LZW encode option (alpha-level code).
  699.         Added percentage on GBMHDR.EXE listing.
  700.  
  701. 1/4/94        Bugfix for speckley IFF file writing.
  702.         Bugfix for map to black and white.
  703.         Added support for PSEGs
  704.  
  705. 18/4/94        Added GBMSCALE.LIB and GBMSIZE.EXE to resize bitmaps.
  706.         Rewrote a large chunk of GBMV2.EXE.
  707.         Added Paste, Resize... and Snapshot capability.
  708.         Added reflect selection only etc. capability
  709.         Removed Select All (now not required).
  710.  
  711. 3/5/94        Added GBMMCUT.LIB to implement median-cut algorithm.
  712.         Made GBMBPP.EXE and GBMV2.EXE able to do median-cut.
  713.         Split GBMHIST.LIB to enable multiple bitmap usage.
  714.         Added GBMCPAL.EXE to map multiple bitmaps to a common palette.
  715.         Added GBMVFSA.EXE to view multi-bitmap full screen animations.
  716.         Added export to PM Metafile (& via clipboard) for GBMV2.EXE.
  717.         Improved documentation.
  718.  
  719. 27/6/94        -m rofreqR:G:B:N:N2 and -m romcutN:N2 options to GBMCPAL.EXE.
  720.         RLE colour mapped, RLE RGB and 8bpp grey Targa loading support.
  721.         Change to Targa file writer to account for CJPEG reader feechur.
  722.         Commonised up source in GBM.DLL.
  723.         Bugfix for some widths of IFF/ILBM file.
  724.  
  725. 1/8/94        Faster/better LZW algorithm for GIF and TIFF writers.
  726.  
  727. Future?        Palette Manager capability in GBMV.EXE and GBMV2.EXE?
  728.         Non-scaled and fixed scale print for GBMV2.EXE?
  729.         Special logic for print to 1bpp and 3bpp printers for GBMV2.EXE?
  730.         JPEG, Photo-CD, RLE-Bitmap, G3-TIFF, G3-Bitmap for GBM.DLL?
  731.  
  732. {{{ Andy Key
  733.  
  734. Internet: ak@vnet.ibm.com    # Currently working at IBM until September 94
  735. IBM-VNET: AKEY AT HVTVM        # so addresses valid at least until then.
  736.