home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 15 / CD_ASCQ_15_070894.iso / vrac / mm010gus.zip / MM010.DOC < prev    next >
Text File  |  1994-01-09  |  21KB  |  442 lines
  1. MIDI-MASTER(TM) v0.10ß, General MIDI File Player, 7-Jan-94
  2. Copyright (C)1994 Cornel Huth - All Rights Reserved.
  3.  
  4.  
  5. Actual Limitations:
  6.  
  7. - MM.EXE is a beta release (0.10) MIDI player and, at this level, is only
  8.   a test-bed for the GUS (Advanced Gravis UltraSound) support code of Ruckus.
  9. - Interactive volume changes should be made gradually.
  10. - AM vibrato not 100% accurate (awaiting full specs before moving on).
  11. - FM vibrato has no specs to follow (awaiting full specs, but pretty close).
  12. - Does not operate in a Windows DOS box if the GUS Windows device driver
  13.   has been installed. Altering the ULTRASND= IRQ/DMA may work, but it is not
  14.   recommended. The normal result is a DMA timeout error.
  15. - Not all MIDI-performance events are currently supported (too many to list,
  16.   either way, but will be in later versions).
  17. - Programmer's inability to recall all actual limitations.
  18. - MIDI files > 64K not reliable. Results vary. Not recommended.
  19. - Notes sticking occasionally. Reducing voices (/X) may help (for now).
  20. - Device patch filenames are statically stored.
  21. - Single waveform size is limited to approximately 256K.
  22. - Single patch size is limited to approximately 256K.
  23.  
  24.  
  25. Actual Features:
  26.  
  27. - Command-line and interactive control of volume, volume response type,
  28.   AM (command-line only) & FM vibrato effects, overall balance, clock
  29.   (elapsed/time remaining), tempo (-50% to +200%), and screen display
  30.   (interactive only).
  31. - Displayed info includes current MIDI state and hardware state.
  32. - Selectable timer (on-board, PC timer-0, alt).
  33. - DMA transfer rate is calculated.
  34. - Both normal and low-rez patch loading (16- or 8-bit form).
  35. - Device memory-use & number of allocations detailed.
  36. - Single waveform size of approximately 256K.
  37. - Single patch size of approximately 256K.
  38. - Failsafe aborts around possible problem areas (both int 3 and int 0 --
  39.   int 3 are not trapped (use DEBUG with breakpoints on) but all int 0
  40.   are handled (either a real div/0, overflow, or a failsafe trap).
  41.   A state-dump is shown on all failsafe traps and the system restored
  42.   to a stable state.
  43. - Automatic detection and handling of Windows dual-sequenced MIDI files
  44.   with option to override.
  45. - Lots of command-line options to select play state, including MIDI channels,
  46.   MIDI events, pitchbend range, volume, volume response type, device memory
  47.   reserve, default patch select, active voices, and a few more.
  48.  
  49.  
  50. Fast Tips:
  51.  
  52. Read this entire document (has to be faster reading it than it was writing it).
  53. Use /L0 for log-response MIDI files (default is linear volume response).
  54. Use General MIDI L1-sequenced files for best results.
  55. Use /Q1 if you have 256K GRAM.
  56. Use /F1 to activate failsafe traps (defaults to off).
  57. Avoid switching log/linear response when playing.
  58. Avoid very low volume levels.
  59. Do not use AM vibrato (/o2 or /o3).
  60. Do not use MM from the Windows DOS box with the GUS drivers installed.
  61. Let me know of any serious problems. Provide lots of details.
  62.  
  63.  
  64. Mail:
  65.  
  66. E-mail address, BBS support info, and the error list is at the end of this
  67. document.
  68.  
  69.  
  70. ----------------------------------------------------------------------------
  71. MIDI-MASTER(TM) was developed using the Ruckus Toolkit. This toolkit will be
  72. made available on the support BBS in the Ruckus developer's conference in
  73. beta form soon. Shareware versions at the usual locations, but release will
  74. come months away from the initial beta versions.
  75.  
  76. This program contains the generic MIDI parser and the static LIB version
  77. of the GUS support code. The parser has some of the controller support and
  78. on hold. Full GM-performance support will be available by release.
  79.  
  80. Back to this program. Here's what you need (GUS):
  81.  
  82.  1. 286 or higher CPU - the GUS support code was written using
  83.     a few 286 instructions that made a world of difference.
  84.     Only high-end cards will have 286+ code. The AdLibs, OPL2s,
  85.     will run just fine with an 8088. 1MB of GRAM probably is
  86.     a good idea. Patches are loaded in native form (16-bit,
  87.     full sample), unless the command-line override option is used.
  88.  
  89.  
  90. Note: For a quick list of the available command-line options, start up
  91.       the program with a single ? parameter.
  92.  
  93.  
  94.  2. The following environment variables must be set:
  95.  
  96.     ULTRASND=260,7,7,11,11
  97.     ULTRADIR=F:\SND\_GUS
  98.     rem PATDIR=F:\SND\_GUS\MIDI   (not needed now)
  99.     rem DLXDIR=F:\PRG\ASM\R2\_DLX (not needed now)
  100.  
  101.     In other words, set the ULTRASND= eVar to something that
  102.     works for your system. The above is my setting. the ULTRADIR=
  103.     eVar is the location of the GUS directory. In this directory
  104.     must be the patch file directory, MIDI. Patch files must be
  105.     the current version (patch version 1.10). The old patch files
  106.     may not work (probably won't). Anyway, everyone should have
  107.     their GUS 2.06 disks by now. The new patches are on these disks
  108.     (5.5MB worth!).
  109.  
  110.  
  111. ----------------------------------------------------------------------------
  112. That's it. Basically, all you have to do is give it a filename.ext. But you
  113. do have these command-line options available:
  114.  
  115.      C>mm midifile.ext [/B /C /D /E /L /O /P /Q /R /T /V /W /X /Z]
  116.  
  117.         midifile.ext can be any valid DOS pathname to a valid MIDI file
  118.         sequenced for General MIDI. Alternate sequencer-support later.
  119.  
  120.         Esc at any time exits to DOS.
  121.  
  122.  
  123.  /Bn=0 to 24, default pitchbend range=2 semitones (0=disable pitchbend)
  124.  /Cn=0 to FFFFh, default channel mask=FFFFh (all MIDI channels on)(see /Wn)
  125.  /Dn=0 to 6, default device=5 [GUS] (this version of MM supports GUS only)
  126.  /En=0 to 7F00h, default event mask=7F00h (all MIDI events on)
  127.  /Ln=0 or 1, default volume response=1 linear, 0=log
  128.  /On=0 to 3, default LFOs off=0 (1=FMvib, 2=AMvib, 3=both)
  129.  /Pn=0 to 15, default drum channel=9 (0=no drums)(channels are 0-based)
  130.  /Qn=0 or 1, default patch quality mode=0 (max), 1=min
  131.  /Rn=-768 to 1023, default reserve=0 (neg for topdown reserve) [GUS]
  132.  /Tn=0 or 1, default timer=1 on-board timer, 0=PC 8253 timer0
  133.  /Vn=0 to 100, default music volume=50 linear & 90 log
  134.  /Wn=0 to 2 default=2 WDS extended-level, 1=base-level, 0=no WDS adjust
  135.  /Xn=14 to 32, default voices=32 [GUS]
  136.  /Zn=0 to 127, default program=0 (AcPiano), 999 for none
  137.  
  138.  
  139. Details on Command-Line Options:
  140.  
  141. /B - pitchbend range
  142.  
  143.         The default pitchbend range is 2 semitones. Increasing this makes
  144.         pitchwheel effects more noticable. 0 disables pitchwheel (see also
  145.         /E).
  146.  
  147. /C - channel mask/selector
  148.  
  149.         /C is to override the default channels selected. You can
  150.         enter either a hex, binary, or if you can figure it out,
  151.         decimal number here. Hex values must be followed with an "h",
  152.         and binary either a "b" or "y". For example:
  153.  
  154.                 /C3FFh  channels 0-9
  155.                 /C3F0h  channels 4-9
  156.                 /C111b  channels 0-2
  157.                 /CFFFFh          0-15 (all 16 MIDI channels)
  158.                 /C1111111b       0-6
  159.                 /C1000011111y    0-4,9
  160.                 /C01000011111b   0-4,9
  161.  
  162.         De-selected channels do not use any device memory. Using /C disables
  163.         WDS detection (see /W).
  164.  
  165. /D - device
  166.  
  167.         Currently MM supports the GUS only (device 5).
  168.  
  169. /E - MIDI event mask
  170.  
  171.         MIDI events range from 80h (note-off) to E0h (pitchwheel).
  172.         Only the most significant byte is current used by Ruckus.
  173.         Others should be as indicated below.
  174.  
  175.         For example:
  176.  
  177.                 /e7F00h         all MIDI events processed
  178.                 /e3F00h         all but pitchwheel
  179.  
  180.  
  181.       F E D C B A 9 8  76543210 FEDVBA98 76543210
  182.       0                11111111 00000000 00000000
  183.         1              pitchwheel change
  184.           1            channel after-touch
  185.             1          program change
  186.               1        controller change
  187.                 1      polyphonic after-touch (not used currently)
  188.                   1    note-on
  189.                     1  note-off
  190.  
  191. /L - linear/log volume response
  192.  
  193.         /L1 (default) selects linear response to volume info.
  194.         /L0 is for a log response. Most MIDI files can be played
  195.         in linear mode, even log-based ones. However, it is very
  196.         obvious when a linear-based MIDI file is played in log
  197.         form (very low volume, for one).
  198.  
  199. /O - LFO effects (letter O)
  200.  
  201.         /O selects what LFO effects to use. /o1 selects FM vibrato.
  202.         /o2 select amplitude vibrato (tremelo). /o3 selects both.
  203.         The default is off since these are not 100% accurate (yet)
  204.         since they have not been documented (yet).
  205.  
  206. /P - drum channel selector
  207.  
  208.         /P alters the drum channel. The default is 9. To use no
  209.         drum channel use /P0. The channel mask/drum channel is shown
  210.         under the channel number (0-F). 1 indicates that that channel
  211.         is active; 0 inactive. A P marks which channel is the percussive.
  212.  
  213. /Q - Convert patch waveforms to 8-bit before moving to device RAM
  214.  
  215.         /Q0 (default) loads all required patches in original form (16-
  216.         or 8-bit, whatever it is). /Q1 loads all patches in low-rez form.
  217.         MM cannot handle /Q1 when a patch is originally 8-bit (not likely
  218.         that you have any patches of 8-bit form). Later versions will allow
  219.         patch-based selection (e.g., load only patch#0 in 8-bit, etc.).
  220.  
  221. /R - reserve GRAM amount
  222.  
  223.         /R reserves a contiguous amount of device RAM so that you
  224.         can skip over selected parts of RAM or for limiting the number
  225.         of banks (on supported hardware) that are used. For example, if
  226.         you wanted to see if a MIDI file will load into a 256K of RAM,
  227.         se /R-768 (if you have 1MB of device RAM). Using a negative value
  228.         reserves in whole blocks only (i.e., -1 reserves 256K as does -256).
  229.         Positive values skip in actual amounts.
  230.  
  231. /T - timer selector
  232.  
  233.         /Tn selects either the PC timer (n=0) or the onboard timer (n=1,
  234.         default). The PC timer permits a very precise resolution (1 part
  235.         per million). The onboard timer is not so precise, at only 1 part
  236.         per 12500 (the alternate timer is 1 part per TBA). For high T/Q
  237.         (MIDI ticks/quarter note) values (say, over 192, 480 especially)
  238.         the PC timer is better.
  239.  
  240. /V - volume
  241.  
  242.         Volume to start at. Range is 1 to 99. Linear response mode will
  243.         use this in the same form. Log, also. The default startup volume
  244.         is 50 for linear and 90 for log. It is not recommended (currently)
  245.         to use much lower volume levels.
  246.  
  247.  /Wn=0 to 2 default=2 WDS extended-level, 1=base-level, 0=no WDS adjust
  248.  
  249. /W - Windows dual-sequence MIDI file adjust
  250.  
  251.         If a Windows MIDI file is detected, by default, the device's
  252.         capabilities are consulted to determine which sequence to play.
  253.         All devices but the OPL2/dual-OPL2 play the extended-sequencer
  254.         channels (0-9, drum on 9). The basic-sequencer plays channels
  255.         12-15, drum on 15. You can override the default sequencer selection
  256.         using the above values (where 0 disables WDS detection, 1 plays
  257.         channels 12-15 regardless, and 2 plays 0-9 regardless).
  258.  
  259.         WDS is also disabled whenever /C channel mask is used.
  260.  
  261. /X - number of voices
  262.  
  263.         The /Xnn is for the number of voices to use. The default is
  264.         32 (1-based). You can use any value from 1 to 32. The lower
  265.         this number the more likely that playing voices will be "stolen".
  266.         If the number of voices selected is out-of-range, the closest
  267.         in-range value will be used.
  268.  
  269. /Z - default patch
  270.  
  271.         The default patch is 0, acpiano.pat, and this patch is always
  272.         installed whether it's needed or not. To alter the default
  273.         patch use /Z where nn is 0 to 127. Values > 127 cause no
  274.         default patch to be loaded (can save about 64K of GRAM if
  275.         acpiano isn't used).
  276.  
  277. ?  - show help screen
  278.  
  279.         Shows some quick start info.
  280.  
  281.  
  282. ----------------------------------------------------------------------------
  283. Additional notes.
  284.  
  285. ┌──────────────────────────────────────────────────────────────────────────────┐
  286. │ MVL FEDCBA9876543210  <───▐▌───> AM T Tks T/Q . Msr B BPM -%+  Clock   Tick  │
  287. │                                  FM                              :           │
  288. │──────────────────────────────────────────────────────────────────────────────│
  289. │ -DEV- I/O C IQ Ti Vx DMA-xRate Rz GRAM  Free  Big  B0+ B1+ B2+ B3= Used  T/A │
  290. │                          K/sec        K     K    K      -   -   -      K     │
  291. └──────────────────────────────────────────────────────────────────────────────┘
  292.  
  293. The following is part of the displayed info. MV is the master volume (V/v
  294. alters volume), L is the log/linear toggle. The "FEDCB...0" is the channel
  295. map mask. Only those channels with a 1 below it are active. In the case of
  296. the drum channel, a P is used instead of the 1. 0 or blank means that
  297. channel is not being processed. See /C & /P for altering this. The < - >
  298. is the overall balance. The < > (or , . keys) adjust the balance. The numbers
  299. below this indicate the number of voices forced off during or prior to
  300. a sustain (left) and the number of voices doffed after a sustain (right).
  301. The latter is prefered. The more voices available the less voices stolen.
  302.  
  303. AM (command-line activated) and FM (CL or F/f key) are the tremelo and vibrato
  304. states. Bright letters indicate that effect as on. T is the MIDI file type
  305. (type-0 and -1 are supported). Tks is the number of tracks (up to 64 supported,
  306. 32 shown). T/Q is the number of MIDI ticks per quarter-note. . marks the
  307. location of the time signature of the piece. Msr/B is the current measure and
  308. beat. BPM is the calculated tempo (in beats/minute). The +/- keys let you
  309. adjust the tempo -50% to +200%. The C/c selects time elapsed or time remaining.
  310. This is calculated and will vary according to tempo changes. Tick is the
  311. current MIDI tick.
  312.  
  313. The device parameters include the device, I/O port, DMA channel, IRQ line,
  314. timer, and active voices. The DMA transfer rate, if applicable, is timed.
  315. Only the first transfer is timed.
  316.  
  317. GUS: When loading the default patch of the current GUS patches (patch 1.10),
  318. the acpiano.pat, the first sample is about 7340 bytes (or half that many
  319. words). Patches are typically loaded in patch number order. Rates of 600K/sec
  320. are typical on a 16-bit channel. Half that on an 8-bit DMA channel.
  321.  
  322. The amount of device RAM (less any negative /R) installed, amount "Free",
  323. and the largest block that can be allocated is shown. Also the amount of RAM
  324. used, by bank, and total amount used. T/A is the total allocations made:
  325. as in number of patches loaded (each patch uses a single allocation;
  326. allocations are made on a best-fit basis). Each bank uses a single 32-byte
  327. allocation for basic housekeeping (meaning that if T/A=6 and you have
  328. four RAM banks (GUS:1MB), then 2 patches have been loaded). This means that
  329. the actual largest patch that can be loaded is 256K less 32 bytes.
  330.  
  331. Several display screens are available. Use TAB/backTAB to select. These
  332. will be documented when all are completed/finalized.
  333.  
  334.  
  335. ----------------------------------------------------------------------------
  336. Contact:
  337.  
  338. You can contact me through the BBS, preferably in the developer's conference,
  339. or through my Fido point (Cornel Huth @ 1:387/800.8), or via Internet
  340. (chuth@lonestar.utsa.edu). As for other cards, the SB16 (CSP), PAS-16,
  341. Aria-based cards, and a refinement of the previous cards supported will
  342. also be in the toolkit. I'll keep a steady flow of alphas/betas in the
  343. onference's download area. Just keep me posted on any problems (it was
  344. over two weeks before I heard about the low DMA channel problem!).
  345.  
  346.         The Fortieth Floor BBS.
  347.         BBS support telephone: 1(210)684-8065. V.32bis (300-14.4k)
  348.         Hours: Monday through Friday, 5pm to 9am next morning
  349.                Weekend hours are 1pm to 9am next morning.
  350.                All times USA Central Time, about UTCtime-6
  351.  
  352.  
  353.  
  354. ----------------------------------------------------------------------------
  355. Error List:
  356.  
  357. Errors are reported in two values: the first is the section that generated
  358. the error, and the second is the error encountered. For example, STAT: 00:2
  359. is a DOS-generated error. Error 2 is file not found. 3 is path not found.
  360. 21 is device not ready. Consult a DOS manual for specifics. As another
  361. example, STAT: 03:31 is the error returned when attempting to use MM
  362. in a Windows DOS box when the GUS device driver is installed.
  363.  
  364.    ERR_DMATIMEOUT  EQU R2E+31  ;DMA transfer did not signal completion
  365.  
  366. R2E is 300h (from below, only the MSB is used) and 31 the error number.
  367. Put them together and you get 03:31.
  368.  
  369.  
  370. ;no section (00);DOS-generated
  371. RKE = 100h      ;kernal-related
  372. R2E = 300h      ;Ruckus-related
  373. RVE = 400h      ;Vox-related
  374. RME = 500h      ;MIDI-related
  375. RDE = 600h      ;Mod-related
  376. RPE = 700h      ;patch-related
  377.  
  378.                  
  379. ;DOS-type errors generated/returned by Rcukus
  380. ERR_UNXEOF      EQU -3      ;unexpected end of file DOS (65533)
  381. ERR_DISKFULL    EQU -2      ;disk full DOS              (65534)
  382. ERR_NOMEMORY    EQU 8       ;cannot allocate required memory from DOS
  383.  
  384.  
  385. ;kernal errors
  386. ERR_NOHANDLES   EQU RKE+04  ;no handles left from ss$Malloc for MCB
  387. ERR_BADHANDLE   EQU RKE+06  ;handle not valid from ss$Free for MCB/xms$ too
  388. ERR_MEMCORRUPT  EQU RKE+07  ;memory corrupt from ss$Malloc for MCB
  389. ERR_NOMEMKRN    EQU RKE+08  ;no/not enough memory from ss$Malloc for MCB
  390. ERR_NOMATCH     EQU RKE+09  ;EnvVar not found
  391. ERR_NOXMSMGR    EQU RKE+20  ;xms$Init called but no XMS manager installed
  392. ERR_XMS16MB     EQU RKE+21  ;XMS allocation crossed 16MB (no-go for ISA DMA)
  393.  
  394.  
  395. ;device init/access errors
  396. ERR_ILLEGAL_CMD EQU R2E+01  ;command code not valid
  397. ERR_NODEVICE    EQU R2E+02  ;device in context not detected
  398. ERR_DEVICEON    EQU R2E+03  ;device in context has already been installed
  399. ERR_DEVIRQ      EQU R2E+04  ;device in context fails IRQ test (NYI)
  400. ERR_DEVDMA      EQU R2E+05  ;device in context fails DMA test (NYI)
  401. ERR_NOMEMDEV    EQU R2E+08  ;device in context has no RAM available
  402. ERR_NOTINGEAR   EQU R2E+11  ;device in context has not been installed
  403. ERR_INGEAR      EQU R2E+12  ;device in context has already been installed
  404. ERR_DMATIMEOUT  EQU R2E+31  ;DMA transfer did not signal completion
  405. ERR_DMABADMODE  EQU R2E+32  ;DMA mode not valid for request
  406. ERR_DMABUSY     EQU R2E+33  ;DMA channel already in use
  407. ERR_DMAGRAM256  EQU R2E+39  ;GRAM 256K page crossing on DMA attempt [GUS]
  408. ERR_BADENVVAR   EQU R2E+91  ;requested EnvVar not found or incomplete
  409. ERR_BADPATH     EQU R2E+92  ;path+filename+ext > MAX_PATHSIZE
  410. ERR_MMSSCORRUPT EQU R2E+93  ;general memory manager is corrupt
  411. ERR_MMSSLOCKFAIL EQU R2E+94 ;general memory manager lock failed
  412. ERR_INVALID_TASK EQU R2E+99 ;internal error
  413.  
  414.  
  415. ;MIDI file errors
  416. ERR_MIDI_FORMAT EQU RME+01  ;file is not of type 0 or type 1
  417. ERR_MIDI_TRACKS EQU RME+02  ;file contains more too many tracks (more than 64)
  418. ERR_MIDI_TIMING EQU RME+03  ;file division timing not metrical
  419. ERR_MIDI_HEADER EQU RME+04  ;file does not start with "MT"
  420.  
  421.  
  422. ;patch/voice allocation errors          
  423. ERR_UNKPATHDR   EQU RPE+01  ;patch file does not start with "GF" [GUS]
  424. ;ERR_BADPATCH   EQU RPE+02  ;patch format not known
  425. ERR_UNKPATINS   EQU RPE+02  ;patch file contains more than 1 instrument [GUS]
  426. ERR_UNKPATLAYER EQU RPE+03  ;patch file contains more than 1 layer [GUS]
  427. ERR_NOMEMDMA    EQU RPE+06  ;no memory for temporary DMA transfer buffer
  428. ERR_NOCACHE     EQU RPE+07  ;patch permanent store/cache not available (XMS)
  429. ERR_NOMEMPATCH  EQU RPE+08  ;cannot allocate required patch memory
  430. ERR_BADPATCHNO  EQU RPE+21  ;melodic/drum patch number out-of-range or not loaded
  431. ERR_NOPATCHMAP  EQU RPE+22  ;drum patch number out-of-range (percCh ky# doesn't map)
  432. ERR_PATCHBOGUS  EQU RPE+23  ;patch contains out-of-bounds data  
  433. ERR_PATCHIS8    EQU RPE+24  ;patch is already in low-rez form
  434. ERR_BADLOOPADDR EQU RPE+25  ;loop points not valid
  435. ERR_PATCHINUSE  EQU RPE+26  ;patch number has already been allocated
  436. ERR_PATCHZERO   EQU RPE+27  ;patch number is not allocated/no patch data
  437. ERR_BADVOICE    EQU RPE+50  ;voice number not valid (user selected)
  438. ERR_VOICENA     EQU RPE+51  ;voice is not available (already in use)
  439. ERR_VOICEACTIVE EQU RPE+52  ;voice active (cannot unassign w/o force)
  440.  
  441. ;<EOF>
  442.