home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / Basic / wst!blz1.dms / in.adf / docs / rilibdocs.lha / RIPackLib.doc < prev    next >
Encoding:
Text File  |  1994-09-05  |  7.7 KB  |  194 lines
  1. Library Name:
  2.   ripacklib #73
  3.  
  4. Authors:
  5.   ReflectiveImages, 17 Mayles Road, Southsea, Portsmouth, Hampshire, UK PO4 8NP
  6.  
  7. OverView:
  8.   Another Reflective Images Library, impriving Blitz2's IFF handling skills.
  9.  
  10. Commands:
  11.   UnpackIFF address.l,bitmap#[,lines,offset]
  12.   suc=UnpackIFF (address.l,bitmap#[,lines,offset])
  13.   ILBMPalette address.l,palette#
  14.   suc=ILBMPalette (address.l,palette#)
  15.   ILBMGrab address.l,bitmap#,palette#
  16.   LoadIFF filename$,bitmap#[,palette#]
  17.   suc=LoadIFF (filename$,bitmap#[,palette#])
  18.   DeIce source_address,dest_address
  19.   suc=DeIce (source_address,dest_address)
  20.   val.l=ChunkHeader (A$)
  21.  
  22. Authors Documentation:
  23.  
  24. PACK Library v0.1
  25. =================
  26.  
  27. By Stephen McNamara with a little help from Steve Matty
  28. (c)1994 Reflective Images
  29.  
  30. This library contains commands for the unpacking of ILBM's (IFF pictures)
  31. and the grabbing of their palettes (CMAP chunks).  Nearly all the commands
  32. in this library can be used as either STATEMENTS or FUNCTIONS.  Usage is
  33. identical in both cases but if used as a function then the command will
  34. return:
  35.     FALSE for failure
  36.     TRUE for success
  37.  
  38. Please feel free to critisise (or praise!) this library, send me anything
  39. you want to say about it at:
  40.  
  41.       Stephen McNamara,
  42.         17 Mayles Road,
  43.               Southsea,
  44.             Portsmouth,
  45.              Hampshire,
  46.                England.
  47.                PO4 8NP.
  48.   Telephone: (England) 0705 781507.
  49.  
  50. Or send us anything you've written........
  51.  
  52.  
  53. Command list:
  54.       UnpackIFF address.l,bitmap#[,lines,offset]
  55.       suc=UnpackIFF (address.l,bitmap#[,lines,offset])
  56.       ILBMPalette address.l,palette#
  57.       suc=ILBMPalette (address.l,palette#)
  58.       ILBMGrab address.l,bitmap#,palette#
  59.       LoadIFF filename$,bitmap#[,palette#]
  60.       suc=LoadIFF (filename$,bitmap#[,palette#])
  61.       DeIce source_address,dest_address
  62.       suc=DeIce (source_address,dest_address)
  63.       val.l=ChunkHeader (A$)
  64.  
  65. Statement/Function: UnpackIFF
  66. ------------------------------------------------------------------------
  67. Modes : Amiga/Blitz
  68. Syntax: UnpackIFF address.l,bitmap#[,lines,offset]
  69.   suc=UnpackIFF (address.l,bitmap#[,lines,offset])
  70.  
  71.   This command is used to unpack an IFF picture file from memory onto a
  72. bitmap.  Address.l should point to the START of the iff file header in
  73. memory (either CHIP or FAST mem can be used), bitmap should be the number
  74. of a previously initialised bitmap.  The optional lines parameter allows
  75. you to specify the number of lines to unpack from the IFF file.
  76.   This command checks the size of the bitmap against the size of the IFF
  77. before it unpacks the IFF onto it.  Checks are made for width, height and
  78. depth of the bitmap and the IFF and the following is done:
  79.  
  80. (size=WIDTH, HEIGHT and DEPTH)
  81.  
  82.     BITMAP 'size' < IFF 'size' : unpack aborted
  83.     BITMAP 'size' = IFF 'size' : pic is unpacked
  84.     BITMAP 'size' > IFF 'size' : pic is unpacked
  85.  
  86.   Extra aborts can be caused by:
  87.     - not using a previously installed bitmap
  88.     - given the optional lines parameter as 0 or less
  89.     - not giving ADDRESS.l as a pointer to a valid IFF ILBM
  90.       header
  91.  
  92.   When using the optional parameters, you should note that if you try to
  93. unpack more lines than the IFF has, the unpack routine will automatically
  94. stop at the last line of the IFF.  It will not reject the UnpackIFF
  95. command.  Also note that the offset is a byte offset from the start of the
  96. bitplanes.  You can use the AddValue command to calculate this value.
  97.  
  98.   NOTE: you should save your IFF pictures with the STENCIL OFF because at
  99. the moment this routine does not check to see if STENCIL data is present in
  100. the IFF file.
  101.  
  102. Statement/Function: ILBMPalette
  103. ------------------------------------------------------------------------
  104. Modes : Amiga/Blitz
  105. Syntax: ILBMPalette address.l,palette#
  106.   suc=ILBMPalette (address.l,palette#)
  107.  
  108.   This command is used to grab the palette from a IFF picture file held in
  109. memory (CHIP or FAST mem).  Address.l should be given as the address of
  110. either an IFF file in memory or a CMAP chunk in memory.  When you use the
  111. SAVE PALETTE command from inside an art program (e.g. DPaint) or from
  112. inside Blitz2, the program saves out a CMAP chunk which gives details
  113. about the palette.  The CMAP chunk is also saved with IFF picture files to
  114. give the palette of the picture.
  115.   This command will look at the address you gave and try and find a CMAP
  116. chunk from the address given to address+5120.  If it finds a chunk it will
  117. grab the palette into the given palette object.  If the palette object
  118. already contains palette information then this information is deleted.
  119. This routine looks in the CMAP chunk and reserves the palette object to
  120. have the same number of colour entries.
  121.   This command will fail if it doesn't find a CMAP chunk.
  122.  
  123.  
  124. Statment: ILBMGrab
  125. ------------------------------------------------------------------------
  126. Modes : Amiga/Blitz
  127. Syntax: ILBMGrab address.l,bitmap#,palette#
  128.  
  129.   This command lets you grab both the palette and the graphics from an IFF
  130. picture file with just one command.  It returns to success parameter to
  131. say whether or not it succeeded in grabbing the data, so if you need to know
  132. if the grabbing was successful you'll have to use the separate commands
  133. for grabbing palettes and graphics.
  134.  
  135.   NOTE: this command essentially just calls both UnpackIFF and ILBMPalette
  136. so everything said about these commands is relevent for ILBMGrab.
  137.  
  138.  
  139. Statment/Function: LoadIFF
  140. ------------------------------------------------------------------------
  141. Modes : Amiga
  142. Syntax: LoadIFF filename$,bitmap#[,palette#]
  143.   suc=LoadIFF (filename$,bitmap#[,palette#])
  144.  
  145.   This command is a direct replacement for Blitz2's LoadBitmap.  It is a
  146. lot faster than Blitz's command since it loads the file into memory and
  147. then unpacks it from there.  Thus you need to ensure that you have enough
  148. free memory to load the IFF into before trying to use this command.
  149.   This command is also more stable than Blitz's since it checks for the
  150. existence of the file before trying to load it in.
  151.   The optional parameter allows you to load in the palette of the IFF
  152. picture.  Refer to UnpackIFF and ILBMPalette for more information about
  153. unpacking the graphics and grabbing the palettes.
  154.  
  155. IMPORTANT NOTE: to use this command you must have our FUNC library
  156. installed in your copy of Blitz2.  Use of this command without this library
  157. will probably lead to a bad crash of your Amiga!
  158.  
  159. Statement/Function: DeIce
  160. ------------------------------------------------------------------------
  161. Modes : Amiga
  162. Syntax: DeIce source_address,dest_address
  163.   suc=DeIce (source_address,dest_address)
  164.  
  165.   This is a command from my (Stephen McNamara) past.
  166.   It is used to unpack data files packed by my favourite Atari ST packer -
  167. PACK ICE v2.40.  I've put it into Blitz because still have loads of files
  168. that I've packed with it.  To use it, source_address should (obviously)
  169. contain the address of the data, dest_address should be where to unpack the
  170. data to.  In the function form, this command returns either 0 for unpack
  171. failed or -1 for success.
  172.   Note: The size of the data unpacked is the long word at source_address+8
  173. (I think, or is it 4?) if anybody is interested......
  174.  
  175.  
  176. Function: ChunkHeader
  177. ------------------------------------------------------------------------
  178. Modes : Amiga
  179. Syntax: val.l=ChunkHeader (A$)
  180.  
  181.   This command was put in by me (Stephen McNamara) before I realised Blitz
  182. already had a command that does exactly the same.  I've left it in just
  183. because I want to.  It is useful when looking through IFF files for chunks
  184. (e.g. ILBM, CMAP, etc.) as it gives you a longword value to look for in
  185. memory to find the chunk.  The string should be a four character string
  186. (e.g. CMAP), you'll be returned the longword value of the string.
  187.   This command does the job of the following bit of Blitz2 code:
  188.  
  189.     a$="CMAP"
  190.     val.l=Peek.l(&a$)
  191.  
  192.  
  193. >> END
  194.