Topic       : The ATARI Compendium
Author      : Scott Sanders / JAY Software
Version     : 1.25 (20/6/2003)
Subject     : Documentation
Nodes       : 1117
Index Size  : 32614
HCP-Version : 6
Compiled on : Atari
@charset    : UTF-8
@lang       : en
@default    : 
@help       : %About
@options    : +g -i -t4 +y +z
@width      : 100
View Ref-FileDosound()                                                             XBIOS

Syntax

VOID Dosound( cmdlist )
char *cmdlist;

Function      Dosound() initializes and starts an interrupt driven sound
              playback routine using the PSG.

Opcode        32 (0x20)

Availability  All TOS versions.

Parameters    If cmdlist is positive, it will be interpreted as a pointer
              to a character array containing a sequential list of
              commands required for the sound playback. Each command is
              executed in order and has a meaning as follows:

              Command                      Meaning
               Byte

              0x00   Select a PSG register (the register number is the
              -      command byte). The next byte in the list will be
              0x0F   loaded into this register. See Appendix I for
                     a detailed listing of registers, musical frequencies,
                     and sound durations.

              0x80   Store the next byte in a temporary register for use
                     by command 0x81.

              0x81   Three bytes follow this command. The first is the PSG
                     register to load with the value in the temporary
                     register (set with command 0x80). The second is
                     a signed value to add to the temporary register until
                     the value in the third byte is met.

              0x82   If a 0 follows this command, this signals the end of
                     processing, otherwise the value indicates the number
                     of 50Hz ticks to wait until the processing of the
                     next command.

              Passing the value DS_INQUIRE (-1) for cmdlist will cause the
              pointer to the current sound buffer to be returned or NULL
              if no sound is currently playing.

Binding       pea      cmdlist
              move.w   #$20,-(sp)
              trap     #14
              addq.l   #6,sp

Caveats       This routine is driven by interrupts. Do not use an array
              created on the stack to store the command list that may go
              out of scope before the sound is complete. This function will
              cause the OS to crash under MultiTOS versions prior to 1.08
              if every running application is not set to 'Supervisor' or
              'Global' memory protection. Dosound( DS_INQUIRE ) will cause
              the OS to crash under MultiTOS versions 1.08 and below.