\documentclass[a4paper,12pt,oneside]{book}

\author{Petteri Kangaslampi}
\title{MIDAS Sound System\\ \ \\ Programmer's Guide}

\setlength{\parindent}{0pt}
\setlength{\parskip}{10pt plus 2pt minus 1pt}


\begin{document}

\maketitle
\pagenumbering{roman}
\tableofcontents

\newpage
\pagenumbering{arabic}
\chapter{Introduction}

\section{Welcome}

Welcome to the exciting world of digital audio! MIDAS Sound System is the
most comprehensive cross-platform digital audio system today. With features
such as an unlimited number of digital channels on all supported platforms,
simultaneous sample, module and stream playback, and seamless portability
across operating systems, MIDAS is all you need for perfect sound in your
application.

This manual is the Programmer's Guide to the MIDAS Sound System. It includes
descriptions about all aspects of MIDAS, including initialization,
configuration and usage of different system components. It does not attempt
to document all features in all modules, but rather give a good overview on
how you can use MIDAS in your own programs. For complete descriptions of all
functions and data structures available in MIDAS, see {\em MIDAS Sound
System, Programmer's Reference}.


\section{What is MIDAS?}

What is MIDAS Sound System anyway?

MIDAS is a multichannel digital music and sound engine. It provides you with
an unlimited number of channels of digital audio, that you can use to play
music, sound effects, speech or sound streams. {\em [TODO]}


\section{Quick start}

Although MIDAS is a very powerful sound engine, it is also extremely
easy to use. This section gives a quick look at how MIDAS works, and how to
use it to add sound to your own programs. Having a working program to
experiment with will also help in the following chapters.


\subsection{Minimal module player}

A minimal module player program written using MIDAS Sound System is only a
few lines of C code:

\begin{verbatim}
#include <stdio.h>
#include "midas.h"

int main(void)
{
    gmpModule   *module;
    int         error;

    midasSetDefaults();
    midasInit();
    MIDASCALL(gmpLoadXM("module.xm", 1, NULL, &module))
    midasPlayModule(module);
    printf("Playing, press any key to quit!\n");
    getch();
    midasStopModule(module);
    MIDASCALL(gmpFreeModule(module))
    midasClose();

    return 0;
}
\end{verbatim}


\chapter{The system}

To maximise portability and ease of maintenance, MIDAS has been designed
as a very modular system. This chapter describes all MIDAS Sound System
modules.


\section{Overview of system architechture}

We need a fancy picture here.


\section{Description of all modules}

\subsection{Sound Devices}

Sound Devices are at the very heart of MIDAS. They provide the basic
functionality for playing audio, they manage the samples loaded in the
system, and provide a common programming interface for all supported sound
hardware.


\subsection{Generic Module Player}

Generic Module Player, or GMPlayer for short, takes care of all module
playing in MIDAS. Modules in different formats are converted to GMPlayer
internal {\em gmpModule}[TODO:link] structure format when loaded to memory,
so that a single module player can handle all formats. To maintain best
possible compatibility with all trackers, however, GMPlayer implements some
commands and features differently depending on the original module format.
This ensures that playback quality is not compromised.

GMPlayer is not limited for playing a single module only, in fact it can be
used to play an unlimited number of songs simultaneously. This way sound
effects can be composed as small song fragments, to eliminate the need for
long samples.


\subsection{MIDAS kernel}

The MIDAS "kernel" consists of smaller modules used by all system components.
This includes [TODO:links] memory management functions, error handling
routines, and common utility functions.


\section{Naming conventions}

[TODO: rewrite, will change in rel 1.0]


\section{Calling conventions}

All MIDAS Sound System functions, with the exception of the Simplified MIDAS
API [TODO:FIX!], use the same calling conventions and a similar method for
returning data. This simplifies programming, as all functions behave
consistently, and ensures that error codes get handled properly.

\subsection{Error codes}

All functions in MIDAS Sound System return an error code. There is no
exception to this, and all other data is returned using pointers (see below).
This simplifies error handling, and makes sure error codes always get handled
properly. In addition, when MIDAS is compiled with DEBUG mode on, the error
handling functions can supply detailed information about the errors that
happened, such as which function originally caused the error and what
functions called it.

\subsection{Returning data}

As the return value of the function is always reserved for the error code,
all other data will need to be returned by using pointers. All MIDAS
functions that return data will accept as their last arguments pointers to
the variables that will hold the return values. Make sure you {\bf always}
pass these functions legal pointers as the return variables even if you don't
need the return values --- memory corruption may occur otherwise.

For example, to query the current volume on channel 3 in the default Sound
Device, you can use:

\begin{verbatim}
unsigned vol;
...
midasSD->GetVolume(3, &vol);
...
\end{verbatim}

Note that in a real-life program you also need to handle the returned error
code.

[TODO:OS-Specific] {\bf MS-DOS Note!} Code using MIDAS needs to have the
compiler ''SS==DS'' -assumption disabled. This is because the stack used by
the timer interrupt (and thus most of MIDAS code plus any user callbacks)
might be different from the main program stack, and the compiler should
therefore not generate code that uses data segment variables via the stack
segment. Because of this, any pointers that you pass to MIDAS functions need
to point to data segment variables --- in other words, in the example above,
\begin{verbatim}
unsigned vol;
\end{verbatim}
needs to be changed to
\begin{verbatim}
static unsigned vol;
\end{verbatim}
to ensure the local variable gets placed in data segment. Pointers to global
variables can naturally be used without any modifications.


\section{Error handling}

The section above already gave a brief introduction to MIDAS error handling,
but this section will describe it in detail.


\chapter{[TODO]}

\subsection{Available Sound Devices}

Currently the following Sound Devices are available:

\begin{itemize}
\item{MS-DOS:}
        \begin{description}
        \item [SB] Creative Labs Sound Blaster regular, pro and 16
        \item [GUS] Gravis UltraSound regular, MAX and PnP
        \item [PAS] Media Vision Pro Audio Spectrum regular, Plus and 16
        \item [WSS] Microsoft Windows Sound System and compatibles
        \item [nosound] No Sound
        \end{description}
\item{Windows NT:}
        \begin{description}
        \item [WinWave] Windows low-level wave output
        \end{description}
\item{Linux:}
        \begin{description}
        \item [USS] Unix Sound System (former Voxware)
        \end{description}
\end{itemize}


\end{document}