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