Sfront Reference Manual: Part II/2A: Control Driver Overview
Description: A part of the Sfront reference manual, that is a collection of reference materials. Sfront is a program that translates MP4-SA files into C programs.
Keywords: MP4-SA, SASL, SAOL, MP4, sfront, command line options.

### From The `sfront` Reference Manual by John Lazzaro and John Wawrzynek.

# Part II/2A: Overview of Control Drivers

## Sections Introduction. Example: `fstr` control driver. Uses the file streaming control driver to introduce the control driver concept.

## Introduction Several sfront command-line options let the user specify control information in a static way. The `-sco` and `-sstr` command line options let user specify SASL commands in an ASCII file, and the `-midi` and `-mstr` options let users specify MIDI commands via standard MIDI files. Both SASL and MIDI commands may be a part of `mp4` binary files, which are specified by the `-bit` and `-bitc` options. When any of these options are specified, sfront transforms the control information into initialization parameters for C global variables in the `sa.c` file. A static compilation approach lets the C compiler optimize the `sa.c` program in significant ways. However, for some applications, a static approach to SASL and MIDI control data is not suitable. An important example is streaming Structured Audio files over the Internet. The `mp4` file format lets users place the SASL and MIDI control information in small packets (called `SA_access_units`) at the end of the file (see this section of the manual to learn how to encode control information into SA_access_units). A Structured Audio decoder that can accept control data dynamically can start playing back an `mp4` file once a few `SA_access_units`s are received, rather than wait for the entire file to arrive. The control driver interface is designed to support dynamic control applications such as audio streaming. The interface lets the user specify a C or C++ driver file to be included into the main `sa.c` file, that is capable of dynamically issuing SASL and MIDI commands at each k-cycle. In addition to providing functionality for normatively streaming Structured Audio, the control driver interface also has facilities for supporting interactive applications such as patch editors, sequencers, and hardware emulations. Our description of control drivers is divided into three sections. In this section, we introduce the control driver architecture by describing the streaming file control driver `fstr` that is included in the sfront distribution. The second and third sections describe the control driver interface in detail. | ##

## Example: `fstr` control driver The right panel shows how to use sfront to stream a Structured Audio binary file that has control information encoded as `SA_access_unit`s. The example uses the file streaming control driver `fstr`. In this section, we will use `fstr` to introduce the control driver concept. The control driver `fstr` is invoked on the sfront command line by using the option `-cin fstr`. This option copies the C or C++ code contained in the file `sfront/src/lib/csys/fstr.c` into the `sa.c` file created by sfront. Like all control drivers, the `fstr` control driver defines a small number of C functions, listed on the right panel. These functions are called at different points during the execution of the `sa.c` program: csys_setup(void) Called at the start of execution of the `sa.c` program, lets the control driver initialize its state. csys_newdata(void) Called once per control cycle (k-cycle). Its return value informs the main program that there are MIDI or SASL events that the driver wishes to execute this cycle. csys_midievent(...) Called if the csys_newdata() return value indicates that the driver wishes to send MIDI events. The actual MIDI event is returned using pointer variables in the function parameter list. The return value is used to request another call to csys_midievent(), to transfer another MIDI event in the same k-cycle. csys_saslevent(...) Called if the csys_newdata() return value indicates that the driver wishes to send SASL events. The actual SASL event is returned using pointer variables in the function parameter list. The return value is used to request another call to csys_saslevent(), to transfer another SASL event in the same k-cycle. The csys_saslevent() function may also be used to send special events that perform functions not included in the SASL language. csys_shutdown(void) Called at the end of execution of the `sa.c` program, lets the control driver close files and devices. If the `-except` option is used during sfront invocation, csys_shutdown() will be called even if the `sa.c` program is ending its execution prematurely due to an error condition. In order to request MIDI and SASL events, the control driver needs to know details about the SAOL file, such as the names of instruments and variables. The next section of the control driver chapter describes the data structures and service functions that inform the SAOL program and the run-time environment. The final section of the control driver chapter describes the calling syntax and semantics for the five functions listed above. It also describes the registration process, by which the sfront program learns the characteristics of a new control driver. Next section: Part II/2B: Control Drivers Data Structures | ## Example `
    sfront -cin fstr -bitc t.mp4
           -aout linux -playback
    gcc -O3 sa.c -o sa
    ./sa

    Notes:

    [1] The control driver is
    specified by "-cin fstr"

    [2] We use -bitc instead of
    -bit to tell sfront to not
    compile in the SA_access_unit
    data into sa.c.

    [3] We use -aout linux -playback
    to tell sfront to send its audio
    directly to the soundcard, instead
    of its default behavior of writing
    an output.wav file.
` ## Functions in Control Drivers `
    /* called at program start */

    int csys_setup(void);

    /* called each k-cycle */

    int csys_newdata(void);

    /* called each kcycle that */
    /* csys_newdata() requests */

    int csys_saslevent( ... );
    int csys_midievent( ... );

    /* called at program end */

    void csys_shutdown(void);
`

Copyright 1999 John Lazzaro and John Wawrzynek.