Difference between revisions of "MGSDRV MML 11"

From MSX MUSIC WIKI
Jump to: navigation, search
(Tags: Mobile edit, Mobile web edit)
(Macro definition)
(Tags: Mobile edit, Mobile web edit)
Line 163: Line 163:
 
Characters written after escape code are capitalized. ¥@ cannot be used because it is internal code for terminating strings.
 
Characters written after escape code are capitalized. ¥@ cannot be used because it is internal code for terminating strings.
 
Strings are written to track 0. If you want define many strings, allocate track buffers previously with #alloc or others. Refer to manuals for control strings.
 
Strings are written to track 0. If you want define many strings, allocate track buffers previously with #alloc or others. Refer to manuals for control strings.
 +
 +
 +
==Tone definition==
 +
 +
Tine definition has "@" at the top of the line. All of <number> means tone number. The range are 0-31.
 +
 +
;@e<number> = { Mode,Noise,data...data }
 +
 +
Defines envelope data. It is the same format as _ESET in old versions of MGSDRV(which means MGSDRV ver2.xx).
 +
 +
(1) Mode
 +
Specifies tone/noise mode for PSG. The range is 0-3 and 1 is used when it is omitted.
 +
 +
0 - no specification (and nothing changed)
 +
1 - only tone
 +
2 - only noise
 +
3 - tone and noise
 +
 +
(2) Noise
 +
 +
Specifies noise frequency for PSG. It is ignored if it is used for tracks other than PSG. It is valid when mide is more than 2. The range is 0-31. 0 is used when it is omitted.
 +
 +
Mode and Noise are set only when @ commands are executed.
 +
 +
(3) Data
 +
Specifies envelope data. It is allowed up to about 255 characters (depends on contents)
 +
 +
;0〜f(hexadecimal)
 +
Sets hexadecimal number as volume and waits one count. It is written as <volume> below.
 +
 +
;<volume>:<counts>
 +
Sets volume and waits counts.
 +
 +
;<volume>=<counts>
 +
Changes current volume automatically to specified volume within a time specified by counts.
 +
 +
;n<noise frequency>
 +
Changes noise frequency of PSG. It is same as Noise of (2).
 +
 +
;/<mode> or *<mode>
 +
Changes Mode of PSG. It is same as Mode of (1).
 +
 +
;[
 +
 +
Defines start position of repetition.
 +
 +
;]
 +
 +
Defines emd position of repetition.
 +
 +
;@<tone_number>
 +
Changes tone data. It is valid only for SCC and FM. It changes only tone data, not envelope. It should be defined tone data previously with @v(@s).
 +
 +
;y<r>,<d>
 +
 +
Writes data<d> to register<r>, which actually uses envelope. It is ignored for SCC.
 +
 +
¥<n>
 +
 +
Adds <n> to current frequency. The range is -127 to 127. It rises frequency with positive number. Unit is the same as "¥" MML command.
 +
 +
;.,
 +
 +
Separator. Place between numerics (example:n4.456789)
 +
 +
The range of the <count> is 2-239.
 +
 +
;@r<number> = { Mode,Noise,AL,AR,DR,SL,SR,RR }
 +
 +
Defines envelope data.
 +
 +
 Mode ... same as@e.
 +
 Noise ... same as@e.
 +
 +
 +
These are brief explanations below. The range of these values are 0-255.
 +
 +
;AL
 +
Volume at the moment of the key on. Bigger number, bigger volume.
 +
 +
;AR
 +
 +
Speed of reaching to maximum volume(255) from key on. AR is added to AL every moment and DR processing starts when sum exceeds 255 in real processing.
 +
 +
;DR
 +
 +
Speed of reaching to next SL from maximum point. DR is reduced from maximum point at every moment and SR processing starts when sum is less than or equal to SL real processing.
 +
 +
;SL
 +
Moving point from DR to SR.
 +
 +
;SR
 +
 +
Speed of reducing volume. This value is reduced from SL at every moment. This processing continues until if volume become zero or key off.
 +
 +
Up to about 10 is appropriate because if you set huge number to this parameter, sound ends in a moment (if you wish it on some purpose).
 +
 +
RR
 +
 +
Speed of reducing volume from key off. RE is reduced from envelope volume which currently holded.
 +
 +
;@r and @e
 +
 +
@r and @e shares working are to define, so both of them cannot be defined simultaneously. Latter one is valid, in such case.
 +
 +
;@s<number> = { data1 .... data32 }
 +
 +
Defines tone data fir SCC. Data are hexadecimal(00-ff). Data should be 32 units and cannot be omitted.
 +
 +
Example:@s02 = { 7f7f7f7f 7f7f7f7f 7f7f7f7f 7f7f7f7f ;PSG
 +
      80808080 80808080 80808080 80808080 }
 +
 +
;@v<number> = { data ... }
 +
 +
Defines original tone of FM.
 +
 +
Example:@v15 = { ;BRASS
 +
  ;      TL FB
 +
          25, 7,
 +
  ;      AR DR SL RR KL MT AM VB EG KR DT
 +
            8, 8, 1, 2, 0, 0, 0, 1, 0, 0, 0,
 +
            8, 2, 1, 1, 1, 1, 0, 1, 0, 0, 0 }
 +
 +
Parameter format is same as _VSETC of the old versions of MGSDRV.
 +
 +
;@#<number> = <n>
 +
Changes assigned ROM tone number of the tone. MGSC assigns 1-15 of ROM tone to @0-14.  Tones after @15 is assigned 0(original tone) and definition of tone is valid when <number> is more than 15. @# changes ROM tone number assigned to each tones. The range of <n> is 0-15 and 0 means original tone(refer about other numbers).
 +
 +
 +
==Comments==
 +
 +
If ";"(semicolon) are found in the lunes(including MML), it is recognized as comment from the semicolon to the end of the line(CRLF) and ignored.

Revision as of 23:08, 6 March 2018

MGSC1.1[en]

MGSC MML compiler version 1.11 Copyright(c) 1992-93 by Ain

MGSC MML Compiler converts MML (text file) to MGS formatted play data.

Usage

SyntaxMGSC <Source file[.MUS]> [<Object file>] [Option]

<Source file>

Specifies the file name of MML source. If extension is omitted, .MUS is used.


[<Object file>]

Specifies the name of data file after compile. If it is omitted, same name as <Source file> is used.

Path can be included as file name in DOS2 environment.

[Option]

Specifies options. These are available below.

-p

Starts playing music after compilation. Error occurs if MGSDRV does not exist. During playing music, you can do forwarding with SELECT (if you use turboR, fast forwarding is available with SHIFT + SELECT) and exiting with ESC. When MGSDRV resides in memory you can continue to playing music after exiting with SHIFT + ESC. Replaying or volume control is available with ten keys in MGSDRV v3.13 or after.

-q

Reterns to dos immediately. Compare to -p option which returns DOS only when ESC is pressed or playing is finished. If MGSDRV does not reside in memory, returns to DOS after playing music instantly. It is not valid without -p option.

-t

Shows status of usage in every tracks after compile. Numerics in parens mean below (left to right) Allocated bytes (with #alloc etc) Used bytes Available bytes Final line shows sums of these bytes.

-s

Ignores #no_mgs and forces data to be saved.

-n

Does not save data. It is recommended to use with -p option while debugging.

-e

Uses only CP/M functions (see appendix).

Control functions

#opll_mode <0|1>

Specifies OPLL modes. 0 means FM 9 sound mode and 1 means FM 6 sounds + rhythm mode. If this command is not executed, all if other control commands(including MML) are not valid. Execute this first definitely.

#machine_id <0〜7>

Specifies vendor codes which the data made (compiled) for. When programs uses this vendor codes, volume balances are adjusted on every MSX vendors models. Vendor codes are preserved like below.

1:SONY 2:Panasonic 3:SANYO

Numerics other than these are invalid and should not be used. Use 0 (same as omitted) for other vendors.

#lfo_mode <0|1>

LFO mode. 1 makes fast LFO speed little bit. Default is 0.

#title <"string">

Specifies title name of the data. Multiple lines are valid if you use with "{" and "}". Maximum length is 1k byte, including comments or others.

Example:#title { "Falcom Ys morning grow" "SCC is needed" }

If you want to use double quotation in strings, repeat twice. If "Object too big" error occurs when exceed 80 characters in the title, usually it can be avoided with allocating track buffer (and reduce it lesser than automatic allocated bytes) with #alloc.

#alloc <track no. = bytes>

Allocates track buffers. Usually, track buffer is automatically allocated (16k/ all tracks(=16 or 18) bytes) when the track is used first time. If you use many tracks to write MML in, allocate bytes with this command.

Example:#alloc 0=100; Allocates 100 bytes to track 0

    #alloc {	3=100,

5=256 }

Allocates multiple track buffers at once

Sums of track buffers are limited upto 16k bytes. Track 0 is not used for MML, but tone settings or others. It is enough to use with default settings.

#psg_tune { notes data for c, c# ... b}

Change data for defining notes for PSG and SCC. Each data define for octave 1( range is from 0 to 4095 and needed for every 12 notes.) Commonly, it is not needed to set up.

#opll_tune { notes data for c, c# ... b}

Change data for defining notes for FM. Each data define for octave 1( range is from 0 to 511 and needed for every 12 notes.) Block information is not included. Commonly, it is not needed to set up. This command destroys parameters of @¥ command of MML(as a specification).

#tempo <57〜2047>

Sets tempo. It us valid in the source codes only once. It is recommended to use this rather than t command in MML when setting tempo at the first time as far as possible. Default is 120.

#macro_offset <definition_character = no>

Sets offset number of macro to a character from alphabet(A-Z). Commonly, definition of macros uses numeric 0-255, and this command makes purpose clearly recognizable by assigning offset number to characters.

Example:#macro_offset a = 32

    *48 = { cdefgab }

It is same as macro number 48, called with *a16.

    #macro_offset { a = 32,
                    c = 16 }
    *20 = { t150 }
    *40 = { v15 }
    *42 = { l16 }
    1 *c4*a8*a10

"t150v15l16" is written to track 1.

These definitions, such as *a16 etc are available in commands and MML which deals macro number. Be care full sums of offsets and value not to exceed 255 or duplication, because it translate simply these strings to macro number.

#play_start

Starts playing music after compiling. It is same as -p option of command line.

#no_mgs

Does not generate .MGS files. It is same as -n option of command line.

#track_status

Shows usage status of every tracks after compiling. It is same as -t option of command line.

#play_track

Plays only tracks specified when starts playing. It is valid only with MGSC. If it is omitted all tracks are played.

Example:#play_track 367ABR

It plays only track 3,6,7,A,B and R.

Note: this command only specifies tracks and does not play actually.

#end

Specifies the end of the source. MGSC stops to compile when it appears on the line. Actually <EOF> is recognized as the end if the source and this command can be omitted.

#disenable_mgsrc

Sets protection attribute not to be discompiled with mgsrc.com. It is not recommend to use this thoughtlessly ...

Macro definition

MGSC can define macro. Macro can be called with "*" MML command. Contents of macros are not retrieved when macro is defined and error occurs in the line which calls it.

Define macro at the top of the line like below.

  • <macro_number> = {strings}

The range of macro number are 0-255 (offset can be set). Lines can be multiple, if the end of the lines have "}". Redefinition (define same macro number more than twice) can not be allowed. The length of macros should be within 4k bytes.

Definition of program control strings

Define strings which are passed to external programs. This function can be used, for example, synchronizing external programs with playing musics etc. (by passing addresses to work area(MIB)). MGSEL shows strings on the screen with @m MML command.

Define it at the top of the line like below.

@m<define_number> = {"strings"}

Strings should be with quotations. The range of definition number are 0-127. If number is omitted, previous number(default 0) +1 is used. Control codes can be used with escape sign(¥) 40H added to character code you want. (¥C means ^C and ¥Z means ^Z).

Other examples are below.

¥¥ means¥

¥" means"

¥x?? character specified with hexadecimal number(2 digits).

Characters written after escape code are capitalized. ¥@ cannot be used because it is internal code for terminating strings. Strings are written to track 0. If you want define many strings, allocate track buffers previously with #alloc or others. Refer to manuals for control strings.


Tone definition

Tine definition has "@" at the top of the line. All of <number> means tone number. The range are 0-31.

@e<number> = { Mode,Noise,data...data }

Defines envelope data. It is the same format as _ESET in old versions of MGSDRV(which means MGSDRV ver2.xx).

(1) Mode Specifies tone/noise mode for PSG. The range is 0-3 and 1 is used when it is omitted.

0 - no specification (and nothing changed) 1 - only tone 2 - only noise 3 - tone and noise

(2) Noise

Specifies noise frequency for PSG. It is ignored if it is used for tracks other than PSG. It is valid when mide is more than 2. The range is 0-31. 0 is used when it is omitted.

Mode and Noise are set only when @ commands are executed.

(3) Data Specifies envelope data. It is allowed up to about 255 characters (depends on contents)

0〜f(hexadecimal)

Sets hexadecimal number as volume and waits one count. It is written as <volume> below.

<volume>
<counts>

Sets volume and waits counts.

<volume>=<counts>

Changes current volume automatically to specified volume within a time specified by counts.

n<noise frequency>

Changes noise frequency of PSG. It is same as Noise of (2).

/<mode> or *<mode>

Changes Mode of PSG. It is same as Mode of (1).

[

Defines start position of repetition.

]

Defines emd position of repetition.

@<tone_number>

Changes tone data. It is valid only for SCC and FM. It changes only tone data, not envelope. It should be defined tone data previously with @v(@s).

y<r>,<d>

Writes data<d> to register<r>, which actually uses envelope. It is ignored for SCC.

¥<n>

Adds <n> to current frequency. The range is -127 to 127. It rises frequency with positive number. Unit is the same as "¥" MML command.

.,

Separator. Place between numerics (example:n4.456789)

The range of the <count> is 2-239.

@r<number> = { Mode,Noise,AL,AR,DR,SL,SR,RR }

Defines envelope data.

 Mode ... same as@e.  Noise ... same as@e.


These are brief explanations below. The range of these values are 0-255.

AL

Volume at the moment of the key on. Bigger number, bigger volume.

AR

Speed of reaching to maximum volume(255) from key on. AR is added to AL every moment and DR processing starts when sum exceeds 255 in real processing.

DR

Speed of reaching to next SL from maximum point. DR is reduced from maximum point at every moment and SR processing starts when sum is less than or equal to SL real processing.

SL

Moving point from DR to SR.

SR

Speed of reducing volume. This value is reduced from SL at every moment. This processing continues until if volume become zero or key off.

Up to about 10 is appropriate because if you set huge number to this parameter, sound ends in a moment (if you wish it on some purpose).

RR

Speed of reducing volume from key off. RE is reduced from envelope volume which currently holded.

@r and @e

@r and @e shares working are to define, so both of them cannot be defined simultaneously. Latter one is valid, in such case.

@s<number> = { data1 .... data32 }

Defines tone data fir SCC. Data are hexadecimal(00-ff). Data should be 32 units and cannot be omitted.

Example:@s02 = { 7f7f7f7f 7f7f7f7f 7f7f7f7f 7f7f7f7f ;PSG 80808080 80808080 80808080 80808080 }

@v<number> = { data ... }

Defines original tone of FM.

Example:@v15 = { ;BRASS

  ;       TL FB
          25, 7,
  ;       AR DR SL RR KL MT AM VB EG KR DT
           8, 8, 1, 2, 0, 0, 0, 1, 0, 0, 0,
           8, 2, 1, 1, 1, 1, 0, 1, 0, 0, 0 }

Parameter format is same as _VSETC of the old versions of MGSDRV.

@#<number> = <n>

Changes assigned ROM tone number of the tone. MGSC assigns 1-15 of ROM tone to @0-14. Tones after @15 is assigned 0(original tone) and definition of tone is valid when <number> is more than 15. @# changes ROM tone number assigned to each tones. The range of <n> is 0-15 and 0 means original tone(refer about other numbers).


Comments

If ";"(semicolon) are found in the lunes(including MML), it is recognized as comment from the semicolon to the end of the line(CRLF) and ignored.