WonX - WonderWitch on X.

■ 配布に当たって

WonX はまだ不完全です．実装されていない機能や，不完全な機能，おかしな
動作をする部分などがいっぱいあります．
バグ情報やアドバイスがあれば，作者の坂井弘亮まで，どんどんメールください．
アドレスは，
sakai@seki.ee.kagu.sut.ac.jp
hsakai@pfu.co.jp
です．
また，坂井の気が向く限り，アップデートは随時行っていきます．
http://www.seki.ee.kagu.sut.ac.jp/~sakai/WonderWitch/index.html
で，随時公開していきます．

現在は坂井が一人で製作していますが，ひとりでは細かい点の整合性
(初期化しなかった場合の動作の違いなど．WonderWitch と WonX では
 微妙に異なっている)を追いきれないのが現状です．
とくにマニュアルに書いてない部分に関しては，WonderWitch ではどのように
動作するのか，ひとりではチェックしきれません．(ていうか面倒)
情報をお待ち(ていうか期待)しています．
いっしょに少しずつ，完全なものに仕上げていきましょう．

ご意見，ご要望なども歓迎します．どしどしお寄せください．
(ただし，返事を書くとは限らないし，要望を反映するとも限りませんので
 その点はご容赦ください)

■ はじめに

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

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

■ 3分WonX

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

~>% tar xvzf wonx.tgz
(中略)
~>% 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

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

■ 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> に修正する必要がある，ということです．
(これをまとめて行うための perl スクリプトを添付してあります．
 sys2wonx.pl *.[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.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. makefile を修正する．

~/wonx/smac-b02>% emacs makefile

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

・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

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

4. ソースを修正する．

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

ソース中の，
#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 ../sys2wonx.pl .
~/wonx/smac-b02>% ./sys2wonx.pl *.[ch]
のようにしてください．
(sys2wonx.pl は，引数で指定したファイル自体を書き換えてしまうので注意)

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ボタンに対応している．
・p を押すと，表示/非表示モードを切替える．
  (非表示だと画面への描画を行わないが高速)
・F1 を押すと，LCDカラーマップのデータをダンプ出力する．
・F2 を押すと，パレットのデータをダンプ出力する．
・F3 を押すと，キャラクターのデータをダンプ出力する．
・F4 を押すと，スプライトのデータをダンプ出力する．

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

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

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

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

> smac | grep -v call

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

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

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 の目的は論理的なバグを早い段階で無くすことにあるので，このへんは
そういうものだと割り切って使ってください．
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 型を単なるカウンタとして使用するような場合には問題に
なりませんが，ビットマップの格納場所として使用するようなときには，
問題になります．
一番問題になりやすいのは，キャラクタのビットマップを扱う場合です．
font_set_colordata()などは，16*8 バイトのキャラクタデータを
short int 型の配列として引数に持ちます．WonderWitch では
sizeof(short int) == sizeof(int) なので，WonderWitch 用のプログラム上では，
キャラクタデータを short int とせずに，int 型の配列として定義してしまう
ことが考えられます．(当然 WonderWitch ならば問題は無いが，UNIX 上で
実行したら，キャラクタに妙な縞々が入るだろうと思われる)
このような場合には，UNIX 上でコンパイルするときには，short int に
修正する必要があります．

[エンディアンの問題]

WonderWitch の CPU は x86系です．SPARC などで使用する場合には，
エンディアンに注意する必要があります．
font_set_colordata()などは，short int 型の配列でキャラクタデータを受け取る
ので，char * で定義したキャラクタデータを short int * にキャストして
font_set_colordata()に渡すなどのことをしていると，画像がひっくり返る
ことが考えられます．
i386 系の PC-UNIX ならば，おそらく問題は無いでしょう．

[割り込みの問題]

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

[キー入力について]

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

[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 に相当するライブラリが無い」と怒られてしまいます．
(しかも，ファイルを 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 -I -O -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 を通すことにより，シリアル通信への出力のみ抽出して，
端末への出力のイメージで表示させることができます．

[ソース中の 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_ */

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

■ 作者

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
ミラーサイトは，坂井が気が向いたときにアップデートするので，常に最新，
というわけではありません．あくまでバックアップ用です．

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