#include <MD_YM2413.h>

Public Types
enum	instrument_t { I_CUSTOM = 0 , I_VIOLIN = 1 , I_GUITAR = 2 , I_PIANO = 3 , I_FLUTE = 4 , I_CLARINET = 5 , I_OBOE = 6 , I_TRUMPET = 7 , I_ORGAN = 8 , I_HORN = 9 , I_SYNTH = 10 , I_HARPSICHORD = 11 , I_VIBRAPHONE = 12 , I_SYNTH_BASS = 13 , I_ACOUSTIC_BASS = 14 , I_EGUITAR = 15 , P_HI_HAT = 16 + 0 , P_TOP_CYMBAL = 16 + 1 , P_TOM_TOM = 16 + 2 , P_SNARE_DRUM = 16 + 3 , P_BASS_DRUM = 16 + 4 , I_UNDEFINED = 0xff }

Public Member Functions
	MD_YM2413 (pin_t *D, pin_t we, pin_t a0)

	MD_YM2413 (MD_IODriver &driver)

	~MD_YM2413 (void)

void	begin (void)

Hardware and Library Management.
uint8_t	countChannels (void)

bool	isPercussion (void)

bool	isPercussion (uint8_t chan)

void	setPercussion (bool bEnable)

void	loadInstrumentOPL2 (const uint8_t *ins, bool fromPROGMEM=true)

void	loadInstrument (const uint8_t *data)

void	setSustain (uint8_t chan, bool sustain)

bool	isIdle (uint8_t chan)

void	run (void)

void	write (uint8_t addr, uint8_t data)

Sound Management.
bool	setInstrument (uint8_t chan, instrument_t instr, uint8_t vol=VOL_MAX)

instrument_t	getInstrument (uint8_t chan)

uint8_t	getVolume (uint8_t chan)

void	setVolume (uint8_t chan, uint8_t v)

void	setVolume (uint8_t v)

void	noteOn (uint8_t chan, uint16_t freq, uint8_t vol, uint16_t duration=0)

void	noteOn (uint8_t chan, uint8_t octave, uint8_t note, uint8_t vol, uint16_t duration=0)

void	noteOff (uint8_t chan)

Static Public Attributes
static const uint8_t	VOL_OFF = 0x0
	Convenience constant for volume off.

static const uint8_t	VOL_MAX = 0xf
	Convenience constant for volume maximum.

static const uint8_t	MIN_OCTAVE = 1
	smallest octave playable

static const uint8_t	MAX_OCTAVE = 8
	largest playable octave

static const uint8_t	CH_UNDEFINED = 255
	undefined channel indicator

static const uint8_t	OPL2_DATA_SIZE = 12
	OPL2 instrument definition size.

static const uint8_t	PERC_CHAN_BASE = 6
	Base channel number for percussion instruments if enabled.

static const uint8_t	CH_HH = PERC_CHAN_BASE + 0
	HI HAT channel number.

static const uint8_t	CH_TCY = PERC_CHAN_BASE + 1
	TOP CYMBAL channel number.

static const uint8_t	CH_TOM = PERC_CHAN_BASE + 2
	TOM TOM channel number.

static const uint8_t	CH_SD = PERC_CHAN_BASE + 3
	SNARE DRUM channel number.

static const uint8_t	CH_BD = PERC_CHAN_BASE + 4
	BASS DRUM channel number.

Detailed Description

Base class for the MD_YM2413 library

Member Enumeration Documentation

◆ instrument_t

enum MD_YM2413::instrument_t

Predefined musical and percussion instrument definitions The IC has a number of predefined profiles instruments with IDs that are defined here.

Constructor & Destructor Documentation

◆ MD_YM2413()

MD_YM2413::MD_YM2413	(	pin_t *	D,
		pin_t	we,
		pin_t	a0
	)

Class Constructor.

Instantiate a new instance of this derived class. The parameters passed are used to connect the software to the hardware. Multiple instances may co-exist.

The D array is arranged to correspond to the IC pins (ie, pin D[0] is connected to IC pin D0, D[1] to D1, etc). D0 is the MSB in the data byte, D7 the LSB.

The we and a0 pins are used for handshaking the data over the data bus.

See also: Hardware Connections

Parameters

D	pointer to array of 8 pins used as the data bus interface
we	pin number used as write enable
a0	pin number used as address/data selector

◆ ~MD_YM2413()

MD_YM2413::~MD_YM2413 ( void )

Class Destructor.

Does the necessary to clean up once the object is no longer required.

Member Function Documentation

◆ begin()

void MD_YM2413::begin ( void )

Initialize the object.

Initialize the object data. This needs to be called during setup() to initialize new data for the class that cannot be done during the object creation.

All the I/O is initialize, percussion mode is disabled and all instruments are set as I_PIANO at VOL_MAX volume by default.

See also: setVolume(), setInstrument(), setPercussion()

◆ countChannels()

uint8_t MD_YM2413::countChannels ( void )

Return the number of channels.

Return the number of channels depending on whether the percussion instruments are set.

See also: setPercussion()

Returns: the number of channels in the current configuration.

◆ getInstrument()

instrument_t MD_YM2413::getInstrument ( uint8_t chan )

Get the current instrument setting

Get the instrument set for the specified channel. This will be one of the instrument_t values.

See also: setInstrument(), instrument_t

Parameters

chan	channel number on which volume is set [0..countChannels()-1].

Returns: the value of the instrument set for the channel.

◆ getVolume()

uint8_t MD_YM2413::getVolume ( uint8_t chan )

Get the volume for a channel.

Get the current volume for a channel.

Parameters

chan	channel number on which volume is set [0..countChannels()-1].

Returns: the current volume in the range [VOL_OFF..VOL_MAX].

◆ isIdle()

bool MD_YM2413::isIdle ( uint8_t chan )

Return the idle state of a channel.

Used to check if a channel is currently idle (ie, not playing a note).

Parameters

chan	channel to check [0..countChannels()-1].

Returns: true if the channel is idle, false otherwise.

◆ isPercussion() [1/2]

bool MD_YM2413::isPercussion ( uint8_t chan )

Check if the channel is for percussion

Returns whether the specified channel is allocated to a percussion instrument. Percussion instruments are allocated to specific channels as explained in setPercussion().

See also: setPercussion()

Parameters

chan	channel to check [0..countChannels()-1].

Returns: true if specified is for percussion, false otherwise.

◆ isPercussion() [2/2]

bool MD_YM2413::isPercussion ( void )

Return the current library mode

Returns the current library/hardware operating mode set by setPercussion().

See also: setPercussion()

Returns: true if percussion channels are enabled, false otherwise.

◆ loadInstrument()

void MD_YM2413::loadInstrument ( const uint8_t * data )

Define direct parameters for a custom instrument.

Define the data for a custom instrument directly. The data is preformatted for the YM2413 device and will be passed through without further processing.

This method is used to set instrument definitions that are in OPLL format and held in the application as a compact byte sequence.

See also: Custom Instruments

Parameters

data	an array of 8 bytes in RAM that will be written to registers 0x00 through 0x07.

◆ loadInstrumentOPL2()

void MD_YM2413::loadInstrumentOPL2	(	const uint8_t *	ins,
		bool	fromPROGMEM = `true`
	)

Define the parameters for a custom instrument.

Define the playing envelope in OPL2/OPL3 format for the custom instrument. The parameters are in higher OPL format, which is readily available and very close to the YM2413 format (OPLL). Translations are made as required.

See also: Custom Instruments

Parameters

ins	an array of OPL2_DATA_SIZE uint8_t bytes in OPL2 format data.
fromPROGMEM	true if the data is loaded from PROGMEM false otherwise.

◆ noteOff()

void MD_YM2413::noteOff ( uint8_t chan )

Stop playing a note

Stop the note currently playing on the specified channel

Causes a key-off event to be processed by the channel.

See also: noteOn(), run()

Parameters

chan	channel number on which to stop this note [0..countChannels()-1].

◆ noteOn() [1/2]

void MD_YM2413::noteOn	(	uint8_t	chan,
		uint16_t	freq,
		uint8_t	vol,
		uint16_t	duration = `0`
	)

Play a note (frequency)

Output a note with frequency freq on the specified channel using the instrument currently defined for the channel.

If specified, the duration will cause an automatic note off event when the total time has expired. If duration is 0 the note will be sustained until it is turned off by the application.

See also: noteOff(), run()

Parameters

chan	channel number on which to play this note [0..countChannels()-1].
freq	frequency to play.
vol	volume to set this note in range [VOL_OFF..VOL_MAX].
duration	length of time in ms for the whole note to last.

◆ noteOn() [2/2]

void MD_YM2413::noteOn	(	uint8_t	chan,
		uint8_t	octave,
		uint8_t	note,
		uint8_t	vol,
		uint16_t	duration = `0`
	)

Play a note (octave and note#)

Output a note defined by octave and note number on the specified channel using the instrument currently defined for the channel.

Middle C is the first note in octave 4 (C4). Notes [C, C#, D, D#, E, F, F#, G, G#, A, A#, B] are numbered sequentially 0 to 11 within the octave.

If specified, the duration will cause an automatic note off event when the total time has expired. If duration is 0 the note will be sustained until it is turned off by the application.

See also: noteOff(), run()

Parameters

chan	channel number on which to play this note [0..countChannels()-1].
octave	the octave block for this note [MIN_OCTAVE..MAX_OCTAVE].
note	the note number to play [0..11] as defined above.
vol	volume to set this note in range [VOL_OFF..VOL_MAX].
duration	length of time in ms for the whole note to last.

◆ run()

void MD_YM2413::run ( void )

Run the music machine.

Runs the automatic note off timing for all channels. This should be called from the main loop() as frequently as possible to allow the library to execute the note required timing for each channel.

This method is not required if the application does not use durations when invoking noteOn().

◆ setInstrument()

bool MD_YM2413::setInstrument	(	uint8_t	chan,
		instrument_t	instr,
		uint8_t	vol = `VOL_MAX`
	)

Set the playing instrument for a channel.

Set the instrument for the channel to be one the value specified. Valid instruments are given by the enumerated type instrument_t.

If percussion is not enabled, the valid range of instruments is one of the I_* values on channels [0..9]. The percussion instruments P_* are automatically set up on the channels CH_* [6..11] when percussion mode is enabled, and instruments I_* can be set up on channels [0..5].

Custom instruments must be defined before they can be used.

See also: setPercussion(), instrument_t, setSustain(), defineInstrument()

Parameters

chan	channel number on which volume is set [0..countChannels()-1].
instr	one of the instruments I_* from instrument_t.
vol	volume to set for the specified channel in range [VOL_OFF..VOL_MAX].

Returns: true if the instrument was set correctly.

◆ setPercussion()

void MD_YM2413::setPercussion ( bool bEnable )

Set the current library/hardware operating mode.

The library can operate with or without percussion instruments configured. Without percussion instruments, there are 9 channels(0..8] available for general instruments. With percussion enabled, there are 6 channels[0..5] available for general instruments and 5 channels[6..10], for a total of 11, allocated to percussion instruments.

The method countChannels() will always return the total number of channels for the current configuration.

See also: isPercussion(), countChannels()

Parameters

bEnable true to enable percussion mode, false otherwise.

◆ setSustain()

void MD_YM2413::setSustain	(	uint8_t	chan,
		bool	sustain
	)

Standardize the instrument release phase

For the specific channel, set the release value to a standarized mid-point for this instance of the instrument.

See also: setInstrument()

Parameters

chan	channel number on which sustain is set [0..countChannels()-1].
sustain	set true to standardize the release phase to a mid level value.

◆ setVolume() [1/2]

void MD_YM2413::setVolume	(	uint8_t	chan,
		uint8_t	v
	)

Set the volume for a channel.

Set the volume for a channel to be the value specified. Valid values are all the values in the range [VOL_OFF..VOL_MAX].

Parameters

chan	channel number on which volume is set [0..countChannels()-1].
v	volume to set for the specified channel in range [VOL_OFF..VOL_MAX].

◆ setVolume() [2/2]

void MD_YM2413::setVolume ( uint8_t v )

Set the volume for all channels.

Set the volume for all channels to be the specified value. Valid values are all the values in the range [VOL_OFF..VOL_MAX].

Parameters

v	volume to set for all channels in range [VOL_OFF..VOL_MAX].

◆ write()

void MD_YM2413::write	(	uint8_t	addr,
		uint8_t	data
	)

Write a byte directly to the device

This method should be used with caution, as it bypasses all the checks and buffering built into the library. It is provided to support applications that are a collection of register setting to be written to hardware at set time intervals (eg, VGM files).

Parameters

addr	the 8 bit device address to write the data.
data	the 8 bit data value to write to the device.

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

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Member Enumeration Documentation

◆ instrument_t

Constructor & Destructor Documentation

◆ MD_YM2413()

◆ ~MD_YM2413()

Member Function Documentation

◆ begin()

◆ countChannels()

◆ getInstrument()

◆ getVolume()

◆ isIdle()

◆ isPercussion() [1/2]

◆ isPercussion() [2/2]

◆ loadInstrument()

◆ loadInstrumentOPL2()

◆ noteOff()

◆ noteOn() [1/2]

◆ noteOn() [2/2]

◆ run()

◆ setInstrument()

◆ setPercussion()

◆ setSustain()

◆ setVolume() [1/2]

◆ setVolume() [2/2]

◆ write()