-

LIBRARIES PUBLIC DOCUMENT MPK

From HI-TECH C for CP/M Fan WIKI(EN)
Jump to: navigation, search

MPK Interface Library for HI-TECH C By Tatsuhiko Syoji 1998

What is it for?

This package is library for controlling FM/PSG/SCC sound driver "MPK" by K-KAZ from HI-TECH C. HI-TECH C and MPK are required separately.

Files

MPK .H  
Header file of this library.
LIBMPK .LIB 
Library file itself of this package.
All of files which has .AS extension other than HIMPKA.AS are source file of each functions of this library.
* .O  
Objects of functions of this library.
INSTALL .BAT 
Bat file to append files of this library to other appropriate library.
REMAKE .BAT 
Bat file for re-assembling.
MPKLIB .TXT 
This file.
HIMPK .COM 
Sample program of this library.
HIMPK .C  
C language part of sample program for this library.
HIMPKA .AS  
Assembler part of sample program for this library.
MKHIMPK .BAT 
Bat file to build sample program
LICENCE .BAT 
License text of this library.

Setting up

Copy MPK.H to the directory of the drive which exist other include files. Next, copy LIBMPK.LIB to the directory and drive which exist library files or attach function objects to existed library by INST.BAT file.

How to use INST.BAT

INST.BAT is a bat file to attach functional object files of this library to appropriate library.

How to use INST.BAT

Copy INST.BAT which is a bat file to attach functional object files of this library to appropriate library. Object files of functions are appended to library file by typing 

>INST LibraryFileName

from directory and drive which has functional objects and is executable environment of LIBR.COM of HI-TECH C. Objects of functions in this package does not depend on any other libraries, thus it is locatable everywhere in library file inside.

Re-assembling

Simply execute REMAKE.BAT and make library files again by INSTALL.BAT.

How to use this library

This is the sequence to use MPK with this library.

Include MPK.H first, in file which use this library.

Next, load MPK.BIN, main routines of MPK into 2000H bytes memory block after address 4000H and hook timer interruption and set 4013H(playing routine of MPK) into timer interrupt routine.

After that, load song data where time interruption routine can see it, initialize the driver, initialize play setting and execute function to start playing. Thus we can play MPK data by HI-TECH C. Link library file which contains object of functions in this library when you compile. Refer sample program for details.

About sample program

Copy source files of sample program and LIBM.LIB to the directory and drive which exist HI-TECH C is set up. Then execute MKHIMPK.BAT file to start compile.

I suppose sample program can be compiled by executing MKHIMPK.BAT with LIBM.LIB at HI-TECH C ready drive and directory. MSX-DOS 1 disk I/O and memory managing functions in HI-TECH C Resource kit #2 are required to compile this sample file.

Sample file reads data file and plays as follows: "HIMPK.COM DATAFILE".

This requires MPK.BIN in current directory.

We can control music with keyboard after starting music.

Keys functions
P Starts music
S Temporarily stops music
+ Play faster
- Play slower
F Fades out
V Change volume of whole channels
L Display Loop Times
Q Quits program

This program is made for testing of the library and does not implement complicated processing like switching driver for music data before v1.03 and v1.04 after, or fade out speed control etc. How about these implementation?

Functions

These are the functions of this library

unsigned int mpk_init(void);
Initializes MPK. This function should be called before execution of other functions.
char mpk_initplay(void *data);
Initializes playing music. Call it with top address of music data as argument data. If it returns other than 0, error occurs. 1 means version error of data and 2 means other errors.
void mpk_stop(void);
Stops playing music and initialize sound devices.
void mpk_playspeed(char speed);
Does forwarding, slow playing and temporary stop. If speed is more than 0, plays music with n times faster. If speed is between -1 and -128 plays music with 1/speed times. If speed is 0 stops playing music.
void mpk_vol(unsigned char v);
Sets master volume of all channels with valuable "v". Valuable "v" takes 0-15 and 15 is maximum volume.
void mpk_fadeout(unsigned char speed);
Soon after this function is executed, start fading out with speed specified with valuable "speed" and finish playing music. More bigger valuable "speed" is set, slower fades out.
unsigned long mpk_getchannel(void);
Gets channel information which is used to play music.
Bits of returned value means channels retrospectively.
Bit 0-1 means FM channel 0-8.
Bit 9-11 means PSG channel 1-3.
Bit 12-16 means SCC channel 1-5.
When musics are playing, every bits for used channel has 1.
Bit 23 represents rhythm mode. 0 means FM 9 sound mode.
void mpk_play(void);
Starts playing music by this function after mpk_initplay is executed.
void mpk_setint(char f);
Interruption is allowed it is called with 1 in valuable f and prohibits when f is 0. Refer MPK manual for details.
unsigned char mpk_getloops(void);
Returns loop times since music has started.
void mpk_getinfo(struct mpkinfo *inf);
Gets values about playing information into mpkinfo structure. Mpkinfo structure is defined as below in MPK.H.
MPK Version 0.99B or higher is needed to use this functions.
struct mpkinfo {
       unsigned int version; /* Version */
       unsigned char m_version; /* Minor version */
       unsigned char fm_slot; /* Slot number of FM */
       unsigned char scc_slot; /* Slot number of SCC */
       unsigned char *ver_mes; /* Address of version message */
       unsigned char *play_info; /* Top address of playing information address */
};
Refer MPK manual for details of each member.
MPK Version 0.99B or higher is needed to use this functions.
void mpk_setchannel(unsigned long);
Specifies playing or masking each channels by same format as return of mpk_getchannel function. Rhythm channel is specified by a bit of FM7. MPK Version 1.04 or higher is needed to use function.

Limitation

This library does not use memory mapper and is not memory resident, MPK itself covers these functions though. MPK Version 1.04 or higher is needed to use functions of this library totally.

References

  • MPK ver 1.06 specification(By K-KAZ)
  • MSX2/2+ Hayawakari Shoujiten(by Nihon Bungeisha)

(En: Pocket encyclopedia of MSX2/2+ quick learning)

Thanks to

All of ray-net, especially, Taro san, Mukasen san and K-KAZ san. Thank you for everything that you have done for me.

NOTE

These programs and source codes are unders BSD copyright. Refer LICENSE.TXT about BSD copyright in this package. Japanese translation of BSD copyright is published at this URL. http://openlab.etl.go.jp/freesoft/BSD-j.htm

/* 

* Copyright (c) 1998-2000 Tatsuhiko Syoji, Japan . All rights reserved.
* 
* Redistribution and use in source and binary forms, with or without 
* modification, are permitted provided that the following conditions are 
* met:
* 
* 1 Redistributions of source code must retain the above copyright notice,
*  this list of conditions and the following disclaimer as the first lines
*  of this file unmodified.
* 
* 2 Redistributions in binary form must reproduce the above copyright 
* notice, this list of conditions and the following disclaimer in the 
* documentation and/or other materials provided with the distribution.
* 
* THIS SOFTWARE IS PROVIDED BY Tatsuhiko Syoji ``AS IS AND ANY EXPRESS 
* ORIMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
*  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
*  DISCLAIMED. IN NO EVENT SHALL Tatsuhiko Syoji BE LIABLE FOR ANY DIRECT,
*  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 
* (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 
* SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 
* STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 
* IN
*  ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
* POSSIBILITY OF SUCH DAMAGE.
*/
Retrieved from "http://hi-tech.msx.click/en/index.php?title=LIBRARIES_PUBLIC_DOCUMENT_MPK&oldid=320"