This Hint documentation assumes that you already have read the MSE-Compiler
documentation and that you are familiar with the definition language.

Note that in the following definition examples, not all required parameters
are included.  Only the parameters necessary to clarify are given.
Assumptions are also made that reference definitions have been defined.

See the MSE-Compiler documentation for required parameters and proper
referencing requirements.

----------------------------------------------------------------------------

Shown as:

	$F0, $43, $1n, $34, $01, T2, $00, N2, $00, V2, $F7

	Where:	n  : Device Number
					T2 : voice channel number
					V2 : parameter value
					N2 : parameter number

Discussion:

	T2, V2 and N2 will be set by gadget definitions.  Here, these are
  initialized as 'Byte' (equivalent to 0).

	Normally, the Device Number, or MIDI Channel as it is commonly called,
	will be defined within the 'Define Device' structure.  It could be forced
	here, but it can be changed within MSE so the CHANNEL variable should be
	used.  If you forced it here, changing the MIDI Channel within MSE would
	have no effect.  Remember that CHANNEL is stored in the lower 4 bits, so
	$1n can be intialized as $10.

	Because the MIDI Channel can be changed within MSE, the 'Midi' structure
  is used here to cause the MIDI Channel to be stored in the MIDI message
	each time it is sent out.  It could also be included in gadget
	definitions, but it would have to be defined for every gadget that used
	this message.  Putting it here is more sensible and makes the module
	smaller too.

Defined as:

	Define Midi "M1" (
		Data (
			$F0
			$43
			$10 'Channel $1n
			$34
			$01
			Byte 'T2
			$00
			Byte 'N2
			$00
			Byte 'V2
			$F7
		)
		Midi (
			2 CHANNEL
		)
	)

----------------------------------------------------------------------------

Shown as:

	0    1    2    3    4    5   6    7   8    9   10  : <offset>

	$F0, $43, $1n, $34, $01, T2, $00, N2, $00, V2, $F7

	Where:	V2: -64 to +63 (o/b)

Discussion:

	Usually, when a parameter has a value range with negative numbers, a
  <modifier> definition must be included.  Negative values usually require
	some kind of conversion.  In this case, (o/b) indicates that 'Offset
	Binary' encoding is used.

Defined as:

	Gadget "G1" (
		Type Slider (
			Range -64 63
		)
		Midi "M1" (
			Data (
				9 VALUE Offset 64 Byte 'V2 with Offset Binary encoding
			)
		)
	)

----------------------------------------------------------------------------

Shown as:

	0    1    2    3    4    5   6    7   8    9   10  : <offset>

	$F0, $43, $1n, $34, $01, T2, $00, N2, $00, V2, $F7

	Where:	V2: voice, -31 to +31 (o/b)

Discussion:

	This examples differs from the previous in that the V2 value can also
	have a value for 'voice'.  In this case, 'voice' takes the value of 0,
	-31 = 1, -30 = 2, etc.

	There are a couple ways to define this example.  The first would be
	to use a method similar to the previous, adjusting the Range value (-31
	becomes -32) to account for the additional 'voice' value.

		Gadget "G1" (
			Type Slider (
				Range -32 31
			)
			Midi "M1" (
				Data (
					9 VALUE Offset 32 Byte 'V2 with Offset Binary encoding
				)
			)
		)

	This would work, but would mean that you had to remember that the value
	of -32 really meant 'voice'.  There is a better way to do this using
	a 'Link' option.  This is a little more work, but is much better.

	A 'Text' link type is used to accommodate the 'voice' option.  This
	forces the remaining values to also be text, so each has to be defined.

	Note that the slider 'Range' is adjusted to start at 0, since this
	is required by links.  This also means that the 'DataValues' option is
	not required within the link definition because the values will already
	be correct.

	Although this method is a bit awkward, keep in mind that links can be
	shared among multiple gadgets.  So, if several parameters use these same
	values, the link need only be defined once.  A new link type may be added
	later to better accommodate this.

Defined as:

	Define Link "L1" (
		Type Texts (
			Data (
				"Voice" "-31" "-30" "-29" "-28" "-27" "-26" "-25" "-24" "-23" "-22"
				"-21" "-20" "-19" "-18" "-17" "-16" "-15" "-14" "-13" "-12" "-11"
				"-10" "-9" "-8" "-7" "-6" "-5" "-4" "-3" "-2" "-1" "0"
				"1" "2" "3" "4" "5" "6" "7" "8" "9" "10" "11" "12" "13" "14" "15"
				"16" "17" "18" "19" "20" "21" "22" "23" "24" "25" "26" "27" "28"
				"29" "30" "31"
			)
		)
	)

	Gadget "G1" (
		Type Slider (
			Range 0 63
			Link "L1"
		)
		Midi "M1" (
			Data (
				9 VALUE Byte 'V2
			)
		)
	)

----------------------------------------------------------------------------

Shown as:

	0    1    2    3    4    5   6    7   8    9   10  : <offset>

	$F0, $43, $1n, $34, $03, T2, $00, N2, $00, V2, $F7

	Where:	V2: -7 to +7 (s/m)

Discussion:

	This is another example of encoding ranges with negative values.  In this
	case, (s/m) indicates that 'Signed Magnitude' encoding is used.

	Note that the maximum value +7 requires 3 bits (0-2), so bit 3 is used to
	hold the magnitude.

Defined as:

	Gadget "G1" (
		Type Slider (
			Range -7 7
		)
		Midi "M1" (
			Data (
				9 VALUE Magnitude 3 Byte 'V2 with Signed Magnitude encoding.
			)
		)
	)

----------------------------------------------------------------------------

Shown as:

	0    1    2    3    4    5   6    7   8   9   10  : <offset>

	$F0, $43, $1n, $34, $04, T2, $00, N2, V1, V2, $F7

	Where:	V1/V2: 0 to 255 (V1;MSB  V2;LS7bits)

Discussion:

	Here, within XBits 'a' represents the MSB (bit 7) and 'b' the lower 7
	bits (0-6).

	Remember that when a value is stored as more than one byte, the <offset>
	value for 'Data' within a 'Midi' definition is the first byte.

Define as:

	Midi "M1" (
		Data (
			8 VALUE XBits abbbbbbb 'V1/V2
		)
	)

----------------------------------------------------------------------------

Shown as:

	0    1    2    3    4    5   6    7   8    9   10  : <offset>

	$F0, $43, $1n, $34, $05, T2, $00, N2, $00, V2, $F7

	Where:	V2: off/on

Discussion:

	Here, 'off' has a value of 0 and 'on' is 1.  A cycle gadget, or a slider
	gadget with a link can be used.  If many parameters use the same values,
	the second method is the better choice.

Define as:

	Gadget "G1" (
		Type Cycle (
			Data (
				"OFF"
				"ON"
			)
		)
		Midi "M1" (
			Data (
				9 VALUE Byte 'V2
			)
		)
	)

	- - OR - -

	Define Link "L1" (
		Type Texts (
			Data (
				"OFF"
				"ON"
			)
		)
	)

	Gadget "G1" (
		Type Slider (
			Range 0 1
			Link "L1"
		)
		Midi "M1" (
			Data (
				9 VALUE Byte 'V2
			)
		)
	)

----------------------------------------------------------------------------

Shown as:

	0    1    2    3    4   5   6    7   8   9   10  : <offset>

	$F0, $43, $1n, $34, T1, T2, $00, N2, V1, V2, $F7

	Where:	V2: b1,0     ;0 to 3    Oscilator output destination
							b3,2     ;0 to 2    Out_Accumulator input 0 source
							b4       ;0 to 1    Out_Accumulator input 1 source

Discussion:

	Sometimes, several parameters share the same byte for storing their
	values, each using one or more bits.  In this case, there are 3
	parameters sharing V2: Parameter 1 uses the lower 2 bits (0-1), parameter
	2 uses the next 2 bits (2-3) and parameter 3 uses the next bit (4).

	************************************************************************
	NOTE: The current method to handle this situation has a problem, related
	to loading patches.  A new feature will be added to MSE in the future
	that will solve this problem.  Until then, there are three possible
	'solutions'.  The first method avoids the problem.  The second, also
	avoids the problem but requires that patch loading not be enabled.  The
	third allows the problem to exist, but requires the user to remember
	certain things about changing some parameters.  Each has it advantages
	and disadvantages.

	1) Only define full patch definitions, ignoring individual parameter
		 messages.  This will allow all parameters to update properly when
		 loading patches.  The disadvantage of this is that every value change
		 will send the full patch message.  With large patch messages this will
		 generate a large amount of data transmission.  In most cases, the
		 device will be unable to keep up with all the data.  To solve this
		 overflow problem, set the 'Updates Final' option in 'Define Device' or
		 force manual patch sending by not including the 'Send' option of
		 'Midi' and using the menu 'Project/Send' to send the patch any time
		 during patch editing.

	2) Only define individual parameter messages, ignoring full patch
		 definitions.  This will allow all parameters to update properly, but
		 has the disadvantage of not being able to save and/or load patches.

	3) Define both individual parameter and full patch messages, but remember
		 that if you adjust one of a group of shared parameters, you must
		 re-adjust the others in the group as well.  For example, if three
		 shared parameters are defined with both message types and are
		 initially set as follows:

				P1 = 10, P2 = 5, P3 = 7

		 and then you load a patch with those parameters set as follows:

				P1 = 3, P2 = 1, P3 = 10

		 At this point, the patch message is correct, but the individual
		 parameter message is wrong.  So far, this is okay because only the
		 patch message has been sent.  But, when you manually edit P2 to be set
		 at 6.  MSE will send the following incorrect individual parameter
		 message values:

				P1 = 10, P2 = 6, P3 = 7

		 However, the gadgets will still correctly display as:

				P1 = 3, P2 = 6, P3 = 10

		 So, to solve the error, you would then have to remember to manually
		 re-set P1 and P3.  After doing so, all three parameters would have been
		 updated in the parameter message.  Everything would then work, until
		 you loaded another patch.

		 Note that, as long as you do not adjust any of the shared parameters,
		 loading patches will work fine.
	************************************************************************

	Regardless of which method you use, the following still applies:

	Parameters that share values require their own 'Define Midi' definition.
	This is so that MSE can send all the shared parameters even when only one
	value is changing.  This means that MSE does not have to remember which
	gadgets represent which bits, nor does it have to determine the other
	parameter values when it sends the message.

	Unlike parameters that do not share, the initial value for these
	parameters must be set within the 'Define Midi' definition.


Define as:

	Define Midi "M1" (
		Data (
			$F0
			$43
			$10 'Channel $1n
			$34
			Byte 'T1
			Byte 'T2
			$00
			Byte 'N2
			Byte 'V1
			%11011 'V2 See defaults below: %1, %10, %11
			$F7
		)
	)

	Gadget "P1" (
		Type Slider (
			Range 0 3
			Default 3 '%11
		)
		Midi "M1" (
			Data (
				9 VALUE Bits 0-1
			)
		)
	)

	Gadget "P2" (
		Type Slider (
			Range 0 2
			Default 2 '%10
		)
		Midi "M1" (
			Data (
				9 VALUE Bits 2-3
			)
		)
	)

	Gadget "P3" (
		Type Slider (
			Range 0 1
			Default 1 '%1
		)
		Midi "M1" (
			Data (
				9 VALUE Bit 4
			)
		)
	)

----------------------------------------------------------------------------


Other Helpful hints:

Some devices do not have textual descriptions of parameters on the display
screens, but do have in the manuals.  Say Device X allows you to
set Parameter #6 to a value of 1, 2 or 3.  Well, that's easy.  Make a
slider gadget with a range of 1 to 3 and text that says "Parameter #6".
Well, that works, but MSE lets you make it even easier to understand.
The manual for Device X says that Parameter #6 is LFO Waveform, and that 1
is SINE, 2 is TRIANGLE and 3 is PULSE... well that makes a lot more sense.
Remember that MSE lets you use any representation of parameter values that
you want.  So, in MSE we could make a cycle gadget with the text "LFO
Waveform" above it with values of "SINE", "TRIANGLE" and "PULSE".  Even
though we see text information in MSE, we can tell it to send #6, 1, 2 and
3 to the device.  Device X will never know what happened, which is good,
because it might get jealous and refuse to operate properly if it did.

Say Device X also has a selection of 150 different waveforms, but it
numbers them from 1 to 150.  It's tough to remember which is which...
wouldn't it be nice if they all had names that meant something to you!
So, go ahead and give them names, call them whatever you want.  MSE can do
that too!  You could do it with a cycle gadget, but a slider gadget with a
Text Type Link would be better.  Try it.

Just because Device X refers to a parameter as ALGSRC0 doesn't mean you
can't call it by something english (or any language for that matter)...
'Oscillator Input 0 Source' makes more sense to us people types.  Doesn't
it?