windows-xp/Source/XPSP1/NT/multimedia/directx/dmusic/dmime/dmime.d

// autodoc's for stuff that's in the public header files
// @doc EXTERNAL
/*
@struct DMUS_PMSG | DMUS_PMSG structure. This is the base message for all
messages queued to the Performance. DMUS_PMSG's are created by calling
<om IDirectMusicPerformance.AllocPMsg>.
*/
typedef struct DMUS_PMSG
{
	void*			pvReserved;			// @field Reserved for use by the Performance. Do not modify. 
	DWORD			dwSize;				// @field Stores the full size of the message. Do not modify.
    REFERENCE_TIME	rtTime;				// @field The message time, in <t REFERENCE_TIME> format.
										// This field is considered valid only if the dwFlags
										// field has DMUS_PMSGF_REFTIME set.
    MUSIC_TIME		mtTime;				// @field The message time, in <t MUSIC_TIME> format.
										// This field is considered valid only if the dwFlags
										// field has DMUS_PMSGF_MUSICTIME set.
	DWORD			dwFlags;			// @field Various bits. See <t DMUS_PMSGF_FLAGS>.
    DWORD			dwPChannel;			// @field Performance Channel. The Performance can 
										// use this to determine the port/channel. 
    DWORD			dwVirtualTrackID;	// @field Virtual track ID. This identifies the exact
										// <i IDirectMusicTrack> that created this message. May
										// be 0 if this message was not created by a Track.
    IDirectMusicTool*		pTool;		// @field <i IDirectMusicTool> pointer. This is normally set
										// by calling <om IDirectMusicGraph.StampPMsg>.
	IDirectMusicGraph*		pGraph;		// @field <i IDirectMusicGraph> pointer. This is normally
										// set by calling <om IDirectMusicGraph.StampPMsg>.
	DWORD			dwType;				// @field message type. See <t DMUS_PMSGT_TYPES>.
	IUnknown*		punkUser;			// @field User com pointer, auto released upon a call
										// to <om IDirectMusicPerformance.FreePMsg>.
} DMUS_PMSG;
/*
@enum DMUS_PMSGF_FLAGS | <t DMUS_PMSGF_FLAGS> are used inside the dwFlags
member of the <t DMUS_PMSG>.
*/
typedef enum enumDMUS_PMSGF_FLAGS
{
    DMUS_PMSGF_REFTIME = 1,		// @emem Set if rtTime is valid.
    DMUS_PMSGF_MUSICTIME = 2,	// @emem Set if mtTime is valid.
    DMUS_PMSGF_TOOL_IMMEDIATE = 4,	// @emem Set if the message should execute right away, regardless of its time-stamp. See
								// <om IDirectMusicPerformance.SendPMsg>.
    DMUS_PMSGF_TOOL_QUEUE = 8,		// @emem Set if the message should execute just prior to its time-stamp. See
								// <om IDirectMusicPerformance.SendPMsg>.
    DMUS_PMSGF_TOOL_ATTIME = 16		// @emem Set if message should execute exactly at its time-stamp. See
								// <om IDirectMusicPerformance.SendPMsg>.
	DMUS_PMSGF_TOOL_FLUSH = 32		// @emem Set if the message is being flushed.
} DMUS_PMSGF_FLAGS;

// DMUS_PMSGT_TYPES defines 
// @enum DMUS_PMSGT_TYPES | <t DMUS_PMSGT_TYPES> are used inside the dwType
// member of the <t DMUS_PMSG>, and identify the type of message.
typedef enum enumDMUS_PMSGT_TYPES
{
	DMUS_PMSGT_MIDI =	0,		// @emem MIDI short message 
	DMUS_PMSGT_NOTE	=	1,		// @emem Interactive Music Note 
	DMUS_PMSGT_SYSEX =	2,		// @emem MIDI long message (system exclusive message)
	DMUS_PMSGT_NOTIFICATION	=	3,	// @emem Notification message 
	DMUS_PMSGT_TEMPO	=	4,		// @emem Tempo message 
	DMUS_PMSGT_CURVE = 5,		// @emem Control change / pitch bend, etc. curve 
	DMUS_PMSGT_TIMESIG =	6,		// @emem Time signature 
	DMUS_PMSGT_PATCH =		7,		// @emem Patch changes 
	DMUS_PMSGT_USER	=	255			// @emem User message 
} DMUS_PMSGT_TYPES;

/* The following flags are sent in the IDirectMusicTrack::Play() method */
/* inside the dwFlags parameter */
typedef enum enumDMUS_TRACKF_FLAGS
{
	DMUS_TRACKF_SEEK = 1,		/* set on a seek */
	DMUS_TRACKF_LOOP = 2,		/* set on a loop (repeat) */
	DMUS_TRACKF_START = 4,		/* set on first call to Play */
	DMUS_TRACKF_FLUSH = 8		/* set when this call is in response to a flush on the perfomance */
} DMUS_TRACKF_FLAGS;

/*
@struct DMUS_NOTE_PMSG | Based off of <t DMUS_PMSG>, the <t DMUS_NOTE_PMSG>
represents an interactive music note.
*/
typedef struct DMUS_NOTE_PMSG : DMUS_PMSG
{
	MUSIC_TIME	mtDuration;		// @field Duration
    WORD	wMusicValue;		// @field Description of note in chord and key.
	WORD	wMeasure;			// @field Measure in which this note occurs
	short	nOffset;			// @field Offset from grid at which this note occurs
	BYTE	bBeat;				// @field Beat (in measure) at which this note occurs
	BYTE	bGrid;				// @field Grid offset from beat at which this note occurs
	BYTE	bVelocity;			// @field Note velocity
    BYTE	bFlags;				// @field See <t DMNoteEventFlags>
    BYTE    bTimeRange;			// @field Range to randomize time.
    BYTE    bDurRange;			// @field Range to randomize duration.
    BYTE    bVelRange;			// @field Range to randomize velocity.
	BYTE	bInversionID;		// @field Identifies inversion group to which this note belongs
	BYTE	bPlayModeFlags;		// @field Play mode.
	BYTE	bMidiValue;			// @field The MIDI note value, converted from wMusicValue.
} DMUS_NOTE_PMSG;

/*
@enum DMUS_NOTEF_FLAGS | Used in the bFlags field of <t DMUS_NOTE_PMSG>.
Currently there is only one flag, DMUS_NOTEF_NOTEON. If it is set, the <t DMUS_NOTE_PMSG>
represents a MIDI Note On. If it is not set, it represents a MIDI Note Off. When
a <t DMUS_NOTE_PMSG> is first queued via <om IDirectMusicPerformance.SendPMsg>,
this flag should be set. The <t DMUS_NOTE_PMSG> will flow through the <i IDirectMusicGraph>
and any <i IDirectMusicTool>'s in the graph, until it reaches the final MIDI Output Tool.
The final MIDI Output Tool looks at the <t DMUS_NOTE_PMSG>'s bFlags field. When it sees
that DMUS_NOTEF_NOTEON is set, it sends a MIDI Note On message to the correct Port (according to
the <t DMUS_NOTE_PMSG>'s <t DMUS_PMSG>'s dwPChannel. It then clears the DMUS_NOTEF_NOTEON
flag, adds mtDuration to the mtTime, and requeues the message.
*/
typedef enum enumDMUS_NOTEF_FLAGS
{
	DMUS_NOTEF_NOTEON = 1,		// @emem Set if this is a MIDI Note On. Otherwise, it is MIDI Note Off.
} DMUS_NOTEF_FLAGS;

/*
@struct DMUS_MIDI_PMSG | Based off of <t DMUS_PMSG>, <t DMUS_MIDI_PMSG> performs a standard MIDI message.
*/
typedef struct DMUS_MIDI_PMSG : DMUS_PMSG
{
	BYTE	bStatus;	// @field Standard MIDI status byte.
	BYTE	bByte1;		// @field Standard MIDI message first byte field. Ignored for MIDI
						// messages that don't require it.
	BYTE	bByte2;		// @field Standard MIDI message second byte field. Ignored for MIDI
						// messages that don't require it.
	BYTE	bPad[1];
} DMUS_MIDI_PMSG;

/* DMUS_PATCH_PMSG */
typedef struct DMUS_PATCH_PMSG
{
	/* begin DMUS_PMSG_PART */
	DMUS_PMSG_PART
	/* end DMUS_PMSG_PART */

	BYTE					 byInstrument;
	BYTE					 byMSB;
	BYTE					 byLSB;
	BYTE					 byPad[1];
	DWORD					 dwGroup;
	DWORD					 dwMChannel;
} DMUS_PATCH_PMSG;

// DMUS_TEMPO_PMSG
/*
@struct DMUS_TEMPO_PMSG | Based off of <t DMUS_PMSG>, <t DMUS_TEMPO_PMSG> controls the performance's tempo.
*/
typedef struct DMUS_TEMPO_PMSG : DMUS_PMSG
{
	double	dblTempo;			// @field The tempo.
} DMUS_TEMPO_PMSG;

#define TEMPO_MAX	350
#define TEMPO_MIN	10
#define RELTEMPO_MAX	200
#define RELTEMPO_MIN	0

// DMUS_SYSEX_PMSG
/*
@struct DMUS_SYSEX_PMSG | Based off of <t DMUS_PMSG>, <t DMUS_SYSEX_PMSG> represents a System Exclusive message.
*/
typedef struct DMUS_SYSEX_PMSG : DMUS_PMSG
{
	DWORD	dwLen;	// @field Length of the data.
	BYTE*	abData;	// @field Array of data, with length equal to dwLen.
} DMUS_SYSEX_PMSG;

// DMUS_CURVE_PMSG
/*
@struct DMUS_CURVE_PMSG | Based off of <t DMUS_PMSG>, <t DMUS_CURVE_PMSG> represents a curve (e.g., a sequence of 
Continuous Controller messages.
*/
typedef struct DMUS_CURVE_PMSG : DMUS_PMSG
{
	MUSIC_TIME	mtDuration;			// @field How long this curve lasts.
	MUSIC_TIME	mtOriginalStart;	// @field Must be set to either zero when this message 
	                                // is created or to the original mtTime of the curve.
	short		nStartValue;		// @field The curve's start value.
	short		nEndValue;			// @field The curve's end value.
	short		nResetValue;		// @field The curve's reset value, sent after mtResetDuration or
									// upon a flush or invalidation.
	WORD		wMeasure;			// @field Measure in which this curve occurs.
	short		nOffset;			// @field Offset from grid at which this curve occurs.
	BYTE		bBeat;				// @field Beat (in measure) at which this curve occurs.
	BYTE		bGrid;				// @field Grid offset from beat at which this curve occurs.
    BYTE		bType;				// @field Type of curve.
	BYTE		bCurveShape;		// @field Shape of curve.
    BYTE		bCCData;			// @field CC# if this is a control change type.
	BYTE		bFlags;				// @field Set to 1 if the nResetValue must be sent when the 
									// time is reached or an invalidate occurs because
									// of a transition. If 0, the curve stays
									// permanently stuck at the new value. All other bits in this field are reserved.
} DMUS_CURVE_PMSG;

// DMUS_TIMESIG_PMSG
/*
@struct DMUS_TIMESIG_PMSG | Based off of <t DMUS_PMSG>, <t DMUS_TIMESIG_PMSG> represents a time signature.
*/
typedef struct DMUS_TIMESIG_PMSG : DMUS_PMSG
{
	// Time signatures define how many beats per measure, which note receives
	// the beat, and the grid resolution.
	BYTE	bBeatsPerMeasure;	// @field Beats per measure (top of the time signature).
	BYTE	bBeat;				// @field What note receives the beat (bottom of time 
								// signature).
								// We can assume that 0 means 256th note.
	WORD	wGridsPerBeat;		// @field Grids per beat.
} DMUS_TIMESIG_PMSG;

// DMUS_NOTIFICATION_PMSG
/*
@struct DMUS_NOTIFICATION_PMSG | Based off of <t DMUS_PMSG>, <t DMUS_NOTIFICATION_PMSG> represents a notification.
*/
typedef struct DMUS_NOTIFICATION_PMSG : DMUS_PMSG
{
	DWORD	dwNotifyType;		// @field Type of notification.
	DWORD	dwField1;			// @field Extra data specific to the type of notification.
	DWORD	dwField2;			// @field Extra data specific to the type of notification.
} DMUS_NOTIFICATION_PMSG;

/*
GUID_Global_Data | Global Data Guids
GUID_PerfRelTempo | Get/Set relative tempo on the <i IDirectMusicPerformance>.
Relative tempo spans all segments. Valid values range from 0 to 200, with 0 meaning
half-tempo, 100 meaning normal tempo, and 200 meaning double-tempo. The data type
associated with the global value is a DWORD.
GUID_PerfRelVolume | Get/Set relative volume on the <i IDirectMusicPerformance>.
Relative volume spans all segments.

<om IDirectMusicPerformance.GetGlobal>, <om IDirectMusicPerformance.SetGlobal>
*/

GUID_EnableTempo
GUID_DisableTempo

Send these GUID's to SetParam() and IsParamSupported() to disable sending and supporting
Tempo. Note that if a Track has received
GUID_DisableTempo, it will no longer return S_OK for GUID_DisableTempo or GUID_TempoTrack
from IsParamSupported(), but will return S_OK for GUID_EnableTempo. After reenabling, it
will return to its original state of supporting Tempos.

DMUS_E_TYPE_DISABLED will be returned from GetParam() and SetParam()
if the type is currently disabled.