home *** CD-ROM | disk | FTP | other *** search
/ Dream 52 / Amiga_Dream_52.iso / RiscOS / PRATIQUE / GZIPSA.ZIP / GZipSa / !gzip / LZW / Docs / Guide / Guide~
Text File  |  1993-06-30  |  6KB  |  141 lines
  1. _______________________________________________________________________________
  2.  
  3. LZW 1.02 (and LZWD 1.03)                     ---------------------------------
  4.                                               These modules are PUBLIC DOMAIN
  5. Version date : 04 Oct 1990                   ---------------------------------
  6.  
  7. ----------------
  8. - Introduction -
  9. ----------------
  10.  
  11. LZW and LZWD are utility modules, which will compress and decompress files.
  12.  
  13. As their names suggest, they use the LZW (Lempel-Zev-Welch) compression
  14. algorithm, which (in one or more variations) is also used in many other file
  15. compression utilities (like ARC/SPARK) and several graphics formats (like GIF
  16. and TIFF).
  17.  
  18. LZW compression can easily achieve more than 50% compression on average
  19. text or mildly to heavily redundant data files and the like.
  20.  
  21. In fact, the variation used in LZW and LZWD is identical to the one used in
  22. GIF files (but without block counts). Compression is up to 12-bit codes,
  23. there's no adaptive reset, and 2 special codes are used to reset the string
  24. table and to signal the end of the data stream.
  25.  
  26. LZW and LZWD are written to be *FAST*. The algorithms are coded in heavily
  27. optimized ARM code.
  28.  
  29. In situations where ARC is unusable, and only 1 file is involved, LZW and LZWD
  30. can be very useful. The speed of (de)compression is many times that of
  31. ARC/SPARK.
  32.  
  33. ---------
  34. - Usage -
  35. ---------
  36.  
  37. To use the modules, simply *RMLoad or *RMRun them. LZW will claim 69K for
  38. (de)compression tables, in/output buffers and internal variables. LZWD claims
  39. only 19K RMA space, so it will consume a minimum of precious memory in
  40. 'crunched' applications using LZW-compressed files.
  41.  
  42. LZW, the main utility, will compress from file/memory to file/memory (i.e.
  43. file to file, file to memory, memory to file or memory to memory). When
  44. compressing/decompressing from file to file, the file's load address,
  45. execution address and attributes will be preserved/restored.
  46.  
  47. LZWD will only decompress from file to memory, but is optimized (i.e. it
  48. does this faster than LZW, though only about 25%).
  49.  
  50. Access is via a set of SWI calls. The prefixes indicate in which module
  51. (LZW or LZWD) the SWI is located.
  52.  
  53. LZW_Compress (&CD000)
  54. ---------------------
  55. Compresses a block of data. The source and destination may both be either a
  56. file, or a block of memory.
  57.  
  58. On entry : - r0 contains flags
  59.              bit 0 : 1 = source in memory (r1=address,r3=length)
  60.                      0 = source in file (r1=pointer to filename)
  61.              bit 1 : 1 = destination in memory (r2=address,r4=length)
  62.                      0 = destination in file (r2=pointer to filename)
  63.            - r1 contains source address or pointer to source filename
  64.            - r2 contains destination address or pointer to destination filename
  65.            - r3 (if source in memory) contains length of source in bytes
  66.            - r4 (if destination in memory) contains length of destination
  67.                 buffer in bytes
  68.  
  69. On exit  : - r0 is corrupted, or contains error pointer (V set)
  70.            - r5 (if destination is in memory) contains length of result data
  71.                 in bytes, otherwise it is corrupted
  72.            - all other registers are preserved
  73.  
  74. If the destination is in memory, and the result data overflows the
  75. destination buffer (i.e. >r3 bytes), a 'Memory overflow' error is generated.
  76. This is probably better than not checking and risking 'Aborts'. Still, if you
  77. need to 'skip' the check, set r3 to 'overkill' of 16Mbytes.
  78.  
  79.  
  80. LZW_Decompress (&CD001)
  81. -----------------------
  82. Is identical to LZW_Compress, but decompresses a block of data.
  83.  
  84.  
  85. LZW_CompressOn (&CD002)
  86. -----------------------
  87. As LZW_Compress, but appends the compressed data to an existing destination
  88. file.
  89.  
  90.  
  91. LZWD_Decompress (&CD100)
  92. ------------------------
  93. Decompresses a block of data. The source is a file, and the destination is
  94. a block of memory.
  95.  
  96. On entry : - r0 contains pointer to source filename
  97.            - r1 contains destination address
  98.            - r2 contains length of destination in bytes (*not* used currently,
  99.              there is no 'Memory overflow' error when exceeded, as when using
  100.              the LZW_ equivalent)
  101.  
  102. On exit  : - r0 is corrupted, or contains error pointer (V set)
  103.            - r2 contains length of result data in bytes
  104.            - all other registers are preserved
  105.  
  106. LZWD_Decompress is about 25% faster than the equivalent LZW_Decompress. This
  107. is because decompression to memory can be done faster. LZW uses a 'common
  108. denominator' routine which can decompress to both file and memory.
  109.  
  110.  
  111. -----------------
  112. - Final remarks -
  113. -----------------
  114.  
  115. If you have complaints, comments or bugs(!) to offer me, write to :
  116.  
  117. John Kortink
  118. Middelhuisstr. 17
  119. 7482 EL Haaksbergen
  120. The Netherlands
  121.  
  122. or send email to kortink@utrcu1.uucp
  123.  
  124. It is not very likely that new versions of these modules will appear. They
  125. serve a (simple) purpose. If you can't use them in their present form (or if
  126. you want a WIMP environment, or other fancy additions), you're probably on
  127. your own, though you are free to contact me at the above address with your
  128. suggestions. Maybe you can persuade me ...
  129.  
  130. _______________________________________________________________________________
  131.  
  132. !!! NOTE !!!
  133.  
  134. You may NOT change these modules or use ANY part of them in other products
  135. without my approval. You may spread them freely (with *ALL* files included),
  136. but not for any profit. This software is provided 'as is'. Using it is
  137. entirely at your own risk.
  138.  
  139. _______________________________________________________________________________
  140.  
  141.