home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / programming / libraries / pchglib14.lha / pchglib.doc < prev    next >
Encoding:
Text File  |  1992-11-15  |  12.0 KB  |  312 lines
  1. TABLE OF CONTENTS
  2.  
  3. pchg.lib/--background--
  4. pchg.lib/PCHG_CompHuffmann
  5. pchg.lib/PCHG_FastDecomp
  6. pchg.lib/PCHG_ParsePCHG
  7. pchg.lib/PCHG_SetUserCopList
  8. pchg.lib/PCHG_SHAM2PCHG
  9. pchg.lib/--background--                               pchg.lib/--background--
  10.  
  11.   The purpose of this library is to give programmers an easy way to
  12.   implement PCHG display technology in their programs. The library
  13.   allows to read and write easily PCHG chunks by providing
  14.   compression/decompression routines and CopperList building
  15.   functions.
  16.  
  17.   When reading PCHG chunks, you have three function you can use:
  18.   PCHG_ParsePCHG() will automagically parse the chunk (possibly using
  19.   decompression) and build the Copperlist for your ViewPort. If you're
  20.   using the ViewPort of an Intuition Screen, when you will call
  21.   CloseScreen() the Copperlist will be automatically deallocated.
  22.  
  23.   Otherwise, you can use PCHG_SetUserCopList(), which gives you a finer
  24.   control (for instance, you can build a Copperlist with an offset).
  25.   However, the chunk parsing is left to you, apart from the
  26.   decompression, which is handled by PCHG_FastDecomp(). This routine
  27.   is called with register parameter passing, so if you're not using
  28.   SAS C or Assembly, you'd better call PCHG_CFastDecomp(), which has
  29.   standard parameter passing.
  30.  
  31.   When writing a PCHG chunk, the function PCHG_CompHuffmann() will
  32.   pack with static Huffmann encoding your LINEDATA (i.e., the line mask
  33.   followed by a SmallLineChanges or BigLineChanges array, as from
  34.   the PCHG specification).
  35.  
  36.   Finally, the function PCHG_SHAM2PCHG() will build a fake PCHG chunk from
  37.   a SHAM chunk, making easy for people to partially support the old
  38.   "standard".
  39.  
  40.   There are two versions of this library: pchg.lib has stack parameter
  41.   passing, while pchgr.lib was compiled with the SAS/C -rr (registerized
  42.   parameter passing) option.
  43.  
  44.   The prototypes for pchg.lib can be found in clib/pchglib_protos.h, while
  45.   the general PCHG include file is iff/pchg.h.
  46.  
  47.   This library was written by Sebastiano Vigna, and it's placed in
  48.   the public domain.
  49.  
  50. pchg.lib/PCHG_CompHuffmann                         pchg.lib/PCHG_CompHuffmann
  51.  
  52.   NAME
  53.       PCHG_CompHuffmann -- Compress a memory block with static Huffmann
  54.  
  55.   SYNOPSIS
  56.       compData = CompHuffmann(Source, SourceSize, DataSize, TreeSize);
  57.  
  58.       UBYTE *PCHG_CompHuffmann(APTR, ULONG, ULONG *, ULONG *);
  59.  
  60.   FUNCTION
  61.       Compress a block of memory into the typical PCHG compression
  62.       format: static Huffmann encoding. A pointer to the compressed data
  63.       (tree+code) is returned. After use, the block of
  64.       *DataSize+*TreeSize length pointed by compData has to be
  65.       FreeMem()ed. The longword pointed by TreeSize will be set to the
  66.       number of bytes used by the tree coding, the one pointed by DataSize
  67.       to the number of bytes of Huffmann code (rounded to longword bounds).
  68.  
  69.   INPUTS
  70.       Source        - A pointer to the start of the data to be compressed.
  71.       SourceSize    - Size in bytes of the data to be compressed
  72.       DataSize      - A pointer to a longword that will receive the length
  73.                       in bytes of the data part of the compressed chunk.
  74.       TreeSize      - A pointer to a longword that will receive the length
  75.                       in bytes of the tree part of the compressed chunk.
  76.  
  77.   RESULT
  78.       compData      - A pointer to the compressed data (tree+data,
  79.                       *DataSize+*TreeSize bytes) or NULL if a
  80.                       memory allocation failed. You have to free
  81.                       this memory after you use it with a
  82.                       FreeMem(compData, *TreeSize+*DataSize).
  83.  
  84.   EXAMPLE
  85.  
  86.   NOTES
  87.  
  88.   BUGS
  89.  
  90.   SEE ALSO
  91.       PCHG_FastDecomp(), PCHG_CFastDecomp()
  92.  
  93. pchg.lib/PCHG_FastDecomp                             pchg.lib/PCHG_FastDecomp
  94.  
  95.    NAME
  96.        PCHG_FastDecomp -- Decompress a PCHG chunk, fast.
  97.  
  98.    SYNOPSIS
  99.        PCHG_FastDecomp(Source, Dest, TreeCode, OriginalSize);
  100.                         A0      A1      A2        D0
  101.  
  102.        VOID PCHG_FastDecomp(APTR, APTR, WORD *, ULONG);
  103.  
  104.        PCHG_CFastDecomp(Source, Dest, TreeCode, OriginalSize);
  105.  
  106.        VOID PCHG_CFastDecomp(APTR, APTR, WORD *, ULONG);
  107.  
  108.    FUNCTION
  109.        Unpack reasonably fast a PCHG chunk. This routine will
  110.        never bypass the OriginalSize limit while writing to
  111.        Dest.
  112.  
  113.    INPUTS
  114.        Source        - The PCHG compressed data (just after the
  115.                        PCHGCompHeader).
  116.        Dest          - A block of memory OriginalSize bytes long
  117.                        which will contain the unpacked data.
  118.        TreeCode      - A pointer to the last word of the code
  119.                        of the tree used when compressing the data.
  120.                        If you're unpacking a standard PCHG chunk,
  121.                        you should set this entry to
  122.                        (char *)(PCHGCompHeader+1)+PCHGCompHeader->TreeSize-2
  123.        OriginalSize  - The original length of the compressed data.
  124.                        If you're unpacking a standard PCHG chunk,
  125.                        you should set this entry to
  126.                        PCHGCompHeader->OriginalSize
  127.  
  128.    RESULT
  129.        None.
  130.  
  131.    EXAMPLE
  132.  
  133.    NOTES
  134.  
  135.    BUGS
  136.  
  137.    SEE ALSO
  138.  
  139. pchg.lib/PCHG_ParsePCHG                               pchg.lib/PCHG_ParsePCHG
  140.  
  141.   NAME
  142.       PCHG_ParsePCHG -- Parse a PCHG chunk and build Copperlist.
  143.  
  144.   SYNOPSIS
  145.       Error = PCHG_ParsePCHG(PCHG, ViewPort);
  146.  
  147.       LONG PCHG_ParsePCHG(struct PCHGHeader *, struct ViewPort *);
  148.  
  149.   FUNCTION
  150.       I-do-all-for-you function. PCHG_ParsePCHG() frees you from
  151.       every hassle. You simply pass it the content of the PCHG
  152.       chunk (i.e., what follows the IFF chunk size) and a pointer
  153.       to your ViewPort. The Copperlist will be built and stuffed in.
  154.  
  155.   INPUTS
  156.       PCHG          - A pointer to the contents of the PCHG chunk.
  157.       ViewPort      - A pointer to the ViewPort that will receive the
  158.                       Copperlist described in the PCHG chunk.
  159.  
  160.   RESULT
  161.       Error will be set to 0 if everything OK. Otherwise you can
  162.       the error listed in iff/pchg.h (PCHGERR_NOMEM, etc.).
  163.  
  164.   EXAMPLE
  165.  
  166.   NOTES
  167.       The Copperlist created by this function will be
  168.       automatically deallocated when you call CloseScreen() if
  169.       you're using the ViewPort of an Intuition Screen.
  170.       This function parses the chunk and then calls
  171.       PCHG_SetUserCopList(); thus, it needs grahics.library.
  172.       After calling it, you will probably need a RethingDisplay()
  173.       if you're using an Intuition Screen, or the suitable graphics
  174.       calls (MrgCop() etc.) if you're directly handling the
  175.       ViewPort.
  176.  
  177.   BUGS
  178.  
  179.   SEE ALSO
  180.       PCHG_SetUserCopList(), iff/pchg.h
  181.  
  182. pchg.lib/PCHG_SetUserCopList                     pchg.lib/PCHG_SetUserCopList
  183.  
  184.   NAME
  185.       PCHG_SetUserCopList -- Set a ViewPort Copperlist using a PCHG chunk
  186.  
  187.   SYNOPSIS
  188.       PCHG_SetUserCopList(Offset, Length, ViewPort, PCHG, LineMask, LineData)
  189. ;
  190.  
  191.       VOID PCHG_SetUserCopList(WORD, UWORD, struct ViewPort *,
  192.                                     struct PCHGHeader *, APTR, APTR);
  193.  
  194.   FUNCTION
  195.       Creates the Copperlist defined by a PCHG header and data. If a user
  196.       Copperlist is already defined on the ViewPort, it is first
  197.       deallocated. If Length is 0, every change specified by the PCHG
  198.       chunk will be generated. If Length is not 0, every change which
  199.       happens on a line in the range Offset<->Offset+Length will be
  200.       generated.  In each case, an offset equal to Offset is subtracted
  201.       from the PCHG indications. For instance, if Offset == 8, Length ==
  202.       10, the changes specified in the PCHG chunk for the line range 8-17
  203.       will happen on the line range 0-9. This allows setting a Copperlist
  204.       for a scrolled picture (i.e., the first displayed line is not the
  205.       first picture line). If Offset == 0, Length == ViewPort->DHeight, only
  206.       the changes which happen inside the ViewPort will be generated (with
  207.       no offset). Do NOT ask for odd offsets for a laced picture, because
  208.       of the well-known limitations of MrgCop(). Note that when Offset is
  209.       non-zero, this function will stuff via SetRGB4() all the changes which
  210.       happens before the Offset line, so that the image will be correctly
  211.       displayed. This however implies you have to reload the CMAP before each
  212.       call with an offset.
  213.  
  214.   INPUTS
  215.       Offset       - A positive offset which will be subtracted from the
  216.                      line specified by the PCHG->StartLine field.
  217.       Length       - A number of lines which will limit the
  218.                      Copperlist generation. Ignored if == 0.
  219.       ViewPort     - The ViewPort which will receive the Copperlist.
  220.       PCHG         - The PCHGHeader.
  221.       LineMask     - The line mask pointer. Technically, the LINEMASK
  222.                      part of the PCHG grammar.
  223.       LineData     - The (Small|Big)PaletteChange array
  224.                      pointer. Technically, the second part of the LINEDATA
  225.                      part of the PCHG grammar.
  226.  
  227.   RESULT
  228.       None.
  229.  
  230.   EXAMPLE
  231.  
  232.   NOTES
  233.       The MAX_PER_LINE_CHANGES #define at the start of the source
  234.       code limits the maximum number of changes allowed on a
  235.       single line. No check is done for changes on odd lines if
  236.       the ViewPort is laced. MaxReg and MinReg are ignored.
  237.       This function does *not* call RethinkDisplay() for you,
  238.       and needs graphics.library. Remember to free the user Copperlist
  239.       (if you're using a &Screen->Viewport, Intuition will do it for you).
  240.  
  241.   BUGS
  242.       Background Copperlists which a PCHGHeader->StartLine
  243.       negative value will not be correctly displayed if Offset
  244.       is not 0, because only changes on a line >=Offset will be
  245.       generated. This shouldn't be a problem however.
  246.  
  247.   SEE ALSO
  248.  
  249. pchg.lib/PCHG_SHAM2PCHG                               pchg.lib/PCHG_SHAM2PCHG
  250.  
  251.   NAME
  252.       PCHG_SHAM2PCHG -- Fakes a PCHG chunk from a SHAM chunk
  253.  
  254.   SYNOPSIS
  255.       PCHGHeader = PCHG_SHAM2PCHG(SHAMChunk, SHAMSize, Increment);
  256.  
  257.       struct PCHGHeader *PCHG_SHAM2PCHG(UWORD *, ULONG, WORD);
  258.  
  259.   FUNCTION
  260.       Creates a PCHGHeader and a LINEMASK (see the PCHG specs) by parsing a
  261.       SHAM chunk. The memory block containing the SHAM is overwritten by an
  262.       array of SmallPaletteChanges (this array is always shorter than the
  263.       original SHAM chunk). A memory block is allocated for the PCHGHeader
  264.       and for the LINEMASK (which is of course placed just after the
  265.       PCHGHeader), and is returned by the function. You can then free it
  266.       using as dimension the size of a PCHGHeader plus the number of bytes
  267.       required by the longword mask, i.e.,
  268.  
  269.            sizeof(struct PCHGHeader)+((PCHGHeader->LineCount+31)/32)*4
  270.  
  271.       You can parse this chunk as any PCHG chunk, but the changes per line
  272.       could be more than seven (up to fifteen). This function, however, is
  273.       intelligent, and doesn't generate useless color changes (i.e., it
  274.       never pokes again the same value two times). You will usually call
  275.  
  276.       PCHG_SetUserCopList(0, 0, Screen, PCHGHeader, &PCHGHeader[1], SHAMChunk
  277. );
  278.  
  279.       after using PCHG_SHAM2PCHG().
  280.  
  281.  
  282.   INPUTS
  283.       SHAMChunk    - The address of the SHAM chunk.
  284.       SHAMSize     - The size of the SHAM chunk (we handle >200
  285.                      lines chunks).
  286.       Increment    - The increment to add to the line number while parsing
  287.                      the SHAM chunk. It has to be 1 for non-laced pictures,
  288.                      2 for laced pictures.
  289.  
  290.   RESULT
  291.       PCHGHeader   - A pointer to a memory block contaning a PCHGHeader
  292.                      followed by a LINEMASK, or NULL if the memory
  293.                      allocation failed. You have to free this memory after
  294.                      you used it.
  295.  
  296.   EXAMPLE
  297.  
  298.   NOTES
  299.       This function will not generate any change on line 0, because the
  300.       line 0 colors should be the same of the CMAP. If you get any problem,
  301.       you can feed the first line of the SHAM chunk as a color table to the
  302.       screen before calling this function.
  303.  
  304.       Since this function writes in the fake PCHG chunk only the real
  305.       changes, you will generally get a better display using this function
  306.       and PCHG_SetUserCopList() than with SHAMVIEW, for instance.
  307.  
  308.   BUGS
  309.  
  310.   SEE ALSO
  311.  
  312.