home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional / OS2PRO194.ISO / os2 / graphic / csg_rt / gbm.txt < prev    next >
Text File  |  1993-04-18  |  12KB  |  237 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: 1.1, note win=2.0)
  19.     Note when OS/2 2.0 becomes more prevalent that OS/2 1.x, the
  20.     default output option will become 2.0 bitmaps.
  21.     There is confusion as to which way round 1bpp palette entrys go.
  22.     Foreground and background colours in palette can be inverted on input.
  23.         Input options: inv
  24.     Foreground and background colours in palette can be inverted on output.
  25.         Output options: inv
  26.     Foreground and background colours in bits can be inverted on input.
  27.         Input options: invb
  28.     Foreground and background colours in bits can be inverted on output.
  29.         Output options: invb
  30.  
  31. GIF : CompuServe Graphics Interchange Format : .GIF
  32.     Reads 1, bit data files.
  33.     Reads 2, 3 and 4 bit data files and presents them as 4 bit.
  34.     Reads 5, 6, 7 and 8 bit data files and presents them as 8 bit.
  35.     Writes 1, 4 and 8 bit data files.
  36.     Reads "GIF87a" and "GIF89a" style files.
  37.     Writes "GIF87a" style files.
  38.     Should correctly handle deferred clear-code in LZW data stream.
  39.     Will not generate output with deferred clear-code.
  40.     ie: should not break older GIF readers.
  41.     Can specify index of image within file on read.
  42.         Input option: index=# (default 0)
  43.     Can specify to return decoded data so far rather than error if corrupt.
  44.         Input option: errok
  45.     Can specify screen size to write in output screen descriptor.
  46.         Output options: xscreen=#,yscreen=# (defaults: image size).
  47.     Can specify background colour index to write in file BMHD header.
  48.         Output option: background=# (default: 0)
  49.     Can specify position information in output image descriptor.
  50.         Output options: xpos=#,ypos=# (defaults: 0,0).
  51.     Tested on selection of .GIF files from starbase1.austin.ibm.com.
  52.     Also tested with output of public domain PPMTOGIF.EXE.
  53.     Compatibility tested with xloadimage and xv.
  54.  
  55. PCX : ZSoft PC Paintbrush Image format : .PCX
  56.     Reads and writes 1,4,8 and 24 bit colour files.
  57.     Subset of plane/bits-per-plane combinations supported.
  58.     Files are read and written using a run-length coding scheme.
  59.     Tested using Zsoft originated .PCX files.
  60.     Compressed runs of pixels are not supposed to straddle scan lines.
  61.     GBM never does this, but some other applications violate this rule.
  62.     By default, if GBM finds that a run of pixels is longer than the scan
  63.     line, it will use the leftover pixels on the next scan line.
  64.     Some images will not load properly, as they require the loading
  65.     program to discard those pixels in the run that extend beyond the end
  66.     of the scan line. This behaviour can be enabled in GBM.
  67.         Input option: trunc
  68.  
  69. TIFF : Microsoft/Aldus Tagged Image File Format support : .TIF
  70.     Reads and writes 1,4,8 and 24 bit colour files.
  71.     Reads uncompressed and Packbits compressed files only.
  72.     DANGER Currently has untested/unknown-sanity attempt at LZW decode.
  73.     Write uncompressed files only.
  74.     Can specify informational tags to append on output.
  75.         Output options: artist=,software=,make=,model=,host=,documentname=,pagename=,imagedescription=
  76.     Data is written out as a single large strip.
  77.     Does not understand tags added after TIFF 5.0 level.
  78.  
  79. Targa : Truevision Targa/Vista bitmap : .TGA .VST .AFI
  80.     Reads any uncompressed type as 8 bit or 24 bit.
  81.     Reads both yup and ydown files.
  82.     Writes out as 8 bit or 16,24,32 bit.
  83.         Output options: 16,24,32 (default 24)
  84.     Can be made to write yup and ydown files.
  85.         Output options: ydown,yup (default: yup)
  86.  
  87. ILBM : Amiga IFF / ILBM Interleaved bitmap format : .IFF .LBM
  88.     Reads 1 bit palettised files.
  89.     Reads 2,3 and 4 bit palettised files, returning them as 4 bit.
  90.     Reads 5,6,7 and 8 bit palettised files, returning them as 8 bit.
  91.     Writes 1,4 and 8 bit palettised colour files.
  92.     Understands the RLE compression scheme used.
  93.     Uses BMHD, CMAP and BODY sections of file only.
  94.     Only writes BMHD, CMAP and BODY sections in output files.
  95.     Can specify position information in file BHMD header.
  96.         Output options: xpos=#,ypos=# (defaults: 0,0).
  97.     Can specify transparent colour to write in file BMHD header.
  98.         Output option: transcol=# (default: 0)
  99.     Can specify aspect ratio to write in file BMHD header.
  100.         Output options: xaspect=#,yaspect=# (defaults: 1,1).
  101.     Can specify screen size to write in output BMHD header.
  102.         Output options: xscreen=#,yscreen=# (defaults: image size).
  103.     Note that when DeluxePaint etc. try to load an 8 bit IFF file, they
  104.     switch to a 32 colour (5 bit mode) and only read the 5 least
  105.     significant planes of the file - this generally looks yukky!
  106.     Tested using DeluxePaint sample bitmaps.
  107.  
  108. YUV12C : YUV12C M-Motion Frame Buffer : .VID
  109.     Reads files and presents data as 24 bit data.
  110.     Writes 24 bit data files by converting them into 12 bit YUV.
  111.     VID files MUST be a multiple of 4 pixels wide.
  112.     When writing a non-multiple of 4, the last 1, 2 or 3 pixels are lost.
  113.     Can specify image origin information in YUV12C header.
  114.         Output options: xpos=#,ypos=# (defaults: 0,0).
  115.     Tested using M-Control Program 2.0, Browser sample application.
  116.  
  117. Greymap : Portable Greyscale-map (binary P5 type) : .PGM
  118.     Credit for file format to Poskancer.
  119.     No palette present in file format.
  120.     Reads 8 bit grey scale files.
  121.     Writes red, green, blue plane or greyscale equivelent of 8 bit image.
  122.         Output options: r,g,b,k (default: k)
  123.  
  124. Pixmap : Portable Pixel-map (binary P6 type) : .PPM
  125.     Credit for file format to Poskancer.
  126.     Reads and writes 24 bit unpalettised RGB data files.
  127.  
  128. KIPS : IBM KIPS : .KPS
  129.     Reads 8 bit palettised files.
  130.     Will look for palette in .PAL file unless .KPL file specified.
  131.         Input options: pal,kpl (default: pal)
  132.     Writes 8 bit palettised files.
  133.     Will write palette in .PAL file unless .KPL file specified.
  134.         Output options: pal,kpl (default: pal)
  135.  
  136. IAX : IBM Image Access eXecutive : .IAX
  137.     Reads array as 8 bit greyscale.
  138.     File format does not hold image dimensions.
  139.     Hence code assumes width is 512 pixels unless overridden.
  140.         Input options: width=# (default: 512)
  141.     File format does not include palette.
  142.     Writes red, green, blue plane or greyscale equivelent of 8 bit image.
  143.         Output options: r,g,b,k (default: k)
  144.  
  145. XBitmap : X Windows bitmap : .XBM
  146.     Reads 1bpp X bitmaps, presenting 1's as black, 0's as white.
  147.     Writes 1bpp X bitmaps, darkest colours as 1's, brightest colour as 0's.
  148.     Tested upon some .XBM files obtained from spock.hursley.ibm.com
  149.  
  150.  
  151. Sample Applications
  152. -------------------
  153.  
  154. GBMHDR - Display header information from bitmap files
  155.  
  156. usage: gbmhdr {filename.ext{,opt}}
  157. flags: filename.ext  input filename (ext used to guess bitmap file format)
  158.                      Bitmap when ext in [BMP VGA BGA RLE DIB RL4 RL8]
  159.                      GIF when ext in [GIF]
  160.                      PCX when ext in [PCX]
  161.                      TIFF when ext in [TIF]
  162.                      Targa when ext in [TGA VST AFI]
  163.                      ILBM when ext in [IFF LBM]
  164.                      YUV12C when ext in [VID]
  165.                      Greymap when ext in [PGM]
  166.                      Pixmap when ext in [PPM]
  167.                      KIPS when ext in [KPS]
  168.                      IAX when ext in [IAX]
  169.                      Xbitmap when ext in [XBM]
  170.        opt           bitmap format specific option to pass to bitmap reader
  171.  
  172.     Note that the GBM module only ever surfaces the size and bits per pixel
  173.     of images (regardless of the other information present in the header).
  174.     All GBM programs have access to the bitmap file formats documented
  175.     above, although this list is omitted in subsequent documentation.
  176.  
  177. GBMREF - Reflect in horizontal and/or vertical directions
  178.  
  179. usage: gbmref [-h] [-v] [-t] fn1.ext{,opt} [fn2.ext{,opt}]
  180. flags: -h             reflect horizontally
  181.        -v             reflect vertically
  182.        -t             transpose x for y
  183.        fn1.ext{,opt}  input filename (with any format specific options)
  184.        fn2.ext{,opt}  optional output filename (or will use fn1 if not present)
  185.                       bitmap formats and options as before
  186.  
  187.     Certain non-obvious combinations of -h, -v and -t can be very usefull.
  188.     None of them    can be used for just file format translation.
  189.     -h -v        reflect both, equivelent to 180 degree turn
  190.     -h -t        equivelent to 90 degree turn clockwise
  191.     -v -t        equivelent to 90 degree turn anti-clockwise.
  192.  
  193. GBMSUB - Extract a subrectangle of a bitmap
  194.  
  195. usage: gbmsub [-x x] [-y y] [-w w] [-h h] fn1.ext{,opt} [fn2.ext{,opt}]
  196. flags: -x x           left edge of rectangle (default 0)
  197.        -y y           bottom edge of rectangle (default 0)
  198.        -w w           width of rectangle (default width of image - x)
  199.        -h h           height of rectangle (default height of image - y)
  200.        fn1.ext{,opt}  input filename (with any format specific options)
  201.        fn2.ext{,opt}  optional output filename (or will use fn1 if not present)
  202.                       bitmap formats and options as before
  203.  
  204.     If none of the -x,-y,-w and -h options are supplied the defaults
  205.     cover the whole of the input file. Hence this program will just read
  206.     one file and write the data as another. Great for format conversion.
  207.  
  208. GBMBPP - Do various bits per pixel conversions
  209.  
  210. usage: gbmbpp [-m map] [-e] [-h] fn1.ext{,opt} [fn2.ext{,opt}]
  211. flags: -m map         mapping to perform (default 7x8x4)
  212.                       bw           black and white
  213.                       vga          16 colour VGA
  214.                       8            8 colour (in 4 bit file)
  215.                       4g           4 bit greyscale
  216.                       7x8x4        7 levels red, 8 green, 4 blue 8514/A
  217.                       6x6x6        6 levels red, 6 green, 6 blue
  218.                       8g           8 bit greyscale
  219.                       tripel       64 reds, 64 greens, 64 blues tripel
  220.                       freqR:G:B:N  keep R red, G green, b blue bits, and map to
  221.                                    N most used colours in 8 bit palette
  222.                       R:G:B        keep R red, G green, B blue bits (eg: 8:8:8)
  223.        -e             enable error-diffusion (default is to truncate)
  224.                       -e not with -m 8g or tripel or freq or -h
  225.        -h             enable halftoning (default is to truncate)
  226.                       -h only with -m 7x8x4, 6x6x6, 8, vga or R:G:B, with no -e
  227.        fn1.ext{,opt}  input filename (with any format specific options)
  228.        fn2.ext{,opt}  optional output filename (or will use fn1 if not present)
  229.                       bitmap formats and options as before
  230.  
  231.     This program reads the input bitmap. If it is not 24 bit, then it is
  232.     expanded to 24 bit per pixel. The data is then processed using the
  233.     supplied mapping giving a 24,8,4 or 1 bit per pixel image, which is
  234.     then written to the output bitmap file. The bw mapping produces a 1
  235.     bpp output file, vga and 4g gives 4 bit output files, 7x8x4, 6x6x6, 8g,
  236.     freq and tripel give 8 bit output files. R:G:B (where R,G and B are
  237.     numbers in the range 0 to 8), gives a 24 bit output file wh1