home *** CD-ROM | disk | FTP | other *** search
/ Acorn RISC PD-CD 1 / Acorn RISC PD-CD 1.iso / music / _coconizer / coconizer / _player / readme / modulecoms < prev    next >
Encoding:
Text File  |  1992-09-30  |  6.3 KB  |  162 lines
  1. ================================================
  2. =  How to control the Coconizer Player Module  =
  3. ================================================
  4.  
  5. The chunk number of the player module lies in the user range, and is &C0640.
  6. All SWIs have prefixes of 'Coco', like Coco_ClaimRMA, etc. A star behind the
  7. name in the description means it's also available as command. In contrast to
  8. the usual OS commands they treat numeric parameters as decimal, except when
  9. an own base (&x or base_x) is given.
  10. When the Coco module is loaded it uses RISC OS' current volume as default
  11. setting. NB: Actually the player module "CocoPlayer" is stored as squeezed
  12. absolute file on disc, buit it unpacks itself as a real module when run.
  13.  
  14.  
  15. ClaimRMA (*)
  16. ¯¯¯¯¯¯¯¯¯¯¯¯
  17. => R0 = Amount of RMA Block to claim in Bytes,
  18.          0 to read current Pool.
  19. <= R0 = Current Block in Bytes (0 means none has been reserved yet).
  20.    R1 = Address of Start of Block (for internal purposes only).
  21.  
  22. This SWI is mainly useful when songs or tracks shall be played while working
  23. in the Desktop. It reserves a block of memory in RMA, so coming tracks can
  24. be loaded in this area without freeing and claiming new blocks every time.
  25. It's a good idea to do this once in order to avoid RMA holes, with the small
  26. risk to have reserved a bit too much memory.
  27.  
  28.  
  29. ReleaseRMA (*)
  30. ¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  31. Frees an earlier reserved block in the RMA. Does also stop any active music
  32. or sound laying in this area.
  33.  
  34.  
  35. LoadTrack (*)
  36. ¯¯¯¯¯¯¯¯¯¯¯¯¯
  37. => R0 = Pointer to Filename.
  38.    R1 = Address (aligned) where to load Track to,
  39.          0 to load into existing RMA Block (or claiming a new one first).
  40. <= R0 = Number of the Voices of that Track.
  41.    R1 preserved.
  42.  
  43. Loads a trackfile, consisting of the song and the samples. Please ensure
  44. that the given address in R1 is word-aligned. If R1=0 then the trackfile is
  45. loaded into the previously claimed RMA block if it fits. In case no block
  46. does exist yet, a new one with the size of the given file is claimed first.
  47.  
  48.  
  49. SystemOn (*)
  50. ¯¯¯¯¯¯¯¯¯¯¯¯
  51. => R0 = Address (aligned) of Track to prepare,
  52.          0 if the Song resists in the RMA.
  53. <= R0 = Address of Interrupt Routine, which then can be called 50 times per
  54.         second.
  55.  
  56. Previously active music/sound is disabled, Coco's soundsystem is linked to
  57. the (new) track's samplepool (if it isn't yet), ie sound is enabled. The
  58. samplepool of the specified track will also be initialised if necessary. But
  59. the new song won't be played via interrupt. This SWI has been invented so
  60. that the user can either make effects without the need to play the song, or
  61. play the song by his/her own (with 50 Hz, Usr_mode and R13 must point to a
  62. valid stack).
  63. Making sound effects without the song being played restricts the available
  64. commands to 07,0C-0F, as the other effects 00-06 are performed in the
  65. interrupt routine of the player which isn't enabled at this point.
  66.  
  67.  
  68. SystemOff (*)
  69. ¯¯¯¯¯¯¯¯¯¯¯¯¯
  70. Stops an active song, disables Coco's soundsystem, and releases an existing
  71. RMA block. On exit of this SWI, the OS is entirely clean from any sound
  72. stuff.
  73. You must always disable the soundsystem with this command before moving or
  74. changing the memory where a linked track is stored, because the enabled
  75. soundsystem does rely on informations stored in the track's samplepool.
  76.  
  77.  
  78. PlayStart (*)
  79. ¯¯¯¯¯¯¯¯¯¯¯¯¯
  80. => R0 = Address (aligned) of Track in Memory to play from,
  81.          0 if the Song resists in the RMA.
  82. <= R0 corrupted.
  83.  
  84. Starts to play the specified song via interrupt. Does call SystemOn before,
  85. in order to enable the soundsystem correctly, so please read this info for
  86. further details.
  87.        
  88.  
  89. PlayStop (*)
  90. ¯¯¯¯¯¯¯¯¯¯¯¯
  91. Just stops the current music, ie releases its interrupt. Does not disable
  92. the soundsystem, so further sound fx are perfectly possible. If you want to
  93. release Coco's entire soundsystem you should call SystemOff (when RMKilling
  94. the player module, this is done automatically).
  95.  
  96.  
  97. GetInfos
  98. ¯¯¯¯¯¯¯¯
  99. <= R0 = Address of the Start of the Header's Workspace.
  100.    R1 = Current Position in Sequence (ie from 0-254).
  101.    R2 = Current Address in the Patternrow (first Channel).
  102.    R3 = Current Address in the Sequence.
  103.    R4 = Address of Track.
  104.    R5 = Current Speed of Playing (in 50Hz Counts)
  105.    R6 = Number of Voices are in the lower Byte (ie R6 AND &FF).
  106.  
  107. This call allows the programmer to get maximum control over a linked track.
  108. With the address of the track provided in R4 the user can read further
  109. informations directly. The internal volume is located at address (Head-4),
  110. so is accessed via !(R0-4) and does use the logarithm lower signed bit
  111. format (LSB) of the VIDC. This means you should only set even numbers
  112. (0-254, bit zero clear) in this location.
  113. Bits 8 to 31 of R6 are reserved, don't expect that they're zero in future
  114. releases. Voices=0 means no soundtrack is linked to the player.
  115.  
  116.  
  117. MakeEffect (*)
  118. ¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  119. => R0 = Tone Information Word, ie &ppiieebb (Tone, Inst, Effect, Byte).
  120.    R1 = Channel Number (1-8).
  121. <= R0,R1 preserved.
  122.  
  123. This makes the effect in R0 on channel R1. It's exactly the tone information
  124. word that is used when editing or playing patterns. Will only work of course
  125. when the soundsystem is enabled (either via PlayStart or via SystemOn).
  126.  
  127.  
  128. AlterVoice (*)
  129. ¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  130. => R0 = 0 to enable this Voice,
  131.         1 to disable it for the Duration of the current Tone (FX),
  132.         2 to disable it constantly.
  133.    R1 = Channel Number (1-8).
  134. <= R0,R1 preserved.
  135.  
  136. This SWI alters the status of a channel. Disabling means that the music on
  137. this channel is not played 1) as long as the current tone (or fx) is still
  138. active (repeated samples are always active!), or 2) until the channel is
  139. enabled again.
  140.  
  141.  
  142. PositionJump (*)
  143. ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  144. => R0 = Position in the Sequence where to jump to (0 to MaxSequenceNumber).
  145.    R1 = Row in the Pattern where to start from (0 to 63).
  146. <= R0,R1 corrupted.
  147.  
  148. Goes to a certain position in the song. In order to restart the song, enter
  149. this SWI with both parameters set to zero (or do *PlayStart [Adr]). Please
  150. note that this SWI doesn't alter the status bytes of the channels.
  151.  
  152.  
  153. SetVolume (*)
  154. ¯¯¯¯¯¯¯¯¯¯¯¯¯
  155. => R0 = New Volume (0-255, and 255=silent)
  156. <= R0 preserved.
  157.  
  158. Sets the volume of the entire soundsystem. It accesses the internal volume
  159. loaction (Head-4) via a linear to logarithm table lockup. So, in contrast to
  160. the internal logarithm volume of Coco, this let you adjust a linear volume.
  161.  
  162. Text edited by Epics.