Visual Basic 4 Power Pack/Visual_Basic4_Power_Pack.bin/vb4files/soundx/sound.doc

Text File | 1996-11-20 | 15.0 KB | 602 lines

   Copyright 1993 by Peter Sprenger   [e-mail]
                     Muenchener Str.6
                     50170 Kerpen
                     Germany

   Permission to use, copy, modify, and distribute this
   software and its documentation for any purpose and without
   fee is hereby granted, provided that the above copyright
   notice appear in all copies.  The author Peter Sprenger
   makes no representations about the suitability of this
   software for any purpose.  It is provided "as is" without
   express or implied warranty.




Welcome to SoundX!

SoundX is a library for making fm sound and playing samples on Adlib/
Soundblaster cards. The following features are implemented:


1. Recognition of soundcard. It recognizes none,adlib,sb,sbpro cards.
   It will set the FM ports correctly. It search for enironment string,
   but when none found it finds the correct addresses, intr and dma channel.
   It will test for DSP of course.

2. Digi play routines. It will play 8bit or adpcm samples. You will only
   have to give a far ptr or a normalized address in the 16mbyte space.
   It works with an interrupt routine, which handles automagically the
   dma transfer over 64k pages. Just say to play the sample and it works
   fully transparent in the background. The adcmp modes are not tested
   yet, they are implemented and should work accordingly to my docs.

3. Sample routines. It works the same like 2. They are not tested.
   Programmed according the Creative Labs docs.

4. FM support. Routines to set the cells of the FM chips. Just give a ptr
   to the 16 byte intrument description (in fact only 11 byte) and a channel
   nr and it will set the characteristics. Also implemented routines to
   set pitch (note) and to play the voice. The parameters are similiar
   to the original SBK routines. Also switch to rythm mode and vice versa
   implemented.

5. VOC play routines. Just give a ptr to the buffer and the voc will
   be played. Support of silence blocks and loops is implemented.


6. Mixer routines. Reset the mixer, set input source, set output
   mode. Set or get the volume of various registers ( not tested yet,
   since I have a sb 2.0, not a pro).

7. Midi interrupt routines ( not sure, because I have no midi cable and
   no midi hardware to test).

8. I included a c program voclook.c, that is capable of analyzing voc
   files with detail description.


What is missing?

1. Recognition of GUS.

2. Midi and CMF background player for the SoundX FM routines.



Please send my your bug reports, bug fixes and suggestions. My e-mail
address is:
                 [e-mail]


Why I made this library: I was myself in a search of a good library
for soundblaster programming. What I encountered was the SBF, that
was a nice idea but written in a such a hurry, that it was still
useless. I has still bugs, too. Some other packages looked
interesting but are quite expensive. I just bought the original SBK
from Creative Labs and was disappointed. It was expensive and bad!
In their design I lost control of Timer 0, that I needed for my other
programming.
So I decided to make a good freeware soundblaster bibleothek. Up to
now I spent about 200 hours working time in this project. It is my
hope that their will be other people who make freeware that can be
used. If every programmer would spend about 100 hours for freeware in
the lifetime, not everybody had to reinvent the wheel again. Look at
the guys from GNU and OSF they are doing a great job!

If you can use this routines use them! There must be non false shame.
I wrote this stuff that not everybody has to write his own routines.
But it would be nice, that when you make something commercial with my
routines, that you send me a copy of your project or send me some bucks,
just enough for pizza and coke to support my night programming sessions.
If you send me nothing, ok. But USE the stuff, if you can need it!

Have fun with SoundX,

            Pete

Germany, 27-Jun-93






--------------------  Documentation  ----------------------------





1. -----------------  FM routines  ------------------------------




All of the FM routines will only work, if fm_addr is set to the correct
FM address. The vriable fm_addr is set in the SB_Setup() call.
Further details will follow.


void FM_Write(WORD data);

With FM_Write() you can write data to the FM chip. The high byte of
the argument is the register number to write into, the low byte is
the data that will be written in the FM register. E.g.
FM_Write(0x1020) will write a 0x20 into register 1.


void FM_Reset();

  This routine will reset the FM chip (both if you have a sbpro).


BYTE FM_Status();

  This function returns the value of the status register of the FM
  chip.


void FM_SetChan(fm_chan channel);

  This routine lets the programmer choose which FM chips are used by
  calling the FM routines. Valid arguments are left,right,both.
  FM_SetChan sets the correct value of fm_addr. All calls will set
  "both" if you have an adlib or sb 2.0 card.


void FM_SetVoice(BYTE voice,BYTE *ins);

  FM_SetVoice will load an instrument definition in the FM cells
  corresponding to the voice parameter. Voice is valid in the range of
  0-8. The 2nd parameter of this call is a pointer to an 11 byte array
  (officially an instrument definition is 16 byte long, but only 11 are
  used).


void FM_SetNote(BYTE voice,BYTE note);

  Here you can set the pitch (freq.) of the voice. This routine
  acceptsa MIDI note as note paremeter.


void FM_SetVol(BYTE voice,BYTE vol);

  Here you can set the volume of a voice. The range of vol is from 0 to
  0x7f. From there an turnaround occurs.


void FM_KeyOn(BYTE voice);

  This call will play the note.


void FM_KeyOff(BYTE voice);

  FM_KeyOff() shuts off the voice.


  The above definitions are similiar to the low level calls of the SBK
  from Creative Labs.

  sbfd_not_on(0,60,0x40) -> FM_SetNote(0,60);FM_SetVol(0,0x40);FM_KeyOn(0);


void FM_RythmMode(BYTE bool);

  Here you can enable the rythm instruments, when you supply a logical
  TRUE as argument. Else you enable melodic mode.


void FM_RythmOn(BYTE inst);

  With this call you can play rythm instruments. You can choose the
  instruments with or'ing the following defintions together.

  FM_HIHAT
  FM_TOPCYM
  FM_TOMTOM
  FM_SNARE
  FM_BASS

  E.g. FM_RythmOn(FM_HIHAT|FM_SNARE);


void FM_RythmOff(BYTE inst);

  This procedures stops playing the selected rythm instrument. The same
  argument as FM_RythmOn().




2. -----------------  Mixer routines  ---------------------------




void MIX_Reset();

  With this call you reset the mixer.


void MIX_SetInput(BYTE opt);

  Here you can set the input source and the input filter. You can
  select it by or'ing the input source and input filter definitions.
  Input source:

  MIX_IN_MICRO
  MIX_IN_CD
  MIX_IN_MICRO2
  MIX_IN_LINE

  Input filter:

  MIX_LOW_FILT
  MIX_HIGH_FILT
  MIX_NO_FILT

  E.g. MIX_SetInput(MIX_IN_CD|MIX_NO_FILT);


void MIX_SetOutput(BYTE opt);

  You can select stereo or mono, or to bypass the output filter.
  definitions:

  MIX_BYPASS_OUT_FILT
  MIX_STEREO
  MIX_MONO

  E.g. MIX_SetOuput(MIX_STEREO);


void MIX_SetVolume(BYTE reg,BYTE left,BYTE right);

  With this routine you can set the volume of the left or right
  channel. For the arguments left and right only values in range from
  0 to 15 are used. For the 1st parameter the following values are
  sensible:

  MIX_VOICE_VOL
  MIX_MICRO_VOL
  MIX_INPUT
  MIX_OUTPUT
  MIX_MASTER_VOL
  MIX_FM_VOL
  MIX_CD_VOL
  MIX_LINE_IN_VOL

void MIX_GetVolume(BYTE reg,BYTE *left,BYTE *right);

  MIX_GetVolume() returns you the left and right volume of the
  specified mixer register. The register definition is the same as in
  MIX_SetVolume(). The function returns the volumes in the variables
  which pointers are defined as the 2nd and 3rd argument.






3. -----------------  MIDI routines  ----------------------------



Sorry none of the MIDI routines are tested yet, because I own no MIDI
hardware.


void MIDI_Write(BYTE data);

  Writes the argument to the MIDI port.


void MIDI_WriteBuf(BYTE *data,int length);

  Supply a pointer to a byte array with the data that should be send.
  The 2nd parameter is the number of bytes that will be send to the
  MIDI port. This routine will wait until all is sent, because the
  soundblaster DSP supports no interrupt MIDI writing, only reading.


WORD  MIDI_ByteAvail();

  This function returns the number of bytes that are available in the
  MIDI read buffer.


BYTE MIDI_GetByte();

  With this routine you get one byte out of the read buffer.


void MIDI_ReadBuf(WORD count,BYTE *buffer);

  MIDI_ReadBuf() will get "count" bytes out of the read buffer and
  will store it in "buffer" (2nd argument).


int MIDI_Init(BYTE mode,WORD buflen);

  This will enable MIDI interrupt mode. The 1st parameter specifies
  normal interrupt mode or UART mode:

  DSP_MIDI_READI
  DSP_MIDI_UART

  The 2nd parameter is the length of the read buffer.

  Only in UART mode you can read and write to the MIDI ports
  simultaneously. But BEWARE, if you enter UART mode, you have to use
  DSP_Write(midi_byte) to write to the MIDI port. All data sent to
  the DSP is sent to the MIDI port. To resume to normal action you
  must use a DSP_Reset(). MIDI_Remove() will do that for you.


void MIDI_Remove();

  This procedure will leave the MIDI modes and deallocate the buffer.






4. -----------------  DSP routines  -----------------------------



WARNING: Most function will only work after a DSP reset. This will
already be done in SB_Setup().


int DSP_Reset();

  This resets the DSP.


BYTE DSP_Read();

  This function returns a byte from the DSP.


void DSP_Write(BYTE output);

  DSP_Write() writes byte data to the DSP.


WORD DSP_Get_Version();

  This function returns the version number of the DSP. The major
  number is in the high byte, the minor number in the low.


DSP_Write(DSP_SPKR_ON);

  Use this to turn the DSP speaker on.


DSP_Write(DSP_SPKR_OFF);

  Andto turn the DSP speaker off.




5. -----------------  Sample routines  --------------------------




WARNING: Most functions will only work, when correct IO address, the
interrupt number and the dma channel is set. This will already be
done in SB_Setup().

To avoid clicking, the speaker will be turned on ONLY in SB_Setup().
If you shut it off during operation, you have to shut it on by
yourself.



void SetRate(DWORD rate);

  Here you can set the sample rate of the DSP. Give the sample rate
  as an unsigned integer.


void SetHighRate(DWORD rate);

  If you want to use high speed mode (over 23khz output), use
  SetHighRate() instead of SetRate().


int Play(char *data,playmode mode,DWORD length);

  This routine will play a sample out of memory with dma. The 1st
  parameter is a far ptr to the data. The 2nd parameter specifies how
  the sample is played:

  bit8
  bit4
  bit26
  bit2
  high

  The normal mode is "bit8" (unpacked). The modes
  "bit4","bit26","bit2" are adpcm modes. If you supply "high", high
  speed mode with unpacked data (8-bit) is used.
  The 3rd parameter is the length of the sample.
  To set the correct sample rate use SetRate() or SetHighRate().

  If you call Play before the end of a previous sample, the previous
  one will be interrupted, and the new one is played.

int PlayXMS(DWORD data,playmode mode,DWORD length);

  Nearly the same as Play(), but you can specifiy the sample address
  as an unsigned long word (only 24 bits used), to play samples that
  are in memory >1mbyte.


int Sample(char *data,playmode mode,DWORD length);

  Sample() will record "Length" bytes of an input source into memory
  with dma. The modes taht are available are:

  bit8
  high


DSP_Write(DSP_HALT_DMA);

  This call will halt playing a dma sample.


DSP_Write(DSP_CONT_DMA);

  And this will continue playing.





6. -----------------  voc routines  -----------------------------



WARNING: Most functions will only work, when correct IO address, the
interrupt number and the dma channel is set. This will already be
done in SB_Setup().

To avoid clicking, the speaker will be turned on ONLY in SB_Setup().
If you shut it off during operation, you have to shut it on by
yourself.



int VocPlay(char far *data);

  This procedure will play a whole voc file that lies at the memory<
  address "adr".


void VocStop();

  This will stop playing the voc file.






7. -----------------  SB setup routines  ------------------------




int SB_Setup();

  SB_Setup() does all what is necessary to startup work with SoundX.
  It resets the DSP. It scans for the soundblaster environment string
  and tests the settings. If they are not correct it will scan all
  possible IO addresses, interrupt numbers and dma channels.
  Then it detects the FM chip, and analyzes if this is an adlib, a
  sb20, a sbpro or no soundcard available.
  The vriable dsp_vers is set to the DSP version (highbyte is major
  number). The variable wh_chard is set to one of the following defs:

  none
  adlib
  sb20
  sbpro

  The following variables are set by SB_Setup() (actually
  WhichCard() ):

  io_addr -- IO port address
  intnr   -- interrupt number
  dma_ch  -- dma channel
  card_id -- Creative Labs soundcard id
  fm_addr -- the actual address of the FM chip
  fm_both -- the address for both chips
  fm_left -- the address for the left chip
  fm_right-- the address for the right chip

  you can use them with an extern statement from your module.


void SB_SetVect(vect which);

  This sets the vector to the midi or sample interrupt routine.
  The possible modes are:

  midi
  sample

  If you want only to use the FM chip, there is no need in calling
  SB_SetVect().


void SB_RemoveVect();

  SB_RemoveVect() restores the original interrupt ventor.







8. -----------------  Misc. routines  ---------------------------




int get_sb_env();

  This routine sets variables out of the environment string:

  io_addr -- IO port address
  intnr   -- interrupt number
  dma_ch  -- dma channel
  card_id -- Creative Labs soundcard id


int CardCheck();

  This routine makes another card check. Upon this it return:

  FM_DETECT
  DSP_DETECT

  The definitions stand for bits. If the bits are set the feature is
  found. E.g. if(ret&DSP_DETECT) printf("yupieee, dsp detected\n");


cardtype WhichCard();

  This is the subprocedure which is used by SB_Setup() to determine
  the sound card and to set the addresses. It returns:

  none
  adlib
  sb20
  sbpro





-----------------------------------------------------------



Vers.                          History
                               -------

 1.00 27-Jun-93  SoundX library 1.0 released