mdSetStampMode(3dm)mdSetStampMode(3dm)NAME
mdGetStampMode, mdSetStampMode - control time stamping for an MDport
SYNOPSIS
#include <dmedia/midi.h>
int mdSetStampMode(MDport port, int mode)
int mdGetStampMode(MDport port)
DESCRIPTION
mdSetStampMode controls the interpretation of the stamp field in an
MDevent by the port. The available interpretation modes are MD_NOSTAMP,
MD_DELTASTAMP, MD_RELATIVESTAMP, MD_RELATIVETICKS and MD_DELTATICKS.
If an output port is in MD_NOSTAMP mode, the interface will ignore the
stamp and transmit the event immediately. On input, events are stamped
with the UST (unadjusted system time) corresponding to the arrival time
of the final byte in the message.
In MD_DELTASTAMP mode, the stamp contains the number of nanoseconds
between the event and its predecessor. If the stamp is 0, the two events
are logically coincident in time. On output, if the stamp is non-zero,
the event will be transmitted the specified number of nanoseconds after
the preceeding event.
In MD_RELATIVESTAMP mode, stamps are relative to the port's origin time
(see mdSetStartPoint(3dm)). A time stamp of 0 indicates that the event
was received or transmitted at the origin UST. If an event with a stamp
of n is sent to an interface in this mode, the driver will transmit the
event n nanoseconds after the origin time. If the application falls
behind and transmits events whose stamps indicate that the event should
have been sent sometime in the past, the event will be transmitted
immediately. If an event with a stamp of n is received, then the last
byte of the event arrived n nanoseconds after the origin time.
MD_RELATIVETICKS and MD_DELTATICKS set the MDport into a mode that allows
the use of ticks instead of real time to control the timing of MIDI
events. Ticks are defined in terms compatible with Standard MIDI files;
at any given point, the duration of a tick is equal to the number of
microseconds per quarter note (as set by mdSetTempo or a tempo event)
multiplied by the current tempo scaling value (set with mdSetTemposcale)
and divided by the current number of divisions (set with mdSetDivision).
The advantage of this mode is that the duration of each beat can be
changed (either synchronously with a tempo event or asynchronously with
mdSetTempoScale) without altering the stamps on the events.
MD_RELATIVETICKS allows the ticks to be reckoned from an origin tick that
is set with mdSetStartPoint(3A). MD_DELTATICKS uses simple delta ticks,
where the stamp's value indicates how many ticks fall between this event
and the time at which its predecessor was transmitted.
Page 1
mdSetStampMode(3dm)mdSetStampMode(3dm)DIAGNOSTICS
An application should set the stamping mode immediately after a port is
opened. Once set, the stamping mode should not be changed again.
RETURN VALUEmdGetStampMode returns the current stamp mode for the port.
mdSetStampMode returns 0 on success and -1 on error. The following error
codes are expected:
EINVAL - An undefined stamp mode was specified.
SEE ALSOmdSetTempo(3dm), mdSetTemposcale(3dm), mdSetDivision(3dm)
Page 2
