WonX - WonderWitch on X.

■ 配布に当たって

ご意見，ご要望など歓迎します．どしどしお寄せください．
バグ情報やアドバイスがあれば，作者の坂井弘亮まで，どんどんメールください．
アドレスは，
sakai@seki.ee.kagu.sut.ac.jp
hsakai@pfu.co.jp
です．
(ただし，返事を書くとは限らないし，要望を反映するとも限りませんので
 その点はご容赦ください)
また，坂井の気が向く限り，アップデートは随時行っていきます．
http://www.seki.ee.kagu.sut.ac.jp/~sakai/WonderWitch/index.html
で，随時公開していきます．

■ はじめに

WonX は，WonderWitch 用のプログラムを X アプリケーションとしてコンパイルする
ための，ライブラリです．以下の特徴があります．

・C言語レベルで互換機能を持っているので，WonderWitch 用のプログラムを
  UNIX上でそのままコンパイルできる．(-lwonx でコンパイルする)
・UNIX上でデバッガを使用してデバッグできるようになる．(強力!)
・キャラクタデータやパレットデータのダンプ機能がある．
・不正な引数の値や，パレットやキャラクタを初期化しないで使用するなどを
  厳しくチェックし，エラーを出力する(ようにする)．厳しくエラーチェックする．
・使用できない機能(関数は用意してあるが，まだ実装してなかったり，
  実装が困難だったりして，中身が空のもの)はたくさんある．
  徐々に追加していくつもり．
・ゲームの画面写真が簡単に撮れる．(デジカメで撮ったり，画像取り込み用の
  プログラムを使ったりする必要が無くなる) これはわりとべんり．
・エミュレータでなくライブラリであり，ソースコード公開しているので，
  自由にカスタマイズが可能．
・描画速度は遅いが，デバッグ目的のためなので，速度を速くすることは
  あまり考えていない．(それよりも上記のデバッグ性を優先する)
・WonderWitch 用のプログラムを，X上で楽しむためのものではない．
  また，エミュレーションが目的なのではない．
  あくまでデバッグ目的のもの．(そういうポリシーで開発を進める)
  従って，WonderWitch での動作を模倣することよりも，デバッグ情報を
  出力することや改造のしやすさを優先したような実装をする場合がある．

■ 必要なもの

WonX では，以下のものを使用しています．

・perl
  (WonderWitch用ソースコード → WonX用ソースコードの変換用 perl スクリプトを
   添付しているので，WonderWitch用ソースコードの中に漢字が入っているのならば，
   日本語 perl が望ましい)
  添付の perl スクリプトは，すべて #!/usr/local/bin/perl になっているので，
  日本語 perl が別のところにあるばあいには，修正してから使用してください．
  日本語 perl が無ければ，まあ，ふつうの perl でもたぶん大丈夫でしょう．
・qkc
  漢字コード変換，改行コード変換に必要．
  (nkf でもべつにいいんだけど，qkc だと改行コードも変換してくれるので，
   この文書では qkc を使用しています)
  qkc は，以下のサイトから入手できます．
  http://hp.vector.co.jp/authors/VA000501/index.html
  qkc には，MS-DOS 版，Windows 版，UNIX 版などがありますので，
  UNIX 版(qkcc100.zip)を入手してください．
  コンパイルは，make するだけなのでとっても簡単です．
・unzip
  添付の smac-b02.zip, wwterm-b05.zip を解凍するのに必要．

このマニュアルは，以上のものがすべてインストールされていることを前提として
説明を進めます．必要ならばインストールするか，他のアプリケーションで
代用してください．

■ 3分WonX

とりあえず，どんなものか見てみたいことでしょう．そんな人は，
サンプルプログラムをコンパイル・実行してみましょう．
以下のようにしてみてください．

~>% tar xvzf wonx-x.x.tar.gz
(中略)
~>% cd wonx

~/wonx>% make sample1
(中略)
~/wonx>% ./sample1

ウインドウが開いて，標準出力にメッセージが出力されます．
スペース・バーを押すと，終了します．

~/wonx>% make sample2
(中略)
~/wonx>% ./sample2

カーソルキーの上下で，キャラクタを移動します．
スペース・バーを押すと，終了します．

~/wonx>% more sample1.c
~/wonx>% more sample2.c

で，サンプルプログラムのリストを見てみましょう．

次に，WonderWitch 用のゲーム，"SpeedMac" をコンパイル・実行してみます．

~/wonx>% make smac
(中略)
~/wonx>% cd smac
~/wonx/smac>% ./smac

ウインドウが開いて，標準出力にメッセージが出力されます．
いったん F10 を押して画面描画を OFF にします．しばらくしたら
(メッセージの内容が変わったら) F10 を押して再び画面表示を ON にすると，
smac のタイトル画面が表示されます．
ここでスペースを押して，さらにまた F10 で画面表示を OFF にして，
しばらくしたら(メッセージの内容が変わったら) F10 で画面表示を ON にします．
どうですか？ SpeedMac のゲーム画面が表示されているでしょうか？
カーソルキーで移動，スペースキーで射撃です．
ただし，キー入力はキー入力用関数が呼ばれたときしか有効ではないので，
キーは反応するまで長めに押してください．
F10 を押して頻繁に描画の ON, OFF を切替えるのは，描画が非常に遅いため，
ONのままだと画面クリアとかに異常に時間がかかるからです．

最後に，WonderWitch 用の端末エミュレータ "WWTerm" をコンパイル・実行
してみます．

~/wonx>% make wwterm
(中略)
~/wonx>% cd wwterm
~/wonx/wwterm>% ./terminal

■ 10分WonX

次に，なにかあなたが作った WonderWitch 用のプログラムを WonX 使って
コンパイル・リンクして，X Window System 上で動作するような実行形式を
作ってみましょう．

まず，WonX を展開して，make してください．libwonx.a ができあがります．

~>% tar xvzf wonx-x.x.tar.gz
(中略)
~>% cd wonx
~/wonx>% make
(中略)
~/wonx>% ls libwonx.a
libwonx.a
~/wonx>% 

次に，libwonx.a と，wonx_include ディレクトリと，
challsrc.sh, filters.pl, sys2wonx.pl, int2sint.pl をあなたの作ったプログラムの
ディレクトリ(ここでは例として，yoursample とします)にコピーします．

~/wonx>% cp -R libwonx.a wonx_include ../yoursample
~/wonx>% cp challsrc.sh filters.pl sys2wonx.pl int2sint.pl ../yoursample
~/wonx>% cd ../yoursample
~/yoursample>% 

*.C というファイル名のファイルがあったら，*.c に変更します．
(*.C だと C++ のプログラムだと思われてしまうので)

~/yoursample>% mv SAMPLE2.C sample2.c

あなたの作ったプログラムのすべてのファイルに対して，以下のことを行います．
・MS-DOS テキスト形式から UNIX のテキスト形式に変換する．
  (つまり，改行コードを \r\n から \n に変換して，漢字コードを SJIS から
   EUC に変換します)
・プログラム中の #include <sys/disp.h> のようなのを，
  #include "wonx_include/disp.h" に変更する．(sys2wonx.pl を通す)
・デフォルトの int を，short int に変換する．(int2sint.pl を通す)
これらのフィルタをまとめて通してくれる filters.pl というスクリプトを
添付してあるので，以下のようにして，すべてのソースファイルに対して，
必要なフィルタを通してください．

~/yoursample>% ./filters.pl "qkc -e -u" ./sys2wonx.pl ./int2sint.pl -f *.[ch] [Mm]akefile* MAKEFILE*

もしくは，以下のようにしてもよいです．

~/yoursample>% ./challsrc.sh *.[ch] [Mm]akefile* MAKEFILE*

(注意! filters.pl や challsrc.sh は，ファイルの本体を書き換えてしまうので，
 変更されると困るようなファイルは必ずバックアップしてください)

makefile を以下のように修正する．
・コンパイラには gcc を使用する．
・オブジェクトファイルを *.obj から *.o に変更．
・コンパイルフラグに -I. -L. -L/usr/X11R6/lib -lwonx -lX11 -lXt を追加．
・mkfent などによる *.fx ファイルの作成などがあったら，コメントアウトする．

~/yoursample>% emacs makefile

おそらく，makefile の修正が２番目に面倒です．(一番面倒なのは，WonX がうまく
適用できなかったときのソースの修正です)
添付の makefile_for_smac や makefile_for_wwterm を参考にして，makefile を
修正してください．

最後に，make をします．

~/yoursample>% make

うまくいけば，一撃でコンパイルが通って，実行できます．

~/yoursample>% ./sample

■ WonX 概要

WonX は，WonderWitch の display_control() とか display_status() といった
関数(BIOS に対するシステムコール)と代替の関数を持っています．
これらの関数は，X上にウインドウを開いて，そこで WonderWitch と互換の動作を
するように書いてあります．

WonX を make すると，libwonx.a というライブラリができます．
で，WonderWitch 用のプログラムを，UNIX 上で -lwonx してコンパイルしてやれば，
WonderWitch の display_control() とかのかわりに，WonX の display_control() が
リンクされ，X 上で動作するようになる，という仕組みです．

■ ヘッダファイルについて

WonX は，UNIXシステム上にある libc を使用します．つまり，/usr/include の
下を include します．
また，WonderWitch には，sys/types.h などといったヘッダファイルがあります．
よって，WonderWitch のヘッダファイル構成をそのまま WonX に引き継ぐと，
WonX のヘッダファイルと UNIX のヘッダファイルがコンフリクトする
可能性が出てきます．
(たとえば，WonderWitch の sys/types.h と /usr/include/sys/types が
 コンフリクトする，などです)
これは，WonderWitch用のアプリケーションをコンパイルするときに，要注意です．
コンパイルがうまくとおらないという障害の原因は，ほとんどがこのような，
「ヘッダファイルのコンフリクトもしくは誤認」に起因しています．

対策として，WonX では wonx_include というディレクトリの下にヘッダファイルを
格納してあります．(本当は sys というディレクトリにしたかったが，
上記の対策のため，このようにした)
WonderWitch 用プログラム中の，
#include <sys/types.h>
のような部分は，すべて，
#include <wonx_include/types.h>
のように修正する必要があります．
(stdio.h や stdlib.h は，UNIX システム付属のものを使用するので，
 そのままでかまいません)
(ただし，コンフリクトしないという絶対の自信があるなら，この限りではありません)
WonderWitch のプログラムの，#include <sys/*.h> は，すべて
#include <wonx_include/*.h> に修正する必要がある，ということです．
(これをまとめて行うための sys2wonx.pl という perl スクリプトを添付して
 あります．./filters.pl ./sys2wonx.pl -f *.[ch] を実行すると，ごっそりと
 書き換えてくれます)

また，UNIXシステムによっては，/usr/include/sys/types.h で ushort, ulong を
定義しているものといないものがあります．よって，コンパイル中に
ulong が２重定義されているとおこられる場合があります．
このあたりの微調整には，wonx_include 以下のファイルを直接修正して
調整してください．wonx_include/system_configure.h を修正することにより，
調整できるようになってます．

■ WonX のコンパイル

まず WonX をコンパイルして，libwonx.a を作成する必要があります．
WonX のコンパイルは，以下の手順で行います．

1. WonX を展開する．

~>% tar xvzf wonx-x.x.tar.gz
~>% cd wonx
~/wonx>% 

2. WonX を make する．

~/wonx>% make
gcc -c WWCharacter.c -O -I. -I/usr/X11R6/include
gcc -c WWColorMap.c -O -I. -I/usr/X11R6/include
...(中略)...
gcc -c wonx.c -O -I. -I/usr/X11R6/include
ar ruc libwonx.a WWCharacter.o WWColorMap.o WWDisplay.o WWLCDPanel.o WWPalette.o WWScreen.o WWSprite.o WonXDisplay.o XDisplay.o disp.o text.o key.o system.o timer.o etc.o wonx.o
~/wonx>% ls lib*
libwonx.a
~/wonx>% 

ここまでで，ライブラリの作成は終りです．

■ WonderWitch 用アプリケーションのコンパイル

次に，WonX の利用の例として，拙作の SpeedMac という WonderWitch 用の
ゲームをコンパイルしてみます．
(SpeedMac はサンプルプログラムとして，WonX に標準添付してあります)
SpeedMac は WonderWitch 用のゲームプログラムです．本来は WonderWitch を
使用してコンパイルし，WonderSwan 上でゲームを楽しむためのものです．
今回は例として，SpeedMac に WonX をリンクして，X 上で動作する SpeedMac の
実行形式を作成してみます．

1. 展開する．

~/wonx>% unzip smac-b02.zip
...(中略)...
~/wonx>% cd smac-b02
~/wonx/smac-b02>% 

2. ヘッダファイルと libwonx.a をコピーする．

~/wonx/smac-b02>% cp -R ../wonx_include .
~/wonx/smac-b02>% cp ../libwonx.a .
~/wonx/smac-b02>% 

3. ソースを修正する．

~/wonx/smac-b02>% emacs chara.c
~/wonx/smac-b02>% emacs dsp.c
... (ファイルをひとつひとつ修正する)

MS-DOS のファイル形式になっているファイルは，UNIXのテキスト形式に
変換します．具体的には，以下の変換をします．
・改行コードを \r\n から \n にする．
・漢字コードを SJIS から EUC にする．
qkc というアプリケーションで，上記のことを一度に行うことができます．
面倒なかたは，以下のようにすれば，まとめて変換されます．
~/wonx/smac-b02>% ./filters.pl "qkc -e -u" -f *.[ch]
qkc が無い人は... nkf とかてきとうに使って変換してください．

また，ソース中の，
#include <sys/disp.h>
#include <sys/key.h>
のような部分を，
#include "wonx_include/disp.h"
#include "wonx_include/key.h"
のように修正します．

これをまとめてやるための perl スクリプト (sys2wonx.pl) を添付してあるので，
面倒なかたは，
~/wonx/smac-b02>% cp ../filters.pl ../sys2wonx.pl .
~/wonx/smac-b02>% ./filters.pl ./sys2wonx.pl -f *.[ch]
のようにしてください．
(filters.pl は，引数で指定したファイル自体を書き換えてしまうので注意)

さらに，WonderWitch では sizeof(int) == sizeof(short int) ですが，
UNIX ではふつうは sizeof(int) == sizeof(long int) なので，
キャラクタのビットマップなど，int 型のバイトサイズに依存する部分で
int を使用している場合には，short int などと明示します．

これをまとめてやるための perl スクリプト (int2sint.pl) を添付してあるので，
面倒なかたは，
~/wonx/smac-b02>% cp ../int2sint.pl .
~/wonx/smac-b02>% ./filters.pl ./int2sint.pl -f *.[ch]
のようにしてください．
(filters.pl は，引数で指定したファイル自体を書き換えてしまうので注意)

日本語 perl は EUC コードでないと正常に動作しないので，
sys2wonx.pl や int2sint.pl を使用する場合には，まず先に qkc で漢字コードを
EUC に変換してから，sys2wonx.pl や int2sint.pl を使用してください．

4. makefile を修正する．

~/wonx/smac-b02>% emacs makefile

以下のように修正します．

・漢字コードを EUC に，改行コードを \r\n から \n に変換する．
  (改行コードを変換しないと make が正常に動作しません．qkc を通すと
   いいでしょう)
・gcc でコンパイルをするように修正する．このときに，コンパイルオプションに，
  -I. -L. -L/usr/X11R6/lib -lwonx -lX11 -lXt
  を追加する．
  (必要なら，-g も追加する)
・mkfent によるファイルのコンバートなどがあったら，削除する．

修正後の makefile を添付してあるので，面倒なかたは手で編集するかわりに，

~/wonx/smac-b02>% mv makefile makefile.orig
~/wonx/smac-b02>% cp ../makefile_for_smac ./makefile

のようにしてコピーしてください．

5. make する．

~/wonx/smac-b02>% make
gcc -c chara.c -g -I.
gcc -c game.c -g -I.
...(中略)...
gcc -c main.c -g -I.
gcc -g -o smac chara.o game.o man.o mansub.o mansub2.o map.o mapsub.o menu.o monster.o picture.o player.o smac.o stage.o dsp.o etc.o main.o -lwonx -lX11 -lXt -L. -L/usr/X11R6/lib
~/wonx/smac-b02>% ls smac
smac
~/wonx/smac-b02>% 

6. smac を起動する．

~/wonx/smac-b02>% ./smac

と，ここまでけっこう面倒ですが，実は，

~/wonx>% make smac

すると，これらの作業を全部やってくれるようになってます．

■ 操作

smac を起動すると，ウインドウが開きます．また，ターミナルには，
以下のデバッグ用の情報が表示されます．

・WonderWitch の代替関数が呼ばれると，引数と戻り値を表示します．

またここでは，以下の操作が行えます．

・カーソルキーが，WonderSwan のX1～X4ボタンに対応している．
・i,j,k,l キーが，WonderSwan のY1～Y4ボタンに対応している．
・スペースバーと左シフトキーが，A,Bボタンに対応している．
・sキーが，STARTボタンに対応している．
・F1 を押すと，LCDカラーマップのデータをダンプ出力する．
・F2 を押すと，パレットのデータをダンプ出力する．
・F3 を押すと，キャラクターのデータをダンプ出力する．
・F4 を押すと，スプライトのデータをダンプ出力する．
・F10 を押すと，表示/非表示モードを切替える．
  (非表示だと画面への描画を行わないが高速)
・F11 で10秒間停止．(画面写真をとるときなどに利用できる)
  (F11は短めに押してください．長めに押すと，復帰しなくなるようです)
・q もしくは Ctrl-c もしくは F12 で強制終了．
・Ctrl-i でアイコン化．

デフォルトではなにか関数が呼ばれるたびに画面の再描画を行うため，
非常に低速です．
たとえば，以下のようなことをやっていると，非常に低速になります．

/* 画面のクリア */
for (y = 0; y < 32; y++)
  for (x = 0; x < 32; x++) {
    screen_fill_char(0, x, y, 1, 1, 0); /* ここで毎回再描画される */
  }
}

このような場合は，F10 を押して非表示モードにして，ループ処理が終ったら
再び F10 を押して表示モードに戻してください．

F1 や F2 を押すと，データをダンプ出力するのですが，標準ではその他にも
メッセージが大量に出力されているので，ふつうに F1 を押しただけでは，
あっというまに大量のメッセージに流されてしまうことがあります．
このようなときは，以下のようにして起動します．たとえばコンパイルして
smac という実行形式ができているのなら，

> smac | grep -v call

もしもキャラクタ番号10番のキャラクタのデータだけが見たい場合には，
以下のように実行してから，F3 キーを押せば良いでしょう．

> smac | grep "character\[010\]"

WonX は，メッセージを出力する際に，grep でフィルタリングできるように，
かならず出力メッセージの先頭に，統一性のある文字列を追加しています．
たとえば，関数呼び出し時に表示されるメッセージには，先頭に必ず
"call" という文字列が追加されてます．よって，grep -v call を通せば，
関数呼び出しのメッセージがごっそり出なくなる，というようになってます．

標準では大量のメッセージが出てくるので，grep をうまく使うようにしてください．
もしくは，

> smac | grep call > function_call.log

のようにして，ログをとるのも有効でしょう．

> smac > /dev/null

だと，文字列を kterm などに表示しないぶん，高速になります．

■ 足りないもの

以下のものにはまだ対応してません．したがって，例えばサウンド関連の
関数を呼び出しても，何も起こりません．(空の関数になっている)

・サウンド
・プロセス
・インダイレクトライブラリ

■ 注意しなければならないこと

WonX は，本来は WonderWitch 用として書かれた(もしくは，書かれる)プログラムを，
UNIX 上でコンパイル・リンクするためのライブラリであり，ハードウエアを
エミュレートするものではありません．
ですから，WonderWitch と UNIX 上のC言語のギャップのため，気をつけなければ
ならないことがいくつかあります．これらは WonX の性質上，仕方の無いことです．

以下のことは，意識することと，きれいなプログラムを書くことで，
かなり回避できると思います．(ビットマップ操作などで，short int にすべき
ところでは，省略せずにちゃんと short int と明示するとか)

まあ，WonX の目的は論理的なバグを早い段階で無くすことと，
論理的バグとハードがらみのバグを切り離して原因を狭めることと，
坂井が電車の中でも WonderWitch のプログラムを書けるようにすることにあるので，
このへんはそういうものだと割り切って使ってください．
WonX を使う限り，なるべく機種依存を無くすように心がけましょう．
(とくに int のサイズにあまり依存しないようにしましょう)

[コンパイルの問題]

先にも書きましたが，コンパイルできないという障害が出たら，原因はたいていは
ヘッダファイルのコンフリクトです．とくに，WonderWitch で sys 以下の
ファイルをインクルードしている場合は注意してください．
ushort, ulong などは，sys/types.h で定義されているシステムもあるし，
そうでないシステムもあります．このへんは，wonx_include/system_configure.h で
調整してください．
(FreeBSD では ushort のみ定義されているが，RedHat Linux では，
 uchort, ulong ともに定義されているので，そのままだとコンパイル中に
 ２重定義のワーニングが出ます)

[int 型の扱い]

WonderWitch では sizeof(short int) == sizeof(int) < sizeof(long int) ですが，
UNIX ではふつう sizeof(short int) < sizeof(int) == sizeof(long int) です．
このことは，int 型を単なるカウンタとして使用するような場合には問題に
なりませんが，ビットマップの格納場所として使用するようなときには，
問題になります．
一番問題になりやすいのは，キャラクタのビットマップを扱う場合です．
(bmpcnv を使用して，ビットマップデータの出力が unsigned int bitmap = {
 のようになっている場合など)
font_set_colordata()などは，16*8 バイトのキャラクタデータを
short int 型の配列として引数に持ちます．WonderWitch では
sizeof(short int) == sizeof(int) なので，WonderWitch 用のプログラム上では，
キャラクタデータを short int とせずに，int 型の配列として定義してしまう
ことが考えられます．(当然 WonderWitch ならば問題は無いが，UNIX 上で
実行したら，キャラクタに妙な縞々が入るだろうと思われる)
このような場合には，UNIX 上でコンパイルするときには，コンパイラオプションで
デフォルトの int は short int になるように指定するか，もしくはソース中の
int を short int にじかに修正する必要があります．i386 上で gcc を使用する
場合には，このようなコンパイラオプションは無いので，じかにソースを修正する
ことになります．
int2sint.pl を通すと，明示されていない int はすべて short int に変換しますが，
もしもあなたが int2sint.pl が信用できなければ，手で修正してください．ふつうは
キャラクタのビットマップデータとそれを扱う部分のみを修正すれば十分でしょう．

コンパイル時のワーニングもちゃんと確認してください．また，コンパイル時には
-Wall オプションをつけましょう．
wonx-2.1 からは，キャラクタのビットマップ設定関連(font_set_colordata()など)
の関数の引数は，適切な型のポインタに修正したので，コンパイラがワーニングを
出していたら，ビットマップデータの型がおかしいかもしれません．

単なるカウンタやフラグとして使用しているような int は，多くの場合は
short int でも long int でも動作は変わりませんが，たとえそうだとしても，
WonX を使用して，gcc で -Wall オプションをつけてコンパイルすると，
WonderWitch で動作させるときの潜在的なバグ(short int の上下限にまつわる
バグなど)を発見できることがあるので，なるべくなら int2sint.pl で int を
ごっそり short int にしてしまうことをおすすめします．

[エンディアンの問題]

WonderWitch の CPU は x86系です．SPARC などで使用する場合には，
エンディアンに注意する必要があります．
font_set_colordata()などは，short int 型の配列でキャラクタデータを受け取る
ので，unsigned char * で定義したキャラクタデータを short int * にキャストして
font_set_colordata()に渡すなどのことをしていると，画像がひっくり返る
ことが考えられます．
i386 系のいわゆる PC-UNIX ならば，おそらく問題は無いでしょう．
WonX-2.1 から，キャラクタデータに関しては，極力エンディアンに依存しないように
修正しました．i386 と SPARC でエンディアンに依存しないことを動作確認
しています．しかしそれでも，キャラクタデータを unsigned char * で定義して，
ビットマップ読み込み用の関数にキャラクタデータを渡すときに short int * に
キャストして渡すような書き方をしていると，依存してしまいます．

キャラクタデータのビットマップ読み込み用の関数には，適切な型のデータを
渡すようにしてください．short int * を渡すべきところに，unsigned char * を
渡したりすると，このようなバグの原因になる可能性があります．不適切な
ポインタを渡している場合には，コンパイラがワーニングを出すので，
コンパイラのワーニングに十分に注意してください．

[タイマ割り込みの問題]

WonderWitch にはタイマ割り込みがありますが，WonX の動作は非常に遅いため，
WonderWitch の時間単位をそのまま UNIX に持ってきたら，割り込みが
かかりっぱなしになってしまいます．よってタイマ割り込みの時間単位は，
WonderWitch よりもかなり大きめにしてあります．
これは，wonx_configure.h で調整できます．
割り込みハンドラの中で，非常に時間のかかる画面描画などをしている
場合には，割り込みの時間単位を大きくしてください．でないと，ハンドラから
戻った瞬間にまたハンドラが呼ばれて，全然実行が先に進まない，ということに
なり得ます．

[キー入力割り込み，シリアル受信割り込みの問題]

(あまりやることはないと思いますが)キー入力割り込みとキー入力検査用関数を
同一ループ内で併用すると，割り込みのとりこぼしが起きやすくなる可能性が
あります．
つまり，以下のようなプログラムを書くときには注意してください．

void far key_handler()
{
  /* キー入力の処理がここに入る */
}

static intvector_t key_intvector;
static intvector_t key_last_intvector;

main()
{
  key_intvector.callback = (void (near *)())FP_OFF(key_handler);
  key_intvector.cs = _asm_inline("\tmov\tax,cs");
  key_intvector.ds = _asm_inline("\tmov\tax,ds");

  sys_interrupt_set_hook(SYS_INT_KEY, &key_intvector, &key_last_intvector);

  while (1) {
    /*
     * キー入力割り込み待ちの状態なのに，key_press_check() でキー入力状態の
     * 検査も行う
     */
    key = key_press_check();
    /* なんか適当な処理をこのへんで行ったりする */
  }
}

キー入力割り込みを待ちながら，key_press_check() でキーの入力状態を
別個に検査する，ということをやると，割り込みのとりこぼしが起きる可能性が
あります．
(ただし，キー入力割り込みによって呼び出される割り込みハンドラ内で
 key_press_check() を使用することは問題ありません．(でないと割り込みの
 意味が無くなってしまうしね) あくまで，同じループ内で併用すると問題が
 発生する可能性がある，ということです)

でも，こんなへんなプログラムあまり書くこと無いだろうし，いいかなと思ってます．
(これを直そうとすると，とてもたいへんなので)
このことは，シリアル受信割り込みに関しても，同様です．

[キー入力について]

キー入力は，キー入力用関数が呼ばれたときのみ感知するので，長めに押してないと
反応しないことがあります．
反応しないからといってなんども押すのでなく，１回を長く確実に押すように
してください．

[MS-DOS 形式ファイルの扱い]

MS-DOS 形式ファイルは，行末の改行コードが UNIX のテキストファイルと
異なるので，注意してください．*.[ch] ファイルの場合は問題無いのですが，
makefile は注意してください．
(UNIX のテキストファイルでは，改行は \n ですが，MS-DOS では \r\n です)
例えば，makefile 中に，

gcc -g -o smac $(OBJS) -L. -L/usr/X11R6/lib -lwonx -lX11 -lXt

のような行があったとして，これが MS-DOS のテキスト形式のファイルだと，
-lXt のあとに余分な改行コード(\r)が付加されてしまうため，UNIX 上で make
しても，「-lXt に相当するライブラリが無い」と怒られてしまいます．
(実際にはコンパイラは，-lXt\r だと思ってしまって，libXt\r.a というライブラリを
 探してしまうのです)
(しかも，ファイルを emacs や less などで参照しても，改行コードは表示されない
 ため，原因がわかりにくい)
また，

gcc -g -o smac $(OBJS) -lwonx -lX11 -lXt -L. -L/usr/X11R6/lib

のようにしていると，/usr/X11R6/lib を指定したつもりなのに，実際には
/usr/X11R6/lib\r というディレクトリが指定されたことになってしまい，
-lX11, -lXt の検索に失敗します．

漢字コードに関しても，同じことがいえます．UNIX での漢字コードは EUC なので，
ソースコード中に SJIS の漢字が入っていると，うまくコンパイルできなかったり，
make がうまく動作しなかったり，コンパイルできてもプログラム自体が
誤動作してしまい，しかも原因に気づきにくくなってしまう可能性があります．
makefile やソースコードは必ず，
> cat makefile | qkc -e -u > makefile.tmp
> mv makefile.tmp makefile
などを通して，UNIXのテキストファイルに変換しましょう．

[ファイル名の問題]

MS-DOS ではファイル名はすべて大文字ですが，gcc では *.C のような
ファイル名のファイルは C++ で書かれていると判断されるため，
SAMPLE.C のような名前のファイルをコンパイルすると，うまくリンクできない
ことがあります．
このような場合は，sample.c にリネームしてコンパイルしてください．

[シリアル通信について]

シリアル通信の受信用関数(comm_receive_char()等)は，fgetc(stdin) から
入力文字を取得して，\n は \r に変換して返します．これは，一般的な通信回線上の
端末をエミュレートするためです．

また，comm_send_char() に渡した文字は，標準出力に出力されますが，
タブや改行コードは，"\t" "\n" のような文字列に変換されて出力されます．
添付の sout2str.pl を通すことにより，シリアル通信への出力のみ抽出して，
端末への出力のイメージで表示させることができます．

■ 割り込みについて

キー入力割り込みやシリアル受信割り込みなどは，UNIXのアラームシグナルを
利用して実装しています．(一定時間おきにポーリングしている)
したがって，以下のようなプログラムもコンパイルして正常に動作させる
ことができます．

void far key_handler()
{
  int key;
  key = key_press_check();
  /* キー入力の処理がここに入る */
}

/* シリアル受信の割り込みハンドラ */
void far com_handler()
{
  int c;
  c = comm_receive_char();
  /* シリアル受信の処理がここに入る */
}

static intvector_t key_intvector;
static intvector_t key_last_intvector;
static intvector_t com_intvector;
static intvector_t com_last_intvector;

main()
{
  key_intvector.callback = (void (near *)())FP_OFF(key_handler);
  com_intvector.callback = (void (near *)())FP_OFF(com_handler);
  key_intvector.cs = _asm_inline("\tmov\tax,cs");
  key_intvector.ds = _asm_inline("\tmov\tax,ds");
  com_intvector.cs = _asm_inline("\tmov\tax,cs");
  com_intvector.ds = _asm_inline("\tmov\tax,ds");

  sys_interrupt_set_hook(SYS_INT_KEY,
                         &key_intvector, &key_last_intvector);
  sys_interrupt_set_hook(SYS_INT_RECEIVEREADY,
                         &com_intvector, &com_last_intvector);

  while (1) {
    /* 無限ループ．割り込みが入ったら，そのハンドラに飛ぶ */
  }
}

_asm_inline() は常に0を返すダミー関数として定義されています．
また，FP_OFF(), FP_SEG() は，
#define FP_OFF(p) (p)
#define FP_SEG(p) (0)
のように定義されています．よって，上記のようなプログラムも WonX で
コンパイルして実行することができます．

このように，while (1) {} で無限ループを回して，割り込みがあったときだけ
処理するようなプログラムを書いても，正常に動作します．
しかし，キー入力はポーリングされているときしか感知されないので，
キー入力割り込みをかけるには，長めにキーを押してやる必要があります．
(キーは基本的に鈍いので，反応するまで長めに押してください)

■ ソース中の WonX 依存部分のくくりかた

WonderWitch 用のプログラムを開発していく際に，WonX の場合のみ組み込みたくて，
WonderSwan 上で実行するときには取り除きたいコードがあったとします．
(例えば，デバッグ情報の出力のために printf() を入れる場合など)
このようなときのために，wonx_include/types.h で
#define _WONX_
してあるので，そのような場所は #ifdef _WONX_ でくくってください．

■ ダンプデータの取りかた

ソース中に，

#include "WonX.h"
#include "WonXDisplay.h"
#include "WWDisplay.h"
#include "WWColorMap.h"
#include "WWPalette.h"
#include "WWCharacter.h"
#include "WWSprite.h"

int i;
WWDisplay ww_display;

ww_display = WonXDisplay_GetWWDisplay(WonX_GetWonXDisplay());

WWColorMap_PrintData(WWDisplay_GetColorMap(ww_display), stdout);

for (i = 0; i < 16; i++)
  WWPalette_PrintData(WWDisplay_GetPalette(ww_display, i), stdout);

for (i = 0; i < 512; i++)
  WWCharacter_PrintData(WWDisplay_GetCharacter(ww_display, i), stdout);

for (i = 0; i < 128; i++)
  WWSprite_PrintData(WWDisplay_GetSprite(ww_display, i), stdout);

のようなコードを挿入することにより，任意の場所でキャラクタやパレットの
ダンプデータを出力させることができます．

プログラム中に，不安な場所があったら，

#ifdef _WONX_
ww_display = WonXDisplay_GetWWDisplay(WonX_GetWonXDisplay());
printf("Before setting:\n");
WWSprite_PrintData(WWDisplay_GetSprite(ww_display, 0), stdout);
#endif /* _WONX_ */

/* ここにスプライトの設定についての不安なコードがある */

#ifdef _WONX_
printf("After setting:\n");
WWSprite_PrintData(WWDisplay_GetSprite(ww_display, 0), stdout);
#endif /* _WONX_ */

のようにして不安なコードの前後でダンプデータを取ると，デバッグに
役立つでしょう．

■ 添付のツールについて

[sys2wonx.pl]

#include <sys/disp.h>
を，
#include "wonx_include/disp.h"
のように変換するフィルタです．

[int2sint.pl]

short か long か明示されていない int を，short int に変換します．
sizeof(int) や uint* も，sizeof(short int), unsigned short int* に
変換されます．
ただ，ひょっとしたらおかしな変換をしてしまうかも... でもたぶんそのときには
コンパイル時にエラーが出るだろうから，いいか．
そうだ．perl は行単位に処理するので，
long
int a;
とか，
void func(long
          int a)
のような変な書き方をしていると，
long
short int a;
とか，
void func(long
          short int a)
に変換されてしまって，きっとエラーになることでしょう．気をつけてください．

[filters.pl]

複数のフィルタをまとめて通すための perl スクリプトです．
書式は，
filters.pl [filters...] -f [files...]
です．例えば，
> filters.pl sort head -f file1 file2 file3
は，
> cat file1 | sort | head > file1.tmp
> mv file1.tmp file1
> cat file2 | sort | head > file2.tmp
> mv file2.tmp file2
> cat file3 | sort | head > file3.tmp
> mv file3.tmp file3
をすることと等価です．

[challsrc.sh]

WonderWitch用ソース → wonx用ソース への変換をするためのシェルスクリプトです．
内容は，単に，
./filters.pl "qkc -e -u" ./sys2wonx.pl ./int2sint.pl -f [files]
するだけです．
日本語 perl を使用する場合には，漢字コードは EUC でないと正常に動作しないので，
"qkc -e -u" を通してから ./sys2wonx.pl と ./int2sint.pl を
通すような順番になっています．

[sout2str.pl]

wonx は，シリアルポートへの出力は，
output to serial port : "A"
とか，
output to serial port : "\n"
のように，標準出力に出力します．sout2str.pl は，この "" でくくられた部分
のみを抽出して，\n や \t を適切なコードに変換して出力するフィルタです．
シリアルポートを使用するプログラム(例: wwterm)を起動するときには，
> wwterm | ./sout2str.pl
のようにして，sout2str.pl を通して起動することにより，実際のシリアルポート
への出力をモニタすることができます．

■ 作者

WonX は，坂井弘亮がその大部分を往復３時間の通勤電車の中で Libretto で書いた，
「電車ソフトウエア」です．GPLで配布します．
作者については，添付の OMAKE.jpn を参照してください．

坂井弘亮の連絡先のメールアドレスは，
sakai@seki.ee.kagu.sut.ac.jp
hsakai@pfu.co.jp
です．また，本ソフトウエアの最新版を，
http://www.seki.ee.kagu.sut.ac.jp/~sakai/WonderWitch/index.html
で配布しています．
以下はミラーサイトです．
http://hp.vector.co.jp/authors/VA014157/index.html
http://www.people.or.jp/~hsakai/index.html
ミラーサイトは，坂井が気が向いたときにアップデートするので，常に最新，
というわけではありません．あくまでバックアップ用です．

■ このファイルはここまで