Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/066.lha/MidiDev/func.doc

Text File | 1986-11-20 | 19.3 KB | 672 lines

TABLE OF CONTENTS

midi.library/CreateMDest
midi.library/CreateMRoute
midi.library/CreateMSource
midi.library/DeleteMDest
midi.library/DeleteMRoute
midi.library/DeleteMSource
midi.library/FindMDest
midi.library/FindMSource
midi.library/FreeMidiMsg
midi.library/GetMidiMsg
midi.library/LockMidiBase
midi.library/MidiMsgLength
midi.library/MidiMsgType
midi.library/ModifyMRoute
midi.library/MRouteDest
midi.library/MRoutePublic
midi.library/MRouteSource
midi.library/PutMidiMsg
midi.library/PutMidiStream
midi.library/UnlockMidiBase
midi.library/CreateMDest

NAME
     CreateMDest -- Create a MIDI destination node

SYNOPSIS
     dest = CreateMDest (name,image)
     d0                  a0   a1
     struct MDest *dest;
     char *name;
     struct Image *image;

FUNCTION
     Creates a new MIDI destination node.  A MsgPort is created and
     linked into the new MDest that will signal you when this MDest gets
     a message (see msg routines for more info).  If a name is given,
     this node will be placed in the library's public destination list
     (so it can be located with FindMDest()).  If name is NULL a private
     node is created.  The image supplied can be used by graphics-based
     patch bay applications and will only be used for public nodes.
     image may be NULL if no image is to be supplied.  You are
     responsible for deleting any nodes you create when you are done with
     them.

INPUTS
     name - pointer to a null-terminated string or NULL
     image - pointer to an Intuition Image structure or NULL

RESULTS
     dest - pointer to the new MDest node or NULL on failure.

SEE ALSO
     DeleteMDest, FindMDest

midi.library/CreateMRoute

NAME
     CreateMRoute -- Create an MRoute

SYNOPSIS
     route = CreateMRoute (source,dest,routeinfo)
     d0                    a0     a1   a2
     struct MRoute *route;
     struct MSource *source;
     struct MDest *dest;
     struct MRouteInfo *routeinfo;

FUNCTION
     Creates and links a new MRoute into a MIDI Source node and a MIDI
     Dest node.  This routine assumes that both source and dest are
     private nodes that you created.  To route to public nodes use one of
     the other MRoute creation routines.  The MRouteInfo structure
     defines the new connection.  You need not preserve the MRouteInfo
     structure after calling this routine since it is copied into the
     newly created MRoute structure.  You are responsible for deleting
     any MRoute's you create.

INPUT
     source - pointer to an MSource node
     dest - pointer to an MDest node
     routeinfo - pointer to an MRouteInfo structure defining this MRoute

RESULTS
     route - a pointer to a new MRoute structure or NULL on failure.

SEE ALSO
     MRouteSource, MRouteDest, MRoutePublic, ModifyMRoute, DeleteMRoute

midi.library/CreateMSource

NAME
     CreateMSource -- Create a MIDI source node

SYNOPSIS
     source = CreateMSource (name,image)
     d0                      a0   a1
     struct MSource *source;
     char *name;
     struct Image *image;

FUNCTION
     Creates a new MIDI source node.  If a name is given, this node will
     be placed in the library's public source list (so it can be located
     with FindMSource()).  If name is NULL a private node is created.
     The image supplied can be used by graphics-based patch bay
     applications and will only be used for public nodes.  image may be
     NULL if no image is to be supplied.  You are responsible for
     deleting any nodes you create when you are done with them.

INPUTS
     name - pointer to a null-terminated string or NULL
     image - pointer to an Intuition Image structure or NULL

RESULTS
     source - pointer to the new MSource node or NULL on failure.

SEE ALSO
     DeleteMSource, FindMSource

midi.library/DeleteMDest

NAME
     DeleteMDest -- Delete a MIDI destination node

SYNOPSIS
     DeleteMDest (dest)
                  a0
     struct MDest *dest;

FUNCTION
     Removes and frees an MDest created by CreateMDest().  Any MRoute's
     connected to this MDest will be unlinked.  Any messages waiting at
     this MDest will be freed.  You should only delete nodes that you
     created.

INPUTS
     dest - pointer to the MDest node to delete

RESULTS
     none

SEE ALSO
     CreateMDest, FindMDest

midi.library/DeleteMRoute

NAME
     DeleteMRoute -- Delete an MRoute

SYNOPSIS
     DeleteMRoute (route)
                   a0
     struct MRoute *route;

FUNCTION
     Unlinks and frees a route previously created with one of the routing
     functions.  You should only delete routes that you created.  You
     will still need to do this even if both the source and dest have
     been deleted in order to free up the memory allocated to the route.

INPUTS
     route - pointer to the MRoute to delete

RESULTS
     none

SEE ALSO
     CreateMRoute, MRouteSource, MRouteDest, MRoutePublic, ModifyMRoute

midi.library/DeleteMSource

NAME
     DeleteMSource -- Delete a MIDI source node

SYNOPSIS
     DeleteMSource (source)
                    a0
     struct MSource *source;

FUNCTION
     Removes and frees an MSource created by CreateMSource().  Any
     MRoute's connected to this MSource will be unlinked.  You should
     only delete nodes that you created.

INPUTS
     source - pointer to the MSource node to delete

RESULTS
     none

SEE ALSO
     CreateMSource, FindMSource

midi.library/FindMDest

NAME
     FindMDest -- Find a public MIDI destination node

SYNOPSIS
     dest = FindMDest (name)
     d0                a0
     struct MDest *dest;
     char *name;

FUNCTION
     Finds a public MIDI destination node by name if it exists.  In order
     to ensure that this node remains valid you should call
     LockMidiBase() prior to calling this routine.

INPUTS
     name - pointer to the null-terminated name to find

RESULTS
     dest - pointer to the requested MDest node or NULL if not found.

SEE ALSO
     CreateMDest, DeleteMDest, LockMidiBase, UnlockMidiBase

midi.library/FindMSource

NAME
     FindMSource -- Find a public MIDI source node

SYNOPSIS
     source = FindMSource (name)
     d0                    a0
     struct MSource *source;
     char *name;

FUNCTION
     Finds a public MIDI source node by name if it exists.  In order to
     ensure that this node remains valid you should call LockMidiBase()
     prior to calling this routine.

INPUTS
     name - pointer to the null-terminated name to find

RESULTS
     source - pointer to the requested MSource node or NULL if not found.

SEE ALSO
     CreateMSource, DeleteMSource, LockMidiBase, UnlockMidiBase

midi.library/FreeMidiMsg

NAME
     FreeMidiMsg -- Free a MIDI message returned by GetMidiMsg

SYNOPSIS
     FreeMidiMsg (msg)
                  a0
     UBYTE *msg;

FUNCTION
     Frees a message returned by GetMidiMsg().

INPUTS
     msg - pointer to a UBYTE array containing one MIDI message

RESULTS
     none

SEE ALSO
     GetMidiMsg()

midi.library/GetMidiMsg

NAME
     GetMidiMsg -- Get the next MIDI message from an MDest

SYNOPSIS
     msg = GetMidiMsg (dest)
     d0                a0
     UBYTE *msg;
     struct MDest *dest;

FUNCTION
     Returns the next message received at a MIDI destination or NULL if
     no more messages are present.  This is the preferred method of
     receiving MIDI messages from an MDest since it strips off and frees
     the packet that carried this message to the MDest's MsgPort
     (dest->DestPort).  This routine will not wait around for the next
     message since you might want to do something else between messages.
     If you want to wait, just Wait for the signal allocated to the
     MDest's MsgPort:

          Wait (1L << dest->DestPort->mp_SigBit);

     Once you have dealt with the messages you have received you should
     dispose of them by calling FreeMidiMsg().  Unlike Intuition,
     midi.library is not halted until you free these messages so you can
     hang on to them as long as you like.  Just free them when you are
     done with them.

     Be aware that the more messages you keep without freeing the more
     fragmented the Amiga's memory will become.  If you plan to keep a
     large number of messages you are probably better off allocating a
     buffer and copying the messages to it.

INPUTS
     dest - pointer to the MDest node to receive from

RESULTS
     msg - pointer to a UBYTE array containing one MIDI message or NULL
             if there are no more messages at this MDest

SEE ALSO
     FreeMidiMsg, MidiMsgType, MidiMsgLength, PutMidiMsg

midi.library/LockMidiBase

NAME
     LockMidiBase -- lock the lists in the library base

SYNOPSIS
     LockMidiBase()

FUNCTION
     Gains exclusive access to the Source and Dest lists in the library
     base.  This will block any other tasks attempts to Create, Delete,
     or Find MSource and MDest nodes.  Use this if you wish to examine a
     public node.  The route linkages within the nodes are not protected
     by this.  Currently you need to Forbid() to prevent them from
     changing.

     Calls to LockMidiBase() may be nested, but each call must be matched
     with a call to UnlockMidiBase().

INPUTS
     none

RESULTS
     none

SEE ALSO
     UnlockMidiBase

midi.library/MidiMsgLength

NAME
     MidiMsgLength -- Determine the length of a MIDI message

SYNOPSIS
     length = MidiMsgLength(msg)
     d0                     a0
     ULONG length;
     UBYTE *msg;

FUNCTION
     Returns the length in bytes of a MIDI message.  The message length
     includes the status byte.  For system exclusive messages the EOX
     status byte at the end is also included.

INPUTS
     msg - pointer to a UBYTE array containing one MIDI message

RESULTS
     length - length of the message in bytes.  For valid messages this
                will be at least 1.  0 is returned for invalid messages.

SEE ALSO
     MidiMsgType

midi.library/MidiMsgType

NAME
     MidiMsgType -- Determine the type of a MIDI message

SYNOPSIS
     type = MidiMsgType(msg)
     d0                 a0
     UWORD type;
     UBYTE *msg;

FUNCTION
     Returns the type a MIDI message.  The flags are defined in
     midi/midi.h (or midi/midi.i) and are the same ones used in
     MRouteInfo.MsgFlags.  Other than the obvious, some special message
     handling takes place:

          Controller changes for ctrl # 122 - 127 return MMF_MODE.

          Note On messages with velocity == 0 return MMF_NOTEOFF.

          EOX and all invalid messages return 0 (an EOX by itself is not
          considered a valid message)

INPUTS
     msg - pointer to a UBYTE array containing one MIDI message

RESULTS
     type - message type

SEE ALSO
     MidiMsgLength

midi.library/ModifyMRoute

NAME
     ModifyMRoute -- Modify an existing an MRoute

SYNOPSIS
     ModifyMRoute (route,newrouteinfo)
                   a0    a1
     struct MRoute *route;
     struct MRouteInfo *newrouteinfo;

FUNCTION
     Modifies the MRouteInfo structure in an existing route.  Any
     messages already delivered to this MRoute's MDest, whether received
     or not, are not affected.  As with CreateMRoute, the supplied
     MRouteInfo structure need not be kept after calling this routine:
     it is merely a template that is copied to the MRoute.

INPUT
     route - pointer to an MRoute to modify
     routeinfo - pointer to the new MRouteInfo for this MRoute

RESULTS
     none

SEE ALSO
     CreateMRoute, MRouteSource, MRouteDest, MRoutePublic, DeleteMRoute

midi.library/MRouteDest

NAME
     MRouteDest -- Create an MRoute from a public MSource to a private
     MDest

SYNOPSIS
     route = MRouteDest (sourcename,dest,routeinfo)
     d0                  a0         a1   a2
     struct MRoute *route;
     char *sourcename;
     struct MDest *dest;
     struct MRouteInfo *routeinfo;

FUNCTION
     Routes an MDest to a public MSource.  This is shorthand for:

          LockMidiBase();
          if (source = FindMSource(sourcename))
               route = CreateMRoute(source,dest,routeinfo);
          UnlockMidiBase();

INPUT
     sourcename - pointer to null-terminated name of a public MSource
     dest - pointer to an MDest node
     routeinfo - pointer to an MRouteInfo structure defining this MRoute

RESULTS
     route - a pointer to a new MRoute structure or NULL on failure.

SEE ALSO
     CreateMRoute, MRouteSource, MRoutePublic, ModifyMRoute, DeleteMRoute

midi.library/MRoutePublic

NAME
     MRoutePublic -- Create an MRoute from a public MSource to a public
MDest

SYNOPSIS
     route = MRoutePublic (sourcename,destname,routeinfo)
     d0                    a0         a1       a2
     struct MRoute *route;
     char *sourcename;
     char *destname;
     struct MRouteInfo *routeinfo;

FUNCTION
     Routes a public MSource to a public MDest.  This is shorthand for:

          LockMidiBase();
          if ( (source = FindMSource(sourcename) &&
               (dest = FindMDest(destname)) )
               route = CreateMRoute(source,dest,routeinfo);
          UnlockMidiBase();

INPUT
     sourcename - pointer to null-terminated name of a public MSource
     destname - pointer to null-terminated name of a public MDest
     routeinfo - pointer to an MRouteInfo structure defining this MRoute

RESULTS
     route - a pointer to a new MRoute structure or NULL on failure.

SEE ALSO
     CreateMRoute, MRouteSource, MRouteDest, ModifyMRoute, DeleteMRoute

midi.library/MRouteSource

NAME
     MRouteSource -- Create an MRoute from a private MSource to a public
     MDest

SYNOPSIS
     route = MRouteSource (source,destname,routeinfo)
     d0                    a0     a1       a2
     struct MRoute *route;
     struct MSource *source;
     char *destname;
     struct MRouteInfo *routeinfo;

FUNCTION
     Routes an MSource to a public MDest.  This is shorthand for:

          LockMidiBase();
          if (dest = FindMDest(destname))
               route = CreateMRoute(source,dest,routeinfo);
          UnlockMidiBase();

INPUT
     source - pointer to an MSource node
     destname - pointer to null-terminated name of a public MDest
     routeinfo - pointer to an MRouteInfo structure defining this MRoute

RESULTS
     route - a pointer to a new MRoute structure or NULL on failure.

SEE ALSO
     CreateMRoute, MRouteDest, MRoutePublic, ModifyMRoute, DeleteMRoute

midi.library/PutMidiMsg

NAME
     PutMidiMsg -- Place a MIDI message at an MSource

SYNOPSIS
     PutMidiMsg (source,msg)
                 a0     a1
     struct MSource *source;
     UBYTE *msg;

FUNCTION
     Sends a MIDI message off to an MSource to be distributed to any
     MDest's that are routed to this source.  Once sent the message
     buffer can be recycled since copies are made of it as necessary.
     This routine assumes that it is getting a valid message.  If you
     wish to send data that is not necessarily valid (and don't wish to
     process it yourself) or your message buffer contains more than one
     message you should consider using PutMidiStream() instead.

INPUTS
     source - pointer to the MSource node to place the message at
     msg - pointer to a UBYTE array containing one MIDI message

RESULTS
     none

SEE ALSO
     PutMidiStream, MidiMsgLength, MidiMsgType, GetMidiMsg

midi.library/PutMidiStream

NAME
     PutMidiStream -- Send an unformatted stream

SYNOPSIS
     PutMidiStream (source,fillbuffer,buf,bufsize,cursize)
                    a0     a1         a2  d0      d1
     struct MSource *source;
     ULONG (*fillbuffer)();
     UBYTE *buf;
     ULONG bufsize,cursize;

FUNCTION
     Converts an unformatted stream into MIDI messages and calls
     PutMidiMsg() to the specified MSource for each one.

     The user supplied fillbuffer routine is called to place data in the
     user supplied buffer.  It can be written in C, assembly or whatever
     as long as it abides by the rules:

          On entry the following registers will be set:

               A0 - points to the user supplied buffer
               D0 - indicates the size of user supplied buffer
               (these are the same values the user supplied in the
               function call)

          On return D0 should be set to the number of bytes placed in the
          buffer.  A value of 0 indicates the end of the stream has been
          reached and that PutMidiStream() should return.

          Any registers that the PutMidiStream() needs are preserved
          before calling the user's fillbuffer routine so fillbuffer need
          not preserve any registers.

     In C the routine should be declared something like:

          long fillbuffer()
          {
               long len;

               geta4();            /* necessary for aztec C small data */
                 .
                 .                 /* whatever it takes to fill up */
                 .                 /* buffer and set len */
                 .
               return len;         /* sets D0 accordingly */
          }

     There are two basic ways of using calling PutMidiStream:

     1.  The stream length is unknown or just simply too large to put
         into a single buffer (like transferring from a file to an
         MSource).

          Assuming that the buffer is initially empty you would use a
          call similar to:

          PutMidiStream (source,fillmybuf,mybuf,(long)sizeof mybuf,0L);

          fillmybuf() will be called immediately to put some data into
          the buffer (mybuf).  Processing will continue until fillmybuf()
          indicates that it's time to quit by returning a 0.

     2.  The stream length is known and it is small enough to place in
         the buffer.

          PutMidiStream (source,NULL,mybuf,(long)sizeof mybuf,
                                           (long)sizeof mybuf);

          The NULL fillbuffer routine indicates that the buffer contains
          all it's ever going to.  The current size is set to the size of
          the buffer to indicate that the buffer is full of data to be
          processed.  Once the buffer is exhausted, PutMidiStream will
          return.

INPUTS
     source - pointer to the MSource to send messages to
     fillbuffer - user supplied routine to fill the user supplied buffer
                    can be NULL if no buffer filling is to be done
     buf - user supplied buffer
     bufsize - size of user supplied buffer
     cursize - amount of data currently in the buffer upon entry to this
                 function.  If non-zero this data will be processed before
                 trying to call (*fillbuffer)()

RESULTS
     none

SEE ALSO
     PutMidiMsg

midi.library/UnlockMidiBase

NAME
     UnlockMidiBase -- unlock the lists in the library base

SYNOPSIS
     UnlockMidiBase()

FUNCTION
     Releases exclusive access to the Source and Dest lists in the
     library base.  Each call to this must be matched with a call to
     LockMidiBase().

INPUTS
     none

RESULTS
     none

SEE ALSO
     LockMidiBase