mdSetDivision(3dm)                                          mdSetDivision(3dm)


NAME
     mdSetDivision, mdSetTempo, mdSetTempoScale, mdGetDivision, mdGetTempo,
     mdTickstoNanos, mdNanosToTicks - set tempo and division for a port

SYNOPSIS
     #include <dmedia/midi.h>

     int mdSetDivision(MDport port, int div)
     int mdSetTempo(MDport port, int tempo)
     int mdGetDivision(MDport port)
     int mdGetTempo(MDport port)
     int mdSetTemposcale(MDport port, double scale)
     long long mdTicksToNanos(MDport, unsigned long long)
     long long mdNanosToTicks(MDport, unsigned long long)


DESCRIPTION
     mdSetDivision and mdSetTempo specify the conversion from MIDI clock ticks
     to real time values for the MDport.  These functions are only applicable
     when a port is in one of the tick modes (MD_RELATIVETICK or
     MD_DELTATICK); they should not be called with ports in the other stamping
     modes.

     The following equation expresses relation of tempo, division, temposcale,
     and tick duration:

                                      tempo (usecs/beat)
     tick duration (usecs/tick)  = ----------------------------------
                                    division (ticks/beat) * temposcale

     mdSetTempo sets the tempo in terms of microseconds per beat, the same as
     in Standard MIDI Files.  Tempo may also be set by sending a SET TEMPO
     meta event to an MDport.  Tempo meta events are encoded by placing a 0xFF
     in the msg[0] byte of a MDevent structure, setting the msglen field to 6,
     and making the sysexmsg field point to a block of memory containing the
     following six bytes:

     sysexmsg[0]  = 0xff
     sysexmsg[1] = 0x51
     sysexmsg[2] = 0x3
     sysexmsg[3] = xx
     sysexmsg[4] = yy
     sysexmsg[5] = zz

     where xx, yy, and zz encode a  24-bit number representing microseconds
     per quarter note.  The tempo is equal to (xx << 16) + (yy << 8) + zz.

     mdSetDivision sets number of ticks into which a beat is divided.
     Divisions are sometimes referred to as pulses per quarter note and
     correspond to the division field in the MIDI file header chunk.  The
     number of ticks per beat is indicated by the div argument.


     mdSetTempo and mdSetDivision are irrelevant  if the port is not in one of
     the tick stamping modes (either MD_RELATIVETICK or MD_DELTATICK) and
     should not be called.

     mdGetTempo and mdGetDivision return the current tempo and division for
     the port.

     mdSetTemposcale and mdGetTemposcale set and return a tempo scale value
     for the port.  mdSetTempoScale changes the tempo of a port asychronously,
     and is commonly used for real-time tempo adjustments.   All tick mode
     time stamps written to the port will be divided by this scale before
     being queued for output, so that scale values greater than 1.0 will
     result in a faster playback rate, while values less than 1.0 will result
     is a slower playback rate.

     mdTicksToNanos and mdNanosToTicks allow conversion between ticks and
     nanoseconds using the current tempo on the port.  These routines do not
     take into account previous tempo or tempo scale changes.  In order to
     accurately convert a tick value to an absolute time (or vice-versa), an
     application must maintain a list of all tempo changes in a MIDI stream.

RETURN VALUE
     mdSetDivision and mdSetTempo return 0 on success and -1 on error.
     mdGetDivision and mdGetTempo return the appropriate value or -1 on error.
     The following error codes are expected:

     ENXIO    - Invalid port

     EINVAL   - An undefined operation was called.

BUGS
     mdGetTempo returns the last tempo set, which is not necessarily the tempo
     currently being used.  In particular, if a MIDI tempo meta event is sent
     to the port, mdGetTempo won't report the tempo change made by the meta
     event.

SEE ALSO
     mdSetStampMode(3dm)


                                                                        Page 2