Dave Lowe: S5 Stereo Sound Sampler/Lowe_S5StereoSoundSampler.adf/Doc/S5.EntryPoints.txt

Text File | 1986-12-10 | 16.5 KB | 406 lines

Part of the S5 manual ....

Entry Points
------------

EP 1 : S5Base = OpenLibrary("s5.library",revision)
       D0                   A1           D0

Mandatory call before any other  routine  in  this library can be
used. Returns the address  of  the  library  node if successfully
opened. If NULL,  do  not  proceed  to  use  any of these library
routines. Reasons for not  opening  might include failure to find
the file LIBS:S5.Library,  or  insufficient  memory,  or  library
already open for use by another  program.  Possibly  an unrelated
program has allocated the parallel printer port, and since the S5
requires access  to  this,  if  the  initialisation  code  cannot
perform all of its functions, then  a CloseLibrary() call is made
automatically. The usual  name  for  the  global  address pointer
variable is S5Base.

EP 2 : CloseLibrary(S5Base)
                    A1
A call to inform  the  system  that  this  library  is  no longer
needed, and that the memory that it is using can be reclaimed for
other programs. During  the  course  of  the  call, any resources
claimed  by  the   OpenLibrary   routine   are  freed,  including
deallocating the parallel device.
EP 3 : Expunge(S5Base)
Used by CloseLibrary(). Do not use.
Remove library from memory.
EP 4 : Null()
Do not use.
Reserved entry  point.  (Reserved  for  system use rather than S5
use.)

EP 5 : Success = S5StartWave(Frequency,type)
                             A0        A1
Begin to play a waveform of  Frequency  Hz, of shape Type (0=Sine
1=Square  2=Triangular  3=Ramp).  Note  that  Frequency  must not
exceed 1800 Hz since each  waveform  is made from 16 samples, and
the Amiga is hardware limited  to  playing sounds at a maximum of
about 30,000 samples/sec. This function  can be used to provide a
simple signal generator  for  your  program.  e.g.  for tuning or
testing some audio equipment. Success is a standard return code.

EP 6 : Success = S5StopWave()

Stop playing the sound started by S5StartSound().

EP 7 : Success = S5StereoStart(LeftFrag,RightFrag,Deviate)
       D0                      A0       A1        D0
This is the main sound  player  routine  in  the  S5 library. The
parameters  LeftFrag   and   RightFrag   are  pointers  to  sound
fragments. These fragments are used  extensively in the S5 system
and are described in a previous section.  Each normally points to
a structure which holds  pointers  to  the actual data buffers to
play and the play rate, repeat count, and several other important
factors. This routine  also  performs  the  envelope operation if
these have been set up.  The  Deviate  parameter  is only used to
change playback pitch during  the  Preview play mode. i.e. if you
hit a key when the mode  is  enabled,  the  key code is passed to
this routine. For normal operation just use a value of 0. Success
is normally E_OK. Occasionally there  might be a port conflict or
insufficient   memory,   but   this   is   unusual.  Under  those
circumstances a  particular  error  code  might  be returned. See
'Return Codes' above.

EP 8 : Success = S5StereoStop(LeftFrag,RightFrag)
       D0                     A0       A1
Stop the sound playing,  even  if  this  means breaking in during
play. Note that  if  either  channel  is  running  with envelopes
enabled,  then   the   S5StereoStart()   routine  will  still  be
executing,   rather   than   exiting   -   so  S5StereoStop()  is
inappropriate in this  circumstance.  Success is the conventional
return value.

EP 9 : Boolean = S5CheckPlaying(Select)
       D0                       A0
Returns TRUE if the selected  channel  is actually playing still,
and FALSE if it is not. Select is 0 for left, 1 for right.

EP 10 : S5WaitForEnd(Select)
                     A0
Waits for the selected channel  to  complete playing. Select is 0
for left, and 1 for right.

EP 11 : Success = S5SoundStartup(Size,LeftFrag,RightFrag)
        D0                       A0   A1       D0
Allocates and initializes the data buffers for these two channels
to the specified number of  bytes  (samples).  Both normally have
the same size. Returns standard success  codes. Equivalent to two
S5AllocateSampleBuffer() calls.

EP 12 : Success = S5AllocateSampleBuffer(Size,Frag)
        D0                               A0   A1
Initialize just one  Frag.  Standard  Success  return. The memory
could be CHIP or  FAST  depending  on  how the Frag was allocated
(S5AllocateFrag()).
(Refer to Frag structure definition.)
Sets up the members of the structure:-
buffer set to address of block of memory;
buffer size set to Size;
Cursors ([ I ]) set to start, mid and end of buffer;
Zoom view set to end points of buffer;
Play and Record enable switches turned on;
Playing(SIC) switch off;
Set initial sample and play rate to 10000;
Set volume to maximum (64);
Set left side preference;
Name cleared;
Envelopes cleared.

EP 13 : S5SoundShutDown(LeftFrag,RightFrag)
                        A0       A1
Deallocates  the  sample  buffers  of  the  two  frags.  Use  two
S5DeallocateFrag() calls to kill the frags entirely.

EP 14 : Success = S5ConfigureHardware()
        D0
Called by the OpenLibrary()  routine.  Attempts  to configure any
hardware registers necessary for use by the S5 recording system.
If used separately don't forget to  S5Seize() the parallel device
first, otherwise there might be big trouble.

EP 15 : Success = S5DeConfigureHardware()
        D0
Called by CloseLibrary() to restore  hardware to the state before
OpenLibrary() (because of S5ConfigureHardware()). Don't forget to
S5Release() the parallel device.
(Users might like  to  claw  back  the  parallel  device during a
program run if they need  to  use  the  printer etc. In that case
call this routine, and later call  S5ConfigureHardware() again to
reallocate the hardware.)

EP 16 : Success = S5RecordSamples(LeftFrag,RightFrag)
        D0                        A0       A1
The  main  routine  for  recording.   Assumes  that  buffers  are
allocated and a sampling rate is set up in each channel fragment.
One important note is that  if  a  stereo  recording is made, the
sample rate will be the  same  for  both  channels, i.e. the left
channel rate. This is because  recording  rates  are usually very
fast, and it is not  possible  to  record  accurately  at any two
rates  simultaneously  with  this  hardware.  Also,  the system's
interrupts are turned off during a  recording, so the screen will
blank and multi-tasking stop.  It  is  not a good idea to run any
other task while making a  recording.  When recording, the buffer
cursors are ignored. Also,  the  number  of  samples taken is the
shorter of the two. When buffer  lengths  are  different, use the
mono record  method  i.e.  turn  off  one  of  the  sample enable
switches. (Part of the Frag structure.)

EP 17 : Value = S5ADC(Select)
        D0            A0
Read a single value from the  specified  channel. Select is 0 for
left, 1 for right. The value returned is between -128 and +127.

EP 18 : S5Read1LR(LeftPtr,RightPtr)
                  A0      A1
Read a single value from each of the  two channels and store them
in the bytes pointed to by the  parameters.  (Byte pointers. i.e.
Not Frag pointers!).
EP 19 : S5ClearTracks(LeftFrag,RightFrag)
                      A0       A1
Fill each entire buffer with zeroes.

EP 20 : Bool = S5ValidRange(Frag)
        D0                  A0
Returns TRUE if the start  cursor  ([)  of the fragment is placed
before the finish cursor (]).

EP 21 : Success = S5BuildEnvelopeTable(Frag,Select)
        D0                             A0   A1
Creates the volume or  period  values  needed  during an envelope
play operation. If Select is 0 create the volume values, else the
period values.

EP 22 : int = S5FreqToPlayRate(Frequency)
        D0                     A0
Convert the play rate in samples/second  into the necessary 'tick
rate'.  i.e.  the  number  required  by  the  lowest  level  play
routines. Each tick would last  about  30nS,  and there MUST be a
minimum of 124  of  these  between  each  sample.  This  function
ensures this happens. i.e. if  you  wish  to play back a sound at
60KHz, you cannot!

EP 23 : int = S5FreqToSamRateStereo(Frequency)
        D0                          A0
Convert the desired sample rate  in  samples/second into a number
of delay loops to perform, assuming this is a stereo sample. Used
by lowest level recording software.

EP 24 : int = S5FreqToSamRateMono(Frequency)
        D0                        A0
Convert the desired sample rate  in  samples/second into a number
of delay loops to  perform,  assuming  this  is  a mono recording
(either left or right). Used by lowest level recording software.

EP 25 : S5SetTiming(con1,con2,con3)
                    A0   A1   D0
Do not use.
Sets some constants used by the recording software to determine
the number  of  software  delay  loops  needed  at  a  particular
recording rate.

EP 26 : S5GetTiming(con1Ptr,con2Ptr,con3Ptr)
                    A0      A1      D0
Do not use.
Returns values  into  pointers  for  the  three  values mentioned
above.

EP 27 : Success = S5LoadIFF(Frag,FileName,Options)
        D0                  A0   A1       D0
Loads a file from disk to  a  fragment  buffer.  Frag  must be an
initialized fragment. Filename is  the full DOS filename. Options
are as follows:-

0 : Load up in default mode. The buffer  is reallocated to be the
length of data required. Highest octave only is loaded.
1 : Load up  into  existing  cursor  range.  If  cursor  range is
smaller than that in the file,  only  load  a part of it. Highest
octave only is loaded.

EP 28 : Success = S5SaveIFF(Frag,FileName,Option1,Option2)
        D0                  A0   A1       D0      D1
Saves a region between cursors  as  a  standard IFF file. Options
are as follows: If Option1  is  0  only  a single octave of a One
Shot section is to be created. i.e. a sound effect rather than an
instrument. If Option1 is in the range  1 to 5 then it represents
the number of  octaves  to  create.  Option2  is  composed of two
quantities (sorry about this !) : the number of octaves above the
current one PLUS 10 times the  number  of samples per high cycle.
For example:  Option1=4  and  Option2=1  means  create  an octave
higher than the current one; the current  octave; and two octaves
below. We recommend that you do  not  have many octaves above the
current one.
When an instrument is  being  created  both  One-Shot  and Repeat
sections are determined by the  three  cursor positions ([ I ]) -
even though you might not  be  using  the  S5  control panel, the
cursors positions  are  still  important.  (Remember  that  the I
cursor separates the One-Shot part from the Repeat part.)
Typical usage:-
S5SaveIFF(LeftFrag,"chickens",0,0); /* one shot FX */
S5SaveIFF(LeftFrag,"clucks",3,1);   /* 3-octave instrument */
S5SaveIFF(LeftFrag,"clucks2",3,482); /* 3-octaves instrument with
2 higher octaves, and SamplesPerHiCycle of 48.

EP 29 : Success = S5LoadSOP2(Left,Right,FileName,Option)
        D0                   A0   A1    D0       D1
Load a standard SOP2 file  into  each  of  the frags (Left,Right)
from  a  single  file  FileName.  A  load  is  only  made  if the
corresponding play enable flag is  set in that Frag. If Option is
0 then the buffer is adjusted  to  an appropriate size. If Option
is 1 then the data is loaded into  the cursor area, truncating if
this is necessary.

EP 30 : Success = S5SaveSOP2(Left,Right,FileName,Option)
        D0                   A0   A1    D0       D1
Save an area identified  by  a  region  possibly  for  two  Frags
(Left,Right) depending  on  whether  their  play enable flags are
set. Save both to the same file, FileName. Option should be 0.

EP 31 : Success = S5LoadSOP3(Frag,FileName,Option)
        D0                   A0   A1       D0
Load a SOP3 file. See notes  in  appendix  for  format.  Standard
success return code. If Option  is  0  then reallocate the buffer
according to the file size.  Otherwise  load  between the [ and ]
cursors.

EP 32 : Success = S5SaveSOP3(Frag,FileName,Option)
        D0                   A0   A1       D0
Save sample data to a  SOP3  file.  Option  is unused. Success is
standard return code.

EP 33 : FragPtr = S5AllocateFrag(Size,Type)
        D0                       A0   A1
Allocate and initialize a Frag structure,  allocating  Size bytes
for the sample buffer. Return  zero  if insufficient memory. Type
is FRAG_CHIP (=0) for  normal  operation  of  FRAG_FAST  (=1) for
fragments with data buffers placed in FAST memory.
EP 34 : S5DeallocateFrag(Frag)
                         A0
Undoes  the   AllocateFrag()   operation,   freeing   any  memory
associated.

EP 35 : Success = S5LoadEnvelope(EnvPtr,FileName)
        D0                       A0     A1
Reads in a text file and sets  up  the Envelope pointed to by the
parameter.
EP 36 : Success = S5SaveEnvelope(EnvPtr,FileName)
        D0                       A0     A1
Write out an envelope as a text file.

EP 37 : S5KillEnvelope(Env)
                       A0
Deallocate and clear structures within the envelope, but does not
deallocate the envelope structure itself.

EP 38 : Success = S5FastMemRecord(Frag)
        D0                        A0
Record into FAST memory. See section 'Extended Memory'. This is a
mono recording, on  the  Left  physical  channel.  Note  that the
ordinary record above will also record into FAST memory.

EP 39 : Success = S5FastMemPlay(Frag)
        D0                      A0
Play a sample buffer from  FAST  memory.  See  section  `Extended
Memory`. CHIP memory  will  be  allocated  at  the  start of this
routine. If two large  buffers  already  exist,  there may not be
enough CHIP memory left, or not in  contiguous blocks. Be sure to
check the Success code.

EP 40 : Success = S5Seize()
        D0
Grabs the Parallel device from  the  system. Stops other programs
from using it accidentally.  This  routine  might fail if another
program is already using the parallel device.

EP 41 : Success = S5Release()
        D0
Release the Parallel device so that other programs may use it.

EP 42 : S5SetPlay(Frag,Option,Value)
                  A0   A1     D0
Change one item  of  the  specified  fragment  depending  on  the
Option.
Option Element changed
  1      Play rate
  2      Volume
  3      Repeat count
  4      Play enable flag. 1=on 0=off
  5      Record enable flag. 1=on 0=off
  6      Record rate. (same as S5SetRecord()).
Useful when called from Basic, where structures are unavailable.

EP 43 : S5SetRecord(Frag,rate)
                    A0   A1
Change record rate.

EP 44 : int = S5FragSize()
        D0
Returns size  (in  bytes)  of  the  Frag  structure.  Useful  for
languages which do not have a  STRUCTURE  construct,  but need to
allocate memory dynamically.

EP 45 : S5STEREOSAMPLE(LeftBuf,RightBuf,Length,Delay)
                       A0      A1       D0     D1
The main stereo recording  routine.  LeftBuf and Rightbuf are the
bases of two byte arrays where  the  data will be written to, for
Length bytes. Delay is a software  loop count per sample computed
from S5FreqToSamRateStereo(frag->Fr_sampHz).

EP 46 : S5LEFTSAMPLE(LeftBuf,Length,Delay)
                     A0      A1     D0
Record on left physical channel only. See S5STEREOSAMPLE().

EP 47 : S5RIGHTSAMPLE(RightBuf,Length,delay)
                      A0       A1     D0
Record on right physical channel only. See S5STEREOSAMPLE().

EP 48 : S5DUMMYREAD(Length)
                  A0
Exercises recording hardware. Only useful for testing hardware.
Do not use.

EP 49 : S5FILL(Buffer,Length,FillByte)
             A0     A1     D0
Copy FillByte Length times to Buffer.

EP 50 : S5MOVE(Source,Destination,Length)
               A0     A1          D0
Block copy from Source to Destination for Length bytes.

EP 51 : S5GetStatus(VariableAddress)
                    A0
Used in Basic to set a LONG  INTEGER  variable  to the error code
returned from the previous S5  routine  which  returned a Success
code - or any other value, such as a pointer or boolean result.

An example portion of an Amiga Basic program :

Succ& = 0 : REM Defines a variable. Most important to do this !!!
f$="plop.sop2"+chr$(0)
CALL S5Player(SADD(f$))
S5GetStatus(VARPTR(Succ&))
IF Succ&<>EOK THEN GOSUB ReportError
REM should have loaded, played, and deallocated OK

EP 52 : Success = S5Player(Filename)
        D0                   A0
Simply  load  and  play   the   sound   in  the  specified  file.
Automatically works out whether  its  IFF,  SOP2, or SOP3 format.
Allocates sufficient space  and  resources  to  do  the job. When
finished, cleans up  accordingly.  This uses the resources of the
rest of the library, so it is not a good idea to use this routine
with the S5StereoStart() routine.

EP 53 : S5LatticeIO(inf,outf,errf)
                    A0  A1   D0
Redundant.
Do not use.
`