Part II/2C: Writing Control Drivers

Example:

File streaming encoder (fstr).


sfront invocation:

sfront -cin fstr


driver file/location:

sfront/src/lib/csys/fstr.c

symbolic constants and
macros must begin with:

CSYSI_


global variables must 
begin with:

csysi_


internal functions must 
begin with:

csysi_


All control drivers must
define:

int csys_setup(void) {}
int csys_newdata(void) {}
void csys_shutdown(void) {}


control drivers that can 
return MIDI commands must 
define:

int csys_midievent(...) {}


control drivers that can 
return SASL commands must 
define:

int csys_saslevent(...) {}


see Part II/2B for the
conventions for
command-line flags a
control driver defines
for the sa.c file.

int csys_setup(void) { }

Called once, near the start
of execution of the sa.c 
file. Return values:

CSYS_DONE : if control driver
            initialization is
            successful.

CSYS_ERROR: if control driver
            wishes to terminate
            the sa.c file due
            to initialization
            problems.

int csys_newdata(void) {}

Called at the start of each
i-pass. Legal return values:

CSYS_NONE:  

  No new MIDI or SASL events
  for this i-pass. The sa.c 
  file will not call the 
  csys_midievent() or the
  csys_saslevent() function
  on this i-pass. 

CSYS_MIDIEVENTS:

  New MIDI events, but no
  new SASL events, on this
  i-pass. The sa.c file will
  call csys_midievent() to
  receive the event(s).

CSYS_SASLEVENTS:

  New SASL events, but no
  new MIDI events, on this
  i-pass. The sa.c file will
  call csys_saslevent() to
  receive the event(s).

CSYS_EVENTS:

  New MIDI events and 
  new SASL events on this
  i-pass. The sa.c file will
  call csys_midievent() and
  csys_saslevent() to 
  receive the events.

void csys_shutdown(void) {}

Called at the normal end of
execution of the sa.c
program, so that the control
driver may close devices and
files. 

If the sfront command-line 
option -except is invoked, the 
csys_shutdown function is also
called in the case of abnormal
termination, such as a floating
point exception.

int csys_midievent(

    unsigned char * cmd,
    unsigned char * ndata,
    unsigned char * vdata,
    unsigned short * extchan,
    float * fval);

Place MIDI event information 
in pointer, i.e:

   *cmd = CSYS_MIDI_NOTEON;
   *ndata = 40;
   *vdata = 64;
   *extchan = 1;
   *fval = 0.0F;

Return values:

   CSYS_EVENTS:

      Requests another call to
      csys_midievent on this 
      i-pass, to communicate
      another MIDI event.

   CSYS_NONE:

      Indicates there are no
      more MIDI events for this
      i-pass.

MIDI commands:

  symbolic         hex

CSYS_MIDI_NOTEOFF   80   
CSYS_MIDI_NOTEON    90   
CSYS_MIDI_PTOUCH    A0   
CSYS_MIDI_CC        B0   
CSYS_MIDI_PROGRAM   C0   
CSYS_MIDI_CTOUCH    D0   
CSYS_MIDI_WHEEL     E0   

Special commands:

CSYS_MIDI_NOOP      70
CSYS_MIDI_NEWTEMPO  71
CSYS_MIDI_ENDTIME   72

The *extchan field 
should be set to the extended
MIDI channel for the command.
For a simple system (a single
MIDI stream with 16 channels)
set *extchan to the
MIDI channel number (0 to 15).

For a complicated system with
several 16-channel MIDI ports,
set *extchan to

16*P + N

where P is the MIDI port 
(numbered from 0) and N is
the MIDI channel number (0-15).

Start a MIDI note on *extchan.

*cmd = CSYS_MIDI_NOTEON
*ndata = [note number, 0-127]
*vdata = [velocity, 0-127]

Note: *vdata = 0 treated as a 
CSYS_MIDI_NOTEOFF.

End a MIDI note on *extchan.

*cmd = CSYS_MIDI_NOTEOFF
*ndata = [note number, 0-127]

Note: MP4-SA does not support
release velocity.

Polyphonic aftertouch on *extchan.

*cmd = CSYS_MIDI_PTOUCH
*ndata = [note number, 0-127]
*vdata = [touch value, 0-127]

Controller change on *extchan

*cmd = CSYS_MIDI_CC
*ndata = [controller number, 0-127]
*vdata = [controller value, 0-127]

Note: See this section
for symbolic MIDI controller 
numbers.

Change program on *extchan

*cmd = CSYS_MIDI_PROGRAM
*ndata = [program number, 0-127]

Note: See left panel for 
MP4-SA semantics.

Channel aftertouch on *extchan.

*cmd = CSYS_MIDI_CTOUCH
*ndata = [touch value, 0-127]

Pitch wheel value on *extchan.

*cmd = CSYS_MIDI_WHEEL
*ndata = [wheel LSB, 0-127]
*vdata = [wheel MSB, 0-127]

Note: Value of MIDIbend will
be read as (*vdata)*128 +
(*ndata). Coding follows the
MIDI command syntax for easy
parsing.

Do nothing.

*cmd = CSYS_MIDI_NOOP

Change the tempo value.

*cmd = CSYS_MIDI_NEWTEMPO
*fval = [new tempo, beats/min]

Note: The current tempo is
available in the global
variable tempo.

Change the endtime value

*cmd = CSYS_MIDI_ENDTIME
*fval = [endtime, in beats]

Note: Global variables
are available that tell the
current endtime status. To
halt execution after the 
current execution cycle, set
*fval to the value of the
global variable scorebeats.

int csys_saslevent(

    unsigned char * cmd, 
    unsigned char * priority,
    unsigned short * id, 
    unsigned short *label, 
    float * fval, 
    unsigned int * pnum, 
    float ** p)	


Place SASL event information 
in pointer, i.e:

   *cmd = CSYS_SASL_TEMPO;
   *fval = 61.0F;

Return values:

   CSYS_EVENTS:

      Requests another call to
      csys_saslevent on this 
      i-pass, to communicate
      another SASL event.

   CSYS_NONE:

      Indicates there are no
      more SASL events for this
      i-pass.

SASL commands:

  symbolic         hex

CSYS_SASL_INSTR    0x00 
CSYS_SASL_CONTROL  0x01 
CSYS_SASL_TABLE    0x02 
CSYS_SASL_ENDTIME  0x04 
CSYS_SASL_TEMPO    0x05 

Special commands:

CSYS_SASL_NOOP     0x06

Note that hexadecimal 
values for the SASL 
command encoding matches
the MP4-SA binary encoding
for class score_line.

Normal priority commands:

*priority = 0;

High priority commands:

*priority = 1;

See right panel for details.

Create a SAOL instr instance.

*cmd   = CSYS_SASL_INSTR
*id    = [instr to create]
*label = [label for instr]
*fval  = [duration, or -1]
*pnum  = [number of parameters]
*p     = [pointer to float array]


Notes:

[1] The *id field specifies
the SAOL instr to create, by
using the csys_instr[].index
number. 

[2] The *label field is the
SASL label, if any, of the
instrument. Use the constant
CSYS_NOLABEL to signify an
unlabelled instrument, use a
constant value greater than
CSYS_LABELNUM to create unique
new labels, or see this 
section for details on how
to specify label names from a
SASL score in the configuration
block.

[3] The *fval field is the
duration of the instr, in
units of scorebeats, or is
-1 if the instr has indefinite
duration.

[4] The *p field points to a
float array of size *pnum that
holds the parameter values for
the instr.  The csys_instr
structure has information on the
number and names of the instr
parameters.

Updates a SAOL global variable.

*cmd   = CSYS_SASL_CONTROL
*id    = CSYS_SASL_NOINSTR
*label = CSYS_NOLABEL
*pnum  = [variable to change]
*fval  = [new variable value]


[1] Set *pnum to the 
csys_global[].index
value of the variable to be
changed.

[2] Set *fval to the new value of
this variable.

Updates an imports
variable in a labelled 
instance of a SAOL instr.
The variable must not 
have a matching variable
in the global block.


*cmd   = CSYS_SASL_CONTROL
*label = [label name]
*id    = [instr name]
*pnum  = [variable to change]
*fval  = [new variable value]


[1] The *label field is
set to the label number
of the target instr 
instances. If the control
driver is labelling its 
CSYS_SASL_INSTR commands
using unique labels, it 
will know the correct label
number to use. If the 
control command targets an
instr created by a SASL
instr command in the 
configuration block, see
this section for details
on how to specify the label
names. 

[2] The same SASL label can
be applied to instances of
multiple instr types. The
CSYS_SASL_CONTROL needs to
be invoked multiple times in
this case, one for each 
instr type. The *id field
specifies the SAOL instr 
a CSYS_SASL_CONTROL command
targets, by using the 
csys_instr[].index number. 

[3] The *pnum field is the
csys_instr[].csys_vars[].index
number for the variable to
be changed (see Note below).

[4] This data structure
simplifies the search for the
correct *id and *pnum values
for some types of control
driver applications.

[5] Set *fval to the new value of
the variable.



Note: Even though the MP4-SA
specification only allows imports
variables to be changed, the
CSYS_SASL_CONTROL command will
change all instr signal variables,
to support control drivers which
help in SAOL program debugging.
Changing a non-imports variable
is not guaranteed to change SAOL
program behavior unless the -O0
option is used, since sfront may
have optimized away the variable
that is being changed.

Updates a SAOL global or future
table.

*cmd   = CSYS_SASL_TABLE
*id    = [table to modify]
*label = [wavetable generator]
*pnum  = [number of parameters]
*p     = [pointer to float array]


[1] Set *id to the 
csys_global[].index
value of the table to be changed.
Note that both global and future
tables are in this array.

[2] Set *label to one of these 
constants to indicate the 
wavetable generator:

  symbolic                hex

CSYS_SASL_TGEN_SAMPLE      6F 
CSYS_SASL_TGEN_DATA        70
CSYS_SASL_TGEN_RANDOM      71
CSYS_SASL_TGEN_STEP        72
CSYS_SASL_TGEN_LINESEG     73
CSYS_SASL_TGEN_EXPSEG      74
CSYS_SASL_TGEN_CUBICSEG    75
CSYS_SASL_TGEN_POLYNOMIAL  76
CSYS_SASL_TGEN_SPLINE      77
CSYS_SASL_TGEN_WINDOW      78
CSYS_SASL_TGEN_HARM        79
CSYS_SASL_TGEN_HARM_PHASE  7A
CSYS_SASL_TGEN_PERIODIC    7B
CSYS_SASL_TGEN_BUZZ        7C
CSYS_SASL_TGEN_CONCAT      7D
CSYS_SASL_TGEN_EMPTY       7E
CSYS_SASL_TGEN_DESTROY     7F

Note that the numeric values match
the MP4 symbol token values for 
these wavetable generators. Also
note that opcode and wavetable
"buzz" are different token!

[3] With the exception of the 
SAMPLE generator, the *pnum
field is the number of wavetable
parameters, and the *p field points
to an array of floats that
are the parameters of the
wavetable generator. Note the
CONCAT generator has table 
values for some of its parameters.
For these parameters, use the 
csys_global[].index value for
the table, cast into a float.

[4] The SAMPLE generator uses 
the *pnum and *p arguments in
a different way. The *pnum value
is 4 + the number of actual
samples in the wavetable. The
control driver is responsible
for executing the semantics of
the size and skip
field, to figure out this actual
size. 

The first four elements in the
*p array have special meanings,
that map into fields of the
class sample of the MP4 binary
file:

(*p)[0]  sampling rate (Hz) (srate)
(*p)[1]  loop start (index) (loopstart)
(*p)[2]  loop end  (index)  (loopend)
(*p)[3]  base frequency (Hz) (basecps)

A value of -1 for these parameters
codes "unknown". The actual sample
elements are placed in elements 
(*p)[4] to (*p)[(*pnum)-1]. Note 
that the loop start and loop end
values are not offset by 4 -- so
a loop start at the top of the
table would be set to 0 (not 4)
and a loop end at the last element
of the table would be set to 
(*pnum) - 4 (not *pnum).

Executes SASL endtime command.

*cmd = CSYS_SASL_ENDTIME
*fval = [endtime in scorebeats]

Note: Global variables
are available that tell the
current endtime status. To
halt execution after the 
current execution cycle, set
*fval to the value of the
global variable scorebeats.

The SASL tempo command

*cmd = CSYS_SASL_TEMPO
*fval = [new tempo, beats/min]

Note: The current tempo is
available in the global
variable tempo.

Do nothing.

*cmd = CSYS_MIDI_NOOP

[1] cd sfront/src/lib

[2] Edit Makefile, and add 
name of your control driver
to the CSYS list. 

[3] Type "make". This will
create:

sfront/src/csyslib.c 
sfront/src/csyslib.h

which includes an embedded
version of your driver. Search
in the files for your driver
name to verify.

[4] Whenever you change your
driver code in sfront/src/lib/csys
you will need to remake the
csyslib.c file.

In sfront/src/control.c, make
these additions, to add driver
"mydriver".

[1] Add the constant definition

#define CDRIVER_MYDRIVER 

top the top of the file. Give it
the current numerical value of
CDRIVER_END, and then increase
the value of CDRIVER_END by 1.

[2] Add a printf line to the
function

void printcontrolhelp(void)

that describes the -cin mydriver
flag. This will be printed out
when "sfront -help" is invoked.

[3] Add an if statement to the
funtion cinfilecheck that takes
this form:

if (!strcmp(fname,"mydriver"))
 {
   cin = CDRIVER_MYDRIVER;
   csasl = 1;            
   cmidi = 1;            
   cmaxchan = 3;
   clatency = ?_LATENCY_DRIVER;
   return 0;
  }

  [a] Set csasl to 1 if your
      driver supports SASL
      commands, else set it
      to 0. If you set it to
      1, the sa.c file expects
      your driver to define the 
      csys_saslevent() function.

  [b] Set cmidi to 1 if your
      driver supports MIDI 
      commands, else set it to 0.
      If you set it to 1, the sa.c
      file expects your driver to
      define the csys_midievent()
      function.

  [c] If you set cmidi to 1, set
      cmaxchan to 1 + the number
      of extended MIDI channels
      your driver supports. Don't
      set this value unnecessarily
      high, since it makes the 
      executable larger.

  [d] Set clatency to 

      LOW_LATENCY_DRIVER 

      if your driver is  
      interactive, for example a
      a MIDI In jack driver. 

      Otherwise, set clatency
      to

      HIGH_LATENCY_DRIVER; 
 

[4] Add this case entry to the
switch statement in 

void makecontroldriver(int num)

  case CDRIVER_MYDRIVER:
    makemydriver();
    break;

This call actually does the code
insertion into the sa.c file: it
calls the function created in 
csyslib.c from your driver file.

Type "make" in sfront/src to 
compile sfront with your driver.

During driver development, you 
should edit your original driver
source in

sfront/src/lib/csys/mydriver.c

then to test first:

cd sfront/src/lib/
make

and then:

cd sfront/src
make