「LIBRARIES PUBLIC DOCUMENT MPK」の版間の差分

2017年8月7日 (月) 18:07時点における最新版

MPKLib_jp

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

何をするものか?

本パッケージはK-KAZ氏が製作したMSX用FM,PSG,SCC音源ドライバーMPKをHI-TECH Cから制御するためのライブラリです。HI-TECH CとMPKが別途必要です。

構成ファイル

MPK .H: 本ライブラリのヘッダーファイルです。
LIBMPK .LIB: 本ライブラリのライブラリファイルです。
HIMPKA.AS以外の拡張子ASのファイル: 本ライブラリの各関数ソースファイルです。
* .O: 本ライブラリの各関数オブジェクトです。
INSTALL .BAT: 本プログラムの各関数を任意のライブラリファイルに結合する為のバッチファイルです。
REMAKE .BAT: 本プログラムの再アセンブル用バッチファイルです。
MPKLIB .TXT: 本ファイルです。
HIMPK .COM: 本ライブラリのサンプルプログラムです。
HIMPK .C: 本ライブラリのサンプルプログラムソースのC言語部分です。
HIMPKA .AS: 本ライブラリのサンプルプログラムソースのアセンブラ部分です。
MKHIMPK .BAT: サンプルプログラム構築用バッチファイルです。
LICENCE .BAT: 本プログラムのライセンスに関するテキストファイルです。

セットアップ

まず、インクルードファイルのあるドライブ・ディレクトリにMPK.Hをコピーします。次に、ライブラリファイルのあるドライブ・ディレクトリにLIBMPK.LIBをコピーするか、INSTALL.BATを使って既存のライブラリに、本ライブラリの関数オブジェクトを結合することで、本ライブラリを使うことができます。

INSTALL.BATの使い方

INSTALL.BATは既存のライブラリファイルに本パッケージの各関数オブジェクトを結合するためのバッチファイルです。HI-TECH CのLIBR.COMが実行できる環境で、本ライブラリの各関数オブジェクトのあるドライブ・ディレクトリから

>INSTALL ライブラリファイル名

とすることで、ライブラリファイルに本パッケージの各関数オブジェクトを結合することができます。本パッケージの関数群は他の関数に依存することが無いので、ライブラリ内の配置はどこでも結構です。

再アセンブル法

本ライブラリの再アセンブルはREMAKE.BATを実行すればOKです。アセンブル後はINSTALL.BATを利用してライブラリファイルを作成して下さい。

本ライブラリの使い方

本ライブラリで、MPKを使う場合、次のような手順を取ります。

本ライブラリを使うプログラムでは、まず、MPK.Hをインクルードします。次に、本ライブラリの関数が使われる前に、MPK.BINを4000H以降の2000Hバイトのメモリブロックにロードし、タイマー割り込みをフックして、タイマー割り込みルーチンから4013H(MPKの演奏ルーチン)が呼び出されるようにします。その後、曲データをタイマー割り込みルーチンから見えるようにロードし、本ライブラリを使って、ドライバの初期化、演奏初期設定を行った後、演奏開始関数を呼ぶことで、とりあえず、HI-TECH CからMPK用のデータを演奏することができます。コンパイルする際には、本ライブラリの関数オブジェクトを収めたライブラリファイルをリンクするようにしてください。これで、本ライブラリを使って、HI-TECH CからMPK用のデータを演奏することができます。詳しくは、サンプルプログラムを参照してください。

サンプルプログラムについて

サンプルプログラムはHI-TECH Cをセットアップしたドライブ・ディレクトリにサンプルプログラムのソースファイルとライブラリLIBM.LIBを置いて、 MKHIMPK.BATを実行することで、コンパイルすることができると思います。なお、このファイルのコンパイルには、HI-TECH C Resource kit #2のMSX- DOS1用ディスク入出力関数とメモリ管理ユーティリティー関数がセットアップされていることが必要です。

サンプルプログラムは、HIMPK Data fileとすることで、Data fileを読み込んで演奏します。カレントディレクトリに MPK.BINが必要です。演奏開始後は、キーボード操作で、簡単な特殊演奏ができます。

キー	機能
P	演奏開始
S	一時停止
+	演奏速度を早くする
-	演奏速度を遅くする。
F	フェードアウト
V	全体のボリュームの調整
L	ループ回数の表示
Q	本プログラムの終了

本プログラムはライブラリのテスト用に作ったので、V1.03以前のMPKで製作された曲とV1.04以降のMPKで製作された曲でドライバを変更したり、フェードアウトのスピードを調節したりといった面倒な処理は実装していませんので、皆さんで実装に挑戦してみてはいかがでしょうか?

関数の説明

本ライブラリの関数について説明します。

unsigned int mpk_init(void);: MPKを初期化します。他の本ライブラリ関数の利用前に、必ず呼び出してください。

char mpk_initplay(void *data);: 演奏をするための初期設定をします。演奏データの先頭アドレスをdataに入れて呼び出します。帰ってきた値が0でないときは、エラーが発生しています。1のときは、データのバージョンエラー、2のときはその他のエラーです。

void mpk_stop(void);: 演奏を終了し、音源を初期化します。

void mpk_playspeed(char speed);: 早送り、スロー演奏、一時停止を行います。; speedが1以上のときは、n倍速、-1から-128で1/speed倍速演奏を行います。; speedを0にすると演奏の一時停止を行います。

void mpk_vol(unsigned char v);: 全体のボリュームをvで設定した音量に設定します。vは0から15までの値を取り、数字が大きくなるほど、音量が大きくなります。

void mpk_fadeout(unsigned char speed);: この関数の実行直後からspeedで指定した速度でフェードアウトして演奏を終了します。speedが大きくなるほど、フェードアウトスピードが遅くなります。

unsigned long mpk_getchannel(void);: 演奏に利用されているチャンネルの情報を得ます。; 帰ってきた値のBit0-8がFM音源のチャンネル1-9に、Bit9-11がPSG音源のチャンネル1-3に、Bit12-16がSCCのチャンネル1-5に対応し、各Bitが1のときは演奏中になっています。; また、Bit23が1のときは、リズムモード、0のときはFM9音モードになっています。

void mpk_play(void);: mpk_initplay関数を実行した後に、この関数を実行することで、演奏が始まります。

void mpk_setint(char f);: fを1にして呼び出すと、演奏中の割り込みを許可し、0で不許可にします。; 詳しくは、MPKのドキュメントを参照してください。

unsigned char mpk_getloops(void);: 演奏開始後のループ回数を返します。

void mpk_getinfo(struct mpkinfo *inf);: 引数で指定されたmpkinfo構造体に演奏情報を得ます。; mpkinfo構造体はMPK.Hで次のように定義されています。; この関数はMPK Version 0.99B以降で利用できます。

struct mpkinfo {
       unsigned int version; /* バージョン */
       unsigned char m_version; /* マイナーバージョン */
       unsigned char fm_slot; /* FM音源のスロット */
       unsigned char scc_slot; /* SCCのスロット */
       unsigned char *ver_mes; /* バージョンのメッセージのアドレス */
       unsigned char *play_info; /* 演奏情報アドレスの先頭アドレス */
};

各メンバーの値の意味に関しては、MPKのマニュアルを参照してください。

この関数はMPK Version 0.99B以降で利用できます。

void mpk_setchannel(unsigned long);: mpk_getchannel関数の返す値と同様の形式で、各チャンネルを演奏中にするかマスクするかを指定します。リズムチャンネルはFM7のビットで指定します。この関数はMPK Version 1.04以降で利用できます。

制限事項

MPKでは、メモリマッパーや常駐に対応していますが、本ライブラリはこれらの機能には対応しておりません。また、本ライブラリの機能をフル活用するには、Version 1.04以降のMPKが必要になります。

参考文献

MPK ver 1.06仕様書(By K-KAZ)
MSX2/2+早分かり小事典(日本文芸社)

謝辞

本ライブラリの開発にあたっては、ray-netの皆様、とくに、たろさん、みかせんさん、K-KAZさんにはいろいろとお世話になりました。この場を借りてお礼を申し上げます。

使用にあたって

本プログラムおよび、ソースコードはBSD copyright に従います。 BSD copyright については、同梱のLICENCE.TXTを参照してください。また、BSD copyrightの日本語訳は下記の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.
*/

@@ 85行目: / 85行目: @@
 ;unsigned int mpk_init(void);
- :MPKを初期化します。他の本ライブラリ関数の利用前に、必ず呼び出してくだ
+:MPKを初期化します。他の本ライブラリ関数の利用前に、必ず呼び出してください。
-さい。
 ;char mpk_initplay(void *data);