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.


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 VALUE
     mdGetStampMode 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 ALSO
     mdSetTempo(3dm), mdSetTemposcale(3dm), mdSetDivision(3dm)


                                                                        Page 2