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