home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / World_Of_Computer_Software-02-387-Vol-3of3.iso / t / tplzh025.zip / TPLZH.DOC < prev    next >
Text File  |  1993-03-10  |  15KB  |  402 lines
  1. ***********************************************************************
  2. Requestable from     : Joe Jared of 1:125/1212@Fidonet.ORG
  3.                        BBS (510) 834-6906 V.32bis/HST 8n1
  4.                        (European Guard tones enabled)
  5.  
  6. File request name    : TPLZH (Magic names only please)
  7. Discription          : (V0.26) Huffman Compression Engine w/TP {$O+} interface.
  8.                      : Atari ST/TT, and IBM.
  9.  
  10. Downloadable name    : TPLZH@##.SQZ where @ is the major release number and
  11.                        ## the minor release. The Squeeze-it compression
  12.                        utility is available by file request as SQZ.
  13.                        (Or download as SQZ*.EXE)
  14.  
  15. Topics:
  16. - What's new
  17. - How to use this utility in your programs
  18. - Legalities and distribution limitations
  19. - Version history: Refer to TPLZH.HST
  20.  
  21. ***********************************************************************
  22. -New in current release:
  23.  
  24.         Basis of comparison is RA.DOC (Remote Access 1.11 documentation)
  25.         being compressed on various processors.
  26.  
  27.         Input size:     306368 bytes
  28.         output size:    101639 bytes
  29.  
  30.         Encode Time:
  31.         33/68030
  32.         33/386              34.49
  33.         12/286              64.97
  34.         8/8086            227.06
  35.  
  36.         Decode time:
  37.         33/68030
  38.         33/386              6.65
  39.         12/286             13.19
  40.         8/8086             42.40
  41.  
  42. ***********************************************************************
  43.         V0.25 (TPLZH025.SQZ) or TPLZH025.exe
  44.  
  45.         Currently under developement is as follows:
  46.         68000 engine.
  47.  
  48. ***********************************************************************
  49. - Implementation: (IBM)
  50.  
  51.   The following is a basic structure of how the engine operates:
  52.  
  53.   ( Your program ) ------------\
  54.             |                   \---( Your program )
  55.             |            +-->(Your procedure for handling input buffer)
  56.             |            |    (These must be far procedures)
  57.             |            |+->(Your procedure for handling output buffer)
  58.             v            ||
  59.            (Huffman Compression Engine)
  60.  
  61.   It's generally a good idea to have some sort of display related function
  62.   in each of your iobuffer routines, and especially during initial setup.
  63.   In the examples, position progress reports keep the user from being bored.
  64.  
  65. Memory requirements:
  66.          Memory requirements are as follows:
  67.          {$M Stack, Minheap, Maxheap}
  68.          {$M 1024, 56000, 56000}
  69.  
  70.          (Lzhasm.obj)
  71.          Note: This does not include sample program space.
  72.          Codespace: 3693 bytes.
  73.          Dataspace: 12 bytes
  74.  
  75.          The stack is probably higher than necessary, but heap memory
  76.          is definately accurate. (Some space is currently reserved for
  77.          updates so there are no hassles Approximately 700 bytes)
  78.  
  79.          This unit is overlayable, and is designed to operate best when
  80.          overlayed.  (With minimum usage of data seg, it makes sense to
  81.          overlay the engine, because its entire process can be contained
  82.          in an overlay.)
  83.  
  84.  
  85.   The following system variables are available for your interface to play
  86.   with:
  87.   Routines available in the engine:
  88. Public    Decode, Encode   ; Encode for compression, Decode for decompression.
  89.  
  90. EXTERN   LZHMemSeg       : WORD      ; Heap pointer to LZH Structure.
  91. (Note: No offset, because the engine expects to have an Addr:0000h)
  92.  
  93. Note that both of these are FAR pointers to procedures.
  94. EXTERN   WriteFromBuffer : FAR PTR   ; External buffer handling.
  95. EXTERN     ReadToBuffer     : FAR PTR   ; External buffer handling.
  96.  
  97. EXTERN   LZHERROR        : WORD      ; Errorlevel return {Future use}
  98.  
  99. (Offset into LZHMem^. allocation)
  100. Text_Buf      equ 0              ; array[0..N + F - 2] of byte; 5155 bytes
  101. ; Text_buf is not a buffer you should care about.  It's placed in the top
  102. ; of the segment because it's most used.
  103. ; The following are variables you should care about.
  104. count         Equ Text_Buf +N+F         ;
  105. textsize      Equ Count+4                 ; LongInt = 0;
  106. textsize      Equ count +4                ; LongInt = 0;
  107. codesize      equ textsize +4             ; LongInt = 0;
  108. inptr         equ codesize +4             ; Word
  109. inend         equ inptr+2                 ; word
  110. outptr        equ inend+2                 ; Word
  111. outend        equ outptr+2                ; Word
  112. Ebytes        equ outend+2                ; LongInt = 0;
  113. Inbuf         equ Ebytes+4                ; IObuf
  114. Outbuf        equ Inbuf +2800h            ; IObuf
  115.  
  116.  
  117. ***********************************************************************
  118.  
  119. - Interfacing to Turbo Pascal:
  120. Const
  121.      N         = $1000            ; {Size of string buffer}
  122.      F         = 60               ; {60 Size of look-ahead buffer}
  123.  
  124. These constants are actually hard coded, but used for one important
  125. reason.  In various flavors of this engine, various buffer sizes are used.
  126. To provide multiple flavors means the N constant needs to be flexible
  127. in both the high level language and the low level intel-relocatable object
  128. file.  That is why the distributed engine is called '4k'.  The 8 bit
  129. variant of this engine is called 256-byte huffman compression, and produces
  130. about 9% less compression.
  131.  
  132.  
  133. type
  134.  
  135.   IObuf = array[0..$2800-1] of byte; {These buffers are now FIXED!}
  136.  
  137.   LZHRec = Record       {Segment:0 aligned}
  138.          WorkSpace1     : Array [0..N+F-1] of byte;
  139.          count          : LongInt;
  140.          textsize       : LongInt;
  141.          codesize       : LongInt;
  142.          inptr,inend,outptr,outend    : Word;
  143.          Ebytes         : Longint;
  144.          inbuf,outbuf        : IObuf;
  145.          {Buffersize and position are critical}
  146.          WorkSpace           : Array [0..$76c3] of byte;
  147.          {LZHASM work space} {Some space reserved}
  148.          End;
  149.  
  150.  {$L LZHASM}
  151.  
  152.     
  153.  
  154. var
  155.    StupidAlloc : Boolean;
  156.    StupidPtr    : Pointer;
  157.        These variable is to provide Segment:0 alignment for versions
  158.        of turbo Pascal prior to 6.0.  Refer to notes in InitLzh.
  159.     
  160.    WriteFromBuffer,
  161.    ReadToBuffer: Procedure;
  162.  
  163.    These variables should "point" to your procedures for reading and
  164.    writing of LZH compressed data.  Before calling any LZH Functions,
  165.    you must have the following lines of code in your routine, or some
  166.    function thereof:
  167.    {$F+}
  168.    Myprocwrite
  169.    {$F-}
  170.    begin
  171.    (Your procedure for handling data from LZHMem^.Inbuff)
  172.    end;
  173.  
  174.    Myprocread
  175.    {$F-}
  176.    begin
  177.    (Your procedure for handling data from LZHMem^.Outbuff)
  178.    end;
  179.  
  180.  
  181.    Your startup for your program should have:
  182.  
  183.    WriteFromBuffer := Myprocwrite;
  184.    ReadToBuffer := Myprocread;
  185.  
  186.    The actual procedure type MUST be a far Call, but the data within
  187.    the procedure may be near.
  188.  
  189.   IObuf = array[0..$2800-1] of byte; {These buffers are now FIXED!}
  190.  
  191.   For your reference, preceed all variables with "LZHMem^.".
  192.  
  193.   LZHRec = Record
  194.          count          : LongInt; {LZHMEM^.Count}
  195.         Current position of compression of input data.  This counter
  196.         will continue to count, until encode or decode is called again.
  197.  
  198.          textsize       : LongInt;
  199.          Size of input text data
  200.  
  201.          codesize       : LongInt;
  202.          Size of output code data.
  203.  
  204.         These variables are available to provide user interface for
  205.         ratios.
  206.  
  207.          inptr,inend,outptr,outend    : Word;
  208.  
  209.         Inptr points to the position of valid data in your input bufferm
  210.         as does outptr for your output buffer.  These are counters to
  211.         determine where in the appropriate buffer to place the next byte
  212.         of data, and how much of your buffer is valid data.
  213.         (See example LZ.PAS for details of implementation).
  214.  
  215.  
  216.         inend, Outend:
  217.  
  218.         These variables point to the last valid byte in the appropriate
  219.         buffer.  You MUST set these values to the pointer. You can
  220.         adjust the size that the engine thinks it has by adjusting these
  221.         values. (From 0..10239]
  222.         (Again see LZ.PAS for details)
  223.  
  224.  
  225.  
  226.          Ebytes         : Longint;
  227.          EBytes is a count of total bytes to compress.  You MUST set this
  228.          variable to the total number of bytes you wish to compress.
  229.  
  230.  
  231.          inbuf,outbuf        : IObuf;
  232.          These are input/output buffers for the compression engine.
  233.          In previous versions, these were seperate from LZHMem^, but it
  234.          seemed more practical to have one call to allocate memory. If
  235.          someone complains loud enough I'll "Put em back" to seperate
  236.          independent pointers.
  237.  
  238.  
  239.          WorkSpace           : Array [0..$8657] of byte;
  240.          {LZHASM work space}
  241.          This variable array is work space for LZHASM.OBJ.  Please do
  242.          not adjust it or change the data while encode or decode is
  243.          active. If you wish to keep the space active on your heap, you
  244.          can use it in between runs for other things.
  245.  
  246.          End;
  247.  
  248.  
  249.    LZHMem: ^LZHRec;
  250.    LZHMemSeg       : WORD;
  251.  
  252.         Notice that there is no offset variable.  This is intentional,
  253.         and the reason is simple:  SPEED!
  254.         In LZH.PAS, there is a sample routine for allocating memory that
  255.         is segment:0 aligned.  The difference in memory allocated using
  256.         this method is up to 32 bytes.
  257.         (For allocations of 55k, who cares!)
  258.                                 
  259.    procedure Encode ; compresses data
  260.    procedure Decode;  decompresses data
  261.    Procedure InitLZH; Segment:0 aligned memory allocation
  262.    Procedure DInitLZH; Memory de-allocation.
  263.  
  264.         (Pay attention to this section in future versions)
  265.         The proper sequence is as follows:
  266.  
  267.         Set writetobuffer and readfrombuffer to point to your procedures
  268.         for handling of buffer data.  Make sure that at bare minimum,
  269.         that the procedure "call" is of far type.  loops within the
  270.         procedure may be near type.
  271.         {$F+}
  272.          Procedure YourProc;
  273.          {$F-}
  274.  
  275.         InitLzh
  276.  
  277.         If compressing:
  278.         Set LZHMEM^.Ebytes to the size of the data you wish to compress.
  279.         (If compressing)
  280.  
  281.         Call encode to compress, or decode to decompress.
  282.  
  283.         The memory buffers will have the decompressed data, and your
  284.         procedures will then process the data as buffers are filled.
  285.  
  286. ***********************************************************************
  287. EXTREEMLY BETA...
  288. Implementation: 680x0 processors   (Preliminary)
  289. This is intended to suppliment the IBM notes.  All exceptions to IBM
  290. operations noted here.
  291.  
  292. Files:
  293.  
  294.  
  295.       LZHASM.O  -- Atari Standard Object file. (ST/TT)
  296.       LZ.PAS    -- sample implementation.
  297.  
  298.       Externals
  299.  
  300.       WFBUFFER
  301.       R2BUFFER
  302.  
  303.  
  304.  
  305.  
  306. ***********************************************************************
  307.  
  308. -Special design notes:
  309.  
  310.         This unit is specifically designed to be a portable unit for all
  311.         versions of Turbo Pascal. (It Should work for windows too.)
  312.         If this unit is modified in any way,
  313.         please keep backwards compatibility in mind.
  314.  
  315.         The following commands are identical in operations, although the
  316.         first listed command is portable only to turbo pascal 6.0 and
  317.         higher:
  318.  
  319.         AllocmemSeg( PointerToType,Sizeof(PointerToType^));
  320.  
  321.         Getmem(PointerToType,(Sizeof(PointerTotype)AND$FFF0)+16)
  322.  
  323.         If you use this unit, for all memory allocations you must use
  324.         the latter command, or modify your unit to use AllocMemSeg.
  325.  
  326. PLEASE DO NOT DISTRIBUTE THIS UNIT IF YOU MODIFY THE MEMORY ALLOCATION
  327. SECTION. ALLOCMEMSEG IS TP6.0 COMPATIBLE AND ABOVE, WHEREAS THIS UNIT IS
  328. COMPATIBLE WITH ALMOST ALL VERSIONS OF TURBO PASCAL.
  329.  
  330.  
  331. ***********************************************************************
  332. -Legalities:
  333.  
  334. -Compression of this archive:
  335.  
  336.         As far as compression type is concerned, I could personally care
  337.         less, as long as the software used to re-compress is freely
  338.         available.  Please to not re-compress this archive with
  339.         crippleware, and do not add useless banner files.
  340.  
  341.         The contents of this archive should contain the following:
  342.         + means compatible with language v x.xx and higher.
  343.  
  344.         .model small,pascal
  345.         LZHASM.OBJ   -=> The huffman compression object file (MSC 5.1+)
  346.  
  347.         TPLZH.HST    -=> Version history
  348.         TPLZH.DOC    -=> This document.
  349.  
  350.         LZ.PAS       -=> Sample TP 5.0+ version
  351.         LZH.PAS      -=> Base unit for all pascal platforms
  352.  
  353.         LZO.PAS      -=> OOPS examples for TP 6.0+
  354.         TESTLZO.PAS  -=> OOPS examples for TP 6.0+
  355.  
  356.         LZ.exe       -=> Compiled Lz.pas using Turbo Pascal 7.0
  357.  
  358.         680x0 related. (Preliminary)
  359.         lzh680x0.RAW -- Binary routines
  360.         Lzh680x0.inc -- Equates for offsets to encode and decode.
  361.         Lzh680x0.asm -- Sample initialization code
  362.  
  363.  
  364.         Anything additional shall be considered twit behavior.
  365.  
  366.         If this object is used in any utility you write for public
  367.         or commercial use, please give credit to the following people
  368.         in your documentation or credits banner (as applicable):
  369.  
  370.         (These people always)
  371.         Haruyasu YOSHIZAKI  : Original lharc program.
  372.         Kenji RIKITAKE      : English translation to C
  373.         Peter Sawatzki      : Pascal interface(TP 5.0+}
  374.         Wayne Sullivan      : Pascal interface(TP 5.0+)
  375.  
  376.         Joe Jared           : Assembler optimization {TP 5.0+}
  377.                             : Assembler routines for 680x0 machines.
  378.  
  379.         (These people as appropriate)
  380.         Andres Cvitkovich   : Object Oriented version (TP 5.5+)
  381.  
  382. -Distribution
  383.  
  384.         No fee may be charged for distribution of this package, and it
  385.         CANNOT be sold for any reason.  All code is property of the
  386.         developers listed.
  387.  
  388.         Exceptions:  The disk this program is on, may be sold for the cost
  389.         of the disk.  (Not to exceed $0.70)+exact mail costs if mailed.
  390.  
  391.         CD-ROM distribution.
  392.         Unrestricted, but please either download or freq the latest prior
  393.         to distribution.
  394.  
  395.         If in a shareware or commercial package, no additional charges may
  396.         be added for the use of this "module".
  397.  
  398.         This is a * militantly freeware * implementation of huffman
  399.         compression.
  400.  
  401. ***********************************************************************
  402.