MidiDriver_Multisource Class Reference

#include <mididrv_ms.h>

Inheritance diagram for MidiDriver_Multisource:

Classes
struct	ControllerDefaults
struct	MidiSource

Public Types
enum	SourceType { SOURCE_TYPE_UNDEFINED, SOURCE_TYPE_MUSIC, SOURCE_TYPE_SFX }
enum	FadeAbortType { FADE_ABORT_TYPE_END_VOLUME, FADE_ABORT_TYPE_CURRENT_VOLUME, FADE_ABORT_TYPE_START_VOLUME }
enum	ControllerDefaultType {   CONTROLLER_DEFAULT_PROGRAM, CONTROLLER_DEFAULT_INSTRUMENT_BANK, CONTROLLER_DEFAULT_DRUMKIT, CONTROLLER_DEFAULT_CHANNEL_PRESSURE,   CONTROLLER_DEFAULT_PITCH_BEND, CONTROLLER_DEFAULT_MODULATION, CONTROLLER_DEFAULT_VOLUME, CONTROLLER_DEFAULT_PANNING,   CONTROLLER_DEFAULT_EXPRESSION, CONTROLLER_DEFAULT_SUSTAIN, CONTROLLER_DEFAULT_RPN, CONTROLLER_DEFAULT_PITCH_BEND_SENSITIVITY }
Public Types inherited from MidiDriver
enum	DeviceStringType { kDriverName, kDriverId, kDeviceName, kDeviceId }
enum	{ MERR_CANNOT_CONNECT = 1, MERR_DEVICE_NOT_AVAILABLE = 3, MERR_ALREADY_OPEN = 4 }
enum	{   PROP_OLD_ADLIB = 2, PROP_CHANNEL_MASK = 3, PROP_SCUMM_OPL3 = 4, PROP_USER_VOLUME_SCALING = 5,   PROP_MIDI_DATA_REVERSE_PANNING = 6, PROP_OPL_ACCURACY_MODE = 7, PROP_OPL_CHANNEL_ALLOCATION_MODE = 8, PROP_MILES_VERSION = 9,   PROP_OPL_RHYTHM_MODE_IGNORE_NOTE_OFF = 10 }
typedef uint32	DeviceHandle

Public Member Functions
void	send (uint32 b) override
void	send (int8 source, uint32 b) override=0
uint32	property (int prop, uint32 param) override
virtual void	deinitSource (uint8 source)
void	setSourceType (SourceType type)
void	setSourceType (uint8 source, SourceType type)
void	setSourceVolume (uint16 volume)
void	setSourceVolume (uint8 source, uint16 volume)
void	resetSourceVolume ()
void	resetSourceVolume (uint8 source)
void	setSourceNeutralVolume (uint16 volume)
void	setSourceNeutralVolume (uint8 source, uint16 volume)
void	startFade (uint16 duration, uint16 targetVolume)
void	startFade (uint8 source, uint16 duration, uint16 targetVolume)
void	abortFade (FadeAbortType abortType=FADE_ABORT_TYPE_END_VOLUME)
void	abortFade (uint8 source, FadeAbortType abortType=FADE_ABORT_TYPE_END_VOLUME)
bool	isFading ()
bool	isFading (uint8 source)
void	setControllerDefault (ControllerDefaultType type)
void	setControllerDefault (ControllerDefaultType type, int16 value)
void	setControllerDefaults (ControllerDefaultType type, int16 *values)
void	clearControllerDefault (ControllerDefaultType type)
void	setInstrumentRemapping (const byte *instrumentRemapping)
void	syncSoundSettings ()
virtual void	stopAllNotes (uint8 source, uint8 channel)=0
void	setTimerCallback (void *timer_param, Common::TimerManager::TimerProc timer_proc) override
Public Member Functions inherited from MidiDriver
void	midiDriverCommonSend (uint32 b)
void	midiDriverCommonSysEx (const byte *msg, uint16 length)
virtual int	open ()=0
virtual bool	isOpen () const =0
virtual void	close ()=0
virtual void	setPitchBendRange (byte channel, uint range)
void	sendMT32Reset ()
void	sendGMReset ()
virtual uint32	getBaseTempo ()=0
virtual MidiChannel *	allocateChannel ()=0
virtual MidiChannel *	getPercussionChannel ()=0
virtual void	setEngineSoundFont (Common::SeekableReadStream *soundFontData)
virtual bool	acceptsSoundFontData ()
Public Member Functions inherited from MidiDriver_BASE
void	send (byte status, byte firstOp, byte secondOp)
void	send (int8 source, byte status, byte firstOp, byte secondOp)
virtual void	sysEx (const byte *msg, uint16 length)
virtual uint16	sysExNoDelay (const byte *msg, uint16 length)
virtual void	metaEvent (byte type, byte *data, uint16 length)
virtual void	metaEvent (int8 source, byte type, byte *data, uint16 length)
virtual void	stopAllNotes (bool stopSustainedNotes=false)
virtual bool	isReady (int8 source=-1)

Static Public Attributes
static const uint8	MAXIMUM_SOURCES = 10
static const uint16	DEFAULT_SOURCE_NEUTRAL_VOLUME = 255
Static Public Attributes inherited from MidiDriver
static const byte	_mt32ToGm [128]
static const byte	_gmToMt32 [128]
Static Public Attributes inherited from MidiDriver_BASE
static const uint8	MIDI_CHANNEL_COUNT = 16
static const uint8	MIDI_RHYTHM_CHANNEL = 9
static const byte	MIDI_COMMAND_NOTE_OFF = 0x80
static const byte	MIDI_COMMAND_NOTE_ON = 0x90
static const byte	MIDI_COMMAND_POLYPHONIC_AFTERTOUCH = 0xA0
static const byte	MIDI_COMMAND_CONTROL_CHANGE = 0xB0
static const byte	MIDI_COMMAND_PROGRAM_CHANGE = 0xC0
static const byte	MIDI_COMMAND_CHANNEL_AFTERTOUCH = 0xD0
static const byte	MIDI_COMMAND_PITCH_BEND = 0xE0
static const byte	MIDI_COMMAND_SYSTEM = 0xF0
static const byte	MIDI_CONTROLLER_BANK_SELECT_MSB = 0x00
static const byte	MIDI_CONTROLLER_MODULATION = 0x01
static const byte	MIDI_CONTROLLER_DATA_ENTRY_MSB = 0x06
static const byte	MIDI_CONTROLLER_VOLUME = 0x07
static const byte	MIDI_CONTROLLER_BALANCE = 0x08
static const byte	MIDI_CONTROLLER_PANNING = 0x0A
static const byte	MIDI_CONTROLLER_EXPRESSION = 0x0B
static const byte	MIDI_CONTROLLER_BANK_SELECT_LSB = 0x20
static const byte	MIDI_CONTROLLER_DATA_ENTRY_LSB = 0x26
static const byte	MIDI_CONTROLLER_SUSTAIN = 0x40
static const byte	MIDI_CONTROLLER_PORTAMENTO = 0x41
static const byte	MIDI_CONTROLLER_SOSTENUTO = 0x42
static const byte	MIDI_CONTROLLER_SOFT = 0x43
static const byte	MIDI_CONTROLLER_REVERB = 0x5B
static const byte	MIDI_CONTROLLER_CHORUS = 0x5D
static const byte	MIDI_CONTROLLER_RPN_LSB = 0x64
static const byte	MIDI_CONTROLLER_RPN_MSB = 0x65
static const byte	MIDI_CONTROLLER_ALL_SOUND_OFF = 0x78
static const byte	MIDI_CONTROLLER_RESET_ALL_CONTROLLERS = 0x79
static const byte	MIDI_CONTROLLER_ALL_NOTES_OFF = 0x7B
static const byte	MIDI_CONTROLLER_OMNI_ON = 0x7C
static const byte	MIDI_CONTROLLER_OMNI_OFF = 0x7D
static const byte	MIDI_CONTROLLER_MONO_ON = 0x7E
static const byte	MIDI_CONTROLLER_POLY_ON = 0x7F
static const uint16	MIDI_RPN_PITCH_BEND_SENSITIVITY = 0x0000
static const uint16	MIDI_RPN_MASTER_TUNING_FINE = 0x0001
static const uint16	MIDI_RPN_MASTER_TUNING_COARSE = 0x0002
static const uint16	MIDI_RPN_NULL = 0x7F7F
static const uint8	MIDI_META_END_OF_TRACK = 0x2F
static const uint8	MIDI_META_SEQUENCER = 0x7F
static const uint16	MIDI_PITCH_BEND_DEFAULT = 0x2000
static const uint8	MIDI_PANNING_DEFAULT = 0x40
static const uint8	MIDI_EXPRESSION_DEFAULT = 0x7F
static const uint16	MIDI_MASTER_TUNING_FINE_DEFAULT = 0x2000
static const uint8	MIDI_MASTER_TUNING_COARSE_DEFAULT = 0x40
static const uint8	MT32_PITCH_BEND_SENSITIVITY_DEFAULT = 0x0C
static const uint8	GM_PITCH_BEND_SENSITIVITY_DEFAULT = 0x02
static const uint8	GS_RHYTHM_FIRST_NOTE = 0x1B
static const uint8	GS_RHYTHM_LAST_NOTE = 0x58

Protected Member Functions
virtual void	applySourceVolume (uint8 source)=0
void	updateFading ()
virtual void	onTimer ()
Protected Member Functions inherited from MidiDriver_BASE
void	midiDumpInit ()
int	midiDumpVarLength (const uint32 &delta)
void	midiDumpDelta ()
void	midiDumpDo (uint32 b)
void	midiDumpSysEx (const byte *msg, uint16 length)
void	midiDumpFinish ()

Protected Attributes
MidiSource	_sources [MAXIMUM_SOURCES]
ControllerDefaults	_controllerDefaults
const byte *	_instrumentRemapping
bool	_userVolumeScaling
uint16	_userMusicVolume
uint16	_userSfxVolume
bool	_userMute
Common::Mutex	_fadingMutex
uint16	_fadeDelay
uint32	_timerRate
void *	_timer_param
Common::TimerManager::TimerProc	_timer_proc
Protected Attributes inherited from MidiDriver_BASE
bool	_midiDumpEnable
uint32	_prevMillis
Common::Array< byte >	_midiDumpCache

Static Protected Attributes
static const uint16	FADING_DELAY = 25 * 1000

Additional Inherited Members
Static Public Member Functions inherited from MidiDriver
static Common::String	musicType2GUIO (uint32 musicType)
static MidiDriver *	createMidi (DeviceHandle handle)
static DeviceHandle	detectDevice (int flags)
static DeviceHandle	getDeviceHandle (const Common::String &identifier)
static bool	checkDevice (DeviceHandle handle)
static MusicType	getMusicType (DeviceHandle handle)
static Common::String	getDeviceString (DeviceHandle handle, DeviceStringType type)
static const char *	getErrorName (int error_code)

Detailed Description

Abstract base class for MIDI drivers supporting multiple simultaneous sources of MIDI data.

These drivers support the following features:

• Multiple MIDI sources If the game plays multiple streams of MIDI data at the same time, each stream can be marked with a source number. When a source has finished playing, it must be deinitialized to release any resources allocated to it. This is done automatically when an End Of Track MIDI meta event is received, or manually by calling deinitSource. Using source numbers enables the following features:
  • Music/SFX volume Using setSourceType a MIDI source can be designated as music or sound effects. The driver will then apply the appropriate user volume setting to the MIDI channel volume. This setting sticks after deinitializing a source, so if you use the same source numbers for the same types of MIDI data, you don't need to set the source type repeatedly. The default setup is music for source 0 and SFX for sources 1 and higher.
  • Source volume If the game changes the volume of the MIDI playback, you can use setSourceVolume to set the volume level for a source. The driver will then adjust the current MIDI channel volume and any received MIDI volume controller messages. Use setSourceNeutralVolume to set the neutral volume for a source (MIDI volume is not changed when source volume is at this level; if it is lower or higher, MIDI volume is reduced or increased).
  • Volume fading If the game needs to gradually change the volume of the MIDI playback (typically for a fade-out), you can use the startFade function. You can check the status of the fade using isFading, and abort a fade using abortFade. An active fade is automatically aborted when the fading source is deinitialized. The fading functionality uses the source volume, so you should not set this while a fade is active. After the fade the source volume will remain at the target level, so if you perform f.e. a fade-out, the source volume will remain at 0. If you want to start playback again using this source, use setSourceVolume to set the correct playback volume. Note that when you stop MIDI playback, notes will not be immediately silent but will gradually die out ("release"). So if you fade out a source, stop playback, and immediately reset the source volume, the note release will be audible. It is recommended to wait about 0.5s before resetting the source volume.
• User volume settings The driver can scale the MIDI channel volume using the user specified volume settings. Just call syncSoundSettings when the user has changed the volume settings. Set the USER_VOLUME_SCALING property to true to enable this functionality.

A driver extending this class must implement the following functions:

• send(source, data): process a MIDI event for a specific source.
• stopAllNotes(source, channel): stop all active notes for a source and/or MIDI channel (called when a source is deinitialized).
• applySourceVolume(source): set the current source volume on active notes and/or MIDI channels.

Member Enumeration Documentation

SourceType

enum MidiDriver_Multisource::SourceType

The type of audio produced by a MIDI source (music or sound effects).

Enumerator
SOURCE_TYPE_UNDEFINED	Source type not specified (generally treated as music).
SOURCE_TYPE_MUSIC	Source produces music.
SOURCE_TYPE_SFX	Source produces sound effects.

FadeAbortType

enum MidiDriver_Multisource::FadeAbortType

Specifies what happens to the volume when a fade is aborted.

Enumerator
FADE_ABORT_TYPE_END_VOLUME	The volume is set to the fade's end volume level.
FADE_ABORT_TYPE_CURRENT_VOLUME	The volume remains at the current level.
FADE_ABORT_TYPE_START_VOLUME	The volume is reset to the fade's start volume level.

ControllerDefaultType

enum MidiDriver_Multisource::ControllerDefaultType

The controllers and parameters for which a default value can be set using setControllerDefault.

Member Function Documentation

send() [1/2]

void MidiDriver_Multisource::send ( uint32  b )

overridevirtual

Output a packed midi command to the midi stream. The 'lowest' byte (i.e. b & 0xFF) is the status code, then come (if used) the first and second opcode.

Implements MidiDriver_BASE.

Reimplemented in MidiDriver_MT32GM.

send() [2/2]

void MidiDriver_Multisource::send ( int8  source, uint32  b  )

overridepure virtual

Send a MIDI command from a specific source. If the MIDI driver does not support multiple sources, the source parameter is ignored.

Reimplemented from MidiDriver_BASE.

Implemented in MidiDriver_ADLIB_Multisource, MidiDriver_NULL_Multisource, MidiDriver_MT32GM, Audio::MidiDriver_Miles_Midi, MidiDriver_Casio, Ultima::Nuvie::MidiDriver_M_MT32, Ultima::Nuvie::MidiDriver_M_AdLib, AGOS::MidiDriver_Accolade_AdLib, and AGOS::MidiDriver_Accolade_MT32.

property()

uint32 MidiDriver_Multisource::property ( int  prop, uint32  param  )

overridevirtual

Get or set a property.

Reimplemented from MidiDriver.

Reimplemented in MidiDriver_MT32GM, and Audio::MidiDriver_Miles_Midi.

deinitSource()

virtual void MidiDriver_Multisource::deinitSource ( uint8  source )

virtual

Deinitializes a source. This will abort active fades and stop any active notes.

Parameters

source

The source to deinitialize.

Reimplemented in MidiDriver_ADLIB_Multisource, MidiDriver_MT32GM, Audio::MidiDriver_Miles_Midi, Ultima::Nuvie::MidiDriver_M_AdLib, AGOS::MidiDriver_Simon1_AdLib, AGOS::MidiDriver_Accolade_AdLib, and AGOS::MidiDriver_Accolade_MT32.

setSourceType() [1/2]

void MidiDriver_Multisource::setSourceType

(

SourceType

type

)

Sets the type for all sources (music or SFX).

Parameters

type	The new type for all sources.

setSourceType() [2/2]

void MidiDriver_Multisource::setSourceType	(	uint8	source,
		SourceType	type
	)

Sets the type for a specific sources (music or SFX).

Parameters

source	The source for which the type should be set.
type	The new type for the specified source.

setSourceVolume() [1/2]

void MidiDriver_Multisource::setSourceVolume

(

uint16

volume

)

Sets the source volume for all sources.

Parameters

volume

The new source volume for all sources.

setSourceVolume() [2/2]

void MidiDriver_Multisource::setSourceVolume	(	uint8	source,
		uint16	volume
	)

Sets the volume for this source. The volume values in the MIDI data sent by this source will be scaled by the source volume.

Parameters

source	The source for which the source volume should be set.
volume	The new source volume for the specified source.

resetSourceVolume() [1/2]

void MidiDriver_Multisource::resetSourceVolume

(

)

Resets the source volume for all sources to each source's neutral volume.

resetSourceVolume() [2/2]

void MidiDriver_Multisource::resetSourceVolume

(

uint8

source

)

Resets the volume for this source to its neutral volume.

setSourceNeutralVolume() [1/2]

void MidiDriver_Multisource::setSourceNeutralVolume

(

uint16

volume

)

Sets the neutral volume for all sources. See the source-specific setSourceNeutralVolume function for details.

Parameters

volume

The new neutral volume for all sources.

setSourceNeutralVolume() [2/2]

void MidiDriver_Multisource::setSourceNeutralVolume	(	uint8	source,
		uint16	volume
	)

Sets the neutral volume for this source. If the source volume is at this level, the volume values in the MIDI data sent by this source will not be changed. At source volumes below or above this value, the MIDI volume values will be decreased or increased accordingly.

Parameters

source	The source for which the neutral volume should be set.
volume	The new neutral volume for the specified source.

startFade() [1/2]

void MidiDriver_Multisource::startFade	(	uint16	duration,
		uint16	targetVolume
	)

Starts a fade for all sources. See the source-specific startFade function for more information.

Parameters

duration	The fade duration in milliseconds
targetVolume	The volume at the end of the fade

startFade() [2/2]

void MidiDriver_Multisource::startFade	(	uint8	source,
		uint16	duration,
		uint16	targetVolume
	)

Starts a fade for a source. This will linearly increase or decrease the volume of the MIDI channels used by the source to the specified target value over the specified length of time.

Parameters

source	The source to fade
duration	The fade duration in milliseconds
targetVolume	The volume at the end of the fade

abortFade() [1/2]

void MidiDriver_Multisource::abortFade

(

FadeAbortType

abortType = FADE_ABORT_TYPE_END_VOLUME

)

Aborts any active fades for all sources. See the source-specific abortFade function for more information.

Parameters

abortType

How to set the volume when aborting the fade (default: set to the target fade volume).

abortFade() [2/2]

void MidiDriver_Multisource::abortFade	(	uint8	source,
		FadeAbortType	abortType = FADE_ABORT_TYPE_END_VOLUME
	)

Aborts an active fade for a source. Depending on the abort type, the volume will remain at the current value or be set to the start or end volume. If there is no active fade for the specified source, this function does nothing.

Parameters

source	The source that should have its fade aborted
abortType	How to set the volume when aborting the fade (default: set to the target fade volume).

isFading() [1/2]

bool MidiDriver_Multisource::isFading

(

)

Check if any source has an active fade.

Returns

True if any source has an active fade.

isFading() [2/2]

bool MidiDriver_Multisource::isFading

(

uint8

source

)

Check if the specified source has an active fade.

Returns

True if the specified source has an active fade.

setControllerDefault() [1/2]

void MidiDriver_Multisource::setControllerDefault

(

ControllerDefaultType

type

)

Specify a controller which should be reset to its General MIDI default value when a new track is started. See the overload for more details.

Parameters

type	The controller which should be reset.

setControllerDefault() [2/2]

void MidiDriver_Multisource::setControllerDefault	(	ControllerDefaultType	type,
		int16	value
	)

Specify a default value for a controller which should be set when a new track is started. Use this if a game uses a MIDI controller, but does not consistently set it to a value at the start of every track, causing incorrect playback. Do not use this if a game depends on controller values carrying over to the next track for correct playback.

This functionality will not work if the fallback MIDI source -1 is used. It is also necessary to call deinitSource whenever playback of a track is stopped, as this sets up the contoller reset.

Use the setControllerDefault(ControllerDefaultType) overload if the General MIDI default value for the controller should be used.

Parameters

type	The controller which should be reset.
value	The default value which should be set.

setControllerDefaults()

void MidiDriver_Multisource::setControllerDefaults	(	ControllerDefaultType	type,
		int16 *	values
	)

Specify a default value for a controller which should be set when a new track is started. This expects an array of values, each of which will be used as the default for the corresponding MIDI channel.

This is currently only supported for program.

See setControllerDefault for more details.

Parameters

type	The controller which should be reset.
values	The default values which should be set. Must be a 16 value array.

clearControllerDefault()

void MidiDriver_Multisource::clearControllerDefault

(

ControllerDefaultType

type

)

Clears a previously set default value for the specified controller.

Parameters

type	The controller for which the default value should be cleared.

setInstrumentRemapping()

void MidiDriver_Multisource::setInstrumentRemapping

(

const byte *

instrumentRemapping

)

Sets an instrument map for arbitrarily remapping instruments in the MIDI data. The map should consist of 128 bytes, with the index representing the instrument number in the MIDI data, and the value being the instrument which should be substituted. This instrument mapping is applied before MT-32 to GM or GM to MT-32 instrument mapping. Call this method with nullptr as parameter to clear a previously set instrument remapping.

Parameters

instrumentRemapping

The instrument map that should be used for remapping, or nullptr to disable remapping.

syncSoundSettings()

void MidiDriver_Multisource::syncSoundSettings

(

)

Applies the user volume settings to the MIDI driver. MIDI channel volumes will be scaled using the user volume. This function must be called by the engine when the user has changed the volume settings.

stopAllNotes()

virtual void MidiDriver_Multisource::stopAllNotes ( uint8  source, uint8  channel  )

pure virtual

Stops all active notes (including sustained notes) for the specified source and MIDI channel. For both source and channel the value 0xFF can be specified, in which case active notes will be stopped for all sources and/or MIDI channels.

Parameters

source	The source for which all notes should be stopped, or all sources if 0xFF is specified.
channel	The MIDI channel on which all notes should be stopped, or all channels if 0xFF is specified.

Implemented in MidiDriver_ADLIB_Multisource, MidiDriver_MT32GM, MidiDriver_NULL_Multisource, and MidiDriver_Casio.

setTimerCallback()

void MidiDriver_Multisource::setTimerCallback ( void *  timer_param, Common::TimerManager::TimerProc  timer_proc  )

inlineoverridevirtual

Sets a callback which will be called whenever the driver's timer callback is called by the underlying emulator or hardware driver. The callback will only be called when the driver is open. Use

See also

getBaseTempo to get the delay between each callback invocation.

Parameters

timer_param	A parameter that will be passed to the callback function. Optional.
timer_proc	The function that should be called.

Implements MidiDriver.

applySourceVolume()

virtual void MidiDriver_Multisource::applySourceVolume ( uint8  source )

protectedpure virtual

Applies the current source volume to the active notes and/or MIDI channels of the specified source. 0xFF can be specified to apply the source volume for all sources.

Parameters

source

The source for which the source volume should be applied, or all sources if 0xFF is specified.

Implemented in MidiDriver_ADLIB_Multisource, MidiDriver_MT32GM, MidiDriver_NULL_Multisource, MidiDriver_Casio, and Audio::MidiDriver_Miles_Midi.

updateFading()

void MidiDriver_Multisource::updateFading ( )

protected

Processes active fades and sets new volume values if necessary.

onTimer()

virtual void MidiDriver_Multisource::onTimer ( )

protectedvirtual

Runs the MIDI driver's timer related functionality. Will update volume fades and calls the timer callback if necessary.

Reimplemented in MidiDriver_MT32GM, Ultima::Nuvie::MidiDriver_M_MT32, and Ultima::Nuvie::MidiDriver_M_AdLib.

Member Data Documentation

MAXIMUM_SOURCES

const uint8 MidiDriver_Multisource::MAXIMUM_SOURCES = 10

static

The maximum number of sources supported. This can be increased if necessary, but this will consume more memory and processing time.

DEFAULT_SOURCE_NEUTRAL_VOLUME

const uint16 MidiDriver_Multisource::DEFAULT_SOURCE_NEUTRAL_VOLUME = 255

static

The default neutral volume level for a source. If the source volume is set to this level, the volume levels in the MIDI data are used directly; if source volume is lower or higher, output volume is decreased or increased, respectively. Use

See also

setSourceNeutralVolume to change the default neutral volume.

---

The documentation for this class was generated from the following file:

• audio/mididrv_ms.h