home *** CD-ROM | disk | FTP | other *** search
/ EuroCD 3 / EuroCD 3.iso / Programming / BlitzBasic / eml17b / eml.doc < prev    next >
Encoding:
Text File  |  1998-06-24  |  16.5 KB  |  753 lines
  1.  
  2.                          Enhanced Music Library v1.7
  3.  
  4.                               For Blitz Basic 2
  5.  
  6.                              (C) Paul Reece 1996
  7.  
  8.  
  9.                          Official Library Number: 60
  10.  
  11.  
  12.                                  DISCLAIMER:
  13.                                  -----------
  14.  
  15. This is BETA RELEASE software.
  16.  
  17. The author takes no responsibility for any damages, loss of data etc. caused
  18. whilst using this program.  The user accepts all responsibility upon loading
  19. this software ie. USE AT YOUR OWN RISK!
  20.  
  21. The author, however will attempt to eradicate all known bugs when they are
  22. reported.
  23.  
  24.  
  25.                               USERS PLEASE NOTE:
  26.                               ------------------
  27.  
  28. The libraries are currently numbers 60, 11 and 12.
  29.  
  30. This release only contains the first library of the set of 3 - The other libs
  31. will be released in the near future...
  32.  
  33.  
  34. -- Tracker Commands -- (These commands are contained in EMLLIB.OBJ)
  35.  
  36. Command: LoadPTModule
  37. ---------------------
  38. Syntax: LoadPTModule PTModule#,Filename$
  39.         suc.b=LoadPTModule(PTModule#,Filename$)
  40.  
  41. Modes: Amiga
  42.  
  43. Description:
  44.  
  45. This command loads the specified file into the specified ptmodule object.
  46. If used as a function, it returns TRUE (-1) if there were no errors.
  47.  
  48. Command: SavePTModule
  49. ---------------------
  50. Syntax: SavePTModule PTModule#,Filename$
  51.         suc.b=LoadPTModule(PTModule#,Filename$)
  52.  
  53. Modes: Amiga
  54.  
  55. Description:
  56.  
  57. This command saves the specified ptmodule object into the file specified.
  58. If use as a function, it returns TRUE (-1) if there were no errors.
  59.  
  60.  
  61. Statement: PlayPTModule
  62. -----------------------
  63. Syntax: PlayPTModule PTModule#[,Position]
  64.  
  65. Modes: Amiga/Blitz
  66.  
  67. Description:
  68.  
  69. Play a module loaded in as the specified Blitz ptmodule object.  The optional
  70. position parameter allows you to specify a starting position to play from.
  71.  
  72. Modules will play correctly in BLITZ mode in version 1.90 and higher of Blitz
  73. Basic 2.  For playing on other versions of Blitz2 in BLITZ mode, see the
  74. details for SetPTNoInt below.
  75.  
  76.  
  77. Statement: StopPTModule
  78. -----------------------
  79. Syntax: StopPTModule
  80.  
  81. Modes: Amiga/Blitz
  82.  
  83. Description:
  84.  
  85. Stops any ptmodule that may be playing.
  86.  
  87.  
  88. Statement: PausePTModule
  89. ------------------------
  90. Syntax: PausePTModule
  91.  
  92. Modes: Amiga/Blitz
  93.  
  94. Description:
  95.  
  96. Pauses any playing ptmodule.
  97.  
  98.  
  99. Statement: ContPTModule
  100. -----------------------
  101. Syntax: ContPTModule
  102.  
  103. Modes: Amiga/Blitz
  104.  
  105. Description:
  106.  
  107. Continues any paused ptmodule from the point it was paused at.
  108.  
  109.  
  110. Statement: SetPTSongLoop
  111. ------------------------
  112. Syntax: SetPTSongLoop On|Off
  113.  
  114. Modes: Amiga/Blitz
  115.  
  116. Description:
  117.  
  118. This command determines whether a tracker module repeats from the start when
  119. a module ends.  As a default, any module will stop when the end is reached.
  120.  
  121.  
  122. Statement: SetPTPatLoop
  123. -----------------------
  124. Syntax: SetPTPatLoop On|Off|Once
  125.  
  126. Modes: Amiga/Blitz
  127.  
  128. Description:
  129.  
  130. This command turns on the pattern looping features of the playroutine.  The
  131. On option will cause the current (or next if music has not started) pattern
  132. to repeat until the music is stopped.
  133.  
  134. The Off option is the default, which causes music to play as normal.
  135.  
  136. The Once option causes the current (or next if music has not started) pattern
  137. to play once and then the music will stop automatically.
  138.  
  139.  
  140. Statement: SetPTZeroSpeed (previously SetPTZeroTempo)
  141. -------------------------
  142. Syntax: SetPTZeroSpeed On|Off
  143.  
  144. Modes: Amiga/Blitz
  145.  
  146. Description:
  147.  
  148. This command tells the playroutine to either stop when a tempo set 0 command
  149. is encountered, or to keep playing.  The On option allows you to set tempo 0
  150. without the music stopping.  The default is to stop the ptmodule.
  151.  
  152.  
  153. Statement: SetPTVolume
  154. ----------------------
  155. Syntax: SetPTVolume Volume
  156.  
  157. Modes: Amiga/Blitz
  158.  
  159. Description:
  160.  
  161. Sets the master volume of any playing or to-be-played ptmodule.  The volume
  162. value must be between 0 and 64.  The setting is copied to ALL voices.
  163.  
  164.  
  165. Statement: SetPTVoiceVolume
  166. ---------------------------
  167. Syntax: SetPTVoiceVolume Voice,Volume
  168.  
  169. Modes: Amiga/Blitz
  170.  
  171. Description:
  172.  
  173. Sets the master volume of the specified voice.
  174.  
  175.  
  176. Function: GetPTVoiceVolume
  177. --------------------------
  178. Syntax: vol.b=GetPTVoiceVolume(Voice)
  179.  
  180. Modes: Amiga/Blitz
  181.  
  182. Description:
  183.  
  184. Returns the master volume of the voice specified.
  185.  
  186.  
  187. Statement: SetPTSpeed
  188. ---------------------
  189. Syntax: SetPTSpeed Speed
  190.  
  191. Modes: Amiga/Blitz
  192.  
  193. Description:
  194.  
  195. This command sets the speed of the currently playing ptmodule.  The value
  196. must be between 0 and 32 - The default is 6.
  197.  
  198.  
  199. Function: GetPTSpeed
  200. --------------------
  201. Syntax: speed.b=GetPTSpeed
  202.  
  203. Modes: Amiga/Blitz
  204.  
  205. Description:
  206.  
  207. This function returns the current speed setting.
  208.  
  209.  
  210. Statement: SetPTTempo
  211. ---------------------
  212. Syntax: SetPTTempo CiaTempo
  213.  
  214. Modes: Amiga
  215.  
  216. Description:
  217.  
  218. This command sets the CIA tempo of the currently playing module.  This will
  219. only work when the CIA playroutines are being used.  Valid values are from
  220. 33 to 255.  The default value is 125.
  221.  
  222.  
  223. Function: GetPTTempo
  224. --------------------
  225. Syntax: tempo.w=GetPTTempo
  226.  
  227. Modes: Amiga
  228.  
  229. Description:
  230.  
  231. This function returns the current tempo setting.
  232.  
  233.  
  234. Statement: SetPTMask
  235. --------------------
  236. Syntax: SetPTMask Voices
  237.  
  238. This command toggles on/off the music playing on the specified voices.  This
  239. allows you to mask out channels for the playing of samples only etc.
  240.  
  241. The bitmap specifies which voices are on and off - Just set/not-set the bit(s)
  242. relating to the channels.
  243.  
  244. eg. %0001 - Channel 0 ON ONLY!
  245.     %1011 - Channel 2 OFF ONLY!
  246.     %1000 - Channel 3 ON ONLY!
  247.  
  248.  
  249. Function: GetPTMask
  250. -------------------
  251. Syntax: mask.b=GetPTMask
  252.  
  253. Modes: Amiga/Blitz
  254.  
  255. Description:
  256.  
  257. This function returns the current protracker mask.
  258.  
  259.  
  260. Statement: SetPTVoiceOff
  261. ------------------------
  262. Syntax: SetPTVoiceOff Voice
  263.  
  264. Modes: Amiga/Blitz
  265.  
  266. Description:
  267.  
  268. Turns the specified voice off - No protracker music will be played on the
  269. specified voice.
  270.  
  271.  
  272. Statement: SetPTVoiceOn
  273. -----------------------
  274. Syntax: SetPTVoiceOn Voice
  275.  
  276. Modes: Amiga/Blitz
  277.  
  278. Description:
  279.  
  280. Turns the specified voice on - Allows protracker music to be played on the
  281. specified voice.
  282.  
  283.  
  284. Statement: SetPTVoiceToggle
  285. ---------------------------
  286. Syntax: SetPTVoiceToggle Voice
  287.  
  288. Modes: Amiga/Blitz
  289.  
  290. Description:
  291.  
  292. Toggles the specified voice from off to on or on to off...
  293.  
  294.  
  295. Function: GetPTVoiceStat
  296. ------------------------
  297. Syntax: stat.b=GetPTVoiceStat(Voice)
  298.  
  299. Modes: Amiga/Blitz
  300.  
  301. Description:
  302.  
  303. This function returns true (-1) if the voice specified is turned on, or false
  304. (0) if it is turned off.
  305.  
  306.  
  307. Function: GetPTVoicePeriod
  308. --------------------------
  309. Syntax: period.w=GetPTVoicePeriod(Voice)
  310.  
  311. Modes: Amiga/Blitz
  312.  
  313. Description:
  314.  
  315. This function returns the sample-period value of the last, or current note
  316. played on the specified channel.
  317.  
  318.  
  319. Function: GetPTVoiceNote
  320. ------------------------
  321. Syntax: note.b=GetPTVoiceNote(Voice)
  322.  
  323. Modes: Amiga/Blitz
  324.  
  325. Description:
  326.  
  327. This function returns the note number of the last, or current note played on
  328. the specified channel.
  329.  
  330.  
  331. Function: GetPTVoiceInstrument
  332. ------------------------------
  333. Syntax: instrument.b=GetPTVoiceInstrument(Voice)
  334.  
  335. Modes: Amiga/Blitz
  336.  
  337. Description:
  338.  
  339. This function returns the instrument number of the last, or current note
  340. played on the specified channel.
  341.  
  342.  
  343. Function: GetPTVuLevel
  344. ----------------------
  345. Syntax: vu.b=GetPTVuLevel(Voice)
  346.  
  347. Modes: Amiga/Blitz
  348.  
  349. Description:
  350.  
  351. This functions returns the 'original' volume level of the last note
  352. played on the specified channel.
  353.  
  354.  
  355. Function: GetPTRealVuLevel
  356. --------------------------
  357. Syntax: vu.b=GetPTRealVuLevel(Voice)
  358.  
  359. Modes: Amiga/Blitz
  360.  
  361. Description:
  362.  
  363. This functions returns the volume level of the last/current note on the
  364. specified channel.
  365.  
  366.  
  367. Function: GetPTSongPos
  368. ----------------------
  369. Syntax: pos.b=GetPTSongPos
  370.  
  371. Modes: Amiga/Blitz
  372.  
  373. Description:
  374.  
  375. This function returns the current position of the ptmodule currently playing.
  376.  
  377.  
  378. Function: GetPTPatternPos
  379. -------------------------
  380. Syntax: pos.b=GetPTPatternPos
  381.  
  382. Modes: Amiga/Blitz
  383.  
  384. Description:
  385.  
  386. This function returns the current position of the currently playing pattern.
  387. (ie. the line number on tracker programs)
  388.  
  389.  
  390. Function: GetPTStat
  391. -------------------
  392. Syntax: stat.b=GetPTStat
  393.  
  394. Modes: Amiga/Blitz
  395.  
  396. Description:
  397.  
  398. This function returns the object number of any ptmodule currently playing OR
  399. -1 if no ptmodule is playing.
  400.  
  401.  
  402. -- PTModule Information --
  403.  
  404.  
  405. Function: GetPTModuleLen
  406. ------------------------
  407. Syntax: len.l=GetPTModuleLen(PTModule#)
  408.  
  409. Modes: Amiga/Blitz
  410.  
  411. Description:
  412.  
  413. This function returns the length (in positions) of the ptmodule specified.
  414.  
  415.  
  416. Function: GetPTPosPattern
  417. -------------------------
  418. Syntax: pat.b=GetPTPosPattern(PTModule#,Position)
  419.  
  420. Modes: Amiga/Blitz
  421.  
  422. Description:
  423.  
  424. This function returns the pattern number that is played at the specified
  425. position in the specified ptmodule.
  426.  
  427.  
  428. Function: GetPTModuleName$
  429. --------------------------
  430. Syntax: name$=GetPTModuleName$(PTModule#)
  431.  
  432. Modes: Amiga/Blitz
  433.  
  434. Description:
  435.  
  436. This function returns the name of the specified ptmodule.
  437.  
  438.  
  439. Function: GetPTInstrumentName$
  440. ------------------------------
  441. Syntax: name$=GetPTInstrumentName$(PTModule#,InstrumentNumber)
  442.  
  443. Modes: Amiga/Blitz
  444.  
  445. Description:
  446.  
  447. This function returns the name of the specified instrument.
  448.  
  449.  
  450. Function: GetPTInstrumentAddr
  451. -----------------------------
  452. Syntax: addr.l=GetPTInstrumentAddr(PTModule#,InstrumentNumber)
  453.  
  454. Modes: Amiga/Blitz
  455.  
  456. Description:
  457.  
  458. This function returns the start address of the specified instrument.
  459.  
  460.  
  461. Function: GetPTInstrumentLen
  462. ----------------------------
  463. Syntax: len.l=GetPTInstrumentLen(PTModule#,InstrumentNumber)
  464.  
  465. Modes: Amiga/Blitz
  466.  
  467. Description:
  468.  
  469. This function returns the length of the specified instrument.
  470.  
  471.  
  472. Function: GetPTInstrumentRepeatStart
  473. ------------------------------------
  474. Syntax: rep.l=GetPTInstrumentRepeatStart(PTModule#,InstrumentNumber)
  475.  
  476. Modes: Amiga/Blitz
  477.  
  478. Description:
  479.  
  480. This function returns the offset from the start of the sample, where the
  481. looping of the sample starts.
  482.  
  483.  
  484. Function: GetInstrumentRepLen
  485. -----------------------------
  486. Syntax: replen.l=GetPTInstrumentRepLen(PTModule#,InstrumentNumber)
  487.  
  488. Modes: Amiga/Blitz
  489.  
  490. Description:
  491.  
  492. This function returns the offset from the start of the sample, where the
  493. looping of the sample ends.
  494.  
  495.  
  496. Function: GetPTInstrumentVol
  497. ----------------------------
  498. Syntax: vol.b=GetPTInstrumentVol(PTModule#,InstrumentNumber)
  499.  
  500. Modes: Amiga/Blitz
  501.  
  502. Description:
  503.  
  504. This function returns the volume setting for the specified instrument.
  505.  
  506.  
  507. -- Advanced Tracker Commands --
  508.  
  509.  
  510. Statement: SetPTCia
  511. -------------------
  512. Syntax: SetPTCia
  513.  
  514. Modes: Amiga/Blitz
  515.  
  516. Description:
  517.  
  518. This command tells the playroutine to use CIA interrupts (and thus CIA tempos)
  519. when playing ptmodules.  It will not switch interrupts whilst playing - if you
  520. do so, any currently playing ptmodules will stop.
  521.  
  522.  
  523. Statement: SetPTVbl
  524. -------------------
  525. Syntax: SetPTVbl
  526.  
  527. Modes: Amiga/Blitz
  528.  
  529. Description:
  530.  
  531. This command tells the playroutine to use VBL interrupts (and thus VBL tempos)
  532. when playing ptmodules.
  533.  
  534.  
  535. Statement: SetPTNoInt
  536. ---------------------
  537. Syntax: SetPTNoInt
  538.  
  539. Modes: Amiga/Blitz
  540.  
  541. Description:
  542.  
  543. This command tells the library not to start an interrupt when playing a song.
  544. It is left to the use to use the PTInt statement each VBL to play the music.
  545.  
  546. Note!  This method only allows VBL tempos, but it DOES allow you to play music
  547.        in Blitz mode on older versions of Blitz!
  548.  
  549.  
  550. Statement: SetPTCiaInt
  551. ----------------------
  552. Syntax: SetPTCiaInt Type
  553.  
  554. Modes: Amiga/Blitz
  555.  
  556. Description:
  557.  
  558. This command tells the playroutine to utilize the specified interrupt type
  559. (like what is specified in the SetInt command) to use when using CIA's.
  560.  
  561. Statement: SetPTCiaPri
  562. ----------------------
  563. Syntax: SetCiaPri Priority
  564.  
  565. Modes: Amiga/Blitz
  566.  
  567. Description:
  568.  
  569. This command sets the internal priority of the CIA interrupt.
  570.  
  571. BE CAREFULL!!  You can un-intentionally cripple your disk interrupts by using
  572. a value too high!!
  573.  
  574.  
  575. Statement: PTInt
  576. ----------------
  577. Syntax: PTInt
  578.  
  579. Modes: Amiga/Blitz
  580.  
  581. Description:
  582.  
  583. Called once every VBL (when in NoInt mode), this statement will play the
  584. previously started ptmodule.
  585.  
  586.  
  587. -- Sample Commands --  (These routines are contained in EMLLIB2.OBJ)
  588.  
  589. (NOT included in this release!)
  590.  
  591. Statement: Sample
  592. -----------------
  593. Syntax: Sample StartAddress,Length,Frequency
  594.  
  595. Modes: Amiga/Blitz
  596.  
  597. Description:
  598.  
  599. This command takes a sample using any connected sampler cartridge..
  600. The sampling speed is measured in hertz and must be higher than 500!!
  601.  
  602. Sampling will stop when the length is reached or any mouse button is pressed.
  603.  
  604. Whilst sampling, ALL interrupts and the Screen DMA are de-activated.
  605.  
  606. NB: Samplers connected to the BUS port will NOT work. (ala DATEL)
  607.  
  608.  
  609. Statement: SampleSound
  610. ----------------------
  611. Syntax: SampleSound Sound#,Frequency
  612.  
  613. Modes: Amiga/Blitz
  614.  
  615. Description:
  616.  
  617. This command takes a sample but samples into the specified sound object.
  618.  
  619. Sampling will stop when the length of the sound is reached or any mouse
  620. button is pressed.
  621.  
  622. NOTE!: Frequency must be higher than 500!
  623.  
  624.  
  625. Statement: Monitor
  626. ------------------
  627. Syntax: Monitor Frequency
  628.  
  629. Modes: Amiga/Blitz
  630.  
  631. Description:
  632.  
  633. This command monitors the input of the sampler and outputs it through the
  634. Amiga's sound channels.  Any mouse button stops monitoring.
  635.  
  636. Whilst monitoring, ALL interrupts are disabled.
  637.  
  638. NOTE!: Frequency must be higher than 500!
  639.  
  640.  
  641. Function: Period
  642. ----------------
  643. Syntax: Period(Hertz)
  644.  
  645. Modes: Amiga/Blitz
  646.  
  647. Description:
  648.  
  649. This function converts a value in hertz to an Amiga sample period.
  650.  
  651.  
  652. Function: Hertz
  653. ---------------
  654. Syntax: Hertz(Period)
  655.  
  656. Modes: Amiga/Blitz
  657.  
  658. Description:
  659.  
  660. This function converts an Amiga sample period to a value in hertz.
  661.  
  662.  
  663.  
  664.  
  665. Copyright, Contact Information, Disclaimer etc..:
  666. -------------------------------------------------
  667.  
  668. This program is NOT Public Domain, FreeWare,  etc..  The author retains FULL
  669. copyright of the program, examples and documentation.
  670.  
  671. This program is NOT to be sold by ANY PD library without written agreement
  672. with myself..  It may NOT be uploaded to ANY ftp site or BBS either.
  673. Updates will be released by the author on aminet as required.
  674.  
  675. Placement of this program on ANY CD-Rom will ALSO be seen as a breach of
  676. these conditions.
  677.  
  678. Also, ANY use of this program in a shareware/commercial software release
  679. must be agreed-to by myself IN WRITING before any such release. (usually
  680. all I'll want is a free copy of the game/program ;)  )
  681.  
  682. For more information in this regard, or for making suggestions/reporting bugs,
  683. please contact me!
  684.  
  685. (Please mail bugs in the manual to me too!!  It was done in a hurry!)
  686.  
  687. Postal:   Paul Reece
  688.  
  689.           12 Howe Elbow,
  690.           Quinns Rocks,
  691.           Western Australia. 6030. (only til mid 1996 at this stage)
  692.  
  693. Internet: paul@tassie.net.au, st962f8e@echidna.cowan.edu.au
  694.  
  695.  
  696. Also Available:  THE ENHANCED MUSIC EXTENSION for AMOS 1.3 / AMOS PRO.
  697.  
  698.  
  699. BTW: If anyone is interested in saving me the time of converting this into
  700. a nice looking .guide, let me know :-)
  701.  
  702.  
  703. PROGRAM HISTORY:
  704. ----------------
  705.  
  706. v1.7 (19-APR-1996)  - Totally replaced and rewrote playroutine - now uses
  707.                       busywait fixed routine by Peter Kunath (hi Deli!).
  708.                       Code generally cleaned up at the same time.. Bugs
  709.                       most likely introduced here :)
  710.  
  711. v1.6 (??-MAR-1996)  - Many attempts to fix a damned playroutine bug. Still
  712.                       dropping notes :(
  713.  
  714. v1.55 (11-NOV-1995) - Gee!  I only just decided to look at this today..
  715.                       Fixed problem with CIA allocation - munged the
  716.                       serial port.
  717.  
  718. v1.54 (24-SEP-1994) - Code cleaned up even more - Portamento problem fixed
  719.                       (bug in Protracker Playroutines - not in PT itself
  720.                       though....)
  721.  
  722. v1.53 (16-SEP-1994) - Return values for LOAD and SAVE added - First public
  723.                       release.
  724.  
  725. v1.52 (15-SEP-1994) - GetPTVoiceNote added. GetPTRealLevel added.
  726.                       Code cleaned up.
  727.  
  728. v1.51 (8-SEP-1994) - SavePTModule fixed.  Some code cleaned up.
  729.  
  730. v1.5 (27-JUL-1994) - Tempo/Speed commands/functions fixed and extended.
  731.                      Master volume setting for voices now included.
  732.  
  733. v1.4 (20-JUL-1994) - First release version.. Only 1 lib included (no. 60)
  734.                      New libnumber!! (60)  Commandnames changed.  Not int
  735.                      option added. Uses it's own Blitz objects!
  736.  
  737. v1.3 (16-JUN-1994) - ALOT of bugs fixed here..  Too many to list!
  738.  
  739. v1.2b(6-JUN-1994) - Now a third library..  Doesn't do much yet, but will soon
  740.                     have full TFMX playroutines...  Work is still in progress.
  741.  
  742. v1.2 (5-JUN-1994) - New sampling commands added!  Program now consists of 2
  743.                     libraries.
  744.  
  745. v1.1 (1-JUN-1994) - CIA or VBL added.  Instrument information functions added
  746.                     and interrupts finally fixed!
  747.  
  748. v1.0 (30-MAY-1994) - First version - Only released to 1 person.  Full of BUGS!
  749.                      Written from scratch in only 3 days!
  750.  
  751. v0.0 (27-MAY-1994) - Blitz2 arrived in the mail TODAY.
  752.  
  753.