[Contents] [Index] [Help] [Retrace] [Browse <] [Browse >]

This is a single-channel command and is the main command for making
sounds. You pass the following to cmd_write:

   *  A pointer to the waveform to be played (must start on a word boundary
      and must be in memory accessible by the custom chips, MEMF_CHIP)

   *  The length of the waveform in bytes (must be an even number)

   *  A count of how many times you want to play the waveform

If the count is 0, cmd_write will play the waveform from beginning to end,
then repeat the waveform continuously until something aborts it.

If you want period and volume to be set at the start of the sound, set the
WRITE command's ADIOF_PERVOL flag. If you do not do this, the previous
volume and period for that channel will be used. This is one of the flags
that is cleared by doio() and sendio(). the ioa_writemsg field in the
IOAudio block is an extra message field that can be replied to at the
start of the cmd_write. this second message is used only to tell you when
the CMD_WRITE command starts processing, and it is used only when the
ADIOF_WRITEMESSAGE flag is set to 1.

If a cmd_stop has been performed, the cmd_write requests are queued up.
The CMD_WRITE command does not make its own copy of the waveform, so any
modification of the waveform before the CMD_WRITE command is finished may
affect the sound. This is sometimes desirable for special effects. To
splice together two waveforms without clicks or pops, you must send a
separate, second CMD_WRITE command while the first is still in progress.
This technique is used in double-buffering, which is described below.

By using two waveform buffers and two cmd_write requests you can compute a
waveform continuously. This is called double-buffering. The following
describes how you use double-buffering.

   1. Compute a waveform in memory buffer A.

   2. Issue cmd_write a with io_data pointing to buffer a.

   3. Continue the waveform in memory buffer B.

   4. Issue cmd_write b with io_data pointing to buffer b.

   5. Wait for cmd_write a to finish.

   6. Continue the waveform in memory buffer A.

   7. Issue cmd_write a with io_data pointing to buffer a.

   8. Wait for cmd_write b to finish.

   9. Loop back to step 3 until the waveform is finished.

  10. At the end, remember to wait until both cmd_write a and b are
      finished.