home *** CD-ROM | disk | FTP | other *** search
/ EuroCD 3 / EuroCD 3.iso / Programming / BlitzBasic / elmorelib / ElmoreLib.Doc < prev    next >
Encoding:
Text File  |  1998-06-24  |  16.7 KB  |  619 lines
  1.   Library name: ELMORELIB
  2.     Written by: Richard T. Elmore
  3.      Copyright: 1994 HeadSoft Software
  4. Library number: 111
  5.  
  6.  
  7.  
  8.  
  9. ******************************************************************************
  10. ***************************** HARDWARE PROGRAMMING ***************************
  11. ******************************************************************************
  12.  
  13.  
  14.  
  15.  
  16.  
  17. Statement: QUIET 
  18. ****************
  19.      Syntax: Quiet ChannelMask 
  20.       Modes: Amiga or Blitz
  21. Description: 
  22. This command will silence the sound channels specified by ChannelMask.
  23. See the description for "Envelope" for more information on channelmasks.
  24.  
  25.  
  26. Statement: FREQ
  27. ***************
  28.      Syntax: Freq Channelmask,period
  29.       Modes: Amiga or Blitz
  30. Description:
  31. This command allows you to change the period, or pitch, of the
  32. currently playing sound effect.  Note that the lower the period,
  33. the higher the frequency; Thus, a period of 100 would be very
  34. high-pitched, whereas a period of 30000 would be low-pitched.
  35.  
  36.  
  37.  
  38.  
  39. Function: TICKS 
  40. ***************
  41.      Syntax: Ticks  
  42.       Modes: Amiga or Blitz
  43. Description: 
  44. This function returns the number of "ticks" since the Amiga was switched
  45. on, or since the last "RESETTIMER" command.  The unit of measurement is
  46. 1/60 of a second for NTSC machines, and 1/50 of a second for PAL machines.
  47.  See Also:
  48.  ResetTimer
  49.  
  50.  
  51.  
  52.  
  53. Statement: RESETTIMER 
  54. *********************
  55.      Syntax: ResetTimer  
  56.       Modes: Amiga or Blitz
  57. Description: 
  58. Resets the Amiga's hardware timer to zero "ticks."  Read the description
  59. for "TICKS" for more information.
  60.  
  61.  
  62. Function: JOYC 
  63. **************
  64.      Syntax: JoyC (Port)  
  65.       Modes: Amiga or Blitz
  66. Description: 
  67. This function works similarly to the JoyB() function, however it allows
  68. you to read the second fire button on two-button joysticks.  It will
  69. return a 1 if the normal fire button is pressed, a 2 if the second button
  70. is pressed, or 3 if both buttons are pressed.  Otherwise, it will return
  71. a zero (no buttons pressed.)
  72.  
  73.  
  74.  
  75. Statement: VWAITPOS 
  76. *******************
  77.      Syntax: VWaitPos RasterLine
  78.       Modes: Amiga or Blitz
  79. Description:
  80. This command is similar to VWAIT, except it allows you to wait for
  81. any raster position, not just the top of the display.  This is useful
  82. for interesting graphics effects.
  83.  
  84.  
  85.  
  86. Function: CHECKAGA
  87. ******************
  88.      Syntax: CheckAGA  
  89.       Modes: Amiga or Blitz
  90. Description: 
  91. Returns 'TRUE' for AGA machines, otherwise returns 'FALSE.'
  92. Using ExecVersion alone will not detect an AGA machine.  Kickstart version
  93. 39 can and does run on pre-AGA machines, such as the A3000, etc.  Therefore,
  94. this function is provided to allow you to accurately determine if the
  95. AGA chipset is present.
  96.  
  97.  
  98.  
  99.  
  100. Function: PEEKTO$ 
  101. *****************
  102.      Syntax: PeekTo$ (Address,byte)  
  103.       Modes: Amiga or Blitz
  104. Description: 
  105. PeekTo$() is similar to the Peek$() function, except you can specify
  106. what terminator byte to use.  With Peek$() the terminator will always
  107. be zero, but PeekTo$() will accept any byte value as a terminator.
  108.  
  109.  
  110.  
  111. Statement: FORCEPAL 
  112. *******************
  113.      Syntax: ForcePAL  
  114.       Modes: Amiga or Blitz
  115. Description: 
  116. This command switches the current screen from NTSC to PAL.
  117.  
  118.  
  119.  
  120. Statement: FORCENTSC 
  121. ********************
  122.      Syntax: ForceNTSC  
  123.       Modes: Amiga or Blitz
  124. Description: 
  125. This command switches the current screen from PAL to NTSC.
  126.  
  127.  
  128.  
  129. Function: DEPTH 
  130. ***************
  131.      Syntax: Depth (Bitmap#) 
  132.       Modes: Amiga or Blitz
  133. Description: 
  134. This function returns the depth of the specified Blitz2 bitmap object.
  135.  
  136.  
  137.  
  138. Statement: CLICKMOUSE 
  139. *********************
  140.      Syntax: ClickMouse  
  141.       Modes: Amiga or Blitz
  142. Description: 
  143. Similar to Mousewait, this command halts program execution until
  144. the user clicks the mouse.  There must must be a separate mouseclick
  145. for each CLICKMOUSE command, unlike Mousewait, which will continue
  146. through without pausing if the left mouse button was already being
  147. pressed.    NOTE:  Avoid using this command in Amiga mode, as it
  148. seriously degrades multitasking.
  149.  
  150.  
  151.  
  152. Function: CHIPFREE
  153. ******************
  154.      Syntax: ChipFree 
  155.       Modes: Amiga or Blitz
  156. Description: 
  157. This function will return the size, in bytes, of the largest block
  158. of free CHIP memory in your system.
  159. See Also:
  160. FastFree
  161. LargestFree
  162.  
  163.  
  164.  
  165. Function: FASTFREE 
  166. ******************
  167.      Syntax: FastFree 
  168.       Modes: Amiga or Blitz
  169. Description: 
  170. This function returns the size of the largest block of FAST memory.
  171.  
  172.  
  173.  
  174. Function: LARGESTFREE 
  175. *********************
  176.      Syntax: LargestFree 
  177.       Modes: Amiga or Blitz
  178. Description: 
  179. This function will return the size of the largest chunk of memory
  180. available.  This memory may be FAST or CHIP, depending on your system.
  181.  
  182.  
  183.  
  184.  
  185.  
  186. ******************************************************************************
  187. ***************************** MATH/NUMERIC FUNCTIONS *************************
  188. ******************************************************************************
  189.  
  190.  
  191.  
  192. Function: XOR
  193. *************
  194.      Syntax: Xor (expression,expression) 
  195.       Modes: Amiga or Blitz
  196. Description: 
  197. Returns Exclusive OR of two expressions
  198. This function returns the "exclusive-OR" or the two supplied arguments.
  199. For example, Xor(255,170) will return 85, and Xor(-1) will return 0.
  200.  
  201.  
  202.  
  203. Function: LARGEST.L 
  204. *******************
  205.      Syntax: Largest.l (Long Integer1,Long Integer2)
  206.       Modes: Amiga or Blitz
  207. Description:
  208. This function will return the larger of the two supplied long integers.
  209. For example, Largest.l(255,20045) would return 20045.
  210.  
  211.  
  212. Function: SMALLEST.L 
  213. ********************
  214.      Syntax: Smallest.l (Long Integer1,Long Integer2)
  215.       Modes: Amiga or Blitz
  216. Description:
  217. This function will return the smaller of two supplied long integers.
  218. For example, Smallest.l(-999,5) would return -999.
  219.  
  220.  
  221. Function: LARGEST.Q 
  222. *******************
  223.      Syntax: Largest.q (Quick1,Quick2)
  224.       Modes: Amiga or Blitz
  225. Description:
  226. Identical to the function "Largest.l" (above) except that it accepts
  227. quick-type variables or expressions.
  228.  
  229.  
  230. Function: SMALLEST.Q 
  231. ********************
  232.      Syntax: Smallest.q (Quick1,Quick2)
  233.       Modes: Amiga or Blitz
  234. Description:
  235. Identical to "Smallest.q" but uses quick-types.
  236.  
  237.  
  238. Function: LARGEST 
  239. *****************
  240.      Syntax: Largest (Integer1,Integer2)
  241.       Modes: Amiga or Blitz
  242. Description:
  243. This is the fastest "Largest()" function.  Note that if passed floats
  244. or quick-types, the fraction will be cut off.  See description for
  245. Largest.l() and Largest.q().
  246.  
  247.  
  248. Function: SMALLEST 
  249. ******************
  250.      Syntax: Smallest (Integer1,Integer2)
  251.       Modes: Amiga or Blitz
  252. Description:
  253. Like Smallest.l() and Smallest.q(), above, with less accuracy, but
  254. faster than the long-integer and quick-type versions.
  255.  
  256.  
  257.  
  258. Function: AVG.L 
  259. ***************
  260.      Syntax: Avg.l (Long Integer 1,Long Integer 2)
  261.       Modes: Amiga or Blitz
  262. Description:
  263. This function will return the average of two long-integers (although
  264. the fraction is cut off.)  Thus, Avg.l(5,15)=10, and Avg.l(1,2)=1.
  265. (Since fractions will be cut off with this function, you may wish to
  266. use the quick-type version of this function for more accuracy.)
  267.  
  268.  
  269. Function: AVG.Q 
  270. ***************
  271.      Syntax: Avg.q (Quick1,Quick2)
  272.       Modes: Amiga or Blitz
  273. Description:
  274. See the description for "Avg.l()" (above)
  275.  
  276.  
  277. Function: AVG 
  278. *************
  279.      Syntax: Avg (Integer1,Integer2)
  280.       Modes: Amiga or Blitz
  281. Description:
  282. See the description for "Avg.l()" (above)
  283. This version is the fastest Avg() function available.
  284.  
  285.  
  286.  
  287. Statement: RRANDOMIZE 
  288. *********************
  289.      Syntax: RRandomize Seed
  290.       Modes: Amiga or Blitz
  291. Description:
  292. Given a float-type expression or variable, RRandomize will "seed" the
  293. reproducible random number generator.  The sequence of pseudo-random
  294. numbers produced by "RRND" will be the same for each seed given it.
  295. If you require trully random numbers, try "RRandomize Ticks."
  296.  
  297.  
  298. Function: RRND 
  299. **************
  300.      Syntax: RRnd (Low,High)
  301.       Modes: Amiga or Blitz
  302. Description:
  303. Given a range such as (1,6) this function will return a random number
  304. based on the seed given it by "RRandomize."  These sets of "random"
  305. numbers can be repeated if you provide the same seed.  This can be
  306. useful in games, etc. so that using "RRandomize Level#" and then using
  307. the RRnd() function to randomly draw the screen, each time the player
  308. returns to that particular level, it will be the same.
  309.  
  310.  
  311.  
  312. *****************************************************************************
  313. ********************************* ARRAY FUNCTIONS ****************************
  314. *****************************************************************************
  315.  
  316.  
  317.  
  318. Function: INDEX
  319. ***************
  320.      Syntax: Index List() 
  321.       Modes: Amiga or Blitz
  322. Description: 
  323. Returns index from top of LIST
  324. This function will return the current index number of the supplied
  325. List() array passed to it.  For example, if the list pointer is currently
  326. at item 10 in the list, Index would return 10.
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333. ******************************************************************************
  334. ***************************** INTUITION PROGRAMMING **************************
  335. ******************************************************************************
  336.  
  337.  
  338.  
  339.  
  340. Statement or Function: REQUEST 
  341. ******************************
  342.      Syntax: Request (Title$,Text$,GadgetText$)
  343.       Modes: Amiga
  344.  
  345. ***************************************************************************
  346. *  This command is 2.0-specific.  If you're still using 1.3, this command *
  347. *  will be unavailable to you.                                            *
  348. ***************************************************************************
  349.  
  350. Description:
  351. "Request" can be used as both a command or a function.  You may
  352. provide an optional title (or "" for default window title) a string
  353. of text (separated by pipes "|" for each line) and a string containing
  354. text for gadgets within the requester.  (Separate with "|" if you
  355. need more than one.)
  356. Used as a command, it merely displays the requester on the current
  357. screen and waits for the user to click a gadget.  As a function, it
  358. will also return a number corresponding to the gadget selected.
  359. The gadget on the right should be reserved for negative responses
  360. such as "CANCEL" or "NO" and will always return zero.  Other gadgets
  361. will return values in the order that they appear, beginning with
  362. 1 for the first gadget, 2 for the next, etc.
  363.  
  364.  
  365.  
  366. Function: ACTIVESCREEN 
  367. **********************
  368.      Syntax: ActiveScreen  
  369.       Modes: Amiga
  370. Description: 
  371. This function returns ADDRESS of current Intuition screen.  This is
  372. useful with many Intuition library commands, or to find out information
  373. about the currently active screen.
  374.  
  375.  
  376.  
  377. Function: SCREENWIDTH 
  378. *********************
  379.      Syntax: ScreenWidth  
  380.       Modes: Amiga
  381. Description: 
  382. This function returns the pixelwidth of the currently active screen.
  383.  
  384.  
  385. Function: SCREENHEIGHT 
  386. **********************
  387.      Syntax: ScreenHeight  
  388.       Modes: Amiga
  389. Description: 
  390. This function returns the pixelheight of the active screen
  391.  
  392.  
  393. Function: ACTIVEWINDOW 
  394. **********************
  395.      Syntax: ActiveWindow  
  396.       Modes: Amiga
  397. Description: 
  398. This function returns the address of the current window.
  399. This address is mainly used in conjunction with Intuition library
  400. commands.
  401.  
  402.  
  403.  
  404. Statement or Function: WAITFOR 
  405. ******************************
  406.      Syntax: WaitFor (IDCMP Code)  
  407.       Modes: Amiga
  408. Description: 
  409. Similar to WaitEvent, WAITFOR puts the Amiga to "sleep" until a specified
  410. IDCMP code wakes it up.  For example, WaitFor $400 would wait until the
  411. user strikes a key, and WaitFor $8 would wait until the "close" gadget
  412. of the current window was clicked on.  These IDCMP codes are additive,
  413. so WaitFor $408 would wait until either the "close" gadget was selected,
  414. or a key was pressed.  Refer to the section on "windows" in the Blitz2
  415. Reference Manual for more information on IDCMP codes.
  416.  
  417.  
  418.  
  419. Statement: SHOWREQUESTERS 
  420. *************************
  421.      Syntax: ShowRequesters OPTION
  422.       Modes: Amiga or Blitz
  423. Description:
  424.  
  425. OPTIONS:  0=Cancel all requesters
  426.           1=Show requesters on Workbench Screen
  427.           2=Direct requesters to current window
  428.  
  429. This command allows you to force system requesters like "Please insert
  430. volume Foo in any drive" etc. to either be turned off, directed to the
  431. workbench, or directed to the current window.  When requesters are turned
  432. off, the system will behave as if the "CANCEL" gadget was selected for
  433. each requester that would otherwise have been displayed.  Be sure to
  434. re-activate requesters before exiting your program!
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441. ******************************************************************************
  442. ********************************** STRING HANDLING ***************************
  443. ******************************************************************************
  444.  
  445.  
  446.  
  447.  
  448.  
  449. Function: CHECKSUM 
  450. ******************
  451.      Syntax: Checksum (String$) 
  452.       Modes: Amiga or Blitz
  453. Description: 
  454. Given a string, Checksum() will return a unique 32-bit integer as
  455. a checksum, useful in situations such as serial transfers, etc. to
  456. ensure both parties have the same data.
  457.  
  458.  
  459.  
  460.  
  461.  
  462. Function: CHARCOUNT 
  463. *******************
  464.      Syntax: CharCount (String$,byte) 
  465.       Modes: Amiga or Blitz
  466. Description: 
  467. This function will return the number of occurances of a given byte
  468. within a string.  For example, CharCount(text$,32) will count the
  469. number of spaces in text$.
  470.  
  471.  
  472.  
  473. Function: SEARCHBEGIN 
  474. *********************
  475.      Syntax: SearchBegin (String$,byte,# from Begin) 
  476.       Modes: Amiga or Blitz
  477. Description: 
  478. Similar to Instr(), SearchBegin will search the given string
  479. for the specified byte.  For example, SearchBegin(a$,32,1)
  480. will return the character position of the first space in a$,
  481. while SearchBegin(a$,32,3) will return the position of the
  482. third space.  If the byte is not found in the string, SearchBegin
  483. will return a zero.
  484.  
  485.  
  486.  
  487. Function: SEARCHEND
  488. *******************
  489.      Syntax: SearchEnd (String$,byte,# from End) 
  490.       Modes: Amiga or Blitz
  491. Description:
  492. Like SearchBegin() (above) except it searches from the end of
  493. the string to the front.  For example, SearchBegin(a$,asc("A"),2)
  494. will return the character position of the second-from-last letter
  495. "A" in the string 'a$.'
  496.  
  497.  
  498. Function: CIPHER$ 
  499. *****************
  500.      Syntax: Cipher$ (String$) 
  501.       Modes: Amiga or Blitz
  502. Description: 
  503. The Cipher$() function will encrypt or decrypt a string passed to it.
  504. This is especially handy if you don't want users "zapping" your executeable
  505. or data files to read it's contents.  Note that Cipher$() can only
  506. decrypt strings previously created with Cipher$().
  507.  
  508.  
  509.  
  510. Function: NULL
  511. ******************
  512.      Syntax: Null (String$)
  513.       Modes: Amiga or Blitz
  514. Description: 
  515. Many Amiga shared libraries (like the DOS library) require addresses
  516. of null-terminated strings as arguments.  This function will return
  517. a long-integer address of a null-terminated string in memory for such
  518. commands.
  519.  
  520.  
  521.  
  522. Function: REPEATS 
  523. *****************
  524.      Syntax: Repeats (String$) 
  525.       Modes: Amiga or Blitz
  526. Description: 
  527. This function will return the number of repeated bytes at the
  528. beginning of your string.  Thus, Repeats("...Test") would return 3,
  529. while Repeats("Example") would return 1.  If the string is null,
  530. Repeats() will return zero.
  531.  
  532.  
  533. Function: SPACE$
  534. ****************
  535.      Syntax: SPACE$ (number of spaces)
  536.       Modes: Amiga or Blitz
  537. Description:
  538. This function is identical to the Space$ function in many other dialects
  539. of BASIC.  It will return a string containing the desired number of
  540. spaces, making it easier to align tables etc. to the screen or printer.
  541.  
  542.  
  543.  
  544. ******************************************************************************
  545. ***************************** LIBRARY PROGRAMMING ****************************
  546. ******************************************************************************
  547.  
  548.  
  549. These functions will return the base address of their respective libraries,
  550. for advanced system programming.  Note that register A6 will also be
  551. loaded with this address, to make programming a bit easier for assembly
  552. routines.
  553.  
  554.  
  555.  
  556. Function: INTUITIONBASE 
  557. ***********************
  558.      Syntax: IntuitionBase  
  559.       Modes: Amiga or Blitz
  560. Description: 
  561. Returns Intuition Library base
  562.  
  563.  
  564. Function: DOSBASE 
  565. *****************
  566.      Syntax: DosBase  
  567.       Modes: Amiga or Blitz
  568. Description: 
  569. Returns DOS Library base
  570.  
  571.  
  572. Function: GRAPHICSBASE 
  573. **********************
  574.      Syntax: GraphicsBase  
  575.       Modes: Amiga or Blitz
  576. Description: 
  577. Returns Graphics Library base
  578.  
  579.  
  580. Function: FFPBASE 
  581. *****************
  582.      Syntax: FFPBase  
  583.       Modes: Amiga or Blitz
  584. Description: 
  585. Returns FFP Math Library base
  586.  
  587.  
  588. Function: DISKFONTBASE 
  589. **********************
  590.      Syntax: DiskFontBase  
  591.       Modes: Amiga or Blitz
  592. Description: 
  593. Returns DiskFont Library base
  594.  
  595.  
  596. Function: COMMODITIESBASE 
  597. *************************
  598.      Syntax: CommoditiesBase  
  599.       Modes: Amiga or Blitz
  600. Description: 
  601. Returns Commodities Library base
  602.  
  603.  
  604. Function: ICONBASE 
  605. ******************
  606.      Syntax: IconBase  
  607.       Modes: Amiga or Blitz
  608. Description: 
  609. Returns Icon Library base
  610.  
  611.  
  612. Function: REXXSYSBASE 
  613. *********************
  614.      Syntax: RexxSysBase  
  615.       Modes: Amiga or Blitz
  616. Description: 
  617. Returns RexxSys Library base
  618.  
  619.