home *** CD-ROM | disk | FTP | other *** search
/ Audio 4.94 - Over 11,000 Files / audio-11000.iso / amiga / players / modplyrs / dstrckr2.lha / DTL / docs / RexxFuncs.DOC < prev    next >
Text File  |  1993-12-17  |  39KB  |  1,066 lines
  1.             destracker.library Release 2.00 (v3.0) Documentation
  2.  
  3.                              as of Dec 18,  1993
  4.  
  5.                           Written by Darren Schebek
  6.  
  7.          destracker.library, LScope, DTC, mJuke, and MODInfo are all
  8.                     Designed and written by Darren Schebek
  9.                     Copyright ⌐1992,1993 by Darren Schebek
  10.                              All rights reserved
  11.  
  12.  
  13.  
  14.                            Library ARexx Functions
  15.  
  16.  
  17.     Here is an explanation of the ARexx functions currently supported by the
  18. destracker.library.  I'll admit that some of the names are a bit long, but
  19. readability is next to godliness, I always say.  :)
  20.  
  21.     There are certain problems inherent with the Rexx interface that I will
  22. try to solve in the future.  The one that bugs me the most is that the
  23. Own/Disown player routines use the address of the calling task's TCB in order
  24. to determine who has a lock on the library and who doesn't.  Problem is, ARexx
  25. scripts all have the same TCB, that being the ARexx resident process.  Oh
  26. well, I'll have to come up with a more sophisticated way of handling library
  27. ownership for a future release.  This little problem does not cause contention
  28. between ARexx tasks competing for use of the library, since they are both part
  29. of the same task and so one cannot interrupt the other.  This *does* mean that
  30. two ARexx programs can still mess up the library parameters for each other if
  31. such a situation occurs.  I'll try to come up with a solution to this in a
  32. future release.
  33.  
  34.     It must be remembered that, since the library can in fact be owned by
  35. another application, any function that does not have the word "Get" in it can
  36. return an error string such as "*** Library has been owned by another prog.".
  37. It should therefore be mentioned that error strings will always start with
  38. "***", and warning strings always start with "+++" (like "+++ Input value was
  39. trimmed.").
  40.  
  41.     So, even though many functions listed below indicate that they return
  42. nothing, they can still return an error string, which you really should be
  43. checking for by saying "retval = DES_{function name}()" instead of just
  44. DES_{function name}()".  Having said that, here is a brief list of the
  45. supported ARexx functions in alphabetical order.  New functions for release
  46. 2.00 (library version 3.0) are indicated by an asterisk next to their
  47. description...
  48.  
  49. DES_ApplyGTempo()                       Apply global tempo to song tempo opcodes.
  50. DES_BeginPlay()                         Begin playing song at start position.
  51. DES_ChannelEnable( [channelbits] )     *Enable/disable specific audio channels.
  52. DES_ContPlay()                          Continue a previously paused song.
  53. DES_CurPos( [curpos] )                  Get/Set current position during playback.
  54. DES_DefaultPath( [path] )               Function removed. See DES_ModulePath().
  55. DES_DefTempo( [newtempo] )              Get/Set default tempo of a song.
  56. DES_DisownPlayer()                      Unlock library so others can use it.
  57. DES_EndPos( [endpos] )                  Get/Set end position for playback.
  58. DES_FadeGlobalVol( destvolume )         Fade global volume to any volume.
  59. DES_Filter( [0/1] )                     Get/Set status of the lo-pass filter.
  60. DES_FineTempo( newfinetempo )           Get/Set global fine tempo.
  61. DES_GetCurChVol( channelnum )           Get current volume of an audio channel.
  62. DES_GetCurInstNum( channelnum )         Get current inst # of an audio channel.
  63. DES_GetCurNoteNum( channelnum )         Get current note # of an audio channel.
  64. DES_GetCurPer( channelnum )             Get current period of an audio channel.
  65. DES_GetCurTempo()                       Get current tempo of a playing song.
  66. DES_GetElapsedTime()                    Get elapsed playback time (HH:MM:SS:JJ)
  67. DES_GetInstAddr( instnum )              Get addr in memory of an instrument.
  68. DES_GetInstLength( instnum )            Get length of an instrument's sample.
  69. DES_GetInstName( instnumber )           Get text name of an instrument.
  70. DES_GetInstRepLen( instnum )            Get repeat length of an instrument.
  71. DES_GetInstRepOff( instnum )            Get repeat offset of an instrument.
  72. DES_GetItersLeft()                      Get # of iterations left to play.
  73. DES_GetLockStat()                       Determine if someone owns the library.
  74. DES_GetModFormat( [ [path]filename ] )  Get file format of a loaded module.
  75. DES_GetModLength()                      Get total length of a loaded module.
  76. DES_GetNewNoteHits()                    Get new note hit information.
  77. DES_GetNumPatts()                       Get # of patterns in a loaded module.
  78. DES_GetNumPos()                         Get # of positions in a loaded module.
  79. DES_GetPlayStat()                       Get current play status of the library.
  80. DES_GetSongAddr()                       This function no longer exists for r2.00.
  81. DES_GlobalTempo( [newtempo] )           Get/Set global tempo.
  82. DES_GlobalVol( [newvolume] )            Get/Set global volume.
  83. DES_InstallMod( module )                "Load" a module already residing in memory.
  84. DES_InstVol( instnum [,volume] )        Get/Set default volume of an instrument.
  85. DES_Iterations( [numiter] )             Get/Set # of iterations to play song.
  86. DES_LoadModule( [path]filename )        Load a song module from disk.
  87. DES_LoopIntent( [loopflag] )            Get/Set/Clear loop intent playback flag.
  88. DES_ModulePath( [pathname|"-"] )        Add/remove search path for DES_LoadModule().
  89. DES_OwnPlayer()                         Lock library for private use only.
  90. DES_PausePlay()                         Pause a currently playing song.
  91. DES_ResetDefaults()                     Reset library parms to their defaults.
  92. DES_SaveFormat( [format] )              Get/Set format that SaveModule uses.
  93. DES_SaveModule( [path]filename )        Save a song module back to disk.
  94. DES_SetTemporalEnd( time )             *Set end of play seq. based on time.
  95. DES_SetTemporalPos( time )             *Set current song position based on time.
  96. DES_SetTemporalStart( time )           *Set start of play seq. based on time.
  97. DES_SongTitle( [newtitle] )             Get/Set the title of a loaded module.
  98. DES_StartPos( [startpos] )              Get/Set start position for playback.
  99. DES_StopPlay()                          Stops play sequence, resets song position.
  100. DES_TempoInterp( [interpretflag] )      Get/Set tempo interpretation (BPM/non-BPM).
  101. DES_TimingMode( [modenum] )             Get/Set timing mode (50Hz/60Hz).
  102. DES_UnloadModule()                      Unload a song module from memory.
  103. DES_VolFadeRate( [newrate] )            Get/Set rate at which volume fades occur.
  104.  
  105.  
  106.     Here now is an explanation of each function in greater detail.  They are
  107. listed in the same order as above:
  108.  
  109. --------------------------------
  110.  
  111. DES_ApplyGTempo()
  112.  
  113.   Example:
  114.  
  115.     call DES_ApplyGTempo()                  Apply global tempo to module.
  116.  
  117.   Function:
  118.  
  119.     Takes the global tempo setting (a signed value), and adds it to all tempo
  120.     commands in the currently loaded module.  The global tempo is then set to
  121.     0.  This is useful for songs that always play too fast or slow.  Rather
  122.     than setting the global tempo for them each time you load it, you can
  123.     just set the global tempo, call DES_ApplyGTempo(), and then save the module
  124.     back to disk.  Then it will always play at the faster/slower speed.
  125.  
  126. --------------------------------
  127.  
  128. DES_BeginPlay()
  129.  
  130.   Example:
  131.  
  132.     call DES_BeginPlay()                    Start play sequence a'playing.
  133.  
  134.   Function:
  135.  
  136.     Starts playing the currently defined play sequence.  A play sequence
  137.     consists of a start position, end position, and number of iterations (see
  138.     DES_StartPos, DES_EndPos, and DES_Iterations).
  139.  
  140. --------------------------------
  141.  
  142. DES_ChannelEnable( [newenable] )
  143.  
  144.   Examples:
  145.  
  146.     call DES_ChannelEnable( 128+(1+2+8) )   Disable channels 0,1,3.
  147.     oldenable = DES_ChannelEnable( 2+4 )    Enable ch. 1,2. Save old enable bits.
  148.                                             enable status.
  149.     curenable = DES_ChannelEnable()         Get current channel enable status.
  150.  
  151.   Function:
  152.  
  153.     Enable/disable channels. Each channel has a corresponding value associated
  154.     with it, as follows:
  155.  
  156.         1    Channel #0
  157.         2    Channel #1
  158.         4    Channel #2
  159.         8    Channel #3
  160.  
  161.     Specify the channels you'd like to affect by adding together their corres-
  162.     ponding input values.  Then, if you want to enable the specified channels
  163.     then simply pass the resulting value to the function.  If you want to
  164.     disable the specified channels, then add 128 to the result and then pass it
  165.     to the function.  See the SetChannelEnable() function description in the
  166.     LibFuncs.DOC file for more information.
  167.  
  168. --------------------------------
  169.  
  170. DES_ContPlay()
  171.  
  172.   Example:
  173.  
  174.     call DES_ContinuePlay()                 Reactivate paused play sequence.
  175.  
  176.   Function:
  177.  
  178.     Reactivates the play sequence from where it was paused.  Note that you
  179.     can also use DES_SetCurPos() while a play sequence is paused.
  180.     DES_ContPlay() will continue from the current position in this case.
  181.  
  182. --------------------------------
  183.  
  184. DES_CurPos( [curpos] )
  185.  
  186.   Examples:
  187.  
  188.     call DES_CurPos( 0 )                    Immediately play at first position.
  189.     oldpos = DES_CurPos( 5 )                Go to position 5, remember old position.
  190.     curpos = DES_CurPos()                   Get current position in song.
  191.  
  192.   Function:
  193.  
  194.     Set the current position of a play sequence.
  195.  
  196. --------------------------------
  197.  
  198. DES_DefaultPath( [path] )   (now defunct)
  199.  
  200.  
  201.     This function has been removed from DES-Tracker as of release 1.5.  It has
  202. been replaced by the DES_ModulePath() function, described later on in this
  203. document.
  204.  
  205. --------------------------------
  206.  
  207. DES_DefTempo( [newtempo] )
  208.  
  209.   Examples:
  210.  
  211.     call DES_DefTempo( 7 )                  Set default tempo to 7.
  212.     oldtempo = DES_DefTempo( 6 )            Set default tempo to 6, save old
  213.                                             default tempo.
  214.     curtempo = DES_DefTempo()               Get current default tempo.
  215.  
  216.   Function:
  217.  
  218.     Allows you to set/get the default tempo.  This is the tempo that is
  219.     used for modules that do not set the tempo themselves.  Such a module
  220.     is invincible to the DES_ApplyGTempo() function.
  221.  
  222. --------------------------------
  223.  
  224. DES_DisownPlayer()
  225.  
  226.   Example:
  227.  
  228.     call DES_DisownPlayer()                 Now anyone can use library.
  229.  
  230.   Function:
  231.  
  232.     Unlock library for public use.
  233.  
  234. --------------------------------
  235.  
  236. DES_EndPos( [endpos] )
  237.  
  238.   Examples:
  239.  
  240.     call DES_EndPos( 41 )                   Set end position of play seq to 41.
  241.     oldendpos = DES_EndPos( 58 )            Set end pos to 58, save old end pos.
  242.     curendpos = DES_EndPos()                Get current end position.
  243.  
  244.   Function:
  245.  
  246.     Set the end position of a play sequence.
  247.  
  248. --------------------------------
  249.  
  250. DES_FadeGlobalVol( destvolume )
  251.  
  252.   Examples:
  253.  
  254.     call DES_FadeGlobalVol( 20 )            Fade global volume to 20.
  255.     retval = DES_FadeGlobalVol( 20 )        Put error return status in retval.
  256.  
  257.   Function:
  258.  
  259.     Starts a global volume fade from the current global volume setting to the
  260.     specified volume at the current fade rate (see DES_VolFadeRate).  You can
  261.     monitor the global volume using the DES_GlobalVol() function if you need
  262.     to know when the fade is finished.
  263.  
  264. --------------------------------
  265.  
  266. DES_Filter( [0/1] )
  267.  
  268.   Examples:
  269.  
  270.     call DES_Filter( 0 )                    Turn low-pass filter off.
  271.     oldfilt = DES_Filter( 1 )               Turn filter on, save old filter setting.
  272.     curfilt = DES_Filter()                  Get current filter setting.
  273.  
  274.   Function:
  275.  
  276.     Turn low-pass filter on/off (0=off, 1=on).
  277.  
  278. --------------------------------
  279.  
  280. DES_FineTempo( newfinetempo )
  281.  
  282.   Example:
  283.  
  284.     finetempo = DES_FineTempo()         Get current fine tempo setting.
  285.     oldftempo = DES_FineTempo(-38)      Speed up song by a fine amount.
  286.  
  287.   Function:
  288.  
  289.     This function allows you to set the fine tempo of a song.  The range of
  290.     values for fine tempo is -128..127 inclusive.  This value affects the base
  291.     timing of the library's CIA player interrupt.  No really in-depth
  292.     technical explanation is necessary for you to use the fine tempo.  For the
  293.     most part, it is used for adjusting the tempo in very fine amounts until
  294.     the song plays at a speed that you're comfortable with.  If you save the
  295.     song to disk using the library's SaveModule function, this fine tempo will
  296.     be stored in the file and remembered the next time you load the song.  If
  297.     a song is loaded that does not contain this information, then the fine
  298.     tempo will be set to 0 by default.
  299.  
  300. --------------------------------
  301.  
  302. DES_GetCurChVol( channelnum )
  303.  
  304.   Example:
  305.  
  306.     vol = DES_GetCurChVol( 1 )              Get current volume of channel #1.
  307.  
  308.   Function:
  309.  
  310.     Returns current volume the the specified channel.  This will be a value
  311.     from 0..64 inclusive.
  312.  
  313. --------------------------------
  314.  
  315. DES_GetCurInstNum( channelnum )
  316.  
  317.   Example:
  318.  
  319.     instnum = DES_GetCurInstNum(3)          Get inst. # last used in channel #3.
  320.  
  321.   Function:
  322.  
  323.     Returns the slot number of the last instrument used in the specified audio
  324.     channel.  Instrument slot numbers range from 0..30 inclusive.
  325.  
  326. --------------------------------
  327.  
  328. DES_GetCurNoteNum( channelnum )
  329.  
  330.   Example:
  331.  
  332.     notenum = DES_GetCurNoteNum(0)          Get current note # for channel #0.
  333.  
  334.   Function:
  335.  
  336.     Returns the number of the last note played in the specified audio
  337.     channel.  Values for channelnum are 0..3 inclusive.  This function is
  338.     only valid while a module is playing.  The note number is a value from
  339.     0..35 inclusive, representing the full three octave range. 0 is the
  340.     lowest note playable, and 35 is the highest.  To determine the octave of
  341.     the note number, just divide it by 12.  The remainder is the semitone
  342.     offset within the octave.
  343.  
  344. --------------------------------
  345.  
  346. DES_GetCurPer( channelnum )
  347.  
  348.   Example:
  349.  
  350.     period = DES_GetCurPer( 2 )             Get current period for channel #2.
  351.  
  352.   Function:
  353.  
  354.     Returns the period value for the last note played in the specified
  355.     channel.  Period values are not terribly useful if you don't understand
  356.     how to interpret them.  You can consult the Hardware Manual for a treatise
  357.     on period values and how they work. :)
  358.  
  359. --------------------------------
  360.  
  361. DES_GetCurTempo()
  362.  
  363.   Example:
  364.  
  365.     curtempo = DES_GetCurTempo()            Get current tempo of song.
  366.  
  367.   Function:
  368.  
  369.     Returns the current tempo setting of an active play sequence.  This is a
  370.     positive value ranging from 0 up to usually about 31 tops (although it
  371.     *can* go higher).
  372.  
  373. --------------------------------
  374.  
  375. DES_GetElapsedTime()
  376.  
  377.   Example:
  378.  
  379.     timestr = DES_GetElapsedTime()          Get current elapsed play time.
  380.  
  381.   Function:
  382.  
  383.     This function returns the elapsed time for an active play sequence since
  384.     it was first started.  The result is a string in the format HH:MM:SS:JJ,
  385.     where HH is hours, MM is minutes, SS is seconds, and JJ is jiffies (i.e.
  386.     60ths of a second).
  387.  
  388. --------------------------------
  389.  
  390. DES_GetInstAddr( instnum )
  391.  
  392.   Example:
  393.  
  394.     instaddr = DES_GetInstAddr(6)           Get address of inst #6's sample data.
  395.  
  396.   Function:
  397.  
  398.     With this function you can obtain the address of a given instrument's
  399.     sample data.
  400.  
  401. --------------------------------
  402.  
  403. DES_GetInstLength( instnum )
  404.  
  405.   Example:
  406.  
  407.     instlen = DES_GetInstLength(8)          Get length of inst. #8's sample data.
  408.  
  409.   Function:
  410.  
  411.     You can obtain the length of a given instrument's sample data with this
  412.     function.  Simply pass the slot number of the instrument and the length of
  413.     the instrument is returned.  The length returned is the size in BYTES of
  414.     the sample data (not in words).
  415.  
  416. --------------------------------
  417.  
  418. DES_GetInstName( instnumber )
  419.  
  420.   Example:
  421.  
  422.     instname = DES_GetInstName( 3 )         Get name of instrument #3.
  423.  
  424.   Function:
  425.  
  426.     Gets the name of the specified instrument. Values for instnumber are
  427.     0..30 inclusive.
  428.  
  429. --------------------------------
  430.  
  431. DES_GetInstRepLen( instnum )
  432.  
  433.   Example:
  434.  
  435.     ireplen = DES_GetInstRepLen(3)          Get repeat length for inst. #3.
  436.  
  437.   Function:
  438.  
  439.     Allows you to acquire the repeat length for a given instrument.  Again,
  440.     the length returned is in BYTES, not words.
  441.  
  442. --------------------------------
  443.  
  444. DES_GetInstRepOff( instnum )
  445.  
  446.   Example:
  447.  
  448.     irepoff = DES_GetInstRepOff(1)          Get repeat offset for inst. #1.
  449.  
  450.   Function:
  451.  
  452.     Allows you to acquire the repeat offset value for a given instrument.
  453.     Note that the offset returned is the offset in BYTES, not words.
  454.  
  455. --------------------------------
  456.  
  457. DES_GetItersLeft()
  458.  
  459.   Example:
  460.  
  461.     Iterleft = DES_GetItersLeft()           Get # of remaining iterations.
  462.  
  463.   Function:
  464.  
  465.     This function returns the number of iterations of the play sequence that
  466.     are still to be played, including the iteration currently playing.  This
  467.     function is only useful while a play sequence is active.
  468.  
  469. --------------------------------
  470.  
  471. DES_GetLockStat()
  472.  
  473.   Example:
  474.  
  475.     stat = DES_GetLockStat()                Get current library lock status.
  476.  
  477.   Function:
  478.  
  479.     Returns the current lock status of the library, i.e. whether or not
  480.     someone has owned the library (with the DES_OwnPlayer() function) or not.
  481.     A return value of 0 means that the library is not locked and all functions
  482.     can be called.  A value of 1 means that the library has been owned by
  483.     someone (perhaps even you) and certain functions that affect the song,
  484.     play sequence parameters, or player status are disallowed unless you are
  485.     the one who owned the library.
  486.  
  487. --------------------------------
  488.  
  489. DES_GetModFormat( [ [path]filename ] )
  490.  
  491.   Examples:
  492.  
  493.     mformat = DES_GetModFormat()            Return format of loaded module.
  494.     mformat = DES_GetModFormat('Killer')    Return format of module on disk.
  495.  
  496.   Function:
  497.  
  498.     Returns the format of a module.  If no input is specified, then the
  499.     format of the currently loaded module is returned.  If a filename with
  500.     optional pathname is provided, then the specified file on disk is
  501.     examined and it's format is returned.  The file on disk will not be
  502.     loaded, nor will this function affect any currently loaded module.  If no
  503.     pathname is specified then the current directory is searched for the file.
  504.     Failing that, each path in the library's list of search paths is scanned.
  505.     See the description of the DES_ModulePath() function further on in this
  506.     document.
  507.  
  508. --------------------------------
  509.  
  510. DES_GetModLength()
  511.  
  512.   Example:
  513.  
  514.     mlength = DES_ModLength()               Get length of module in memory.
  515.  
  516.   Function:
  517.  
  518.     Returns the length in bytes of the currently loaded module.  This
  519.     includes all instruments.
  520.  
  521. --------------------------------
  522.  
  523. DES_GetNewNoteHits()
  524.  
  525.   Example:
  526.  
  527.     newnotes = BITXOR( oldnotes,DES_GetNewNoteHits() )  Get new note hits.
  528.  
  529.   Function:
  530.  
  531.     This function is not terribly useful for ARexx programs, but I threw it in
  532.     here anyway.  The library has four status bits (1 for each audio channel)
  533.     that record new note hits by toggling the bit between 0 and 1 each time a
  534.     new note is played in the corresponding audio channel.  Combining these
  535.     bits together, a value from 0..15 is the result (bit 0 of the result is
  536.     channel #0, bit 1 is channel #1, etc).  By remembering the previous state
  537.     of these bits from the last time you read them, you can determine which
  538.     channels received new note hits since you last checked by simply getting
  539.     the new states of the bits and exclusive-ORing them with the previous
  540.     state.  The resulting set bits indicate that a new note was played in the
  541.     corresponding channel.  However, in order to work properly, these bits
  542.     must be scanned at least 50-60 times a second, which is certainly asking
  543.     quite a bit from an ARexx script.  Hmmm.  I'll have to come up with
  544.     something better in the future.
  545.  
  546. --------------------------------
  547.  
  548. DES_GetNumPatts()
  549.  
  550.   Example:
  551.  
  552.     numpatts = DES_GetNumPatts()            Get # of patterns in a module.
  553.  
  554.   Function:
  555.  
  556.     This function returns the number of unique patterns in the currently
  557.     loaded module.  Patterns are each 256 bytes in length and contain
  558.     information for 64 notes to play in a single audio channel.
  559.  
  560. --------------------------------
  561.  
  562. DES_GetNumPos()
  563.  
  564.   Example:
  565.  
  566.     numpos = DES_GetNumPos()                Get # of positions in a module.
  567.  
  568.   Function:
  569.  
  570.     Returns the number of play positions in the currently loaded module,
  571.     regardless of the start and end position settings.  Positions are groups
  572.     of four patterns to play simultaneously - one for each audio channel.
  573.  
  574. --------------------------------
  575.  
  576. DES_GetPlayStat()
  577.  
  578.   Example:
  579.  
  580.     stat = DES_GetPlayStat()                Get current play status.
  581.  
  582.   Function:
  583.  
  584.     This function returns the current status of the player. It currenty
  585.     returns one of four strings. They are "NO MODULE LOADED" (if no module is
  586.     currently loaded), "PLAYING" (if a module is loaded and a play sequence is
  587.     active), "PLAY SEQ DONE" (if a song has finished playing), and "IDLE" (if
  588.     a module is loaded but no play sequence is active).
  589.  
  590. --------------------------------
  591.  
  592. DES_GetSongAddr()    (function no longer exists for release 2.00, lib v3.0)
  593.  
  594.   Example:
  595.  
  596.     addr = DES_GetSongAddr()                Get address in memory of module.
  597.  
  598.   Function:
  599.  
  600.     This function no longer exists.  Major internal redesign of the library's
  601. file system resulted in there not actually being any one pointer to the song
  602. in memory.  The song is now rather here and there in memory, once loaded.
  603.  
  604. --------------------------------
  605.  
  606. DES_GlobalTempo( [newtempo] )
  607.  
  608.   Examples:
  609.  
  610.     call DES_GlobalTempo( -1 )              Reduce effective tempo by 1.
  611.     oldgtempo = DES_GlobalTempo( 2 )        Increase effective tempo by 2.
  612.     curgtempo = DES_GlobalTempo()           Get current global tempo.
  613.  
  614.   Function:
  615.  
  616.     Sets/gets the global tempo.  This is a delta adjustment made dynamically
  617.     to all tempo commands in a module.  Negative values for the global tempo
  618.     make the module play faster, positive values make it play slower. A value
  619.     of zero returns play to "normal" speed.
  620.  
  621. --------------------------------
  622.  
  623. DES_GlobalVol( [newvolume] )
  624.  
  625.   Examples:
  626.  
  627.     call DES_GlobalVol( 64 )                Set maximum global volume.
  628.     oldgvol = DES_GlobalVol( 24 )           Set volume to 24, save old volume.
  629.     curgvol = DES_GlobalVol()               Get current global volume.
  630.  
  631.   Function:
  632.  
  633.     Set the global playback volume.  All volumes are scaled down
  634.     proportionately.  newvolume is a value from 0..64 inclusive.
  635.  
  636. --------------------------------
  637.  
  638. DES_InstallMod( module )
  639.  
  640.   Examples:
  641.  
  642.     retval = DES_InstallMod( mod )    Assumes module loaded into var called "mod".
  643.  
  644.   Function:
  645.  
  646.     This function behaves just like the LoadModule function except that this
  647.     one will "load" a module that already resides in memory.  This can be
  648.     very useful.  For more details see the InstallModule() function in the
  649.     "LibFuncs.DOC" file.
  650.  
  651. --------------------------------
  652.  
  653. DES_InstVol( instnum [,volume] )
  654.  
  655.   Examples:
  656.  
  657.     call DES_InstVol( 3,32 )                Set volume of instrument #3 to 32.
  658.     oldvol = DES_InstVol( 3,32 )            Set new volume. save old volume.
  659.     curvol = DES_InstVol( 3 )               Get default volume of instrument #3.
  660.  
  661.   Function:
  662.  
  663.     Sets the default volume for the specified instrument. instnum is a value
  664.     from 0..30 inclusive.  The optional volume is a value from 0..64
  665.     inclusive.
  666.  
  667. --------------------------------
  668.  
  669. DES_Iterations( [numiter] )
  670.  
  671.   Examples:
  672.  
  673.     call DES_Iterations( 3 )                Play sequence plays three times.
  674.     olditer = DES_Iterations( 2 )           Set to two iterations, save old
  675.                                             # of iterations.
  676.     curiter = DES_Iterations()              Get current setting of iterations.
  677.  
  678.   Function:
  679.  
  680.     Set the number of iterations for the play sequence. numiters is a value
  681.     from 0..255 inclusive.  A value of 0 will cause the play sequence to
  682.     iterate forever.
  683.  
  684. --------------------------------
  685.  
  686. DES_LoadModule( [path]filename )
  687.  
  688.   Examples:
  689.  
  690.     retval = DES_LoadModule('Mod:Hamsters') Loads module MOD:HAMSTERS.
  691.     retval = DES_LoadModule('Hamsters')     Loads HAMSTERS from default path.
  692.  
  693.   Function:
  694.  
  695.     Attempts to load the specified module into memory.  If no path is given,
  696.     then the current directory is searched for the file.  If the file isn't
  697.     found, then each path entry in the library's linked list of search paths
  698.     is examined (see DES_ModulePath() function further down).  Several library
  699.     parameters are modified every time a new module is loaded.  These include
  700.     the global tempo (reset to 0), timing mode (unless auto-timing-detection
  701.     is turned off, otherwise it is set to the timing mode of the new module
  702.     or, if the module has no timing info in it, it is set to 50Hz), and the
  703.     loop intent flag (reset to 0 unless new module has loop info in it).
  704.  
  705.     See the explanation of the "LoadModule" function in the file "LibFuncs.DOC"
  706.     for more detailed information on this function.
  707.  
  708. --------------------------------
  709.  
  710. DES_LoopIntent( loopflag )
  711.  
  712.   Example:
  713.  
  714.     loopflag = DES_LoopIntent()         Return current loop flag status.
  715.     oldflag = DES_LoopIntent(1)         Set loop flag on, save old flag condition. 
  716.  
  717.   Function:
  718.  
  719.     This function has no real use to the library itself, but the library will
  720.     save this flag with the song when you use the library's SaveModule
  721.     function (Rexx equivalent is DES_SaveModule()).  When the song is later
  722.     loaded, you can obtain the status of this flag and act accordingly.  For
  723.     example, if you write a jukebox program, you can examine this flag when
  724.     you load a song, and if the flag is set, you can loop the song and fade it
  725.     out (by using the DES_Iterations() and DES_FadeGlobalVol() functions).
  726.     Other parameters that are saved with the song include timing mode (i.e.
  727.     50Hz or 60Hz timing), default tempo, and fine tempo.  Just remember that
  728.     the library itself doesn't use this flag, but supports it so you can
  729.     use it to your own benefit.  If a song is loaded that does not have this
  730.     flag information stored in it, then the flag defaults to non-looping (0).
  731.  
  732. --------------------------------
  733.  
  734. DES_ModulePath( [pathname|"-"] )
  735.  
  736.   Example:
  737.  
  738.     curpaths = DES_ModulePath()           Return string of all search paths.
  739.     curpaths = DES_ModulePath("Mods:")    Add path "Mods:" to list of paths.
  740.     curpaths = DES_ModulePaths("-")       Remove all paths from path list.
  741.  
  742.   Function:
  743.  
  744.     This function replaces the (no longer available) DES_DefaultPath()
  745. function.  As of release 1.5, DES-Tracker now maintains an internal list of
  746. search paths used when loading modules.  You can add a path to this list with
  747. this function by merely giving the name of the path (e.g. "mods:classics").
  748.  
  749.     If the path you specify already exists in the list, then it will be
  750. removed.  Also, by giving the "-" character as the pathname, you will remove
  751. all paths from the list.
  752.  
  753.     See also the DES_LoadModule() function, elsewhere in this document.
  754.  
  755. --------------------------------
  756.  
  757. DES_OwnPlayer()
  758.  
  759.   Example:
  760.  
  761.     call DES_OwnPlayer()                    Noone else can make library calls now.
  762.  
  763.   Function:
  764.  
  765.     Lock library for private use.
  766.  
  767. --------------------------------
  768.  
  769. DES_PausePlay()
  770.  
  771.   Example:
  772.  
  773.     call DES_PausePlay()                    Pause currently active play sequence.
  774.  
  775.   Function:
  776.  
  777.     Pauses an active play sequence. Note that elapsed time is suspended as
  778.     well.
  779.  
  780. --------------------------------
  781.  
  782. DES_ResetDefaults()
  783.  
  784.   Example:
  785.  
  786.     call DES_ResetDefaults()                Reset library parameters to defaults.
  787.  
  788.   Function:
  789.  
  790.     This function resets several library parameters to their default values.
  791.     This is a convenient routine, since an application using the library
  792.     before you may have left these parameters in an unpredictable state.  By
  793.     simply calling this routine, you can reset the following library
  794.     parameters to the following default values:
  795.  
  796.         Global volume      = 64
  797.         Global tempo       = 0
  798.         Fine tempo         = 0
  799.         Default tempo      = 6
  800.         Volume fade rate   = 6
  801.         # of iterations    = 1
  802.         Save format        = Soundtracker v2.6
  803.         Timing mode        = Native (50Hz for PAL Amigas, 60Hz for NTSC).
  804.         Auto-timing detect = ON
  805.         Loop intent flag   = 0 (non-looping)
  806.         Lo-pass filter     = OFF
  807.  
  808.     By calling this function, you are saved the hassle of having to set these
  809.     parameters individually when you first open the library.  Of course, this
  810.     should be one of the first functions you should call (perhaps just after
  811.     you call OwnPlayer(), see above).
  812.  
  813. --------------------------------
  814.  
  815. DES_SaveFormat( [0/1] )
  816.  
  817.   Examples:
  818.  
  819.     call DES_SaveFormat( 0 )                Set save format to Soundtracker v2.6.
  820.     oldfmat = DES_SaveFormat( 1 )           Set save format to Noisetracker v2.0.
  821.     curfmat = DES_SaveFormat()              Get current save format setting.
  822.  
  823.   Function:
  824.  
  825.     This function allows you to select the module file format that will be
  826.     used by the SaveModule function.  A format value of 0 specifies
  827.     Soundtracker v2.6 format, and a value of 1 specifies Noisetracker v2.0
  828.     format.  The default format used when the library is opened for the first
  829.     time is 0 (Soundtracker v2.6 format).
  830.  
  831. --------------------------------
  832.  
  833. DES_SaveModule( [path]filename )
  834.  
  835.   Examples:
  836.  
  837.     retval = DES_SaveModule('Mod:Hamsters') Save module as MOD:HAMSTERS.
  838.     retval = DES_SaveModule('Hamsters')     Save HAMSTERS using default path.
  839.     retval = DES_SaveModule()               Save using load path & filename.
  840.  
  841.   Function:
  842.  
  843.     Saves the currently loaded module to disk under the specified filename.
  844.     The library will save your module in the currently selected file format
  845.     (see the DES_SaveFormat() function above).  The library also adds extra
  846.     information above and beyond the scope of the standard Sound/Noisetracker
  847.     file format.  An extra construct is appended to the end of the saved
  848.     module that includes playback information such as the timing mode (i.e.
  849.     50Hz or 60Hz playback speed), loop intent (indicates whether song is meant
  850.     to loop when it reaches the end or just stop), default tempo and fine
  851.     tempo.  The DES_LoadModule() function looks for this info when it loads a
  852.     song module.  If this info exists, it is automatically used (of course,
  853.     you can still load the saved module with the Sound/Noisetracker editor,
  854.     but the extra info will be thrown away by the editor and will not save it
  855.     back if you save the song from the Tracker editor).
  856.  
  857.     Note also that, as of release 1.5 of DES-Tracker, you can now call
  858.     DES_SaveModule() without a file specification at all.  DES-Tracker now
  859.     remembers the path and filename of a module when it is loaded.  Not
  860.     passing a file specification will cause this function to save the module
  861.     over top of itself on disk.
  862.  
  863.     See also the DES_LoadModule() and DES_ModulePath() functions elsewhere in
  864.     this document.
  865.  
  866. --------------------------------
  867.  
  868. DES_SetTemporalEnd( time )      (New for release 2.00, lib v3.0)
  869.  
  870.   Examples:
  871.  
  872.     call DES_SetTemporalEnd( 8*3600 )     Set end position to 8 minutes
  873.                                           from beginning of song.
  874.     call DES_SetTemporalEnd( 300*60 )     Set end to 300 seconds (10 minutes)
  875.                                           from beginning of song.
  876.  
  877.   Function:
  878.  
  879.     This function allows you to set the end position of a play sequence based
  880.     on time.    You specify the time in units of 60ths of a second.  This
  881.     is the time relative to the beginning of the song (at position 0, note 0).
  882.  
  883.     Note however, that the time you specify is relative to the beginning of
  884.     the song (position 0, note 0) and NOT the current start position.
  885.  
  886.     If you specify a time that precedes the current play sequence start
  887.     position, then the end position will be set to one note after the start
  888.     position.
  889.  
  890. --------------------------------
  891.  
  892. DES_SetTemporalPos( time )      (New for release 2.00, lib v3.0)
  893.  
  894.   Examples:
  895.  
  896.     call DES_SetTemporalPos( 3600 )     Set current position to 1 minute from
  897.                                         beginning of song.
  898.     call DES_SetTemporalPos( 30 )       Set current position to half a second
  899.                                         from beginning of song.
  900.  
  901.   Function:
  902.  
  903.     This function allows you to set the current position of a currently
  904.     playing (or playing, but paused) song based on time.  Time is specified in
  905.     the same way as it is for the DES_SetTemporalEnd() function above.  Note
  906.     however, that the time you specify is always relative to the beginning of
  907.     the song (position 0, note 0).
  908.  
  909.     Time can only be specified within the current iteration of the song.  If
  910.     you specify a time that goes beyond the last note of the song, then the
  911.     current position will be set to the last note of the song.
  912.  
  913. --------------------------------
  914.  
  915. DES_SetTemporalStart( time )    (New for release 2.00, lib v3.0)
  916.  
  917.   Examples:
  918.  
  919.     call DES_SetTemporalStart( 3*3600 )     Set start position at 3 minutes
  920.                                             from beginning of song.
  921.     call DES_SetTemporalStart( 5*60 )       Set start to 5 seconds from
  922.                                             beginning of song.
  923.  
  924.   Function:
  925.  
  926.     This function allows you to set the start position of a play sequence
  927.     based on time.  Time is specified in the same way as with
  928.     DES_SetTemporalEnd() above.
  929.  
  930.     If you specify a time that goes beyond the current play sequence end
  931.     position, then the start position will be set to one note before the end
  932.     position.
  933.  
  934. --------------------------------
  935.  
  936. DES_SongTitle( [newtitle] )
  937.  
  938.   Examples:
  939.  
  940.     call DES_SongTitle( 'HamsterDance' )    Retitle module as "Hamster Dance".
  941.     oldname = DES_SongTitle( 'Gerbil Funk') Retitle as "Gerbil Funk", get
  942.                                             old song title.
  943.     title = DES_SongTitle()                 Get title of currently loaded module.
  944.  
  945.   Function:
  946.  
  947.     Not much to say here.  Sets/gets the title of the currently loaded
  948.     module.  The length of the title is limited to 20 characters, because of
  949.     the soundtracker/noisetracker file format.  This does not include a
  950.     terminating NULL, meaning that your title can be a full 20 characters in
  951.     length.
  952.  
  953. --------------------------------
  954.  
  955. DES_StartPos( [startpos] )
  956.  
  957.   Examples:
  958.  
  959.     call DES_StartPos( 0 )              Set start position of play seq to 0.
  960.     oldstrtpos = DES_StartPos( 4 )      Set start pos to 4, save old start pos.
  961.     curstrtpos = DES_StartPos()         Get current start position.
  962.  
  963.   Function:
  964.  
  965.     Set start position of play sequence. Positions start at 0 and go up to
  966.     the number of positions in the currently loaded module.
  967.  
  968. --------------------------------
  969.  
  970. DES_StopPlay()
  971.  
  972.   Examples:
  973.  
  974.     call DES_StopPlay()                 Stop current play sequence!
  975.     rcode = DES_StopPlay()              Stop play seq, remember error status.
  976.  
  977.   Function:
  978.  
  979.     Immediately stops the current play sequence.  This function will also
  980.     reset the song position to the play sequence's defined start position.
  981.     You must use DES_BeginPlay() to start the play sequence up again
  982.     (DES_ContPlay() will not work).
  983.  
  984. --------------------------------
  985.  
  986. DES_TempoInterp( [interpretflag] )
  987.  
  988.   Example:
  989.  
  990.     oldinterp = DES_TempoInterp(0)      Enable BPM tempo interpretation. Will
  991.                                         return old tempo interpretation as well.
  992.  
  993.   Function:
  994.  
  995.     This function allows you to set the tempo interpretation for the currently
  996.     loaded module.  This setting affects the way tempo commands (the ones
  997.     embedded in the music data) are treated.
  998.  
  999.     If tempo interpretation is set to 0 (the default) then tempos in the range
  1000.     1..31 are treated as normal tempo values, while tempos in the range 32.255
  1001.     are treated as "BPM" ("Beats" Per Minute) tempo values, where a "beat"
  1002.     represents 4 note events (hence "16 beats to the bar").  You don't have to
  1003.     really understand BPM tempos to use this command, however.
  1004.  
  1005.     If tempo interpretation is set to 1 (non-BPM) then all tempos in the range
  1006.     1..255 are treated as normal tempo values, and BPM tempos are disabled.
  1007.  
  1008.     When you save the currently loaded module back to disk, this setting is
  1009.     saved along with it.  When you load the song from then on into
  1010.     DES-Tracker, the setting will be detected and set automatically.
  1011.  
  1012. --------------------------------
  1013.  
  1014. DES_TimingMode( modenum )
  1015.  
  1016.   Example:
  1017.  
  1018.     oldmode = DES_TimingMode(1)         Switch to PAL (50Hz) timing. Remember
  1019.                                         old timing mode as well.
  1020.  
  1021.   Function:
  1022.  
  1023.     Since some song modules were composed on PAL Amigas using editors that
  1024.     played music from the vertical blank, they would run at 60Hz (about 20%
  1025.     faster) when played on the same editor on an NTSC Amiga.  Since there is
  1026.     no way to tell what type of system a song module was originally composed
  1027.     on (i.e. NTSC or PAL) by looking at it.  This function allows you to switch
  1028.     the library's player between PAL and NTSC timing, i.e. 50 and 60 Hz.  Note
  1029.     that the old timing mode value is returned.  A value of 0 specifies NTSC
  1030.     timing and a value of 1 specifies PAL timing.
  1031.  
  1032. --------------------------------
  1033.  
  1034. DES_UnloadModule()
  1035.  
  1036.   Example:
  1037.  
  1038.     retval = DES_UnloadModule()             Remove current module from memory.
  1039.  
  1040.   Function:
  1041.  
  1042.     Removes the currently loaded module from memory, if a module is loaded,
  1043.     that is.
  1044.  
  1045. --------------------------------
  1046.  
  1047. DES_VolFadeRate( [newrate] )
  1048.  
  1049.   Examples:
  1050.  
  1051.     call DES_VolFadeRate( 8 )               Set nice, slow volume fade speed.
  1052.     oldrate = DES_VolFadeRate( 2 )          Set to faster fade speed, remember
  1053.                                             old fade rate.
  1054.     currate = DES_VolFadeRate()             Get current volume fade rate.
  1055.  
  1056.   Function:
  1057.  
  1058.     Sets/gets the rate at which volume fades transpire (see DES_FadeGlobalVol).
  1059.     Values for newrate are from 0..255 inclusive.  Lower values result in
  1060.     faster fades.  Values greater than 20 may require next of kin to hear
  1061.     completely.
  1062.  
  1063.                        --------------------------------
  1064.  
  1065.                              End of RexxFuncs.DOC
  1066.