home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / Basic / bb_ext.dms / in.adf / LibsDev.lha / userlibdocs / ElmoresIncLib.doc < prev    next >
Encoding:
Text File  |  1994-09-05  |  15.1 KB  |  567 lines
  1. Library Name:
  2.   elmoreinclib      #111  ;see other doc
  3.  
  4. Author:
  5.   Richard T Elmore, HeadSoft, 126 STATE ST. #20, SPEARFISH, SD 57783, USA
  6.  
  7. OverView:
  8.   This is a crippled version of a library which Richard has put
  9.   a whole heap of time into. It basically allows you to include
  10.   compressed object data into your programs which you can unpack
  11.   at your leisure. Please see the registration material at the
  12.   bottom of this file if you like what you see.
  13.  
  14.   Demo, util and lh.library are in userlibprogs/elmore.
  15.  
  16. Commands:
  17.   IncSound      *success=IncSound(Sound#, ?Label)
  18.   IncBitmap     *success=IncBitmap(bitmap#,?Label)
  19.   IncMod        *success=IncMod(ST-NT Module#,?Label)
  20.   IncMed        *success=IncMed(MEDModule#,?Label)
  21.   IncShape      *success=IncShape(Shape#,?Label[,Cookiecut?])
  22.   IncNextShape  *success=IncNextShape [CookieCut?]
  23.  
  24.   IncText$      string$=IncText$(?Label[,optional length])
  25.   SaveIncData   *success=SaveIncData(Filename$,?Label)
  26.   IncData       Address=IncData(?Label,memory type)
  27.   IncData       asmloc.l=IncData(?mlroutine,0)
  28.   IncSize       FreeIncData IncSize(?mlroutine),asmloc
  29.   IncDataAbs    bytesize=IncDataAbs(?Label,Destination Address)
  30.  
  31. Author's Docs:
  32.  
  33.  
  34.  
  35.                          ABOUT INCLUDE.ELMORELIB
  36.                         =========================
  37.  
  38.  
  39.   The Include library by Richard T. Elmore of HeadSoft Software enables
  40. Blitz2 programmers to make stand-alone files that don't require special
  41. directories, external IFF files, etc. to run.  To achieve this in the most
  42. efficient manner possible, the incredible efficiency and speed of the
  43. LH.Library is used (in the INCLUDE-UTIL tool, which is freely distributeable.)
  44.  
  45.   At present, the Include library supports Bitmaps, (up to 8 bitplanes!)
  46. sound effects, MED music modules, IFF brushes for Blitz2 SHAPES,
  47. Blitz2 SHAPES-FILES for multiple shapes, (as created by the SAVESHAPES command
  48. or with the SHAPESMAKER utility) entire ASCII text files, or raw binary data
  49. which gives the advanced programmer the ability to include other object types
  50. or other data such as executeable programs, variable arrays for cosine tables,
  51. etc.
  52.  
  53.   The library was designed with Blitz2's INCBIN compiler directive, but may
  54. also be used with data loaded with READMEM or similar commands, to conserve
  55. disk space when you don't mind having external files, not to mention they will
  56. be made next to impossible to "rip" by anyone without the Include Library!
  57.  
  58.  
  59.   NOTE:  Your executeables do NOT require the "lh.library" to run...  They
  60. will have their own self-contained decrunching routine (which is much faster
  61. than the crunching routine in lh.library!)
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.                         USING THE INCLUDE-UTIL PROGRAM
  69.                        ================================
  70.  
  71.   In order to include the above-mentioned data in your Blitz2 executeables,
  72. the original data files must be converted and packed so that the resulting
  73. runtime program consumes the least memory possible.  This also allows the data
  74. to be stored in public or "fast" memory, not just CHIP ram.  The INCLUDE-UTIL
  75. program is supplied with the library to convert the data for you.
  76.  
  77.  
  78.   First, ensure the "LH.Library" file resides in your LIBS: directory.  The
  79. INCLUDE-UTIL program will crash if it isn't availble.
  80.  
  81.  
  82.   In order to run the program, just click on it's icon, and a custom screen
  83. will appear containing icons representing the types of data you wish to
  84. convert to includeable data.  Note that the ST/NT Module button is ghosted, as
  85. this data type is not supported in the public domain release of the library.
  86.  
  87.   You may note there is a gadget to "quit" even though there is also a "close"
  88. gadget in the top-left of the main window.  Clicking the close-gadget will
  89. NOT quit the program, it will merely close the window and screen, then an
  90. icon will appear on the Workbench screen.  Simply click the icon to reactivate
  91. the program.  (While in this idle mode, INCLUDE-UTIL uses no processor time
  92. and consumes less memory.)
  93.  
  94.   Upon clicking one of the other icons, a file requester will appear prompting
  95. you to select a source file (the IFF, text, MOD, whatever) to convert.
  96. Note that you may load either IFF brushes *OR* BB2 shapes-files in the
  97. SHAPES filerequester, the appropriate INCLUDE-OBJECT type will be created.
  98.  
  99.   After the file has been converted to it's INCLUDE-OBJECT form, you will be
  100. given a filerequester to SAVE the object with.  Note that an INCLUDE-OBJECT
  101. extension will be appended to the filename to help you more easily recognise
  102. the object types in a directory listing.  They are:
  103.  
  104.  
  105.  
  106.   .ISFX     - Sound effects
  107.   .IBMP     - Bitmaps
  108.   .ISHP     - Single shapes
  109.   .ISHPS    - Multiple shapes
  110.   .IMED     - MED modules
  111.   .IBIN     - Either binary or text (IncText$, IncDataABS, IncData, etc.)
  112.  
  113.  
  114.  
  115.  
  116.   The INCLUDE-UTIL program accepts tooltypes for default paths.  Then
  117. whenever you click on an appropriate gadget the file requester will use
  118. the path you prefer.  The following keywords identify the paths:
  119.  
  120.  
  121. SOUNDS=pathname
  122. BITMAPS=pathname
  123. SHAPES=pathname
  124. MODULES=pathname
  125. BINARIES=pathname
  126. SAVE=pathname     (This is the same path for saving all object types)
  127.  
  128.  
  129.   You should keep the name of this utility "INCLUDE-UTIL" or the
  130. tooltype preferences will not be available.
  131.  
  132.  
  133.   A few features are available under OS2.0 and above only:  Notably,
  134. when you iconify INCLUDE-UTIL, it uses a real appicon, so you can drag
  135. objects onto it to have them automatically identified and loaded.  You
  136. can also simply double-click the icon without dragging anything if you
  137. just want to wake the program up.
  138.  
  139.  
  140.  
  141.  
  142.  
  143.   Now that you have your INCLUDE-OBJECTs, how do you go about making them
  144. part of your Blitz2 executeables?  It is relatively simple, but you must be
  145. careful to follow these guidelines unless you know EXACTLY what you're doing
  146. or you'll crash your Amiga!
  147.  
  148.  
  149. 1.  Place a copy of Include.ElmoreLib in your Blitzlibs:Userlibs directory,
  150. then optionally create a new DEFLIBS file.
  151.  
  152.  
  153.  
  154. 2.  Write and debug your program using normal loading routines until you're
  155. satisfied with it.  No need to use INCLUDE-OBJECTs during debugging, as it
  156. will only slow down development.  (Before being made executeable, Blitz2
  157. will both load the objects from disk AND decrunch them.)
  158.  
  159.  
  160.  
  161. 3.  Go to the end of your sourcecode (usually the safest place) and select
  162. a different program label for EACH INCLUDE-OBJECT to be decrunched at
  163. run-time.  Directly following the label, enter INCBIN "filename" which should
  164. reference the name you saved the INCLUDE-OBJECT as from INCLUDE-UTIL.
  165. See page 8-3 of your Blitz2 reference manual for details on INCBIN and
  166. INCDIR commands if you're not familiar with them.
  167.  
  168.  
  169.  
  170. 4.  Ensure you have an "END" statement or some such before your fist
  171. INCLUDE-OBJECT's label.  If program flow continues into the data, you will
  172. almost surely have a crash.
  173.  
  174.  
  175.  
  176. 5.  Replace your Blitz2 DOS-based loading commands with the approriate
  177. Include library versions.  It's wise to check the results of those commands
  178. that return "success" or "failure" (TRUE or FALSE) so that your program can
  179. exit gracefully if there isn't enough memory, etc. when its run.
  180.  
  181.  
  182.  
  183. 6.  That's all!  You should be able to run your program normally, and
  184. executeables you create will run fine with graphics, sounds, whatever you
  185. want, and *NO* external files needed!!  Of course since all the data is
  186. included in the size of the executeable, it will be much larger than usual.
  187. (Size of INCLUDE-OBJECTs+normal executeable size)  You may have some success
  188. crunching the entire executeable with PowerPacker or similar programs, but
  189. if the percentage of INCLUDE-OBJECT data in the executeable is very high,
  190. most crunchers will choke on it, since most of the program is already crunched
  191. by INCLUDE-UTIL.
  192.  
  193.  
  194.  
  195.  
  196.  
  197.                              ELMORE.INCLUDELIB
  198.  
  199.  
  200.   Well, okay, these docs are not the best, but I only had 25 minutes! :-)
  201.  
  202.  
  203. Anyway, I will give you the syntax and an example for each command, and
  204. I'll get some example sourcecodes to you as soon as possible.
  205.  
  206. Commands marked with a star (*) can be used either as a function or a
  207. statement, depending upon whether you're interested in their success or
  208. not.  About the only reason the commands could fail is insufficient memory
  209. or the executeable was corrupt or something.
  210.  
  211. Functions that are marked with *success=.....  will return either TRUE
  212. or FALSE (-1 or 0) depending on whether they could be unpacked etc.
  213.  
  214.  
  215.  
  216.  
  217.  
  218. *success=IncSound(Sound#, ?Label)
  219.  
  220. Ensure you put the question mark before the label name or you'll have
  221. errors!  The actual include-object should be INCBINed directly after the
  222. label, and be careful to put an END statement somewhere above your INCBIN
  223. data or you'll crash!
  224.  
  225.  
  226.  
  227. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  228.  
  229. ;Example
  230.  
  231. If IncSound(0,?Mysound)=False Then End  ;Unpack the sound or end!
  232.  
  233. Sound 0,15  ;Play it back!
  234.  
  235. Mousewait   ;pause for the user....
  236.  
  237. End
  238.  
  239.  
  240.  
  241. Mysound:
  242. IncBin "RAM:SoundEffect.isfx"
  243.  
  244.  
  245. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  246.  
  247.  
  248.  
  249. NOTE:  In the above example the FUNCTION version was used so you could
  250. test it with an IF/THEN statement to see if it was successful...  If
  251. you don't think you'll need to be so careful, the STATEMENT version would
  252. be:
  253.  
  254.  
  255.  
  256. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  257.  
  258. ;Example
  259.  
  260. IncSound 0,?Mysound  ;Unpack the sound (Note no parentheses for statement!)
  261.  
  262. Sound 0,15  ;Play it back!
  263.  
  264. Mousewait   ;pause for the user....
  265.  
  266. End
  267.  
  268. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  269.  
  270.  
  271.  
  272.  
  273.  
  274.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280. *success=IncBitmap(bitmap#,?Label)
  281.  
  282. Nearly identical in useage to IncSound (above)
  283. Note that if the bitmap already exists, it should be the same dimensions
  284. such as 640x256x4 or IncBitmap will return FALSE (for failure)  if you
  285. don't know for sure, you can let IncBitmap create the bitmap exactly like
  286. it was Included by doing FREE BITMAP 0 or some such before you INCBITMAP it.
  287.  
  288.  
  289.  
  290. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  291.  
  292. ;Example
  293.  
  294. Blitz
  295.  
  296. If IncBitmap(0,?Mypicture)=0 Then End
  297.  
  298. Slice 0,32,4
  299.  
  300. Show 0
  301.  
  302. Mousewait:end
  303.  
  304.  
  305. Mypicture:
  306. IncBin "RAM:Picture.ibmp"
  307.  
  308. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316. *success=IncMod(ST-NT Module#,?Label)
  317.  
  318. Like the above examples, only for music mods.   You could then
  319. use StartModule etc. just as if you had loaded it from disk.
  320.  
  321. ----------- NOTE: This function is a bit buggy, so it has
  322.             been temporarily disabled with this release of
  323.             the library!  (Sorry!) --------------------------------
  324.  
  325.  
  326.  
  327.  
  328. *success=IncMed(MEDModule#,?Label)
  329.  
  330. For including MED modules.  Usage is otherwise the same as IncMod.
  331.  
  332.  
  333.  
  334.  
  335.  
  336. *success=IncShape(Shape#,?Label[,Cookiecut?])
  337.                                ^^^^^^^^^^^^
  338.                                OPTIONAL DUMMY VALUE
  339.  
  340.  
  341. The one you've been waiting for!  Will retrieve the shape# for BLITTING...
  342. Along with the command below, IncNextShape, you can even include several
  343. shapes in one step!  I will be adding multiple shapes as an option in the
  344. INCLUDE-UTIL program as well... For now, just INCBIN as many shapes as you
  345. want (only need label for the first one)
  346.  
  347. Note: If you don't need a cookiecut for the shape, you can leave out the
  348. CookieCut parameter.  Any number placed in the cookiecut parameter will
  349. cause a cookiecut to be made for the shape when it is made however.  If
  350. you plan to do BLITs etc. you should always use the cookiecut.
  351.  
  352.  
  353. *success=IncNextShape [CookieCut?]
  354.                       ^^^^^^^^^^^^
  355.                       OPTIONAL DUMMY VALUE
  356.  
  357.  
  358.  
  359.  
  360. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  361.  
  362.  
  363. ;Example:
  364.  
  365.  
  366. ;Include shape #0
  367. IncShape(0,?Shapes,1)
  368.  
  369.  
  370. ;Will loop 3 times from shape #1 to #3 in this case
  371.  
  372. While IncNextShape(1):Wend
  373.  
  374.  
  375. ;(Do your blitting stuff etc. here)
  376.  
  377.  
  378. End
  379.  
  380.  
  381.  
  382. Shapes:
  383. IncBin "Shape0.ISHP"
  384. IncBin "Shape1.ISHP"
  385. IncBin "Shape2.ISHP"
  386. IncBin "Shape3.ISHP"
  387.  
  388.  
  389. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  390.  
  391.  
  392.  
  393.  
  394. ;(Note this is a FUNCTION only, no statement version)
  395.  
  396.  
  397. string$=IncText$(?Label[,optional length])
  398.  
  399.  
  400. Used with BINARY include types....  You can then put whole text files
  401. into strings.  The optional LENGTH will limit then string length to
  402. whatever number you want, similar to the LEFT$ function.
  403. It will only return a null-string "" in case of failure.
  404.  
  405.  
  406. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  407.  
  408. a$=IncText$(?text)
  409. Nprint a$
  410.  
  411. b$=IncText$(?text2,32)
  412. Nprint b$
  413.  
  414. Mousewait:End
  415.  
  416.  
  417. text:
  418. IncBin "Message.IBIN"
  419.  
  420. text2:
  421. IncBin "Greetz.IBIN"
  422.  
  423. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  424.  
  425.  
  426.  
  427.  
  428.  
  429. *success=SaveIncData(Filename$,?Label)
  430.  
  431.  
  432. This will write to disk the unpacked version of whatever BINARY
  433. include-object you specify.  One good use of this is to save
  434. programs to RAM and then EXECUTE them, and DELETE them again.
  435.  
  436. Of course there are hundreds of uses....
  437.  
  438.  
  439. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  440.  
  441. If SaveIncData("Ram:newfile",?executeable)=0 Then End
  442.  
  443. Execute_ "Ram:Newfile"
  444.  
  445. KillFile "Ram:Newfile"
  446.  
  447. End
  448.  
  449.  
  450. executeable:
  451. IncBin "myprog.ibin"
  452.  
  453.  
  454. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  455.  
  456.  
  457.  
  458.  
  459.  
  460. Address=IncData(?Label,memory type)
  461.  
  462. This allows you to include BINARY data for any number of uses that
  463. aren't provided with the other functions.  Memory types are:
  464.  
  465.  
  466. 0-  Any kind of memory (preferably FAST RAM)
  467.  
  468. 2-  CHIP RAM ONLY!
  469.  
  470.  
  471.  
  472. This function will return the address of the binary data in
  473. memory, or 0 for failure....
  474.  
  475.  
  476.  
  477. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  478.  
  479. ;Example of including a pure ASM routine object file for execution:
  480.  
  481.  
  482. asmloc.l=IncData(?mlroutine,0)
  483.  
  484. Call asmloc
  485.  
  486. End
  487.  
  488.  
  489. mlroutine:
  490. IncBin "Ram:MLRoutine.IBIN"
  491.  
  492.  
  493. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  494.  
  495.  
  496. size.l=IncSize(?Label)
  497.  
  498. Returns the size in bytes of the BINARY object at the specified label
  499. Among other uses, you need it if you want to FREE the uncrunched
  500. binary data.  (It will automatically be freed when your program ends)
  501.  
  502.  
  503.  
  504. FreeIncData Size,Address
  505.  
  506.  
  507. If you wanted to free up the memory allocated by the above IncData
  508. function, here is how you'd do it:
  509.  
  510.  
  511. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  512.  
  513. FreeIncData IncSize(?mlroutine),asmloc
  514.  
  515. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  516.  
  517.  
  518.  
  519.  
  520.  
  521. ***********************************************************
  522. **                                                       **
  523. **  A D V A N C E D :  Use with caution!                 **
  524. **                                                       **
  525. ***********************************************************
  526.  
  527.  
  528.  
  529. This command will unpack the binary data directly to the area of memory
  530. you specify, so if you're not sure what you're doing you'll probably
  531. GURU the Amiga!  However, it is very useful to fill arrays, uncrunch data
  532. directly to Banks, or whatever.  Just be careful!
  533.  
  534.  
  535. bytesize=IncDataAbs(?Label,Destination Address)
  536.  
  537. It will return zero for failure, or the number of bytes in the binary
  538. object.  I'll provide a better example of making use of this function
  539. later....  (Filling up array variables, etc.)
  540.  
  541.  
  542.  
  543.  
  544. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  545.  
  546.  
  547. InitBank 0,1000,0
  548.  
  549. size.l=IncDataAbs(?Binary,BankLoc(0))
  550.  
  551. Mousewait:End
  552.  
  553. Binary:
  554. IncBin "binarydata.IBIN"
  555.  
  556.  
  557. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  558.  
  559.  
  560. That's it for now---- I'm improving the INCLUDE-UTIL to make it
  561. easier to use and provide a few more functions like multiple shapes
  562. and source-code generator.... Anyway, call me if you have any questions
  563. or find a bug....
  564.  
  565.  
  566. 1-605-642-1564
  567.