home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 1 / GoldFishApril1994_CD2.img / d4xx / d436 / lhlib / lh.doc < prev    next >
Text File  |  1991-01-15  |  17KB  |  394 lines
  1. ===========================================================================
  2. ================================= Lh v1.8 =================================
  3. ===========================================================================
  4.         A data compression system for the Commodore Amiga computer
  5.            written by Holger P. Krekel and Olaf 'Olsen' Barthel
  6.                   © Copyright 1990, all rights reserved.
  7.  
  8. ============================== What is `Lh'? ==============================
  9. ===========================================================================
  10. Do  you  know LhArc?  If you do, you will probably remember the compression
  11. ratio  (astonishing!)  and  the  time  required  for  data  compression and
  12. decompression (a lot!).
  13.    It  took  us  more than three months to create an MC680x0 version of the
  14. data compression / decompression routines (we have `baptized' the resulting
  15. package  "Lh").   Special  stress  has been put on two features:  speed and
  16. efficiency.   Lh  is much faster than any other implementation of the LhArc
  17. data  compression  /  decompression routines and generates about 2% smaller
  18. data files.  Unfortunately, the data files are incompatible with the output
  19. produced  by  the  standard  LhArc  routines,  i.e.   data  files cannot be
  20. exchanged between both implementations.
  21.  
  22. ============================ Performance of Lh ============================
  23. ===========================================================================
  24. The  following  tables  give a brief overview on the performance of Lh.  We
  25. compared  Lh  to  the following popular data compression programs:  LhArcA,
  26. The  Imploder  & PowerPacker.  `Compression' and `Decompression' denote the
  27. time  required  to execute the approriate action.  The duration is given in
  28. minutes.
  29.  
  30. 1. Picture, 320x256, (32 colours), hand-drawn, 1 pixel = 1 byte
  31. ---------------------------------------------------------------
  32. Input length in bytes: 81920
  33.  
  34.              Output Compression Decompression
  35. Lh           11838  01:56       00:01
  36. LhArcA       11849  02:04       00:10
  37. The Imploder 13076  01:41       00:01
  38. PowerPacker  14868  00:30       00:01
  39.  
  40. 2. Picture, 320x256, (32 colours), hand-drawn, bitplanes
  41. --------------------------------------------------------
  42. Input length in bytes: 51200
  43.  
  44.              Output Compression Decompression
  45. Lh           13870  01:27       00:02
  46. LhArcA       14041  02:40       00:10
  47. The Imploder 15342  02:40       00:01
  48. PowerPacker  15840  00:27       00:01
  49.  
  50. 3. Picture, 640x400, (16 colours), sampled, 1 pixel = 1 byte
  51. ------------------------------------------------------------
  52. Input length in bytes: 256000
  53.  
  54.              Output Compression Decompression
  55. Lh           76428  03:01       00:06
  56. LhArcA       77970  04:05       00:38
  57. The Imploder 93152  09:12       00:08
  58. PowerPacker  90728  02:20       00:08
  59.  
  60. 4. Picture, 640x400, (16 colours), sampled, bitplanes
  61. -----------------------------------------------------
  62. Input length in bytes: 128000
  63.  
  64.              Output Compression Decompression
  65. Lh           81886  01:02       00:09
  66. LhArcA       81580  01:42       00:44
  67. The Imploder 93152  09:12       00:02
  68. PowerPacker  86956  01:52       00:06
  69.  
  70. 5. Executable file, Amiga-hunk format
  71. -------------------------------------
  72. Input length in bytes: 130964
  73.  
  74.              Output Compression Decompression
  75. Lh           71330  01:07       00:08
  76. LhArcA       77970  01:48       00:34
  77. The Imploder 73172  08:23       00:03
  78. PowerPacker  74208  01:40       00:06
  79.  
  80. 6. ASCII file
  81. -------------
  82. Input length in bytes: 81627
  83.  
  84.              Output Compression Decompression
  85. Lh           32596  00:35       00:04
  86. LhArcA       33091  00:54       00:17
  87. The Imploder 37166  03:50       00:02
  88. PowerPacker  38700  00:39       00:03
  89.  
  90. ============================ Supplied material ============================
  91. ===========================================================================
  92.                 This package includes the following files:
  93.  
  94.       Lh.doc ......... The file you are currently reading.
  95.  
  96.       lh.library ..... Amiga shared-reentrant runtime library containing
  97.                        compression / decompression and auxilary routines.
  98.       lhglue.lib ..... Library glue routines (blink/ln format).
  99.       LhGlue.LZH ..... Library glue source codes.
  100.       lhlib.h ........ Library support header file.
  101.       lh_lib.fd ...... Library function definitions.
  102.  
  103.       Decode.bin ..... Decompression routines in raw binary format.
  104.  
  105.       LhDecode ....... Demonstration data decompression tool.
  106.       LhDecode.c ..... Source code for the above.
  107.       LhEncode ....... Demonstration data compression tool.
  108.       LhEncode.c ..... Source code for the above.
  109.       MakeFile ....... Script file to create the demonstration tools.
  110.       PreInclude.c ... Global definitions and includes (to be precompiled).
  111.  
  112. ================================== Usage ==================================
  113. ===========================================================================
  114. As  shown above, Lh is based on two files:  the library which contains both
  115. the  compression  and  the  decompression  routines  as  well  as  auxilary
  116. routines.   Decode.bin  has been included for assembly language programmers
  117. who  want  to take advantage of Lh in standalone applications which are not
  118. to require the library.
  119.    In order to use the routines, your application has to open lh.library by
  120. calling  OpenLibrary.   The current library revision supports four standard
  121. functions which are described below:
  122.  
  123.                                      *
  124.  
  125. CreateBuffer - Allocate auxilary buffers required by the compression and
  126.                decompression routines.
  127.  
  128. Usage: LhBuffer = CreateBuffer(OnlyDecode)
  129.           D0                       D0
  130.  
  131.    This function call allocates and initializes an LhBuffer structure to be
  132. passed to the data compression / decompression routines.  In respect to the
  133. library  routine to call with the buffer structure, `OnlyDecode' can be set
  134. to  TRUE  if  a  small  buffer  (4500  bytes  in  the  current  revision of
  135. lh.library) is required for data decompression.  Pass FALSE to CreateBuffer
  136. to  allocate  a  larger  buffer  (40000  bytes  in  the  current release of
  137. lh.library)  suitable both for data compression and decompression.  A value
  138. of NULL (= 0) is returned if the memory allocation fails.
  139.  
  140.                                      *
  141.  
  142. DeleteBuffer - Free auxilary buffers allocate by CreateBuffer
  143.  
  144. Usage: DeleteBuffer(LhBuffer)
  145.                        A0
  146.  
  147.    Passing  an  LhBuffer  structure previously allocated by CreateBuffer to
  148. this routine will free all associated resources.
  149.  
  150.                                      *
  151.  
  152. LhEncode - Perform adaptive Lempel-Ziv-Huffman data compression
  153.  
  154. Usage: Size = LhEncode(LhBuffer)
  155.         D0                A0
  156.  
  157.    The  real  data  compression  is  handled  by this routine.  The calling
  158. parameter  is an LhBuffer structure as initialized by CreateBuffer.  It has
  159. the following format:
  160.  
  161.         struct LhBuffer
  162.         {
  163.         /* 0*/  APTR  lh_Src;
  164.         /* 4*/  ULONG lh_SrcSize;
  165.  
  166.         /* 8*/  APTR  lh_Dst;
  167.         /*12*/  ULONG lh_DstSize;
  168.  
  169.         /*16*/  APTR  lh_Aux;
  170.         /*20*/  APTR  lh_AuxSize;
  171.  
  172.         /*24*/  ULONG lh_Reserved;
  173.         };
  174.  
  175. lh_Src ........ Points to the beginning of the memory region to compress.
  176. lh_SrcSize .... Denotes the size of the source memory region.
  177.  
  178. lh_Dst ........ Points to the beginning of the memory region  to  send  the
  179.                 compressed data to.
  180.  
  181.                 NOTE: 1) lh_Src and lh_Dst _M_U_S_T_ _N_O_T_ overlap!
  182.  
  183.                       2) The size of the memory region pointed to by lh_Dst
  184.                          MUST  be  1/8  larger  than  the  size  stored  in
  185.                          lh_SrcSize!
  186.  
  187. lh_DstSize .... Size of the memory region to send the compressed data to.
  188.  
  189. lh_Aux,
  190. lh_AuxSize .... Private data, DO NOT TOUCH!
  191.  
  192. lh_Reserved ... Currently unused, leave it zero.
  193.  
  194.    The  size  of  the compressed data will both be stored in lh_DstSize and
  195. returned  in  D0.   In  its worst case, the compressed data will become 1/8
  196. longer  than the source data which is the reason why the destination memory
  197. region has to be exactly 1/8 larger than the source region.  If you fail to
  198. add this safety-distance innocent memory may be overridden!
  199.    This  function  call  returns  zero  (=  0)  if the LhBuffer hasn't been
  200. initialized correctly or the buffer allocated by CreateBuffer is too small.
  201.  
  202.                                      *
  203.  
  204. LhDecode - Perform adaptive Lempel-Ziv-Huffman data decompression
  205.  
  206. Usage: Size = LhDecode(LhBuffer)
  207.         D0                A0
  208.  
  209. The  real  data  decompression  is  handled  by  this routine.  The calling
  210. parameter  is  an  LhBuffer  structure  as  initialized by CreateBuffer and
  211. listed below:
  212.  
  213.         struct LhBuffer
  214.         {
  215.         /* 0*/  APTR  lh_Src;
  216.         /* 4*/  ULONG lh_SrcSize;
  217.  
  218.         /* 8*/  APTR  lh_Dst;
  219.         /*12*/  ULONG lh_DstSize;
  220.  
  221.         /*16*/  APTR  lh_Aux;
  222.         /*20*/  APTR  lh_AuxSize;
  223.  
  224.         /*24*/  ULONG lh_Reserved;
  225.         };
  226.  
  227. lh_Src ........ Points to the beginning of the memory region to decompress.
  228. lh_SrcSize .... Denotes the size of the source memory region.
  229.  
  230. lh_Dst ........ Points to the beginning of the memory region to send the
  231.                 decompressed data to.
  232.  
  233.                 NOTE: The size of the memory region pointed  to  by  lh_Dst
  234.                       MUST be larger than or equal  to  the  original  size
  235.                       of the data before compression.
  236.  
  237. lh_DstSize .... Size of the memory region to send the decompressed data to.
  238.  
  239. lh_Aux,
  240. lh_AuxSize .... Private data, DO NOT TOUCH!
  241.  
  242. lh_Reserved ... Currently unused, leave it zero.
  243.  
  244.    The  size of the decompressed data will both be stored in lh_DstSize and
  245. returned in D0.
  246.    This  function  call  returns  zero  (=  0)  if the LhBuffer hasn't been
  247. initialized correctly.
  248.  
  249.                                      *
  250.  
  251.    Do not allocate an LhBuffer of your own and do not peek or poke into the
  252. private  fields  following  the  public  portion of the LhBuffer structure!
  253. Future  library  versions  may  support  more  structure  tags  or  require
  254. less/more memory for data compression / decompression.
  255.    As  far  as  error  checking  is  possible  within  the library, illegal
  256. arguments  (such  as passing NULL to a library function or leaving parts of
  257. the  LhBuffer structure uninitialized) are rejected.  Bear the notes on the
  258. lh_Dst  memory  region  in  mind  to  avoid  unexpected  results and system
  259. crashes!
  260.    Due  to  limitations in the tree structure built by the data compression
  261. routine  more  than 65535 equal bytes in a row can - but need not - lead to
  262. problems.   The  same  difficulties  arise with the original LhArc program.
  263. The  most  imminent tree construction error to be found in the original 'C'
  264. program has been fixed in Lh.
  265.    As  a  rule of thumb, the longer the data compression takes, the smaller
  266. the resulting compressed data file will become.
  267.  
  268.    Examples  how  to  access  the lh.library routines from 'C' are supplied
  269. through  `LhEncode.c'  and  `LhDecode.c'.  Both programs have been compiled
  270. using  the  Manx Aztec 'C' Compiler version 5.0d and require arp.library to
  271. run.  Feel free to send us assembly language demonstration programs.
  272.  
  273. ========================== How to use Decode.bin ==========================
  274. ===========================================================================
  275. The Decode.bin data file was added to support standalone applications which
  276. are  not to require the library to perform data decompression.  The file is
  277. a raw dump of the assembly language decompression routine which can also be
  278. found  in the library (i.e.  it obeys the Amiga library calling conventions
  279. in  preserving  all  registers  except  for  d0/d1  and a0/a1).  Result and
  280. calling  parameter  are the same as with LhDecode.  Note that you will have
  281. to  initialize  the auxilary decompression buffer on your own.  The pointer
  282. to  the  buffer  immediately  follows  lh_DstSize and must be at least 4500
  283. bytes  in  size.   The  single  decompression  routine does not require the
  284. Reserved long word.
  285.    Since   the   decompression   routine  uses  pc-relative  adressing  and
  286. pc-relative  branches  only  it  can  be  freely relocated and moved to any
  287. memory location.  The raw code will work fine on any MC680x0 based computer
  288. system (Apple MacIntosh, NeXT, SUN workstations, Atari ST/TT, etc.).
  289.    Here's the beef, an example assembly fragment follows:
  290.  
  291.    ; This is just an example, don't expect too much!
  292.  
  293.    ; Decode - Decode data previously encoded by LhEncode
  294.  
  295.    ; Inputs:  d0 - size of source region
  296.    ;          a0 - pointer to source region
  297.    ;          a1 - pointer to destination region
  298.    ;          a2 - pointer to beginning of auxilary buffer (4500 bytes)
  299.    ;
  300.    ; Outputs: d0 - size of destination region (after decompression)
  301.  
  302.    ; Note:    Previous contents of d0/d1, a0/a1 must be considered
  303.    ;          gone.
  304.  
  305.    Decode: clr.l   -(sp)         ; Size of auxilary buffer (unused)
  306.            pea     (a2)          ; Auxilary buffer
  307.  
  308.            clr.l   -(sp)         ; Size of destination buffer (unused)
  309.            pea     (a1)          ; lh_Dst
  310.  
  311.            move.l  d0,-(sp)      ; lh_SrcSize
  312.            pea     (a0)          ; lh_Src
  313.  
  314.            lea     (sp),a0       ; At this point we have created a
  315.                                  ; properly initialized LhBuffer-
  316.                                  ; sized structure right on the stack.
  317.  
  318.            lea     DecodeDump,a1 ; DecodeDump is the starting address
  319.                                  ; of Decode.bin (can be located
  320.                                  ; anywhere).
  321.  
  322.            jsr     (a1)          ; Decompress data...
  323.  
  324.            lea     6*4(sp),sp    ; Restore previous stack pointer
  325.  
  326.            rts                   ; and return
  327.  
  328.    While the library code includes a couple of sanity checks the Decode.bin
  329. raw  code  is  the  bare-bone decompression routine only.  You will have to
  330. make  sure  that  the values you are calling the routine with make sense to
  331. avoid undefined behaviour.
  332.    Think  twice  before  using  the  raw  code instead of the library.  The
  333. library  code  can be shared by a number of applications while the raw code
  334. cannot.
  335.  
  336. ================================= Credits =================================
  337. ===========================================================================
  338. The  original  Lzhuf.c  adaptive  Huffman compression code was developed by
  339. Haruyasu Yoshizaki, thanks a lot for placing it in the public domain.
  340.  
  341. ============= Shareware fee & how to become a registered user =============
  342. ===========================================================================
  343. A good amount of time and work was required to create Lh and the associated
  344. utilities.   Needless  to say, we didn't do it just for fun.  Include Lh in
  345. any  program  which  has  need  of  it  but  don't  forget  us!  Any humble
  346. contribution  of  at  least,  say  15$  US  or  DM  20,-  will  insure your
  347. registration  (i.e.   you will receive Lh updates as they become available)
  348. and  encourage  us  to  continue working on Lh (we know that Lh can be made
  349. faster  and more efficient with a bit of extra work, but time - we both are
  350. students of Medical Informatics at Hildesheim, Germany - does currently not
  351. permit us to make severe enhancements).
  352.  
  353.   Please keep the following in mind if you include Lh in your program(s):
  354.  
  355. Public domain program - No need to register Lh with us as  long as  you  do
  356.                         not intend to make money with your program.
  357.  
  358. Shareware program     - Register Lh with us once to distribute an unlimited
  359.                         number of copies of your program.
  360.  
  361. Commercial program    - Lh will need to be licensed for each copy  of  your
  362.                         program.
  363.  
  364. Lh was written by Holger P.  Krekel & Olaf 'Olsen' Barthel.  Copyright 1990
  365. by  Holger  P.   Krekel  &  Olaf  'Olsen'  Barthel.   Shareware, all rights
  366. reserved.   No  guarantee of any kind is made that the program(s) described
  367. in  this  document  are  100%  reliable.  You use this material on your own
  368. risk.
  369.  
  370.                 Send suggestions and registration fees to:
  371.  
  372.                            Olaf 'Olsen' Barthel
  373.                              Brabeckstrasse 35
  374.                             D-3000 Hannover 71
  375.  
  376.                         Federal Republic of Germany
  377.  
  378.  
  379. =============== Revision history (most recent change first) ===============
  380. ===========================================================================
  381.  
  382. V1.8    Bumped the minimum sequence length LhEncode starts to compress to 2
  383.         bytes which makes compression both faster and more efficient.
  384.  
  385. V1.7    First public release.
  386.  
  387. V1.0-   Not released.
  388.  
  389.                                   *
  390.  
  391.              Do only its possibilities make it an Amiga?
  392.  
  393.                         WHERE IS THE MAGIC ???
  394.