RosegardenMapper.HOWTO -  Richard Bown, 12th July '97


Intoduction
-----------
This is a smallish HOWTO that'll hopefully give you a
few pointers on how to provide MIDI support for your
machine if Rosegarden does not currently support it.

This blurb probably won't be a lot of interest to you
unless your box isn't currently supported.  If it isn't
then if you have some time, expertise and are feeling
brave then you may want to develop yourself local support
on the skeleton API provided.  This is what this HOWTO 
is for.

Obligatory health Warning:

   Read this file before you decide whether you want to
   take on this task - it's not trivial unless you're
   already an expert on your machine's MIDI capabilities
   and can write C.

Ok where do we start?


What's this Mapper thing anyway?
--------------------------------

This Mapper library provides a common interface for
Rosegarden to talk to the MIDI IO stream on your
specific, local, friendly computer.  You may feel
that your box might not be so friendly if it isn't
supported. This HOWTO tells you generally how you
can add support to Rosegarden through extension of
the Mapper library.

If the src/ directory below the one which contains this
file has files in it with your system's type/name on
them then it's a fair bet that your system is supported
in one way or another.


What do I do if my box isn't supported?
---------------------------------------

If your box isn't supported as yet and you're feeling
brave then follow these handy hints for adding support
to the library.


Where do we start?
----------------------

With a little 'architecture'.

Three files currently comprise the Mapper library:

 Device.c - gives the application routines to create
            and control both device and track
            information.  Useful to allow Rosegarden
            to tell what is happening where during IO.

 Mapper.c (with system specific variants)

          - provides routines that wrap the MIDI IO
            functionality of various UNIX flavours.
            This will need all the work if it's not
            already supported.

 Timer.c  (with variants)
          - provides Timer routines for any low level
            timer you see fit to implement.  The Linux
            example is simple because we directly call
            the OSS API.  SGI/ZILOG examples show the
            messy (but perhaps more satisfying) approach.


These three files and compiled and linked to create
the Mapper library.  The sequencer compiles against
the generic Mapper.h file which itself can include a 
system specific Mapper file.  The sequencer is then
linked against the library to build the system specific
executable.


How well defined is the API?
----------------------------

The API responsibilties do blur a little occasionally.
This is mainly do to system constraits, time constraints
or mindless hackery but the API is defined for you to
follow if you want to make life easy for yourself.

Some stub files create a skeleton with which you can build
a new system specific verion of the Mapper for your box.
Theoretically the Sequencer code is "generic" (in practise
it isn't completely) and your Mapper additions will be
called in the place of other system's native calls.


What is an API anyway?
----------------------

Well it's an interface to a software module that
insulates another "layer" or part of application from
the internals of the module.  The outside world doesn't
care about what's happening inside, only the results.


How can I be sure my Mapper extension will work?
------------------------------------------------

You can't, however if you have programmed the Mapper
interface correctly then you'll be able to make noise
and record things and change devices and do all the
wonderful things that the sequencer allows you to do
currently supported platforms.

As I say though, or not.  It could very well be that
the sequencer will make _some_ noise but that it's
not _nice_ noise - this could be down to the architecture
of the Sequencer and the API.  Music is asynchronous
in it's syncroncity - in other words it's difficult to
know how to handle seemingly "random" events coming in
and out - different computers have many wild and wonderful
ways of performing MIDI I/O and managing devices.


So it's going to be difficult, how do I know if I can do it?
------------------------------------------------------------

Only take this task on if:

 a) you know what you're doing with C and you have a clue about
    how your machine performs MIDI I/O and device management.

 b) you aren't going to need a lot of hand holding (we're
    available for the occasional question, sure)

 c) you don't mind Chris complaining about your code.
    (only joking, Chris)


So, how where do I start?
-------------------------

By following the API layed down in Timer_STUB.c and
Mapper_STUB.c you can build your own low level support
for your local system.

You'll need to add your new system type to the umbrella
files Timer.c and Mapper.c as well as changing a definition
in the top level Makefile (*).  This will allow you to build
your new library (make Mapper).  If this is successful
then you can try and re-link the Sequencer with the new
library.  According to the sophistication of the system
that you're supporting you may want some extra bits and
bobs in the Sequencer proper.  You may notice that some
GUI changes are made by using the same system definitions
that you used to make the library (i.e SYSTEM_LINUX).
You may use this method to alter Sequencer functionality
but *please* don't alter it for the sake of it with this
method - it's ugly enough already in places.

(* - the GNU configure stuff doesn't make life as simple
     anymore - you'll have to change rosegarden/configure
     to fit your system - well either that or hack 
     together a Makefile for testing)

The header file Mapper.h provides the prototypes for the
Mapper library.  This file itself includes system specific
includes.  If you need other than the supplied GENERIC
and OSS definitions then work this in yourself.


So what do I do if I get something working?
------------------------------------------

Send it in.  Send it in if by working you mean with the
configure stuff in and that the sequencer and editor have
full "normal" functionality.  Of course if your box isn't
supported then you're working a little in the dark.

Anyway, if you're willing to share it then send us the code
and we'll stick it in the next release of the distribution.
You won't get any money, but you'll earn the heartiest thanks
of possibly tens of people, a warm and satisfied glow for the
rest of the week and also make us change the web site again
to add another machine to list of those supported.

Good luck.

