
MoonShell Plugin (MSP Format) Ver5.0 SDK 2006/12/28

MSPV20については下の方で。

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

新しいプラグインを作るための準備。

Imageプラグインならbmp辺り、Soundプラグインならwav辺りが、シンプルでテンプレート向きです。

./make_plug.bat

copy arm9\arm9.bin pluginname.msp

pluginnameは8文字以下のショートファイル名にしてください。
その下の2行は私のテスト用なので削除して構いません。

./arm9/specs/ds_arm9_mshlplg_crt0.s

対応拡張子とプラグイン名と制作者名を書き換えてください。

./arm9/source/main.cpp

元々ある関数をばさーっと削除して、新しいプラグインを書いてください。

・両方のプラグインで必要な関数一覧

Start/Free/GetInfoIndexCount/GetInfoStrL/GetInfoStrW/GetInfoStrUTF8

・ImagePluginで必要な関数一覧

RefreshScreen/GetWidth/GetHeight

・SoundPluginで必要な関数一覧

Update/GetPosMax/GetPosOffset/SetPosOffset/GetChannelCount/GetSampleRate/GetSamplePerFrame

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

注意とかできないこととか。

・標準ライブラリは使えません。

mallocやstrcpyなどはplugin.hとplugin_def.hを定義してから使ってください。
特に、stdlib.hとstring.hをインクルードすると重複してしまうので絶対にインクルードしないでください。
リンク時に_sbkkセクションが見つからないとか言われたときは大体標準ライブラリを使っているときです。
'->'が余分だとか言われるときは、string.hをインクルードしているときが多いです。

・空きメモリについて。

大きなフォントやスキンを使っていても、2MByteほどメモリが残っています。
プラグイン本体と（後述の）拡張定義ファイルはオンメモリで渡されますので、合計量は2MByteくらいを目安にしてください。
プラグイン起動後はMoonShell側でメモリを確保することはないので、ギリギリまで（safemallocがNULLを返すまで）使って大丈夫です。

・ITCMセクションは使えません。

まったく使えません。読み込みアクセスもしないでください。

・DTCMセクションの初期化済み変数は使えません。

static、global共にテーブルなどは実行時にメインメモリから転送して初期化してください。
ゼロ初期化もしません。初期値は未定です。
スタックもDTCMにいますので、容量に注意してください。10kbくらいなら大丈夫です。

・0x5e90を含む定数は使えません。

DLLパッチが誤動作します。どうしても使いたいときは./arm9/specs/ds_arm9_mshlplg.ldの中の、
	dlram	: ORIGIN = 0x5e900000, LENGTH = 4M - 4k
の0x5e90を使っていない定数に書き換えてください。（0x5e90は私が有り得なさそうな値を入れただけです）

・NDSの共有レジスタについて

基本的に自由に使っていただいて構いません。
DMA3は使用前と終了後にBusyフラグが降りていることを確認すれば使えます。
DMA0/1/2は割り込みで使用するので使わないでください。
VRAMレジスタは関数終了前に全て復帰することを保証するなら使えます。（割り込みでは使いません）

・サウンドバッファサイズについて

GetSamplePerFrame関数は一回のUpdateで処理するサンプル数を返します。
640サンプル以下は常に動作保証します。

周波数によりオーバーサンプリングファクタを自動調整します。
48000Hz以下の時は、4倍なので640サンプルが最大です。
96000Hz以下の時は、2倍なので1280サンプルが最大です。
192000Hz以下の時は、1倍なので2560サンプルが最大です。
モノラル1chのときは更にサンプル数の2倍が使えますが推奨しません。

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

拡張定義ファイルとか。

プラグイン起動時に、MSPファイル名と同じINIとBINがあるとメインメモリに読み込んでから起動します。
example : bmp.msp -> bmp.ini & bmp.bin
オンメモリで動作するので、あまり大きなファイルは置いておかないでください。

INIファイルの解析パーサーサンプルは、spcかmikmodプラグインのinifile.cpp/.hを参考にしてください。
BINファイルはvoid*です。サウンドフォントとかに使えるかも。
MoonShellとしてはどちらも単にバイナリを読み込んでポインタを渡しているだけなので何に使っても構いません。

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

MoonShellPluginVersion2.0(MSPV20)について。

プラグインの作り方は基本的にMSPV10と同じですが、GetBINFileHandleとmsp_fopenとmsp_fcloseが追加されています。

従来は拡張バイナリを使うためにGetBINDataを使っていました。この場合、全てのバイナリデータがメモリに展開されるため、メモリ容量以上のファイルは扱えませんでした。
GetBINFileHandleを使うと、通常のfseekやfreadなどが使えるようになります。
この関数で取得したファイルハンドルはmsp_fcloseで解放しないでそのまま終了してください。初期化や解放はMoonShell側で処理します。

msp_fopenとmsp_fcloseはプラグイン(.msp)が置いてあるフォルダにある任意のファイルを開くことが出来ます。
最大同時ハンドル数は４つくらいを目処にしてください。同時でなければいくつでも構いません。
msp_fopenで取得したハンドルは終了前にmsp_fcloseしてください。実際のアクセスは通常のfseekやfreadなどでOKです。

ヘッダファイルと実際の使用例は標準MIDIファイルプラグインのサウンドフォント辺りを参考にしてください。

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

MoonShellPluginVersion3.1(MSPV31)について。

タイム構造体の温度変数の名称が、Temperature16からTemperature12に変わりました。アドレスは一緒なのでソース中を置換すればOKです。
formdt_FormatDate関数が追加されました。MoonShell環境のユーザ指定文字列で日付文字列を生成します。

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

MoonShellPluginVersion4.0(MSPV40)について。

例によって基本的には同じですが、GBAカートの拡張メモリアクセス用インターフェースが追加されています。

最初に一度だけextmem_SetCountでスロットの数を決めて、あとは各スロットに対して処理します。
解放や再割り当てという概念はありません。プラグインが終了すると全てのメモリを解放します。

extmem_Existsは、メモリ割り当てがされているかどうかを返します。
extmem_Allocは、指定されたサイズのスロットを作成します。
extmem_Writeは、スロットに書き込みます。
extmem_Readは、スロットから読み込みます。

スロット読み書きで、新しくメモリを確保したりはしません。必ずスロットサイズ以上のメインメモリ領域を渡してください。


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

MoonShellPluginVersion5.0(MSPV50)について。

例によって基本的には同じです。（コピペ）
拡張メモリが使えない以外は、普通のサウンドプラグインと同じです。INIもBINも使えます。

必要な情報（周波数など）はStart関数が呼ばれたときだけ渡されますので、staticで保存しておいてください。
あとはUpdate関数で希望の処理をするだけです。
ボリュームを二倍にするだけの簡単なサンプルが'mspv50_sndeff_volumex2_plugintutorial/arm9/source/main.cpp'にありますので参照してください。

