home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 612b.lha / PicPak_v1.3c / pic_pak.doc.pp / pic_pak.doc
Text File  |  1992-03-05  |  23KB  |  850 lines
  1.                                   PIC_PAK
  2.                                    v1.3c
  3.                 Picture allocation/loading/manipulation routines
  4.                             written by Paul Miller
  5.  
  6.  
  7. DISCLAIMER:
  8.  
  9. The code in this package is provided "as-is" and I make no guarantee that
  10. it will work for your application. It might blow up your computer, and you
  11. can't do anything to me if it does (however, it is unlikely that it will do
  12. anything of the sort, but if it does, you are warned).
  13. This code or derivatives may be used in your application, as long as you
  14. give me credit somewhere in the documentation, or in the code if source is
  15. present. This code is NOT in the public domain, and I'm allowing its free
  16. use because I'm a nice guy. Enjoy.
  17.  
  18.  
  19.    For those of you who are having trouble loading and using IFF ILBMs or
  20. other picture types in your programs, here is a little package (OK, so it's
  21. not so little any more) of functions which provides general-purpose picture
  22. allocation/loading/manipulation functions. Also included is support for color
  23. effects on ViewPorts, including color cycling (based on information returned
  24. from the picture file), fading, and SHAM images.
  25.  
  26.  
  27. TABLE OF CONTENTS
  28.  
  29. PIC_PAK/AllocateFrame
  30. PIC_PAK/AllocatePic
  31. PIC_PAK/ClearViewPortColors
  32. PIC_PAK/FadeViewPortIn
  33. PIC_PAK/FadeViewPortOut
  34. PIC_PAK/FreeCycler
  35. PIC_PAK/FreeFrame
  36. PIC_PAK/FreePic
  37. PIC_PAK/FreeSHAM
  38. PIC_PAK/GetPicAttrs
  39. PIC_PAK/InitCycler
  40. PIC_PAK/InitSHAM
  41. PIC_PAK/IsCycling
  42. PIC_PAK/Pic2BitMap
  43. PIC_PAK/LoadFrame
  44. PIC_PAK/LoadPic
  45. PIC_PAK/LoadPic2BitMap
  46. PIC_PAK/SetFadeSpeed
  47. PIC_PAK/SetPicReadBufSize
  48. PIC_PAK/SetViewPortPicColors
  49. PIC_PAK/StartCycling
  50. PIC_PAK/StopCycling
  51. PIC_PAK/ToggleCycling
  52.  
  53. ---------------------------------------------------------------------------
  54.  
  55. PIC_PAK/AllocateFrame (1.3)
  56.  
  57.    NAME
  58.       AllocateFrame -- Allocate a new Frame and BitMap.
  59.  
  60.    SYNOPSIS
  61.       Frame = AllocateFrame(width, height, depth)
  62.  
  63.       struct Frame *AllocateFrame(UWORD, UWORD, UBYTE);
  64.  
  65.    FUNCTION
  66.       Allocate a Frame structure and BitMap memory of type CHIP.
  67.  
  68.    INPUTS
  69.       width,height - size of BitMap in pixels
  70.       depth        - depth of BitMap in planes
  71.  
  72.    RESULTS
  73.       result - pointer to a Frame structure if successful
  74.                NULL of not successful
  75.  
  76.    BUGS
  77.  
  78.    SEE ALSO
  79.       FreeFrame, LoadFrame, PIC_PAK/pic_pak.h
  80.  
  81. ---------------------------------------------------------------------------
  82.  
  83. PIC_PAK/AllocatePic
  84.  
  85.    NAME
  86.       AllocatePic -- Allocate a new Pic and BitMap.
  87.  
  88.    SYNOPSIS
  89.       Pic = AllocatePic(width, height, depth, memtype)
  90.  
  91.       struct Pic *AllocatePic(UWORD, UWORD, UBYTE, UBYTE);
  92.  
  93.    FUNCTION
  94.       Allocate a Pic structure and BitMap memory of the specified type
  95.       and size. Memtypes can be of the following types:
  96.          MEMTYPE_NONE   - allocate no BitMap plane memory
  97.          MEMTYPE_CHIP   - allocate BitMap plane memory using CHIP RAM
  98.          MEMTYPE_FAST   - allocate BitMap plane memory using FAST RAM
  99.          MEMTYPE_ANY    - allocate BitMap plane memory for any available
  100.                            type of RAM, starting with CHIP
  101.  
  102.    INPUTS
  103.       width,height - size of BitMap in pixels
  104.       depth        - depth of BitMap in planes
  105.       memtype      - memtype bit (see above)
  106.  
  107.    RESULTS
  108.       result - pointer to a Pic structure if successful
  109.                NULL of not successful
  110.  
  111.    BUGS
  112.  
  113.    SEE ALSO
  114.       FreePic, LoadPic, PIC_PAK/pic_pak.h
  115.  
  116. ---------------------------------------------------------------------------
  117.  
  118. PIC_PAK/ClearViewPortColors
  119.  
  120.    NAME
  121.       ClearViewPortColors -- Set a ViewPort's color registers to black.
  122.  
  123.    SYNOPSIS
  124.       ClearViewPortColors(vp, colors)
  125.  
  126.       void ClearViewPortColors(struct ViewPort *, UWORD);
  127.  
  128.    FUNCTION
  129.       Clear a ViewPort's color registers to black, usually used before a
  130.       ViewPort fade in.
  131.  
  132.    INPUTS
  133.       vp     - pointer to the ViewPort to affect
  134.       colors - number of colors in the ViewPort's colortable
  135.  
  136.    RESULTS
  137.  
  138.    BUGS
  139.  
  140.    SEE ALSO
  141.       FadeViewPortIn
  142.  
  143. ---------------------------------------------------------------------------
  144.  
  145. PIC_PAK/FadeViewPortIn
  146.  
  147.    NAME
  148.       FadeViewPortIn -- Fade a ViewPort's colors in.
  149.  
  150.    SYNOPSIS
  151.       FadeViewPortIn(vp, colormap, colors)
  152.  
  153.       void FadeViewPortIn(struct ViewPort *, UWORD *, UWORD);
  154.  
  155.    FUNCTION
  156.       Fades a ViewPort's colormap from black into the specified colormap's
  157.       colors. The speed of fade is specified in the global variable
  158.       fade_speed, and is set externally via SetFadeDelay().
  159.  
  160.    INPUTS
  161.       vp       - pointer to ViewPort to affect
  162.       colormap - pointer to a filled-out array of UWORDs containing
  163.                  destination colors
  164.       colors   - number of colors in the colormap
  165.  
  166.    RESULTS
  167.  
  168.    BUGS
  169.  
  170.    SEE ALSO
  171.       FadeViewPortOut, SetFadeDelay
  172.  
  173. ---------------------------------------------------------------------------
  174.  
  175. PIC_PAK/FadeViewPortOut
  176.  
  177.    NAME
  178.       FadeViewPortOut -- Fade a ViewPort's colors out.
  179.  
  180.    SYNOPSIS
  181.       FadeViewPortOut(vp, colors)
  182.  
  183.       void FadeViewPortOut(struct ViewPort *, UWORD);
  184.  
  185.    FUNCTION
  186.       Fades a ViewPort's colormap from the current colors to black.
  187.       The speed of fade is specified in the global variable fade_speed,
  188.       and is set externally via SetFadeDelay().
  189.  
  190.    INPUTS
  191.       vp       - pointer to ViewPort to affect
  192.       colors   - number of colors in the ViewPort's colortable
  193.  
  194.    RESULTS
  195.  
  196.    BUGS
  197.  
  198.    SEE ALSO
  199.       FadeViewPortIn, SetFadeDelay
  200.  
  201. ---------------------------------------------------------------------------
  202.  
  203. PIC_PAK/FreeCycler
  204.  
  205.    NAME
  206.       FreeCycler -- Free memory allocated by InitCycler().
  207.  
  208.    SYNOPSIS
  209.       FreeCycler()
  210.  
  211.       void FreeCycler(void);
  212.  
  213.    FUNCTION
  214.       Stops color cycling, if occuring, removes the vertical-blanking
  215.       interrupt installed via InitCycler(), and frees up memory used by
  216.       the color-cycling system, also initalized by InitCycler().
  217.  
  218.    INPUTS
  219.  
  220.    RESULTS
  221.  
  222.    BUGS
  223.  
  224.    SEE ALSO
  225.       InitCycler, StartCycling, StopCycling
  226.  
  227. ---------------------------------------------------------------------------
  228.  
  229. PIC_PAK/FreeFrame (1.3)
  230.  
  231.    NAME
  232.       FreeFrame -- Free a Frame and its BitMap memory.
  233.  
  234.    SYNOPSIS
  235.       FreeFrame(frame)
  236.  
  237.       void FreeFrame(struct Frame *);
  238.  
  239.    FUNCTION
  240.       Frees up a Frame structure and BitMap memory allocated by
  241.       AllocateFrame(). Use only with dynamic Frame structures allocated with
  242.       AllocateFrame().
  243.       NOTE: (1.4) - FreeFrame() also detects if an extra mask plane has been
  244.       added (possibly by MakeMask() in BITMAP_PAK), and frees that as well.
  245.  
  246.    INPUTS
  247.       frame - pointer to a Frame structure returned by AllocateFrame()
  248.  
  249.    RESULTS
  250.  
  251.    BUGS
  252.  
  253.    SEE ALSO
  254.       AllocateFrame
  255.  
  256. ---------------------------------------------------------------------------
  257.  
  258. PIC_PAK/FreePic
  259.  
  260.    NAME
  261.       FreePic -- Free a Pic and its BitMap memory.
  262.  
  263.    SYNOPSIS
  264.       FreePic(pic)
  265.  
  266.       void FreePic(struct Pic *);
  267.  
  268.    FUNCTION
  269.       Frees up a Pic structure and BitMap memory allocated by
  270.       AllocatePic(). Use only with dynamic Pic structures allocated with
  271.       AllocatePic().
  272.  
  273.    INPUTS
  274.       pic - pointer to a Pic structure returned by AllocatePic()
  275.  
  276.    RESULTS
  277.  
  278.    BUGS
  279.  
  280.    SEE ALSO
  281.       AllocatePic
  282.  
  283. ---------------------------------------------------------------------------
  284.  
  285. PIC_PAK/FreeSHAM (1.3)
  286.  
  287.    NAME
  288.       FreeSHAM -- Free ViewPort copper-lists created by InitSHAM().
  289.  
  290.    SYNOPSIS
  291.       FreeSHAM(vp)
  292.  
  293.       void FreeSHAM(struct ViewPort *);
  294.  
  295.    FUNCTION
  296.       Frees up the ViewPort copper-lists generated with InitSHAM(). This
  297.       routine need only be called if the ViewPort was created dynamically
  298.       instead of via OpenScreen(). If the SHAM is initialized on the ViewPort
  299.       of an opened custom Screen, then the call to CloseScreen() will free
  300.       the copper-lists, and this routine may safely be ignored.
  301.  
  302.    INPUTS
  303.       vp - pointer to dynamic ViewPort to free the copper-lists from
  304.  
  305.    RESULTS
  306.  
  307.    BUGS
  308.  
  309.    SEE ALSO
  310.       InitSHAM
  311.  
  312. ---------------------------------------------------------------------------
  313.  
  314. PIC_PAK/GetPicAttrs
  315.  
  316.    NAME
  317.       GetPicAttrs -- Returns information about a picture file.
  318.  
  319.    SYNOPSIS
  320.       success = GetPicAttrs(filename, *width, *height, *depth, *viewmodes)
  321.  
  322.       int GetPicAttrs(UBYTE *, WORD *, WORD *, WORD *, ULONG *);
  323.  
  324.    FUNCTION
  325.       Returns width, height, depth, and viewmodes of an IFF Pic file
  326.       in pointer variables. ViewModes are returned in a ULONG variable
  327.       compatible with both 1.3 and 2.0 display formats (use lower 16 bits
  328.       for 1.3-compatible ViewModes).
  329.  
  330.    INPUTS
  331.       filename - name of IFF Pic file
  332.       width, height, depth - pointer to a WORD to return width, height, depth
  333.       viewmodes - pointer to a ULONG to return ViewModes in
  334.  
  335.    RESULTS
  336.       result - TRUE if file exists and is an IFF ILBM
  337.                NULL if file is not an ILBM Pic or does not exist
  338.  
  339.    BUGS
  340.  
  341.    SEE ALSO
  342.  
  343. ---------------------------------------------------------------------------
  344.  
  345. PIC_PAK/InitCycler
  346.  
  347.    NAME
  348.       InitCycler -- Initialize the cycling system.
  349.  
  350.    SYNOPSIS
  351.       success = InitCycler()
  352.  
  353.       int InitCycler(void);
  354.  
  355.    FUNCTION
  356.       Allocates memory used by the cycling system and installs a vertical-
  357.       blank interrupt to perform the color cycling, when active.
  358.  
  359.    INPUTS
  360.  
  361.    RESULTS
  362.       result - TRUE if memory was allocated successfully
  363.                NULL if unsuccessful
  364.  
  365.    BUGS
  366.  
  367.    SEE ALSO
  368.       FreeCycler, StartCycling, StopCycling
  369.  
  370. ---------------------------------------------------------------------------
  371.  
  372. PIC_PAK/InitSHAM (1.3)
  373.  
  374.    NAME
  375.       InitSHAM -- Initialize a SHAM color-palette into a ViewPort.
  376.  
  377.    SYNOPSIS
  378.       success = InitSHAM(vp, pic)
  379.  
  380.       int InitSHAM(struct ViewPort *, struct Pic *);
  381.  
  382.    FUNCTION
  383.       Initializes the proper color-palettes and copper-lists required to
  384.       view a SHAM image into the specified ViewPort. If the SHAM is to be
  385.       viewed on a custom screen, then this function must be called only if
  386.       the screen is the front-most screen (call ScreenToFront(screen) to
  387.       make sure).
  388.  
  389.    INPUTS
  390.       vp  - pointer to ViewPort to load the copper-lists into
  391.       pic - pointer to Pic structure containing the SHAM color packet
  392.  
  393.    RESULTS
  394.       result - TRUE if copper-list memory was allocated successfully
  395.                NULL if unsuccessful
  396.  
  397.    BUGS
  398.  
  399.    SEE ALSO
  400.       FreeSHAM
  401.  
  402. ---------------------------------------------------------------------------
  403.  
  404. PIC_PAK/IsCycling
  405.  
  406.    NAME
  407.       IsCycling -- Determine whether color cycling is currently taking place.
  408.  
  409.    SYNOPSIS
  410.       result = IsCycling()
  411.  
  412.       int IsCycling(void);
  413.  
  414.    FUNCTION
  415.       Determines whether or not color-cycling is currently being performed.
  416.  
  417.  
  418.    INPUTS
  419.  
  420.    RESULTS
  421.       result - TRUE if color-cycling is being performed
  422.                NULL if not
  423.  
  424.    BUGS
  425.  
  426.    SEE ALSO
  427.       StartCycling, StopCycling, ToggleCycling
  428.  
  429. ---------------------------------------------------------------------------
  430.  
  431. PIC_PAK/Pic2BitMap
  432.  
  433.    NAME
  434.       Pic2BitMap -- download a Pic BitMap into a specified BitMap.
  435.  
  436.    SYNOPSIS
  437.       success = Pic2BitMap(pic, bitmap)
  438.  
  439.       int Pic2BitMap(struct Pic *, struct BitMap *);
  440.  
  441.    FUNCTION
  442.       Copies the BitMap imagery in the Pic to the planes of a specified
  443.       BitMap. Both BitMaps must be the same size (use the size and depth
  444.       information in the Pic to initialize the destination BitMap). If
  445.       the source Pic BitMap imagery resides in CHIP memory, this routine
  446.       uses the Blitter to copy the imagery. If in FAST memory, standard
  447.       memory-block transfer will be used.
  448.       NOTE: This routine is useful in situations where it may be necessary
  449.       to load many images into memory, regardless of memory type. When it
  450.       is time to display the image, this will effectively place it into
  451.       a CHIP memory area that is displayable, such as an opened Screen.
  452.  
  453.    INPUTS
  454.       pic - pointer to a Pic structure to be used as source BitMap
  455.       bitmap - pointer to an allocated destination BitMap
  456.  
  457.    RESULTS
  458.       result - TRUE if BitMaps are same size and operation is successful
  459.                NULL otherwise
  460.  
  461.    BUGS
  462.  
  463.    SEE ALSO
  464.       AllocatePic, LoadPic, LoadPic2BitMap, PIC_PAK/pic_pak.h
  465.  
  466. ---------------------------------------------------------------------------
  467.  
  468. PIC_PAK/LoadFrame (1.3)
  469.  
  470.    NAME
  471.       LoadFrame -- Allocate and load an IFF Frame image.
  472.  
  473.    SYNOPSIS
  474.       pic = LoadFrame(filename)
  475.  
  476.       struct Frame *LoadFrame(UBYTE *);
  477.  
  478.    FUNCTION
  479.       Calls AllocateFrame() with the proper information to allocate a Frame
  480.       of the proper size, then loads the specified IFF image (usually a
  481.       brush) file into the BitMap.
  482.  
  483.    INPUTS
  484.       filename - pointer to filename string
  485.  
  486.    RESULTS
  487.       result - pointer to a Frame if successful
  488.                NULL if not successful
  489.  
  490.    BUGS
  491.  
  492.    SEE ALSO
  493.       AllocateFrame, FreeFrame, PIC_PAK/pic_pak.h
  494.  
  495. ---------------------------------------------------------------------------
  496.  
  497. PIC_PAK/LoadPic
  498.  
  499.    NAME
  500.       LoadPic -- Allocate and load an IFF Pic image.
  501.  
  502.    SYNOPSIS
  503.       pic = LoadPic(filename, memtype)
  504.  
  505.       struct Pic *LoadPic(UBYTE *, UBYTE);
  506.  
  507.    FUNCTION
  508.       Calls AllocatePic() with the proper information to allocate a Pic
  509.       of the proper size and memory type, then loads the specified IFF Pic
  510.       file into the BitMap (if allocated, and not of type MEMTYPE_NONE),
  511.       as well as colormap and color-cycling information.
  512.  
  513.    INPUTS
  514.       filename - pointer to filename string
  515.       memtype - memtype bit (see AllocatePic())
  516.  
  517.    RESULTS
  518.       result - pointer to a Pic if successful
  519.                NULL if not successful
  520.  
  521.    BUGS
  522.  
  523.    SEE ALSO
  524.       AllocatePic, FreePic, LoadPic2BitMap, Pic2BitMap, PIC_PAK/pic_pak.h
  525.  
  526. ---------------------------------------------------------------------------
  527.  
  528. PIC_PAK/LoadPic2BitMap
  529.  
  530.    NAME
  531.       LoadPic2BitMap -- Load an IFF Pic into a specified BitMap.
  532.  
  533.    SYNOPSIS
  534.       pic = LoadPic2BitMap(filename, bitmap)
  535.  
  536.       struct Pic *LoadPic2BitMap(UBYTE *, struct BitMap *);
  537.  
  538.    FUNCTION
  539.       Loads the specified IFF Pic imagery into a specified BitMap, and
  540.       allocates a Pic structure containing size, depth, colormap, and
  541.       color-cycling information. No BitMap memory is allocated for Pic,
  542.       and the supplied BitMap must be the same dimensions as the IFF Pic
  543.       file. FreePic() must still be called on the returned Pic, when it
  544.       is through being used.
  545.       NOTE: This function is useful when loading an image into an already-
  546.       opened screen, by passing a pointer to the screen's BitMap.
  547.  
  548.    INPUTS
  549.       filename - pointer to filename string
  550.       bitmap   - pointer to a supplied destination BitMap for the image
  551.  
  552.    RESULTS
  553.       result - pointer to a filled-out Pic structure if successful
  554.                NULL if not successful
  555.  
  556.    BUGS
  557.  
  558.    SEE ALSO
  559.       FreePic, PIC_PAK/pic_pak.h
  560.  
  561. ---------------------------------------------------------------------------
  562.  
  563. PIC_PAK/SetFadeDelay
  564.  
  565.    NAME
  566.       SetFadeDelay -- Set the speed of FadeViewPortIn()/FadeViewPortOut().
  567.  
  568.    SYNOPSIS
  569.       SetFadeDelay(delay)
  570.  
  571.       void SetFadeDelay(UWORD);
  572.  
  573.    FUNCTION
  574.       Sets the delay time (in ticks) that will ellapse between color shifts
  575.       during ViewPort fading, performed by FadeViewPortIn() and
  576.       FadeViewPortOut(). The higher the number, the slower the fade (note
  577.       that as the delay gets higher, the fade will also appear to be more
  578.       "jerky"). This function sets the global variable fade_speed directly.
  579.       The default delay time is 0, which provides the smoothest fade.
  580.  
  581.    INPUTS
  582.       delay - delay (in ticks) to ellapse between successive color shifts
  583.  
  584.    RESULTS
  585.  
  586.    BUGS
  587.  
  588.    SEE ALSO
  589.       FadeViewPortIn, FadeViewPortOut
  590.  
  591. ---------------------------------------------------------------------------
  592.  
  593. PIC_PAK/SetPicReadBufSize (1.4)
  594.  
  595.    NAME
  596.       SetPicReadBufSize -- Sets the maximum image decompression buffer size.
  597.  
  598.    SYNOPSIS
  599.       SetPicReadBufSize(size)
  600.  
  601.       void SetPicReadBufSize(ULONG);
  602.  
  603.    FUNCTION
  604.       Sets the current maximum size of decompressed image data to allocate
  605.       memory for, in order to allow decompression of run-byte-encoded image
  606.       files directly from RAM. In other words, if the compressed ILBM image
  607.       file is smaller than this value, memory will be allocated and the
  608.       image data will be loaded directly into the memory, where it will be
  609.       decompressed from there. Otherwise, the image is decompressed as it is
  610.       loaded from the file. Naturally, there is a speed of decompression
  611.       increase when image data is decompressed directly from RAM. The default
  612.       is 32K. If no memory can be spared in decompression, call this routine
  613.       with a value of zero.
  614.  
  615.    INPUTS
  616.       size - new maximum image buffer size
  617.  
  618.    RESULTS
  619.  
  620.    BUGS
  621.  
  622.    SEE ALSO
  623.       LoadFrame, LoadPic
  624.  
  625. ---------------------------------------------------------------------------
  626.  
  627. PIC_PAK/SetViewPortPicColors (1.3)
  628.  
  629.    NAME
  630.       SetViewPortPicColors -- Initialize ViewPort for proper picture colors.
  631.  
  632.    SYNOPSIS
  633.       SetViewPortPicColors(vp, pic)
  634.  
  635.       void SetViewPortPicColors(struct ViewPort *, struct Pic *);
  636.  
  637.    FUNCTION
  638.       Initializes the ViewPort with the Pic's color data, depending on what
  639.       type of image it is. Normal images will have the colormap loaded into
  640.       the ViewPort. If the Pic is a SHAM image, then InitSHAM() will be
  641.       called in order to set that up. Use this if not sure what type of image
  642.       the Pic is, and you don't want to check.
  643.  
  644.    INPUTS
  645.       vp  - pointer to ViewPort to initialize colors into
  646.       pic - pointer to the initialized Pic structure to initialize with
  647.  
  648.    RESULTS
  649.  
  650.    BUGS
  651.  
  652.    SEE ALSO
  653.       PIC_PAK/pic_pak.h
  654.  
  655. ---------------------------------------------------------------------------
  656.  
  657. PIC_PAK/StartCycling
  658.  
  659.    NAME
  660.       StartCycling -- Begin cycling the cyclable colors in a Pic.
  661.  
  662.    SYNOPSIS
  663.       StartCycling(vp, pic)
  664.  
  665.       void StartCycling(struct ViewPort *vp, struct Pic *pic);
  666.  
  667.    FUNCTION
  668.       Notifies the cycling system of the ViewPort, colormap, and color
  669.       ranges to use in the color cycling, and begins cycling the cyclable
  670.       color ranges defined within the specified Pic. You must call
  671.       InitCycler() before calling this function the first time.
  672.  
  673.    INPUTS
  674.       vp  - pointer to the ViewPort containing the colors to cycle
  675.       pic - pointer to the source Pic containing the cycle ranges and
  676.             colormap
  677.  
  678.    RESULTS
  679.  
  680.    BUGS
  681.  
  682.    SEE ALSO
  683.       StopCycling, ToggleCycling
  684.  
  685. ---------------------------------------------------------------------------
  686.  
  687. PIC_PAK/StopCycling
  688.  
  689.    NAME
  690.       StopCycling -- Stop cycling the current ViewPort.
  691.  
  692.    SYNOPSIS
  693.       StopCycling()
  694.  
  695.       void StopCycling(void);
  696.  
  697.    FUNCTION
  698.       Stops cycling the defined color ranges in the current ViewPort set
  699.       via StartCycling(). This routine is called by FreeCycler(), so there
  700.       is no need to call this if cycling is meant to be shut down for good.
  701.  
  702.    INPUTS
  703.  
  704.    RESULTS
  705.  
  706.    BUGS
  707.  
  708.    SEE ALSO
  709.       StartCycling, ToggleCycling
  710.  
  711. ---------------------------------------------------------------------------
  712.  
  713. PIC_PAK/ToggleCycling
  714.  
  715.    NAME
  716.       ToggleCycling -- Turn cycling on if off, and vice versa.
  717.  
  718.    SYNOPSIS
  719.       ToggleCycling()
  720.  
  721.       void ToggleCycling(void);
  722.  
  723.    FUNCTION
  724.       Turns color cycling off if it is on, and on and if it is off.
  725.       The current state of the cycling can be determined with IsCycling().
  726.  
  727.    INPUTS
  728.  
  729.    RESULTS
  730.  
  731.    BUGS
  732.  
  733.    SEE ALSO
  734.       StartCycling, StopCycling, IsCycling
  735.  
  736. ---------------------------------------------------------------------------
  737.  
  738. PIC_PAK Modification History:
  739. -----------------------------
  740. 11-25-90    v1.1 - limited release
  741.             Initial release, including support for normal/HAM/EHB images and
  742.                brushes, including color cycling and ViewPort fading. Plenty
  743.                of hooks for future image types.
  744.  
  745. 11-28-90    v1.2 - limited release
  746.             Improved image-type processing
  747.  
  748. 12-02-90    v1.3a - limited test release
  749.             Clean up IFF parsing into a dynamic chunk analysis loop.
  750.             Add SHAM ViewPort initialization code.
  751.             General-purpose SetViewPortPicColors() function for automatic
  752.                initialization of correct image colors for specific image
  753.                types (ie. automatically sets up for SHAM if pic->Type = SHAM)
  754.             Frame structure for simple positional information of brushes,
  755.                used for quick frame animation without overhead of Pic struct
  756.             Alternative frame allocation/loading used brush brush animation
  757.  
  758. 12-06-90    v1.3b - limited test release
  759.             Fixed a bug in the color palette loader. Wouldn't read enough
  760.                colors on non-EHB/HAM pictures.
  761.             Fixed horrible bug in standard image allocation.
  762.             v1.3c - sped up image decompression by loading entire BODY chunk
  763.                into memory, and decompressing from RAM - assumes chunk size
  764.                under 32K, so doesn't use up too much memory.
  765.  
  766. 12-31-91    v1.3c - alpha RELEASE
  767.             (just in time for the holidays!)
  768.  
  769.  
  770. EXAMPLE PIC_PAK USAGE CODE:   A simple image-displayer
  771.  
  772. /* this image viewer supports SHAM-format images too */
  773. #include <exec/types.h>
  774. #include <intuition/intuition.h>
  775. #include "pic_pak.h"
  776.  
  777. extern struct IntuitionBase *IntuitionBase;
  778. extern struct GfxBase *GfxBase;
  779.  
  780. struct NewScreen ns;
  781.  
  782. main(argc, argv)
  783. int argc;
  784. char *argv[];
  785. {
  786.    struct Screen *screen;
  787.    struct Pic *pic;
  788.  
  789.    /* open up the ROM libs */
  790.    GfxBase = (struct GfxBase *)OpenLibrary("graphics.library", 0L);
  791.    IntuitionBase=(struct IntuitionBase *)OpenLibrary("intuition.library",0L);
  792.  
  793.    /* attempt to load the Picture */
  794.    pic = LoadPic(argv[1], MEMTYPE_CHIP);
  795.    if (!pic)
  796.    {
  797.       CloseLibrary((struct Library *)IntuitionBase);
  798.       CloseLibrary((struct Library *)GfxBase);
  799.       puts("Couldn't open picture.");
  800.       exit(1);
  801.    }
  802.    /* clear out and initialize the NewScreen from the Pic data */
  803.    setmem(&ns, sizeof(struct NewScreen), 0L);
  804.    ns.Width = pic->Width;
  805.    ns.Height = pic->Height;
  806.    ns.Depth = pic->Depth;
  807.    ns.ViewModes = (UWORD)pic->ViewModes;
  808.    ns.Type = CUSTOMSCREEN | CUSTOMBITMAP | SCREENQUIET | SCREENBEHIND;
  809.    ns.CustomBitMap = &pic->BitMap;
  810.  
  811.    screen = OpenScreen(&ns);
  812.    if (screen)
  813.    {
  814.       ClearViewPortColors(&screen->ViewPort, pic->Colors);
  815.  
  816.       /* SHAM pics must be on top when initialized with InitSHAM() */
  817.       ScreenToFront(screen);
  818.  
  819.       /* test for special image types */
  820.       if (pic->Type == PICTYPE_SHAM)
  821.          InitSHAM(&screen->ViewPort, pic);   /* can't fade SHAMs (yet) */
  822.       else
  823.          FadeViewPortIn(&screen->ViewPort, &pic->Colormap[0], pic->Colors);
  824.  
  825.       /* NOTE: SetViewPortPicColors(&screen->ViewPort, pic);
  826.           will accomplish the above test and color palette initialization */
  827.  
  828.       ScreenToFront(screen);
  829.  
  830.       Delay(120);                   /* ... pause.... */
  831.  
  832.       if (pic->Type != PICTYPE_SHAM)         /* can't fade a SHAMs (yet) */
  833.          FadeViewPortOut(&screen->ViewPort, pic->Colors);
  834.  
  835.       ScreenToBack(screen);
  836.       CloseScreen(screen);          /* close up the Screen */
  837.    }
  838.    if (pic) FreePic(pic);           /* free up the Pic */
  839.  
  840.    CloseLibrary((struct Library *)IntuitionBase);
  841.    CloseLibrary((struct Library *)GfxBase);
  842. }
  843.  
  844. ---------------------------------------------------------------------------
  845.  
  846.    Please report any bugs, suggestions, or comments to me, Paul Miller, via
  847. my internet address:
  848.  
  849. pmiller@csugrad.cs.vt.edu
  850.