home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / Misc / TRSICAT.LZX / CATS_CD2_TRSI / Reference_Library / Devices / IFFP_Modules.README < prev    next >
Encoding:
Text File  |  1992-08-21  |  8.4 KB  |  185 lines
  1.             IFFP Modules - July 1991
  2.                  version 37.5
  3.  
  4. These iffparse.library code modules and examples are designed as
  5. replacements for the original EA IFF code.  In some modules, it has been
  6. possible to retain much of the original code.  However, most structures
  7. and most higher level function interfaces have changed.
  8.  
  9. On the plus side, these new modules contain many new high-level
  10. easy-to-use functions for querying, loading, displaying, and saving ILBMs.
  11. During their development, modules similar to these have been used inhouse
  12. at Commodore for the 2.0 Display program and several other ILBM
  13. applications.  The screen.c module provides powerful display-opening
  14. functions which are 1.3-compatible yet provide a host of new options under
  15. 2.0 such as centered overscan screens, full-video display clips, border
  16. transparency control, and autoscroll.  New modules have been added for
  17. printing (screendump) and for preserving/adding chunks (copychunks). And
  18. the 8SVX example now actually plays samples and instruments. In addition,
  19. clipboard support is automatic for all applications that use the IFFP
  20. modules because parse.c's openifile() interprets the filename -c[n] (ie.
  21. "-c", "-c1", "-c2", etc.) as clipboard unit n.
  22.  
  23. All of the applications presented here require iffparse.library which is
  24. distributed on Workbench 2.0.  Please note that iffparse.library is a
  25. 1.3-compatible library, and that all of these modules and examples have
  26. been designed to take advantage of 2.0, but also work under 1.3.
  27. Developers who wish to distribute iffparse.library on their commercial
  28. products may execute a 2.0 Workbench license, or may get an addendum to
  29. their 1.3 Workbench license to allow distribution of iffparse.library.
  30.  
  31. It was not necessary to port the gio IO speedup code since iffparse can
  32. use your compiler's own buffered IO routines through the callback
  33. stdio_stream() in parse.c.  Depending on your application, you may want to
  34. add your own additional buffering to this stdio_stream() code.
  35.  
  36. Most of the high-level function pairs provided in these modules have been
  37. designed to provide safe cleanup for themselves.  For example, a
  38. loadbrush() that succeeds or fails at any point can be cleaned up via
  39. unloadbrush.  The cleanup routines null out the appropriate pointers so
  40. that allocations will not be freed twice.
  41.  
  42. All applications are built upon the parse.c module.  The basic concept of
  43. using the parse.c module are:
  44.  
  45.     - Define tag-like arrays of your desired chunks (readers only)
  46.     - Allocates one or more [form]Info structures as defined in
  47.         iffp/[form]app.h (for example an ILBMInfo defined in
  48.         iffp/ilbmapp.h).
  49.     - Initialize the ParseInfo part of these structures to the desired
  50.         chunk arrays, and to an IFFHandle allocated via iffparse
  51.         AllocIFF().
  52.     - Use the provided high level load/save functions, or use the
  53.         lower level parse.c openifile(), reader-only parseifile()/
  54.         getcontext()/nextcontext(), and closeifile().  The filename
  55.         -c[n] may be used to read/write clipboard unit n.
  56.     - Clean up, FreeIFF(), and deallocate [form]Info's.
  57.  
  58.  
  59. IMPORTANT NOTES - Most of the higher-level load functions keep the
  60.     IFFHandle (file or clipboard) open.  While the handle is
  61.     open, you may use parse.c functions (such as findpropdata)
  62.     OR direct iffparse functions (FindProp(), FindCollection())
  63.     for accessing the gathered chunks.  However, it is not a good
  64.     idea to keep a filehandle OR the clipboard open.  While
  65.     a clipboard unit is open, no other applications can clip
  66.     to the unit.  And while a file is open, you can't write the
  67.     file back out.  So, instead of keeping the file or unit
  68.     open, you can use copychunks (in copychunks.c) to create
  69.     a copy of your gathered chunks, and do an early closeifile()
  70.     (parse.c).  Then access and later write back out (if you wish)
  71.     and deallocate your copied chunks via the routines in the
  72.     copychunks module (findchunk, writechunklist, freechunklist).
  73.  
  74. WARNING REGARDING COMPLEX FORMS
  75.         Regarding Complex FORMs - The parse.c module will enter complex
  76.     formats such as CATSs, LISTs, and nested FORMs to find the FORM
  77.     that you are interested in.  This is great.  However, if you are
  78.         a read-modify-write program, you should warn your user when this
  79.         occurs unless YOU are capable of recreating the complex format.
  80.     Otherwise, your user may unknowingly destroy his complex file
  81.     by writing over it with your program.  Example - a paint
  82.     program could read an ILBM out of a complex LIST containing
  83.     pictures and music, and then save it back out as a simple ILBM,
  84.     causing the user to lose his music and other pictures.
  85.     To determine if a complex form was entered after a load,
  86.     check the (form)Info.ParseInfo.hunt field.  If TRUE (non-zero),
  87.     then your file was found inside a complex format.
  88.  
  89. COMPILATION NOTES
  90.     These modules and examples have been compiled using SAS C 5.10a
  91.     and Manx C 5.0d, with 2.0 (37.1) include files and 2.0 amiga.lib.
  92.     You must have at least 37.1 alib_protos.h (older versions of
  93.     this include file contained the amiga.lib stdio protos also
  94.     which conflict with both SAS and Manx stdio).  For Manx, I
  95.     also had to comment out the conditional definition of abs() in
  96.     libraries/mathffp.h.  These modules do not use mathffp, but
  97.     the mathffp include file is pulled in by alib_protos.h.
  98.     When compiling with Manx, a warning seems to be generated for
  99.     each string constant assigned to a UBYTE * field, and also
  100.     by some references to ilbm->colortable.
  101.  
  102.  
  103.  
  104.         LIST OF IFFP MODULES AND APPLICATIONS
  105.                 -------------------------------------
  106.     NOTE - Some useful functions are listed with each module
  107.         See module source code for docs on each function.
  108.  
  109.  
  110. APPLICATIONS (these require linkage with modules - see Makefiles)
  111. ------------
  112. ILBMDemo    Displays an ILBM, loads a brush, saves an ILBM, opt. print
  113. ILBMLoad    Queries an ILBM and loads it into an existing screen
  114. ILBMtoC        Outputs an ILBM as C source code
  115. ILBMtoRaw    Converts an ILBM to raw plane/color file
  116. RawtoILBM    Converts raw plane/color file (from ILBMtoRaw) to an ILBM
  117. 24bitDemo    Saves a simple 24-bit ILBM and then shows it 4 planes at
  118.         a time (if given filename, just does the show part)
  119. Play8SVX    Reads and plays an 8SVX sound effect or instrument
  120.           - LoadSample, UnloadSample, PlaySample, OpenAudio,
  121.             CloseAudio, and body load/unpack functions
  122. ScreenSave    Save the front screen as an ILBM, with an icon
  123.  
  124.  
  125. OTHER EXAMPLES (use iffparse.library directly and require no modules)
  126. --------------
  127. Sift        Checks and prints outline of any IFF file (uses RAWSTEP)
  128. ILBMScan    Prints out useful info about any ILBM
  129. ClipFTXT    Demonstrates simply clipping of FTXT to/from clipboard
  130. cycvb.c        Dan Silva's routine for interrupt based color cycling
  131. apack.asm    Dr. Gerald Hull's assembler replacement for packer.c
  132.  
  133.  
  134. GENERAL IFFPARSE SUPPORT MODULE
  135. -------------------------------
  136. parse.c        File/clipboard IO and general parsing
  137.           - openifile, closeifile, parseifile, getcontext,
  138.             nextcontext, contextis, currentchunkis, PutCk chunk
  139.             writing function, and IFFerr text error routine
  140.  
  141.  
  142. ILBM READ MODULES
  143. -----------------
  144. loadilbm.c      High level ILBM load routines which are passed filenames
  145.         (calls getbitmap)
  146.           - loadbrush/unloadbrush,loadilbm/unloadilbm,and queryilbm
  147. getbitmap.c    brush/bitmap loading (non-display, calls ilbmr.c)
  148.           - createbrush/deletebrush, getbitmap/freebitmap
  149. getdisplay.c    bitmap load/display (calls screen.c, ilbmr.c)
  150.           - showilbm/unshowilbm, createdisplay/deletedisplay
  151. screen.c    1.3/2.0 ECS/non-ECS compatible screen/window module
  152.           - opendisplay, openidscreen, modefallback, clipit
  153. ilbmr.c        Lower level ILBM body/color load routines(calls unpacker.c)
  154.           - loadbody, loadcmap, getcolors/freecolors,
  155.             alloccolortable, getcamg (gets or creates modeid)
  156. unpacker.c    BODY unpacker
  157.  
  158.  
  159. ILBM WRITE MODULES
  160. ------------------
  161. saveilbm.c    High level ILBM saving routines which are passed filenames
  162.         (calls ilbmw.c)
  163.           - screensave and saveilbm
  164. ilbmw.c        Lower level ILBM body/color save routines (calls packer.c)
  165.           - InitBMHD, PutCMAP, PutBODY
  166. packer.c    BODY packer
  167.  
  168.  
  169. EXTRA MODULES
  170. -------------
  171. copychunks.c    Chunk cloning and chunk list writing routines
  172.           - copychunks, findchunk, writechunklist, freechunklist
  173. screendump.c    Screen printing module (iffparse not required)
  174. bmprintc.c    Module to output ILBM as C code
  175.  
  176.  
  177. INCLUDE FILES
  178. -------------
  179. iffp/#?.h    This subdirectory may be kept in your current directory
  180.         or in your main include directory.
  181.  
  182.  
  183. Thanks to Steve Walton for his code changes for Manx/SAS compatibility,
  184. and to Bill Barton and John Bittner for their comments and suggestions.
  185.