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.
Page 1
mdSetDivision(3dm)mdSetDivision(3dm)
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 ALSOmdSetStampMode(3dm)
Page 2
