home *** CD-ROM | disk | FTP | other *** search
/ Amiga Elysian Archive / AmigaElysianArchive.iso / newlibs / ifflb161.zoo / IffLib.doc < prev    next >
Text File  |  1988-12-10  |  14KB  |  493 lines
  1.  
  2.          THE UNIVERSAL IFF LIBRARY FOR THE AMIGA
  3.  
  4.         BY CHRISTIAN A. WEBER, ZURICH/SWITZERLAND
  5.  
  6.                 VERSION 16.1    01-DEC-88
  7.  
  8. THIS PROGRAM IS IN THE PUBLIC DOMAIN. IT MAY BE FREELY DISTRUBUTED, COPIED
  9. AND USED FOR COMMERCIAL OR NON-COMMERCIAL PURPOSES.  IT MAY BE DISTRIBUTED
  10. WITH OR WITHOUT THIS DOCUMENTATION FILE.
  11.  
  12. TO MAINTAIN COMPATIBILITY,  YOU SHOULD NOT MAKE ANY CHANGES ON THE LIBRARY
  13. ITSELF. UPDATES WILL BE RELEASED BY THE AUTHOR.
  14.  
  15.  
  16. CHANGES SINCE V15.3
  17. -------------------
  18.  
  19. Since V15.3 I got lots of suggestions, so I made the following changes.
  20. Note that this version is fully downward-compatible to V15.3.
  21.  
  22. * There was a bug in the DecodePic() routine which called the guru if the
  23.   width of the picture was not a multiple of 16. It's fixed now.
  24.  
  25. * The GetViewModes() routines now calculates the viewmodes correctly for
  26.   all picture sizes, including Super-Overscan (produced by DigiView 3.0).
  27.  
  28. * When you open an IFF file with the OpenIFF() call, memory is allocated
  29.   and the file is read into that memory. Normally, all files are loaded
  30.   into whatever memory is available, but '8SVX' files are always loaded to
  31.   CHIP memory (the memory which is accessable by the Amiga's custom chips).
  32.   This solution is good for playing IFF sounds, but it is not satisfactory
  33.   for some other applications. The solution of this problem is quite easy:
  34.   I added a new routine called 'NewOpenIFF', which allows you to specify
  35.   the type of memory for the file.
  36.   So if you want to load an IFF instrument into any RAM, the right command
  37.   is: 'f=NewOpenIFF(filename,0L)' or 'f=OpenIFF(filename,MEMF_PUBLIC)'.
  38.   You can use any memory attributes you want (PUBLIC,CHIP,FAST...).
  39.  
  40. * The file 'iff.h' is now split into two files: 'iff.h', which contains the
  41.   structure definitions and function declarations, and 'IffGlue.asm',
  42.   which contains the C to Assembler interface routines.
  43.  
  44. * The file 'IFFPragmas.h" is added to support the Lattice C compiler. It
  45.   was taken from an usenet article by Lyle E. Levine. Thanks!
  46.  
  47. * The demo file 'ShowIFF.c' now correctly handles overscan pictures.
  48.  
  49.  
  50.  
  51. THE LIBRARY FUNCTIONS (Overview, Version 16.1)
  52. ----------------------------------------------
  53.  
  54. Name        Offset    Description
  55.  
  56. OpenIFF        -30    Allocate memory for an IFF-file and load it
  57. CloseIFF    -36    Finish access to an IFF-file and deallocate memory
  58. FindChunk    -42    Find a specific chunk in an IFF file
  59. GetBMHD        -48    Find the BitMapHeader of an ILBM file
  60. GetColorTab     -54    Find CMAP chunk, convert it to an Amiga ColorTable
  61. DecodePic    -60    Decode the BODY of an ILBM file into a BitMap
  62. SaveBitMap    -66    Save the contents of a BitMap as an IFF-file
  63. SaveClip    -72    Save a part of a BitMap as an IFF-file
  64. IffError    -78    Get detailed error descrpition if a routine fails
  65. GetViewModes     -84    Get the Amiga-specific ViewModes-Word
  66. NewOpenIFF    -90    Allocate specific memory for an IFF-file and load it
  67. (to be continued)
  68.  
  69.  
  70.  
  71. DETAILED DESCRIPTION OF THE LIBRARY FUNCTIONS
  72. ---------------------------------------------
  73.  
  74. (This documentation was translated from German to English in half an hour,
  75. so please be tolerant!)
  76.  
  77. IFF/NewOpenIFF                                                 IFF/NewOpenIFF
  78.  
  79.    NAME
  80.     NewOpenIFF -- allocate memory for an IFF-file and read it
  81.  
  82.    SYNOPSIS
  83.     ifffile = NewOpenIFF(filename,memattr)
  84.      D0                   A0       D0
  85.  
  86.    OFFSET
  87.         -90
  88.  
  89.    FUNCTION
  90.     This function opens a file on a disk and looks whether it's an IFF
  91.     file or not. If it is an IFF file, memory is allocated and the file
  92.     is read into memory. The 'memattr' argument is taken to define the
  93.     memory type. Normally memattr is set to 0 or MEMF_PUBLIC.
  94.     If an error occurs, 0 is returned, and you can call IffError() to
  95.     get the error number.
  96.  
  97.    INPUTS
  98.     filename - Pointer to a null-terminated string
  99.     memattr  - Memory requirements as used for Exec's AllocMem(),
  100.                such as MEMF_CHIP, MEMF_PUBLIC ...
  101.    RESULT
  102.     ifffile - 'FileHandle', points to the beginning of the IFF file
  103.     ("FORM...."), 0 if unsuccessful. Call IffError() to get the
  104.     reason of the failure.
  105.  
  106.    SEE ALSO
  107.     OpenIFF, CloseIFF, IffError
  108.  
  109.    BUGS
  110.     None
  111.  
  112.  
  113.  
  114.  
  115. IFF/OpenIFF                                                       IFF/OpenIFF
  116.  
  117.    NAME
  118.     OpenIFF -- allocate memory for an IFF-file and read it
  119.  
  120.    SYNOPSIS
  121.     ifffile = OpenIFF(filename)
  122.      D0                A0
  123.  
  124.    OFFSET
  125.         -90
  126.  
  127.    FUNCTION
  128.     This function does the same as the NewOpenIFF() routine above,
  129.     except that you cannot specify the type of memory which is
  130.     allocated for the file. Normally the type is 0 which means 'any
  131.     memory', but if the IFF file type is '8SVX', the file is ALWAYS
  132.     loaded into CHIP memory. If you wish to override these defaults,
  133.     use NewOpenIFF() instead of OpenIFF().
  134.  
  135.    INPUTS
  136.     filename - Pointer to a null-terminated string
  137.  
  138.    RESULT
  139.     ifffile - 'FileHandle', points to the beginning of the IFF file
  140.     ("FORM...."), 0 if unsuccessful. Call IffError() to get the
  141.     reason of the failure.
  142.  
  143.    SEE ALSO
  144.     NewOpenIFF, CloseIFF, IffError
  145.  
  146.    BUGS
  147.     None
  148.  
  149.  
  150.  
  151. IFF/CloseIFF                                                     IFF/CloseIFF
  152.  
  153.    NAME
  154.     CloseIFF -- finish access to an IFF-file and deallocate memory
  155.  
  156.    SYNOPSIS
  157.     CloseIFF(ifffile)
  158.               A1
  159.  
  160.    OFFSET
  161.         -36
  162.  
  163.    FUNCTION
  164.     Returns the memory previously allocated by OpenIFF().
  165.  
  166.    INPUTS
  167.     ifffile - IFF file pointer, from OpenIFF()
  168.  
  169.    RESULT
  170.     none
  171.  
  172.    SEE ALSO
  173.     OpenIFF
  174.  
  175.    BUGS
  176.     If A1 contains garbage, an 81000005 Guru will visit you...
  177.  
  178.  
  179.  
  180.  
  181. IFF/FindChunk                                                   IFF/FindChunk
  182.  
  183.    NAME
  184.     FindChunk -- find an IFF-chunk
  185.  
  186.    SYNOPSIS
  187.     chunk = FindChunk(ifffile,chunkname)
  188.      D0               A1       D0
  189.  
  190.    OFFSET
  191.         -42
  192.  
  193.    FUNCTION
  194.     Find a specific chunk in an IFF file
  195.  
  196.    INPUTS
  197.     ifffile - IFF file pointer, returned by OpenIFF()
  198.     chunkname - 4 characters packed ASCII ('BODY', 'VHDR' ...)
  199.  
  200.    RESULT
  201.     Pointer to the beginning of the chunk (that means to the chunk
  202.     name itself, followed by the chunk size), zero if chunk not found
  203.  
  204.    SEE ALSO
  205.     GetBMHD, GetColorTab
  206.  
  207.    BUGS
  208.     none
  209.  
  210.  
  211.  
  212. IFF/GetBMHD                                                       IFF/GetBMHD
  213.  
  214.    NAME
  215.     GetBMHD -- find a BitMapHeader of an IFF-file
  216.  
  217.    SYNOPSIS
  218.     header = GetBMHD(ifffile)
  219.      D0              A1
  220.  
  221.    OFFSET
  222.         -48
  223.  
  224.    FUNCTION
  225.     Returns a pointer to a 'BitMapHeader' structure as defined in
  226.     iff.h and iff.i
  227.  
  228.    INPUTS
  229.     ifffile - IFF file pointer, returned by OpenIFF()
  230.  
  231.    RESULT
  232.     Pointer to the BitMapHeader, or 0 if no BMHD chunk found
  233.  
  234.    SEE ALSO
  235.     FindChunk, GetColorTab
  236.  
  237.    BUGS
  238.     none
  239.  
  240.  
  241.  
  242.  
  243. IFF/GetColorTab                                               IFF/GetColorTab
  244.  
  245.    NAME
  246.     GetColorTab -- find a CMAP chunk and convert it to a ColorTable
  247.  
  248.    SYNOPSIS
  249.     count = GetColorTab(ifffile,colortable)
  250.      D0                  A1      A0
  251.  
  252.    OFFSET
  253.         -54
  254.  
  255.    FUNCTION
  256.     Searches the CMAP chunk of an IFF file and converts it, if it's
  257.     there, to an Amiga color table structure. This colortable can
  258.     directly be used as a parameter for the LoadRGB4() function.
  259.  
  260.    INPUTS
  261.     ifffile - IFF file pointer, returned by OpenIFF()
  262.     colortable - Pointer to a block of memory which must be large
  263.                  enough to hold the colortable (2 bytes per color)
  264.  
  265.    RESULT
  266.     Number of colors actually found, or zero if the file has no
  267.     CMAP chunk
  268.  
  269.    SEE ALSO
  270.     FindChunk, GetBMHD
  271.  
  272.    BUGS
  273.     the colortable must be WORD aligned (this isn't really a bug)
  274.  
  275.  
  276.  
  277. IFF/DecodePic                                                   IFF/DecodePic
  278.  
  279.    NAME
  280.     DecodePic -- decode an IFF-BODY into a BitMap
  281.  
  282.    SYNOPSIS
  283.     bitmap = DecodePic(ifffile,bitmap)
  284.      D0                 A1      A0
  285.  
  286.    OFFSET
  287.         -60
  288.  
  289.    FUNCTION
  290.     Decodes and decrunches a picture into the BitMap you supplied.
  291.     If the picture is larger than your BitMap's planes, it will be
  292.     truncated. If your BitMap is larger than the picture, the picture
  293.     will be drawn into the top left corner of your BitMap.
  294.     If the picture has more planes (colors) than your BitMap, the
  295.     operation will fail and 0 will be returned.
  296.  
  297.    INPUTS
  298.     ifffile - IFF file pointer, from OpenIFF()
  299.     bitmap  - Pointer to a properly initialized BitMap structure:
  300.           bm_Planes[] must point to valid BitPlanes,
  301.           bm_Depth contains the number of planes.
  302.           bm_Width and bm_Height must be set according to the
  303.           size of your bit planes.
  304.  
  305.    RESULT
  306.     Non-zero if  OK, 0 if error, Call IffError() to know the reason
  307.     of the failure
  308.  
  309.    BUGS
  310.     The width of the IFF picture (in pixels) must be a multiple of 8
  311.     (I've never seen a picture which didn't obey this rule!)
  312.  
  313.  
  314.  
  315.  
  316. IFF/SaveBitMap                                                 IFF/SaveBitMap
  317.  
  318.    NAME
  319.     SaveBitMap -- save the planes of a BitMap as an IFF-file
  320.  
  321.    SYNOPSIS
  322.     result = SaveBitMap(filename,bitmap,colortable,flags)
  323.      D0                  A0       A1     A2         D0
  324.  
  325.    OFFSET
  326.         -66
  327.  
  328.    FUNCTION
  329.     Save the planes of a BitMap as an IFF-file, optionally with a
  330.     colortable. The IFF file will contain the following chunks:
  331.  
  332.     FORM  -  The IFF header, with the type ILBM
  333.     BMHD  -  The BitMap Header structre
  334.     CMAP  -  The color map, this chunk is omitted if colortable is zero
  335.     CAMG  -  The Amiga ViewModes word, contains the special ViewModes
  336.              information (HAM, LACE, HIRES ...)
  337.     BODY  -  The (crunched or uncompressed) picture
  338.  
  339.    INPUTS
  340.     filename    - Name of the IFF file to create
  341.     bitmap      - Pointer to the BitMap holding your picture
  342.     colortable  - Pointer to an Amiga ColorTable structure or zero
  343.                   (if colortable = 0, no CMAP chunk will be generated).
  344.     flags       - Bit 0: 1 = Use the "CmpByteRun1" compression algorythm,
  345.                          0 = Save the file uncompressed
  346.                       Bit 7: 1 = This is a HAM (Hold and modify) picture
  347.                          0 = This is a normal or Extra-Halfbrite picture
  348.  
  349.    RESULT
  350.     Non-zero if successful, 0 if error, Call IffError() to know the
  351.     reason of the failure
  352.  
  353.    SEE ALSO
  354.     SaveClip
  355.  
  356.  
  357.  
  358. IFF/SaveClip                                                     IFF/SaveClip
  359.  
  360.    NAME
  361.     SaveClip -- save a part of a BitMap as an IFF-file
  362.  
  363.    SYNOPSIS
  364.     result = SaveClip(filename,bitmap,coltab,flags,xoff,yoff,width,height)
  365.      D0                A0       A1     A2     D0    D1   D2   D3    D4
  366.  
  367.    OFFSET
  368.         -72
  369.  
  370.    FUNCTION
  371.     Save a part of a BitMap as an IFF file
  372.  
  373.    INPUTS
  374.     filename    - Name of the IFF file to create
  375.     bitmap      - Pointer to the BitMap holding your picture
  376.     colortable  - Pointer to an Amiga ColorTable structure or zero
  377.                   (if colortable = 0, no CMAP chunk will be generated).
  378.     flags       - Bit 0: 1 = Use the "CmpByteRun1" compression algorythm,
  379.                          0 = Save the file uncompressed
  380.                       Bit 7: 1 = This is a HAM (Hold and modify) picture
  381.                          0 = This is a normal or Extra-Halfbrite picture
  382.     xoff        - X offset of the clip to be saved (bytes from the left)
  383.     yoff        - Y offset of the clip to be saved (lines from the top)
  384.     width       - width in bytes of the rectangle
  385.     height      - height in lines of the rectangle
  386.  
  387.    RESULT
  388.     Non-zero if successful, 0 if error, Call IffError() to know the
  389.     reason of the failure
  390.  
  391.    SEE ALSO
  392.     SaveBitMap
  393.  
  394.    BUGS
  395.     The width of the rectangle will be rounded to WORD boundaries,
  396.     because DPAINT® wants it!
  397.  
  398.  
  399.  
  400.  
  401. IFF/IffError                                                     IFF/IffError
  402.  
  403.    NAME
  404.     IffError -- Get detailed error descrpition
  405.  
  406.    SYNOPSIS
  407.     error = IffError()
  408.     D0
  409.  
  410.    OFFSET
  411.         -78
  412.  
  413.    FUNCTION
  414.     If one of the above functions returns zero, you can call IffError()
  415.     to know the reason for the failure. An error code is returned,
  416.     please refer to the files 'iff.h' or 'iff.i' for the complete
  417.     list of errors!
  418.  
  419.    INPUTS
  420.     none
  421.  
  422.    RESULT
  423.     Error-number generated by the latest function call, or zero if
  424.     no error
  425.  
  426.     Cuurently the following numbers are used:
  427.  
  428.     Nr.  Symbol             Function     Description
  429.  
  430.     16   IFF_CANTOPENFILE   OpenIFF()    File not found
  431.     17   IFF_READERROR      OpenIFF()    Read() returned an error
  432.     18   IFF_NOMEM          OpenIFF()    Not enough memory for the file
  433.     19   IFF_NOTIFF         OpenIFF()    File is not IFF
  434.     20   IFF_WRITEERROR    SaveBitMap() Cannot write the file
  435.  
  436.     24   IFF_NOILBM         DecodePic()  IFF file is not an ILBM file
  437.     25   IFF_NOBMHD         DecodePic()  BMHD chunk not found
  438.     26   IFF_NOBODY         DecodePic()  BODY chunk not found
  439.     27   IFF_TOOMANYPLANES  DecodePic()  Picture has more planes than
  440.                                          your BitMap
  441.     28   IFF_UNKNOWNCOMPRESSION  "       Unknown compression type
  442.  
  443.     -1   IFF_BADTASK        A task which did not open the IFF library
  444.                             tried to call IffError(). Since the IFF
  445.                             library is capable of multi-tasking, the
  446.                             error-values are stored for each task
  447.                             separately.
  448.  
  449.    SEE ALSO
  450.  
  451.    BUGS
  452.     If you don't close the IFF library at the end of your program
  453.     (using CloseLibrary()) the error node will not be freed. The
  454.     same task will then not be able to re-open the iff.library!!!
  455.  
  456.  
  457.  
  458. IFF/GetViewModes                                             IFF/GetViewModes
  459.  
  460.    NAME
  461.     GetViewModes -- Get Amiga-specific ViewModes-Word
  462.  
  463.    SYNOPSIS
  464.     viewmodes = GetViewModes(ifffile)
  465.     D0                        A1
  466.  
  467.    OFFSET
  468.         -84
  469.  
  470.    FUNCTION
  471.     Searches the IFF file for a 'CAMG' chunk which holds the view modes
  472.     information. If there is no CAMG chunk, the view modes are calcu-
  473.     lated using the information in the BitMapHeader structure.
  474.     You can set the result of GetViewModes() directly into the
  475.     ns_ViewModes field of a NewScreen structure!
  476.  
  477.    INPUTS
  478.     ifffile - IFF file pointer, returned from OpenIFF()
  479.  
  480.    RESULT
  481.     viewmodes - WORD containing the view modes (HAM, LACE, HIRES ...)
  482.  
  483.    SEE ALSO
  484.  
  485.    BUGS
  486.     If the IFF file has no CAMG chunk and 6 bitplanes, the HAM bit
  487.     will be set. This is not always correct since the picture could
  488.     be in the Extra Halfbrite mode.
  489.  
  490.  
  491. PS: The file 'ShowIff.c' shows you how to use the IFF library from C.
  492.  
  493.