Allegro( バージョン 4.2.0 現在)のAPIに関するメモです、オフィシャルのThe Allegro manual を完全に網羅はしていません。 例になるコードは基本的にAllegroのマニュアルやサンプルを参照しているほか、不明な部分は自分で検証したり 新規に補足した部分もある反面、 分からないところは省略したり、意訳部分もあります。また、バージョンアップに伴いAllegroのAPI仕様が変更される可能性も考えられます。 ここに書かれたメモや仕様の正確性は保証しません。もし利用する場合は自己責任でお願いします。

API

Transparency and patterned drawing (ブレンド処理)は別ページに分けてあります。

#include <std_disclaimer.h>

"I do not accept responsibility for any effects, adverse or otherwise, that this code may have on you, your computer, your sanity, your dog, and anything else that you can think of. Use it at your own risk."

このコードによって、あなたや、あなたの気分、PC、愛犬、あなたがその他思いつく何かに対して損害が発生したとしても
私はどのような責任も受け入れない。使う場合は自己責任で。

乱数の取得
rand()%6　この場合 0〜5 までのランダムな数字を返す。ただし、乱数の出るパターンはいつも同じ周期に偏る。

AL_RAND() これも、ランダムな数字を返す。

乱数生成を補正
srand(time(NULL)); プログラムの最初(allegro_init()の直後)で呼び出せば、rand() 関数の値の偏りを防止できる。

Allegroの初期化
int allegro_init();
Allegro ライブラリを有効にするマクロ。どんなAllegroアプリケーションも、たいていこのマクロによって初期化されている。

Allegroの終了処理
Macro END_OF_MAIN();
Allegroライブラリを終了するマクロ。Linux , Windows , MacOSX それぞれに対応した終了処理を行う。普通にAllegroを使う場合はmain();関数の最後にこのマクロが配置される。

Allegroの初期化(手動,詳細設定)
int install_allegro(int system_id, int *errno_ptr, int (*atexit_ptr)());
特になにも問題がなければ、allegro_init();で済ます事ができるらしい、install_allegro();を使う局面は 特殊な状況下に限られる。

allegroのライブラリを初期化する。 allegro_init (); と同じく、UTF-8以外のテキストモードを使用したければ、そのまえに set_uformat();関数を呼び出しても良い。 set_config_file();のような他の機能もまた同じである。

system_id には、利用可能なシステム を 限定しなければ、ほとんどの場合 SYSTEM_AUTODETECT を引数として渡せるかもしれない。
その代わりに SYSTEM_NONEを指定すると、 それぞれのOSのシステム固有のハードウェアドライバを使用せずに allegro を使う設定になる。 これは、 メモリビットマップを操作したり、WindowsのGDIインターフェイス機能を利用するときに有用かもしれない。

` errno_ptr ' 及び` atexit_ptr ' 変数 には あなたが使う lib から、 エラーナンバーや 終了機能を指す。 これらは、Allegro がダイナミックリンクライブラリ(DLL)としてリンクしている場合、直接呼び出せないので `atexit_ptr' が、 NULLになった場合、 あなたはallegro_exit(); を手動で呼ぶ必要がある。 通常は&errno , atexit関数を引数に渡す。　

install_allegro(SYSTEM_AUTODETECT, &errno, atexit);

返値：
0..... 成功
0以外..... 失敗。 使えるドライバが見つからない。


Allegro システムの終了(手動)
int allegro_exit();
Allegro システムの終了。 これは、マウス、キーボード、タイマー 処理を終了させ無効にする。atexit() のルーチンに従って、 Allegro のプログラム終了時に、allegro_exit(); が自動的に呼び出されるので、通常はこの関数を明確に呼び出すことに注意を払う必要はない。
これも手動で終了させる場合に使用するのかもしれない。


ウインドウタイトルを表示する
void set_window_title(const char *name);
Allegroアプリケーションのウインドウタイトルバーに文字を表示する。
allegro_init(); 直前に set_uformat( U_UTF8 ); を呼び出しておけば、 タイトル部分に 日本語を含むユニコード文字列を表示することができる。

エラーダイアログを出す
void allegro_message(const char *text_format, ...);
エラーダイアログを出して、ユーザーにメッセージを表示する。 この関数には、printf と同じ書式が使える、また、改行により数行にわたる長文も表示可能(OSX)。

allegro_message("ダイアログには日本語が通る。エラーは`%s'\n", err_number);　

日付を取得する
#define ALLEGRO_DATE
日付は `yyyymmdd'形式で格納されている。

const int year = ALLEGRO_DATE / 10000;
const int month = (ALLEGRO_DATE / 100) % 100;
const int day = ALLEGRO_DATE % 100;

allegro_message("Year %d, month %d, day %d\n", year, month, day);

時間を取得する
Allegroには、時分秒を取得する関数が存在しない。(4.1.1.18 現在)
フレームレートを求めるには、time_int で 周期的にフレームを更新して得る。

もし時間表示や時分秒を取得してフレームレート等を求めたい場合には、
time.h と localtime関数を使う。
http://www.allegro.cc/forums/view_thread.php?_id=265165

C/C++ リファレンス → 標準 C ライブラリ:localtime
http://www.shibu.jp/cppreference/stddate_details.html#asctime

#include <time.h>

time_t temptime;
struct tm *curtime;

time(＆temptime); 　
curtime = localtime(&temptime);

struct tm 構造体の使い方 hogehoge->tm_hour

各項目を参照。
もし、自作の関数にAllegro の bitmap ストラクチャを渡さなければいけないときは、引数にストラクチャの型名も記述する。 ストラクチャは、ポインタとして渡されたり、メンバ変数にアクセスできたりする。

void my_function( BITMAP *bitmap ){
〜処理〜
int height = bitmap->h; /* ビットマップの高さ */
int width = bitmap->w; /* ビットマップの幅 */
}

メンバ変数にアクセスする場合
構造体ポインタの場合 は アロー演算子を使う。
int width = bitmap->w;

そうではない場合は。ドット演算子を使う。
int width = bitmap.w;

プログラム中で扱う文字コードを指定する
void set_uformat(int type);
int type には 次のいずれかのエンコーディングモード を指定します。

●Allegroに初めから用意されているエンコーディングモード
U_ASCII - 固定長 8-bit ASCII 文字
U_ASCII_CP - 拡張 8-bit ASCII コード (set_ucodepage()関数を参照)
U_UNICODE - 固定長 , 16-bit Unicode 文字
U_UTF8 - 可変長, UTF-8 形式の文字　

日本語文字列を扱うには、U_UNICODE か U_UTF8 を指定すると良いです。
たとえば、 set_uformat( U_UTF8 ); と書く事で、プログラム中でUTF8文字列を使うことができます。
重要：この関数はAllegroの初期化 allegro_init(); よりも 先に 呼び出す必要があります。


現在設定されている文字コードの種類を取得する
int get_uformat(void);
文字コード別に処理を振り分ける時に使う。　

switch(get_uformat()) {
case U_ASCII:
do_something();
break;
case U_UTF8:
do_something_else();
break;
...
}　

返値：現在使用している 文字コートの種類を返す。


拡張ASCIIコードを設定する。
void set_ucodepage(const unsigned short *table, const unsigned short *extras);
set_uformat()関数で、エンコーディングモードを U_ASCII_CP を指定した場合は、この関数で拡張ASCIIコードを設定しておきます。拡張ASCIIコードは、ASCIIコードを多言語に拡張したもので、ラテン、ウムラウト文字やアラビア文字、トルコ語文字、キリル文字を表示できるようになります。*table にはコードテーブルを配列に格納し、256文字ぶん割り当てることができます。しかし、日本語文字コードとは関係ないので、日本語を使う場合あまり役に立たないかもしれません。


文字コードの変換が必要か調べる
int need_uconvert(const char *s, int type, int newtype);
文字コード type の 文字列 s を 文字コード newtype に変換する必要があるか教えてくれる。 変換が必要ない場合というのは、文字コードが一致する( type == newtype ) の時。 type, newtype に指定するパラメータは、U_ASCII　U_UTF8 , U_CURRENT などが使える。

if (need_uconvert(text, U_UTF8, U_CURRENT)) {
/* 変換処理 */
}

返値：
変換可能であれば 0以外 を返す
そうでなければ 0 を返す


(仮)エンコーディングモードを追加、拡張する
void register_uformat(int type, int (*u_getc)(const char *s), int (*u_getx)(char **s), int (*u_setc)(char *s, int c), int (*u_width)(const char *s), int (*u_cwidth)(int c), int (*u_isok)(int c));
set_uformat()関数で指定可能なエンコーディングモードを追加します。

ただし、実際のエンコード処理や文字列処理関数は自前で用意しなければいけません。

登録された 各関数はフック関数として呼び出されます。
register_uformat(int type, AllegroIDで定義した定数
int (*u_getc)(const char *s), ugetc 関数に相当する関数名を登録
int (*u_getx)(char **s), ugetx 関数に相当する関数名を登録
int (*u_setc)(char *s, int c), usetc 関数に相当する関数名を登録
int (*u_width)(const char *s), uwidth 関数に相当する関数名を登録
int (*u_cwidth)(int c), ucwidth 関数に相当する関数名を登録
int (*u_isok)(int c) uisok 関数に相当する関数名を登録

);

例えば EUC_JP エンコーディングで何かしたい場合は、次のようになるそうです。
文字コードのデータ形式に関するの知識が必要です。

// まず、 ugetc, ugetx, usetc, uwidth, ucwidth, uisok 関数に相当する日本語文字コード処理関数を書いて下さい。
int euc_getc(const char *s) {
// 日本語文字コード処理を書く
}


// これは AL_ID 関数といって、Allegroシステムが使用可能な定数を追加したりする時に使用します。
// 定義に必要なID識別子は英大文字の4文字(この例では E,U,C,J)で指定します。各文字は必ずシングルクォートで囲みます。
//エンコーディングモード定数の定義
#define U_EUC_JP AL_ID('E','U','C','J')

//register_uformat関数を使い、新しいエンコーディングモード定数 U_EUC_JP と 各フック関数を登録。 register_uformat( U_EUC_JP, euc_getc, euc_getx, euc_setc, euc_width, euc_cwidth, euc_isok);

// ここで初めてエンコーディングモード定数として U_EUC_JP が使えるらしい。
set_uformat( U_EUC_JP );
他には、uconvert() 等の関数に、U_EUC_JP を定数として指定可能にもなるので、うまくすれば変換もできる!?

この項目を書くにあたって、register_uformat()？ のトピックを参考にしました：

---

文字からユニコードを得る(文字列の一番最初の文字だけ)
int ugetc(const char *s);
Unicode テキストデータを読むための 低レベル機能サポート関数です。

int first_unicode_letter = ugetc(text_string);
textprintf_ex(screen, font,10, 96, makecol(255, 155, 0), -1, "code:%d " ,first_unicode_letter );

返値：
現在のエンコーディングモードの形式で、文字あるいは、文字列の一番最初の文字のコードが返ります。

文字からユニコードを得る
int ugetx(char **s);
int ugetxc(const char **s);
Unicode テキストデータを読むための 低レベル機能サポート関数です。ugetc()関数 と違い、文字列を構成する すべての文字のコードデータを扱うことができます。この関数は、const がついた文字変数でも使えます。

char *p = string;
int first_letter, second_letter, third_letter;
first_letter = ugetx(&p);// *p の最初の文字
second_letter = ugetx(&p);// *p の２番目の文字にポインタが移動
third_letter = ugetx(&p);// *p の3番目の文字にポインタが移動
textprintf_ex(screen, font,10, 96, makecol(255, 155, 0), -1, "code: %d %d %d " ,first_letter, second_letter, third_letter );

結果：
string="abc" code: 97 98 99

string="あいう" code: 12354 12356 12358
( 16進表記では、それぞれUTF16コードの 3042 3044 3046 を表している)

string="\xE3\x81\x82\xE3\x81\x84\xE3\x81\x86" code: 12354 12356 12358
( UTF8表記で同様に書いても UTF16コードが返ります。 )

set_uformat( U_UTF8); でエンコードをUTF8にしても、UTF16で返るようです。

返値：
現在のエンコーディングモードの形式で、数値が返ります。この関数は、同じポインタに対して 使用するたびに、前回指し示すポインタのアドレスから、さらに1つ前進したアドレスを指し示すという特徴をもっています。


アドレスに書き込む
int usetc(char *s, int c);
Unicode テキストデータを書き込むための 低レベル機能サポート関数です。 s によって指定されたアドレスに、文字 c を書き込みます。
返値：
現在のエンコーディングモードの形式のbyte数と等しければ。書き込まれたbyte数が返ります。


文字のbyte数を得る(文字列の最初の一文字から)
int uwidth(const char *s);
Unicode テキストデータを調べるための 低レベル機能サポート関数です。
返値：
現在のエンコーディングモードで、指定した文字列が占めているbyte数を返します。


文字のbyte数を得る(文字コード値から)
int ucwidth(int c);
Unicode テキストデータをを調べるための 低レベル機能サポート関数です。
返値：
現在のエンコーディングモードでエンコードされた場合に、指定した文字コード値が占めている byte数を返します。


エンコーディングの変換
int uisok(int c);
Unicode テキストデータをを調べるための 低レベル機能サポート関数です。
文字コード値 c が現在の現在のエンコーディングモードでエンコード可能なら、それを探し出します。 もし、Unicode から ASCII やその他のエンコーディングに変換したとしても、役立つ 文字アドレスの範囲 は限定されます。
返値：
返値 が 0 以外なら エンコーディングの変換が正常に行われたことを示します。そうでない場合は、0 が返ります。

---

文字コードの変換 type→ newtype
void do_uconvert(const char *s, int type, char *buf, int newtype, int size);
指定した文字列 s を 文字コード type から 文字コード newtype 変換する。 変換データは 文字列 buf に size バイト出力される。 文字コードを示す type パラメータ には現時点で選択している文字コードを意味する 「U_CURRENT」 を指定する事ができる。

char temp_string[256];
do_uconvert(input_string, U_CURRENT, temp_string, U_ASCII, 256);

注意：空文字列を指定する場合でも、バッファに終端文字列を考慮したサイズを与えなければいけない。 さもなければ、デバッグ版のAllegroは Assert により中断し、通常のAllegroでは展開バッファをオーバーランすることになる。


文字コードの変換 type→ newtype
char *uconvert(const char *s, int type, char *buf, int newtype, int size);
do_convert() 関数で実行される、より高機能な関数。この関数は文字コード type 形式の文字列 s を newtype 形式に変更する。 変換された文字列は buf に size バイト(終端文字列含む)出力される。 type, newtype に指定するパラメータは、U_ASCII　U_UTF8 , U_CURRENT などが使える。
もし、buf が NULL なら、一時的な内部バッファに文字列が格納され、sizeパラメータは無視される。 そして次にこの関数が呼ばれた時に上書きされる。 内部バッファは1Kにも満たないので、内部バッファで大きな文字列を扱う事はできない。

char *p = uconvert(input_string, U_CURRENT, buffer, U_ASCII, 256);

返値：
buf への ポインタ/ buf をnull に指定した場合は 内部バッファの内容。
そうでなければ、 文字列 s のコピーを返す。
常にbufのポインタは移動されるが、いずれにせよ、いつも 返り値 を使用しなければならない。


ASCII→現在使用している文字コード
char *uconvert_ascii(const char *s, char buf[]);
ASCII コード文字列 を現在の文字コード に変換する補助マクロ
uconvert(s, U_ASCII, buf, U_CURRENT, sizeof(buf)) を指定するのと同じ。


現在使用している文字コード→ASCII
char *uconvert_toascii(const char *s, char buf[]);
現在の文字コード を ASCII コード文字列 に変換する補助マクロ
uconvert(s, U_CURRENT, buf, U_ASCII, sizeof(buf))を指定するのと同じ。


空文字列
extern char empty_string[];
どの文字コードでも 有効な 空文字列を表現できる。この グローバル変数のバッファはいくつかの連続したゼロを含んでいる。 そのため ASCII, Unicode, UTF-8 モード 等 でも 問題なく対応することができる。


文字列の長さを取得(文字数)
int ustrlen(const char *s);
文字列 s の 長さ(文字数)を返す。

文字列の長さ(連続したスペース抜き, byte数)
int ustrsize(const char *s);
文字列 s の長さ(byte)を返す。ただし 連続した空白文字列は数えない。

文字列の長さ(連続したスペース含む, byte数)
int ustrsizez(const char *s);
文字列 s の長さ(byte)を返す。　連続した空白文字列を含む。

set_uformat( U_UTF8 );
int dist =ustrlen("花");
int dist2 = ustrlen("ひまわり");
int dist3 = ustrlen("Summer");
結果：
dist = 1, dist2 = 4 , dist3 = 6

ustrsize との違い

set_uformat( U_UTF8 );
int dist =ustrsize("花");
int dist2 = ustrsize("ひまわり");
int dist3 = ustrsize("Summer");
結果：
dist = 3, dist2 = 12 , dist3 = 6

なお、文字列をスクリーンに描画した時の幅(pixel)を取得するには text_length( ); 関数を使う。

n番目の文字を得る。
int ugetat(const char *s, int index);
文字列 s から index 番目の 文字を 探し出す。 index に 0 を指定した場合は 文字列 s の 先頭の文字を 探し出す。 index に -1 等 負の数を指定した場合は、 文字列 s の最後から index 番目の文字探し出す。

int third_letter = ugetat( "abcdefg", 2);
textprintf_ex( screen font, x, y , makecol(0, 0, 0), -1,"3rd letter: 0x%04x", third_letter );
// 文字列「c」 ではなく、「99」 = 文字コード「0x0063」 が返ってくる。　

返値： コードそのものを返す


n番目の文字を置き換える
int usetat(char *s, int index, int c);
文字列 s の index 番目 にある 文字データを変数 c のコードデータ に置き換える。 可変的に文字列データを調節するための処理( 直前の文字と 変数 c の エンコードが 違っている場合)。 もし index が 負の数ならば、 文字列の最後から数えて index 番目の文字が指定される。

usetat(text_string, 2, letter_a);

返値：文字列が移動したbyte数を返す。
( UTF-8 エンコード のような可変長データであっても)


文字列のn番目に文字を挿入
int uinsert(char *s, int index, int c);
変数 c ( コードデータ ) を 文字列 s の index 番目 に挿入する。場所を空けるためにデータの残りがずらされる。 もし index が 負の数ならば 文字列 c の最後から数えられる。

uinsert(text_string, 0, prefix_letter);　

返値：挿入によって文字列が移動したbyte数



文字列の比較とマッチング
int ustrcmp(const char *s1, const char *s2);
文字列 s1 と s2 を比較する。

返値：
0 マッチした。
正の数 照合順序 ( collating sequence) が s2 の後に s1 がくる場合。( s1 ＞ s2)
負の数 s2 の後に s1 がくる場合。( s1 ＜ s2 )



文字列の比較とマッチング(最初のn文字)
int ustrncmp(const char *s1, const char *s2, int n);
文字列 s1 と s2 の 最初から n 文字 を比較する。

接頭語 prefix が long_string に含まれているかどうかを調べる。
if (ustrncmp(prefix, long_string, ustrlen(prefix)) == 0) {
/* long_string starts with prefix */
}

返値：
0 マッチした。
正の数 照合順序 ( collating sequence) が s2 の後に s1 がくる場合。( s1 ＞ s2)
負の数 s2 の後に s1 がくる場合。( s1 ＜ s2 )


文字列の比較とマッチング(大文字/小文字無視)
int ustricmp(const char *s1, const char *s2);
文字列 s1 と s2 を比較する。ただし大文字か小文字どうかは無視する。
( case ignoring とは 大文字小文字を無視するという意味。)

if (ustricmp(string, user_input) == 0) {
/* string and user_input are equal (ignoring case) */
}

返値：
0 マッチした。
正の数 照合順序 ( collating sequence) が s2 の後に s1 がくる場合。( s1 ＞ s2)
負の数 s2 の後に s1 がくる場合。( s1 ＜ s2 )


文字列の比較とマッチング(大文字/小文字無視,最初のn文字)
int ustrnicmp(const char *s1, const char *s2, int n);
文字列 s1 と s2 の 最初から n 文字 を比較する。ただし大文字か小文字どうかは無視する。

返値：
0 マッチした。
正の数 照合順序 ( collating sequence) が s2 の後に s1 がくる場合。( s1 ＞ s2)
負の数 s2 の後に s1 がくる場合。( s1 ＜ s2 )
　
　
printf書式な表示
int uszprintf(char *buf, int size, const char *format, ...);
バッファのサイズに合わせて、書式に合ったテキストを表示する。文字列のほかに、変数の書き出しもできる。　 返値は、NULL terminated を含む 文字数を返す。
(Allegro に収録されている unicod.dat 内にある DATAFILE形式のフォントを利用するとひらがな、カタカナの表示は可能)

　 char buffer[10];
int player_score;
...
uszprintf(buffer, sizeof(buffer), "Your score is: %d", player_score);

文字列のコピー
char *ustrncpy(char *dest, const char *src, int n);
ポインタ dest へ 文字列 src の n文字ぶんをコピーする

文字列の連結
char *ustrncat(char *dest, const char *src, int n);
ポインタ dest の最後に 文字列 src の n文字ぶんを連結する


printf書式な表示(配列全体)
int uvsprintf(char *buf, const char *format, va_list args);
上の　uvsprintf　と同じですが、これは 配列全体を 渡すタイプである。
　　 返値は、　NULL terminated を含む 文字数を返す。
　　
特定の文字列の出現位置を記録
char *ustrrchr(const char *s, int c);
c が最後に現れた部分のポインタを返す、なければNULLを返す。

char *p = ustrrchr("one,two,three,four", ',');

特定の文字列と一致した位置を記録
char *ustrpbrk(const char *s, const char *set);
*set に渡された文字列 のどれかとマッチする最初の位置のポインタを 返す。
なければNULLを返す。

char *p = ustrpbrk("one,two-three.four", "-. ");

文字列の検索
char *ustrtok(char *s, const char *set);
該当する 文字列 を検索する(文字列中に同じパターンが複数見つかっても、最初のものしか発見しない。)

char *word;
char string[]="some-words with dashes";
char *temp = ustrdup(string);
word = ustrtok(temp, " -");
while (word) {
allegro_message("Found `%s'\n", word);
word = ustrtok(NULL, " -");
}
free(temp);

返値: トークン(字句)へのポインタがもし見つからなければ NULLを返す。
あなたは NULLが返ってきた場合にメモリを解放することができる。
　　
文字列の検索(複数マッチ対応)
char *ustrtok_r(char *s, const char *set, char **last);
該当する 文字列 を検索する(文字列中に複数見つかってもOK)。
最後のパラメータは、char ポインタのポインタ last です。

char *word, *last;
char string[]="some-words with dashes";
char *temp = ustrdup(string);
word = ustrtok_r(string, " -", &last);
while (word) {
allegro_message("Found `%s'\n", word);
word = ustrtok_r(NULL, " -", &last);
}
free(temp);

返値: トークンへのポインタor もし見つからなければ NULLを返す。
あなたは NULLが返ってきた場合にメモリを解放することができる。

マウス入力を有効にする
int install_mouse();
マウス関連の関数を利用するには、まずこのマウスハンドラをインストールする必要があります。

マウスの状態を調べる
int poll_mouse(); // マウスの情報に問い合わせる(ポーリング)関数
int mouse_needs_poll(); //マウスがポーリングモードかを調べる、返値が TRUEならポーリング状態

マウスカーソルの表示
void select_mouse_cursor(int cursor);
マウスカーソルは以下の定数を指定することができます。

MOUSE_CURSOR_NONE：カーソルを透明にする show_mouse(NULL);と同じ
MOUSE_CURSOR_ALLEGRO：Allegroカーソル set_mouse_sprite() でカスタマイズ可能。
MOUSE_CURSOR_ARROW： OS デフォルトの矢印カーソル
MOUSE_CURSOR_BUSY：ビジー状態の時のカーソル
MOUSE_CURSOR_QUESTION：？マークカーソル
MOUSE_CURSOR_EDIT：エディット時のカーソル(文字入力時など)

void show_mouse(BITMAP *bmp); マウスカーソルを表示する
void scare_mouse(); マウスカーソルを隠す
void enable_hardware_cursor(void); OS標準のカーソル使用を有効にする(ハードウェアカーソル)
void disable_hardware_cursor(void); OS標準のカーソル使用を無効にする

マウスの位置情報や押されたボタン情報が格納されている
extern volatile int mouse_x; // 現在のマウスカーソルのある x座標
extern volatile int mouse_y; // 現在のマウスカーソルのある y座標
extern volatile int mouse_z; // マウスのホイールの位置
extern volatile int mouse_b; // マウスボタン
extern volatile int mouse_pos; // 上位16bitに x座標,下位16bitに y座標の位置を格納している

マウスカーソル表示位置の指定・変更
void position_mouse(int x, int y);
マウスカーソルをスクリーンの指定位置に表示。カーソルが既に表示されている時でも使える。

マウスの移動量
void get_mouse_mickeys(int *mickeyx, int *mickeyy);
この関数が最後に呼ばれてからマウスがどのくらい移動したのかを計測します。マウスがスクリーンの端に到達していても、計測しつづけます。マウスの移動範囲が無限大の処理が必要な場合に利用されます。

MOUSE_FLAG_MOVE, MOUSE_FLAG_LEFT_DOWN, MOUSE_FLAG_LEFT_UP, MOUSE_FLAG_RIGHT_DOWN, MOUSE_FLAG_RIGHT_UP, MOUSE_FLAG_MIDDLE_DOWN, MOUSE_FLAG_MIDDLE_UP, and MOUSE_FLAG_MOVE_Z

マウスのコールバック関数

その他
リアルタイムに頻繁な画面書き換え処理とマウスカーソル描画を同時に行う場合、プログラムが強制終了してしまうことがあります。 この問題は、カーソル位置は捕捉されるので、マウスカーソルの描画をAllegroのマウスカーソル描画関数ではなく、スプライト( draw_sprite() )等を使って描画することで回避できます。

キーボード入力を有効にする
int install_keyboard();
キーボード割り込みを行う為には、必ず最初にこの呼び出す必要がある。さもなければキーボード関連の関数を呼べなくなってしまう。

キーボードに入力された状態を取得
int poll_keyboard();
key[]配列を使って、押されたキーが何であるか 調べたりする場合、キーボードの状態を取得 するには定期的にこの関数を呼び出すことが必要である。 ただし、 keypressed(), readkey(), and ureadkey()関数は自動的に、この poll_keyboard()関数を呼ぶ。
返値: 0を返せば成功、マイナス値を返せば失敗

ポーリングモード かどうかを調べる
int keyboard_needs_poll();
キーボードがポーリングモードかを調べる、返値が TRUEならポーリング状態

押されたキー
extern volatile char key[KEY_MAX];
Allegroシステム変数　scancode によって得られたフラグの配列。 poll_keyboard 関数を呼ぶたびに、この配列の値は更新される。 値がTRUEなら、そのキーが押されたことを示す。

if (key[KEY_SPACE]) printf("Space is pressed\n");

キーボードのscancode 一覧
例えばキー「A」が押されると、key[KEY_A] の値はTrueになる。

KEY_A ... KEY_Z,　 KEY_0 ... KEY_9, KEY_0_PAD ... KEY_9_PAD, KEY_F1 ... KEY_F12,

KEY_ESC, KEY_TILDE, KEY_MINUS, KEY_EQUALS,
KEY_BACKSPACE, KEY_TAB, KEY_OPENBRACE, KEY_CLOSEBRACE,
KEY_ENTER, KEY_COLON, KEY_QUOTE, KEY_BACKSLASH,
KEY_BACKSLASH2, KEY_COMMA, KEY_STOP, KEY_SLASH,
KEY_SPACE,

KEY_INSERT, KEY_DEL, KEY_HOME, KEY_END, KEY_PGUP,
KEY_PGDN, KEY_LEFT, KEY_RIGHT, KEY_UP, KEY_DOWN,

KEY_SLASH_PAD, KEY_ASTERISK, KEY_MINUS_PAD,
KEY_PLUS_PAD, KEY_DEL_PAD, KEY_ENTER_PAD,

KEY_PRTSCR, KEY_PAUSE,

KEY_ABNT_C1, KEY_YEN, KEY_KANA, KEY_CONVERT, KEY_NOCONVERT,
KEY_AT, KEY_CIRCUMFLEX, KEY_COLON2, KEY_KANJI,

KEY_LSHIFT, KEY_RSHIFT,
KEY_LCONTROL, KEY_RCONTROL, KEY_ALT, KEY_ALTGR,
KEY_LWIN, KEY_RWIN, KEY_MENU,
KEY_SCRLOCK, KEY_NUMLOCK, KEY_CAPSLOCK

KEY_EQUALS_PAD, KEY_BACKQUOTE, KEY_SEMICOLON, KEY_COMMAND

NumLock 等、特殊キー
extern volatile int key_shifts;
これらはSHFTやControl やWindow のaltキーや 特殊文字キーの状態を含んでいる。
poll_keyboard 関数によってこれらの値が更新されるが、現在の状態を調べるには、
現時点で poll_keyboard 関数を呼ぶ必要がある。

KB_SHIFT_FLAG KB_CTRL_FLAG KB_ALT_FLAG　KB_LWIN_FLAG KB_RWIN_FLAG
KB_MENU_FLAG KB_COMMAND_FLAG KB_SCROLOCK_FLAG KB_NUMLOCK_FLAG
KB_CAPSLOCK_FLAG KB_INALTSEQ_FLAG KB_ACCENT1_FLAG KB_ACCENT2_FLAG
KB_ACCENT3_FLAG KB_ACCENT4_FLAG

　　　if (key[KEY_W]) {
　　　　　　if (key_shifts & KB_SHIFT_FLAG) {
　　　　　　/* User is pressing shift + W. */
　　　　　　} else {
　　　　　　/* Hmmm... lower case W then. */
　　　　　　}
　　　}

たとえば、capslockキーで、カタカナひらがな入力の切り替えを行う例。 capslockキーが押されている間は カタカナを入力するという場合。

if ( key_shifts ＆ KB_CAPSLOCK_FLAG ) {
ustrcat( tests , rtok_table[j].dist);//カタカナ
}else{
ustrcat( tests , rtok_table[j].disth); //ひらがな
}

if ( key_shifts ＆ KB_CAPSLOCK_FLAG ){ mode="カナ"; }else{ mode="かな";}
textprintf_ex(keybuffimage, font, 30, list_pos , makecol(250, 0, 0), -1,"【キー入力情報】[%s]" , mode);

何かキーが押されたか判断する
int keypressed();
返値：TRUE なら、何かキーが押されたことを示す
readkey(); は入力待ちのためプログラムの進行がストップしてしまう。それを回避するには keypressed(); を使って判断し、 キーが押されたときだけキー入力を拾うようにするとよいです。

キー入力を拾う
int readkey();
キーで入力された文字を得る。

int val;
val = readkey();

バッファが空の間は、キー入力までプログラムの進行を待機させるので ユーザーの入力に対して次の場面に進ませるという使い方もできる。

textout(screen, font, 30, 20, 0 , -1," -PUSH ANY KEY - なにかキーを押してネ" );
readkey();
// スクリーンを消去して 次の場面へ
clear_to_color(screen , makecol(255, 255, 255));

キー入力を拾う(Unicode版)
int ureadkey(int *scancode);
readkey 関数と同じくバッファが空の間は、キー入力までプログラムの進行を待機させるが、 ureadkeys関数は 255以上の値も扱える点が違っている。また、スキャンコードのアドレスを引数に入れなければいけない。

キー入力からコードに変換
int scancode_to_ascii(int scancode);
キー入力からキーの名称を取得
const char *scancode_to_name(int scancode);

int val, scancode,ascii;
char keyname;
if( keypressed() ){
　　val = ureadkey(&scancode);
　　ascii = scancode_to_ascii( scancode);
　　keyname = scancode_to_name( scancode);
}

textprintf_ex(screen, font, 30, 20, 0 , -1,"Scancode:　0x%04x ", scancode );
textprintf_ex(screen, font, 30, 30, 0 , -1,"ASCII　　:　0x%04x ", ascii );
textprintf_ex(screen, font, 30, 40, 0 , -1,"Val　　　:　0x%04x ", val );
textprintf_ex(screen, font, 30, 50, 0 , -1,"keyname:　%s ", keyname );
textprintf_ex(screen, font, 30, 60, 0 , -1,"String　　: %c ", val );

結果：(スペースキーを押した場合)
Scancode：0x004b
Ascii　 　：0x0020
Val　　 　：0x0020
Keyname　：SPACE
String　 ：　//実際に入力された文字

UTF8では、"ん"＝ E38293 なので "\xE3\x82\x93" のように書いても"ん" と表示できます。 (※ 「￥」は実際には、バックスラッシュ)
textout_centre_ex(screen, font, "\xE3\x82\x93" , 160, 96, makecol(0, 255, 0), -1);
textout_centre_ex(screen, font, "ん" , 160, 96, makecol(0, 255, 0), -1);

キー入力のシミュレート
void simulate_keypress(int key);
キーを押さなくても、 キーバッファにキー入力情報を渡すことで、ユーザーがキーを押したようにみせかける。 キーバッファの内容は、それぞれreadkey();、 ureadkey(); を使って判別する。

simulate_keypress(KEY_SPACE << 8);
if (readkey() == (KEY_SPACE << 8))
allegro_message(" Alt+Space キーを押しましたか？");

キー入力のシミュレート(Unicode版)
void simulate_ukeypress(int keyy, int scancode );

simulate_ukeypress(0x00DF, 0);
if (ureadkey(&scancode) == 0x00DF)
allegro_message("シャープ記号を入力した");

使っている キーボードの種類によってキーが存在しなくても 、この関数によってフォローすることができる。 また、 キーボード以外の ソフトウェアキーボードやストロークを利用して文字入力する場合にも使えるかもしれない。

キー入力設定
void set_keyboard_rate(int delay, int repeat);
リピート入力認識までの時間と、キーのリピート速度を設定する。 それぞれ ミリ秒 単位 で指定する。 もし 引数に 0 を指定した場合は リピート入力認識が「切」になる。

キーバッファをクリアする
void clear_keybuf();
キーバッファの内容をクリアしたい場合に使うことができる。

時間やタイミングに関する分野。ウェイトをかけたり、定期的に関数を呼び出したい場合に使える。

タイマー機能を有効にする
int install_timer(void);
Allegro システムによる割り込みハンドラを有効にする。

インターバル機能を有効にする
int install_int(void);
ユーザーによる割り込みハンドラを有効にする(int = interval のことか？)

ウェイトをかける
int rest(unsigned int time);
この関数は install_timer() に属し、指定した 時間(ミリ秒)だけ プログラムを待機させる。
他には、 画面の書き換えと同期するには vsync() 関数を使う方法がある。

メモリの保護
Macro LOCK_VARIABLE(variable_name);
Macro LOCK_FUNCTION(function_name);
Macro END_OF_FUNCTION(function_name);
タイマー関数や変数のメモリを保護する。 END_OF_FUNCTION は、タイマー関数の最後に必須。

volatile int counter;

void my_timer_handler()
{
counter++;
}

END_OF_FUNCTION(my_timer_handler)

メモリ保護の詳細については install_int_ex() の説明を見ること。

(仮)
Allegroはマウスやキーボードでもないハードウェア、ジョイスティック入力を実装する。
しかし、ほとんどのプラットホームがジョイスティックの割り込みに対応していないので、
正しいジョイスティックの入力を得るには、プログラム中で、すくなくとも1フレームにつき1回は
入力を監視(ポーリング)されなければならない。

ジョイスティックの初期化
int install_joystick(int type);
ジョイスティックの初期化と、中心位置を調節する。
ジョイスティック関連の関数を呼び出す前に必ず初期化を行う。
通常パラメータ int type は JOY_TYPE_AUTODETECT を指定する。

textout_centre_ex(screen, font,
"Center the joystick and press a key",
SCREEN_W/2, SCREEN_H/2, red_color, -1);
readkey();
if (install_joystick(JOY_TYPE_AUTODETECT) != 0)
abort_on_error("Error initialising joystick!");

返値：
0 成功


ジョイスティックの使用を終了
void remove_joystick();
ジョイスティックの使用を終了する。これは allegro_exit()が自動的に行うので、呼び出す必要はない。


ジョイスティックのポーリング
int poll_joystick();
ジョイスティックには割り込み機能が備わっていない。
そのため、ジョイスティックからの入力を調べるにはこの関数をそのつど呼び出さなければいけない。

コードの例：
do {
/* Get joystick input */
poll_joystick();

/* Process input for the first joystick */
if (joy[0].button[0].b)
first_button_pressed();

if (joy[0].button[1].b)
second_button_pressed();
...
} while(!done);

返値：
0　成功
マイナス 失敗


接続しているジョイスティックの数
extern int num_joysticks;
グローバル変数。 有効なジョイスティックの番号が格納されている。
現在サポートされているドライバーは4つまで認識する。


ジョイスティックの情報
extern JOYSTICK_INFO joy[n];
ジョイスティックの情報が格納されているグローバル配列
この内容は、poll_joystick() 関数が呼ばれるたびに更新される。

はじめは、num_joysticks と同じ値しか入っていない。

typedef struct JOYSTICK_INFO
{
int flags; - このジョイスティックの状態フラグ　
int num_sticks; - 何個のジョイスティックが接続されているか?
int num_buttons; - いくつのボタンがあるか?
JOYSTICK_STICK_INFO stick[n]; - スティックの状態
JOYSTICK_BUTTON_INFO button[n]; - ボタンの状態
} JOYSTICK_INFO;

int flags;が返す値

JOYFLAG_DIGITAL - 現在提供されているコントローラはデジタル入力モードである。
JOYFLAG_ANALOGUE - 現在提供されているコントローラはアナログ入力モードである。
　
JOYFLAG_CALIB_DIGITAL - デジタル入力の提供可能だが、一度調整されなければ今使用することはできない。

JOYFLAG_CALIB_ANALOGUE- アナログ入力の提供可能だが、一度調整されなければ今使用することはできない。

JOYFLAG_CALIBRATE - 調整が必要。このフラグが取り除かれるまで、calibrate_joystick() 関数を呼び出して機能を有効にしなければ動かない。


JOYFLAG_SIGNED - アナログスティックの位置が signed format (-128 to 128)で表されている。これは2D 方向の制御である。
JOYFLAG_UNSIGNED - アナログスティックの位置が unsigned format( 0 to255)で表されている。これは1D スロットル制御である。

ボタン情報。

typedef struct JOYSTICK_BUTTON_INFO
{
int b; - boolean on/off フラグ
char *name; - 押されたボタン名に関する情報
} JOYSTICK_BUTTON_INFO;

機能がどのボタンに割り当てられるか表示したければ、これらの情報が利用できる。
各ジョイスティックに備わっている、1つまたは複数のスティック入力の変化や、指定位置にあるかコントロールする事ができる。

スティック入力に関するストラクチャはこのようになっている。

typedef struct JOYSTICK_STICK_INFO
{
int flags; - 入力に関する 状態フラグ
int num_axis; - コントローラが装備しているスティックの数
JOYSTICK_AXIS_INFO axis[n]; - スティックの軸の状態に関する情報
char *name; - この入力に対する記述
} JOYSTICK_STICK_INFO

ひとつのジョイスティックは、複数の違ったスティック入力が提供されるかもしれないが、
安心してスティックの初期配列をメインのコントローラの方向性に委ねることができる。


スティックの初期位置やボタン割り当てがストラクチャに格納されている。

typedef struct JOYSTICK_AXIS_INFO
{
int pos; - アナログスティックの 軸位置
int d1, d2; - デジタルスティックの 軸位置
char *name; - 軸に関する記述
} JOYSTICK_AXIS_INFO;

int pos の部分にはアナログ入力( 制御方式によっては 値は -128〜128 または 0〜255の範囲をとる)
int d1 と d2 の部分にはデジタル入力の値が格納される。

たとえば、 X軸に対する入寮があったとき pos には 水平位置が、 d1 にはそれが左に傾いた、d2にはそれが右に傾いたという情報が入る。 Allegroは、これらすべての値がアナログジョイスティックからの入力なのか、デジタルジョイスティックからの入力なのかどうかを気にせずに取得する。 つまり、デジタルスティックからの入力の場合、　pos には、 min, middle , maximum の位置から割り出された 値が エミュレートされる。 また、アナログスティック から入力したの場合、d1とd2 は アナログスティックの中心位置と現在位置を比較して計算された値がエミュレートされることになる。
　


ジョイスティックの 調整
const char *calibrate_joystick_name(int n);
あなたが調整したいと思うジョイスティックの番号をint n に渡す。

返値：
テキスト　- 指定されたジョイスティックのタイプ
NULL 　-　 調整が得られなかった場合



ジョイスティックの 調整
int calibrate_joystick(int n);

ほとんどのジョイスティックは完全なアナログ入力を提供する前に調整する必要がある。
この関数はスティックの軸を設定するために、calibrate_joystick_name() の前に呼び出される必要がある。
　
例えば、十分にジョイスティックすべてが有効かどうか調整するには次のようにする

int i;

for (i=0; i<;num_joysticks; i++) {
while (joy[i].flags & JOYFLAG_CALIBRATE) {
char *msg = calibrate_joystick_name(i);
textprintf_ex(..., "%s, and press a key\n", msg);
readkey();
if (calibrate_joystick(i) != 0) {
textprintf_ex(..., "oops!\n");
readkey();
exit(1);
}
}
}

返値：
0 - 成功
0以外 - 調整はうまくいかなかった。

ジョイスティックの 調整データのロード
int save_joystick_data(const char *filename);
頭痛の種になりそうなジョイスティックの調整作業を、をユーザーにまた繰り返させたいは思わないかもしれない。 この関数によって、コンフィグファイルに、ジョイスティックの調整データを保存することができる。 このデータは、後でload_joystick_data() を呼び出す事で読み込む事が出来る。 ファイルネームに NULLを 渡すと、現在選択されているコンフィグファイルが指定される。

返値：
0 - 　コンフィグファイルへ調整データの記録が成功した
0以外 - データは記録されない。


ジョイスティックの 調整データのセーブ
int load_joystick_data(const char *filename);
save_joystick_data() または セットアップユーティリティによって記録された ジョイスティック調整データを読み込む。
なお、この関数を呼んだ場合には、install_joystick() を呼ぶ必要はない(内部で呼び出しているため)。
ファイルネームに NULLを渡すと、現在選択されているコンフィグファイルが指定される。


返値：
0 - 　読み込みが成功した
0以外 - もしジョイスティックが未定義で読み込みが失敗するなら、再びジョイスティックを初期化しなければならない。

Allegro の画面を設定する機能を提供する。これがなければ画面に文字や画像を貼付けることもできない。
Allegroは 主に「フルスクリーンモード」 と 「ウインドウモード」 の2つのタイプの表示方法を扱う事が出来る。

この項では、最低限知っておいたほうがいい関数だけ紹介。
他にも機能はたくさんありますが、説明は割愛する。
( mode-X 、create_video_bitmap() 、スクロール関数 や トリプルバッファリング等)


スクリーンを設定する
int set_gfx_mode(int card, int w, int h, int v_w, int v_h);

パラメータ：
int card には グラフィックモードを設定するAllegro magic drivers を設定する。
int w： スクリーンの幅
int h ：スクリーンの高さ
int v_w： 仮想スクリーン　 の幅
int v_h ：仮想スクリーン　 の高さ

仮想スクリーン は トリプルバッファリングなどによる ハードウェアスクロールや Page Flipping を利用する時に活用されます。　 仮想スクリーン　 についてあれこれ心配したくなければ、 それぞれ 0 を指定してください。
色深度を設定する場合は、この関数を呼ぶ前に設定してください。

Allegro magic drivers - int card の パラメータに設定する引数。

* GFX_AUTODETECT:
Allegro は、まず、フルスクリーンモードで 現在の 色深度に対応した 解像度を設定しようとする。もし該当する解像度をを見つけられなければ 今度はウインドウモードで同じように 試みる。 set_gfx_mode() 関数 呼び出しに成功すると、解像度と色深度が保証されるが、プログラムが フルスクリーンで動くか ウインドウモードで動かされるのかは、ユーザーのPC環境やビデオカードに左右される。

* GFX_AUTODETECT_FULLSCREEN:
Allgro はフルスクリーンモードで指定された 解像度と色深度 を設定しようとする。もしその指定が設定でなければ、 set_gfx_mode() 呼び出しは失敗する。

* GFX_AUTODETECT_WINDOWED:
Allgro はウインドウモードで指定された 解像度と色深度 を設定しようとする。もしその指定が設定でなければ、 set_gfx_mode() は失敗する。 ウインドウモードが実行されるとき、'指定した解像度' は、そのウインドウ内のグラフィック描画エリアの縦横のサイズを意味する。 もし、Allegro ウインドウ内の色深度と デスクトップ画面の色深度と一致しない場合は、描画速度に差が出る可能性がある。 この場合は desktop_color_depth() 関数を使って解決する。

* GFX_SAFE:
Allegro ドライバは、指定された解像度が見つからなければ、 グラフィックカードに用意されている解像度に正しく設定する。320x200 , 640x480 など。 もしどんな解像度設定も不可能な場合は -1 を返してプログラムを終了させる。

* GFX_TEXT:
あらゆるグラフィックモードを閉じて、グローバルなscreen オブジェクトを利用できなくして、テキストモード (ふつうは 80x25) に入る。 このドライバモードをセットした場合、他のパラメータはどんな意味もなさなくなるので、他のパラメータには 0 を指定しておく。

返値：
0　=　成功
負の数 = 失敗, allegro_error. が記録されるらしい。

この関数の呼び出しに成功すると、以下のマクロにスクリーンの情報が反映される。
SCREEN_W, SCREEN_H, VIRTUAL_W, VIRTUAL_H


リフレッシュレートの要求(WIN, DOSのみ)
void request_refresh_rate(int rate);
この関数を事前に呼び出しておくと、次に set_gfx_mode() が呼ばれたときにリフレッシュレートを取得する。 現在、 DOS VESA 3.0, X DGA 2.0 といくつかの Windows DirectX drivers しかサポートしていない。

request_refresh_rate(60);
if (set_gfx_mode(GFX_AUTODETECT, 640, 480, 0, 0) != 0)
abort_on_error("Couldn't set graphic mode!");
if (get_refresh_rate() != 60)
abort_on_error("Couldn't set refresh rate to 60Hz!");

リフレッシュレートの参照(WIN,DOSのみ)
int get_refresh_rate(void);
もし取得可能であれば リフレッシュレートを返す。

返値
正の数 = リフレッシュレート
0 = リフレッシュレートが不明


色深度のセット
void set_color_depth(int depth);
set_gfx_mode() や create_bitmap() で呼び出される 色深度を設定する。
デフォルトでは、 8 が設定されており 15, 16, 24, 32 (bits) の深度が設定できる。
※必ず、set_gfx_mode()関数 の前に呼び出してください。

set_color_depth(32); if (set_gfx_mode(GFX_AUTODETECT, 640, 480, 0, 0) != 0) { abort_on_error("Couldn't set a 32 bit color resolution"); }

色深度の取得
int get_color_depth(void);
現在の画面モードの 色深度を取得する。

画面表示領域
extern BITMAP *screen;
Allegroのシステムで予約されているグローバルなポインタ。画面表示を受け持つ特殊なオブジェクトであり、 他のビットマップオブジェクトと違って仮想領域に内包される形で、画面表示領域が存在する。

仮想領域の大きさは、VIRTUAL_W x VIRTUAL_H , 画面表示領域は SCREEN_W x SCREEN_H という定数で表される。 通常は左上隅(0,0)が起点になっていますが、もし興味があればハードウェアスクロールや page flipping によってこの制限を無視する事もできるらしい。 基本的には画面表示領域の窓となる部分を変更することで、表示領域の大きさを変えることになる。

画面表示領域は、左上隅(0,0)が起点になっている。例えば画面上に点を描画するにはこのようにする。

putpixel(screen, x, y, color);

画面表示領域の幅と高さ
#define SCREEN_W;
#define SCREEN_H;
Allegroのシステムであらかじめ定義されている定数。
画面モードを設定した場合、表示画面の幅と高さはそれぞれこの定数で得る事ができる。
SCREEN_W , SCREEN_H


ビットマップオブジェクトの宣言
BITMAP *images;
画像データを扱うオブジェクト。画像を表示するだけではなく、スプライトパターン格納領域や オフスクリーンバッファ の入れ物としても使える。 宣言しただけでは、まだ使えない。create_bitmap 関数によって描画領域を指定する必要がある。

描画領域の作成
BITMAP *create_bitmap(int width, int height);
BITMAP *create_bitmap_ex(int color_depth, int width, int height); 色深度を指定するタイプ
ビットマップオブジェクトのメモリ上に 高さx,幅yのビットマップ領域が作られる。これによってはじめて描画か可能となる。

ビットマップ画像ファイルの読み込み
BITMAP *load_bitmap(const char *filename, RGB *pal);
BMP, LBM, PCX, TGA 画像ファイルを読み込むことができる。(一応、各画像形式を読み込む関数も用意されている)　 256色のRGBパレットを読み込むことも可能。

BITMAP *images;
images = load_bitmap("picture.pcx", NULL);
if (!bmp) abort_on_error("Couldn't load picture.pcx!");
blit( screen , 0,0,0,0,320,200);//画面に表示
destroy_bitmap(images);

PackFile内の bmpファイルの読み込み
BITMAP *load_bmp_pf(PACKFILE *f, RGB *pal);
AllegroのPackFile圧縮 がかけられたbmpファイルを読み込む。

ビットマップ画像をファイルとして保存
int save_bitmap(const char *filename, BITMAP *bmp, const RGB *pal);
BMP, PCX , TGA 形式で保存できる。この関数は、画面上に表示された ビットマップ オブジェクトの内容をファイルに出力するが 　 スクリーンショットを保存する場合は注意が必要である。

BITMAP *screen オブジェクトは特殊で 実際に見えてる画面領域の 外側に 仮想画面領域 を持っているため、そのまま保存すると仮想画面領域まで含んでしまうのでファイルサイズが大きくなる。 この問題を回避するには sub-bitmap 関数を使って *screen オブジェクトの一部分を切り取った内容をファイルに出力する。

BITMAP *bmp;
PALETTE pal;
...
get_palette(pal);
bmp = create_sub_bitmap(screen, 0, 0, SCREEN_W, SCREEN_H);
save_bitmap("screenshot.pcx", bmp, pal);
destroy_bitmap(bmp);

システム描画領域の作成
BITMAP *create_system_bitmap(int width, int height);
システムメモリ上に割り当てる。ほかのビットマップオブジェクトとは違い特殊な性質を持つ。

サブ描画領域の作成
BITMAP *create_sub_bitmap(BITMAP *parent, int x, y, width, height);
このcreate_sub_bitmap関数によって作られたビットマップオブジェクトは、 親である *parent の描画領域の内容を共有している。 sub_bitmap で指定する場合、幅と高さwidth, height は、親ビットマップの描画領域よりも小さくなければならない。
返値：NULL なら 作成に失敗。
注意：親ビットマップオブジェクト をdestroy_bitmap を解放する場合は、先に sub_btmap で作られた ビットマップを解放しなければいけない。さもなければメモリリークが発生する。

ビデオメモリ領域の作成
BITMAP *create_video_bitmap(int width, int height);
指定サイズのビデオメモリビットマップを割り振る。ハードウェアアクセラレーションによって行われる画像の転送のために割り振られたビデオメモリが使われる。またはshow_video_bitmap() の呼出しによって表示することができる多数のビデオ記憶ページを作成するのに使用することができる。

注意：ビデオメモリビットマップは通常スクリーンビットマップと同じスペースから割り振られている。それゆえ、この関数と グローバルなビットマップスクリーン (*screen オブジェクトのこと) を同時に使用するのはあまりよい考えとはいえない。


マスクカラーの取得
int bitmap_mask_color(BITMAP *bmp);
マスクカラーは、スプライトやblitting を使う場合、背景を透過する透明色となる色のことで、色深度によってそれぞれ定義されている。 この関数は、該当ビットマップの色深度に応じたマスクカラーを返す。

返値：
0. - 256色モードのマスクカラーは「0」
makecol(255,0,255)にあたるピンク色 - TrueColor の場合は。

/* マスクカラーを他の色に変更するサンプル. */
for (y = 0; y < bmp->h; y++)
for (x = 0; x < bmp->w; x++)
if (getpixel(bmp, x, y) == bitmap_mask_color(bmp))
putpixel(bmp, x, y, another_color);

メモリの解放
void destroy_bitmap(BITMAP *bitmap);
使い終わったら destroy_bitmap によってデータを破棄します。

色指定についての関数はたくさんある。初めはこれ1つだけ知っておくと便利。

色指定
int makecol(int r, int g, int b);
RGB それぞれ0-255の範囲で指定した形式で、色データを指定する汎用の関数。 例えば、文字色や画面消去や様々な場面に使われる。 ここでは紹介しないが、ビデオモードや色深度 8, 15, 16, 24, 32-bit 専用の関数もある。

/* どんな色深度モード でもこれは緑色に見える */
int green_color = makecol(0, 255, 0);

/* 透明色の指定 (truecolor の場合) */
int masked_color = makecol(255, 0,255);

返値：
色深度と指定したパラメータに対応した RGB 三項値

この関数は、他の関数内のパラメータに直接書く事もできる。

textprintf_ex( screen font, x, y , makecol(0, 0, 0), -1,"3rd letter: 0x%04x", third_letter );

ビットマップからピクセル値を取得
getpixel — getpixel().の高速版
_getpixel15 — getpixel().の高速版
_getpixel16 — getpixel().の高速版
_getpixel24 — getpixel().の高速版
_getpixel32 — getpixel().の高速版

ビットマップにピクセル値を書き込む
putpixel — putpixel().の高速版
_putpixel15 — putpixel().の高速版
_putpixel16 — putpixel().の高速版
_putpixel24 — putpixel().の高速版
_putpixel32 — putpixel().の高速版

円や直線 、ポリゴン等を描画
arc — 円弧を描画　
calc_spline — スプライン曲線を計算する
circle —円を描画　
circlefill — 塗られた円を描画　
do_arc — すべての点を通る円弧を描画　
do_circle —すべての点を通る円を描画　
do_ellipse — すべての点を通る楕円体を描画
do_line — すべての点を通る直線を描画
ellipse — 楕円体を描画
ellipsefill — 塗られた楕円体を描画
fastline — line()の高速版
floodfill — 閉じた領域を塗る
getpixel — ビットマップピクセルを読み込む
hline — 水平線を描画
line —　直線を描画
polygon — 塗られた多角形(ポリゴン)を描画
putpixel — ビットマップピクセルを書き込む.
rect — 長方形を描画
rectfill — 塗られた長方形を描画
spline — コントロールポイントを持ったスプライン曲線を描画
triangle — 塗られた三角形を描画
vline — 垂直線を描画

ビットマップオブジェクトの指定領域のデータをコピーして、スクリーン画面の指定した場所へ表示する。

単に画像を表示するだけでなく、画面上にマップチップなどを配置したり、カウンター数字を表示したり、画面上に見えないバッファとして利用したり 様々な場面でよく使われる。

画像の転送
void blit( BITMAP *src コピー元
, BITMAP *dest 転送先
, int cx コピー元 x座標
, int cy コピー元 y座標
, int dx 転送先 x座標
, int dy 転送先 y座標
, int width 幅 width
, int height 高さ height
);
コピー元 描画領域 の (cx,xy)-(cx+width,cy+height)の矩形領域を、
転送先のメモリ領域 (dx,dy)-(dx+width,dy+height)へコピーする。
コピー元 と 転送先が同じでも問題ないとか。

BITMAP *bmp 転送元 --- 画面に表示されない オフスクリーン
↓ 転送ー
BITMAP *scren 転送先が screen の場合 画面上に表示される

画像の転送(拡大)
画像を拡大して表示する。
void stretch_blit( BITMAP *source コピー元
, BITMAP *dest 転送先
, int source_x コピー元x座標
, source_y コピー元y座標
, source_width幅
, source_height高さ
, int dest_x転送先x座標
, dest_y 転送先y座標
, dest_width 拡大後の幅
, dest_height拡大後の高さ
);
引数は、コピー元の( x , y , 幅 , 高) 転送先(x,y,幅,高)の順になっているので注意する。 コピー元のビットマップ画像データのメモリ領域 から(cx,xy)-(cx+original_width,cy+original_height)の矩形領域を、 転送先のメモリ領域 (dx,dy)-(dx+dist_width,dy+dist_height)へコピーする。 画像サイズ以上の座標を指定するとエラーになる。

blit と blit stretch は内部処理が微妙に違うそうです。32000色モード上で、白黒2色のbmp形式の画像を正常に表示するには 必ずset_gfx_mode()関数の直前で、set_color_depth 関数で色深度を設定しておけば問題ありません。

画像の転送(透過)
void masked_blit( BITMAP *src コピー元
, BITMAP *dest 転送先
, int cx コピー元 x座標
, int cy コピー元 y座標
, int dx 転送先 x座標
, int dy 転送先 y座標
, int width 幅 width
, int height 高さ height
);
画像中のピクセルRGB(255,0, 255)=「濃いピンク」 を 透明色として扱い、透過させることができる。ただし、コピー元と転送先の色深度は同じでなければならない。

画像の転送(透過 拡大)
void masked_stretch_blit(BITMAP *source コピー元
, BITMAP *dest 転送先
, int source_x コピー元x座標
, source_y コピー元y座標
, source_width幅
, source_height高さ
, int dest_x転送先x座標
, dest_y 転送先y座標
, dest_width 拡大後の幅
, dest_height拡大後の高さ
);
↑上記の拡大処理

スプライトは、前述の blit 関数 よりも高速で、重い処理をしてもゴミが残らない。 また、ビットマップオブジェクト全体を一度に送るので、幅や高さのパラメータを指定する必要がないという特徴をもっている。

Allegro のスプライトには、通常のスプライト, 圧縮スプライト,コンパイルスプライト の3方式が存在する。

スプライトを表示させる
void draw_sprite(BITMAP *bmp, BITMAP *sprite, int x, int y);
転送先の領域 *bmp の座標 (x,y)の位置に、スプライト *sprite を表示する。

スプライトの拡大処理
void stretch_sprite(BITMAP *bmp, BITMAP *sprite, int x, int y, int w, int h);


スプライトの反転処理 (垂直方向/水平方向)
void draw_sprite_v_flip(BITMAP *bmp, BITMAP *sprite, int x, int y);
void draw_sprite_h_flip(BITMAP *bmp, BITMAP *sprite, int x, int y);
void draw_sprite_vh_flip(BITMAP *bmp, BITMAP *sprite, int x, int y);


スプライトの回転処理 (回転の中心座標は画像の左上)
void rotate_sprite(BITMAP *bmp, BITMAP *sprite, int x, int y, fixed angle);


半透明スプライト 　
void draw_trans_sprite(BITMAP *bmp, BITMAP *sprite, int x, int y);
void draw_trans_rle_sprite(BITMAP *bmp, const RLE_SPRITE *sprite, int x, int y);
ブレンド関数に依存 こちらを参照。

RLE圧縮スプライト

メモリ消費を抑えたい場合はこの圧縮スプライトを使う。処理速度は通常のスプライトとあまり変わらないようだ。 RLE圧縮スプライトは 拡大、回転処理は用意されていないが、半透明処理 はサポートしている。

RLE_SPRITE *get_rle_sprite(BITMAP *bitmap );RLEスプライトを定義。
void draw_rle_sprite(BITMAP *bmp, const RLE_SPRITE *sprite, int x, int y);表示

RLEスプライトを使用する方法。
　 通常の画像をスプライトをRLEスプライトとして使用するには一行足すだけで済む。
しかし、get_rle_sprite でRLEスプライトを定義するタイミングを間違えるとプログラムは強制終了する。
これは、 blitして画像データを転送した後のタイミングでRLEスプライトを定義すると問題なく動作する。

BITMAP *image;//画像
BITMAP *tako_bitmap_pat[4];//スプライト用
RLE_SPRITE *tako_pat[4];//RLEスプライト用
//タコ画像→スプライト用領域へコピー
int i;
for(i=0;i<3;i++){ ;
//tako_bitmap_pat[i] = create_bitmap(25,33);
blit(image, tako_pat[i] , 26*i, 0 ,0,0 ,25,33);//画像を転送。
tako_pat[i]=get_rle_sprite(tako_bitmap_pat[i]);//このタイミングで RLEスプライトを定義
}
// tako_pat が BITMAP でもなぜか動くけど 構造体自体が違うので間違いです。.... tako_pat[i]=get_rle_sprite(tako_pat[i]);。
メモリの解放や、表示は　関数はRLEスプライト用のものが用意されている。
draw_rle_sprite( buffer, tako_pat[pat], tako[j].x, tako[j].y );//RLEスプライト用の関数
destroy_rle_sprite(tako_pat);//RLEスプライトを破棄

COMPILED_SPRITE

COMPILED_SPRITE *get_compiled_sprite(BITMAP *bitmap, int planar);
　 Compiled Sprite の処理速度はシステムのハードウェアに依存する。比較的高速だがメモリを多く消費するという。　 二番目のパラメータ int planar は、 FALSEなら ビットマップメモリを利用し、TRUE なら mode-X or Xtended mode を利用する。 詳細は不明だが 通常使用するならFALSE を指定しておく。

COMPILED_SPRITEを表示
draw_compiled_sprite( BITMAP *dist_screen, BITMAP *charachip, int x, int y );
COMPILED_SPRITEのメモリを解放
destroy_compiled_sprite( BITMAP *charachip );　//スプライトを破棄
Compiled Sprite の導入法も RLEスプライトと同じやり方。

拡張子 .fnt の bios 形式または、Allegro のDATAFILE 形式のUnifontによる文字表示を行う。 FONTオブジェクト に格納されている フォントデータをもとに文字を描画する。

これらの関数で日本語を表示するには、プログラムで使うコードをユニコードにして、DATAFILE形式のUnifontを自作するか、拡張ライブラリによってTrueTypeフォントを bios フォントに適用するしかない。

UTF8 エンコードを使っている場合、"ん"は UTF8では「E38293」と表されるので "\xE3\x82\x93" のように書いても"ん" と表示できます。
textout_centre_ex(screen, font, "\xE3\x82\x93" , 160, 96, makecol(0, 255, 0), -1);
textout_centre_ex(screen, font, "ん" , 160, 96, makecol(0, 255, 0), -1);
(※ 「￥」は実際には、半角バックスラッシュ)

システムフォント・オブジェクト
extern FONT *font;
Allegro システム内部で定義されているオブジェクト。
GUI や textout_ex 関数で表示される文字は この font オブジェクトが使われる。
デフォルトのフォントサイズは 8x8 pixel で、ASCII (U+20 to U+7F), Latin-1 (U+A1 to U+FF), Latin 拡張(U+0100 to U+017F)キャラクタの範囲が割り当てられている。

見つからない文字
extern int allegro_404_char;
Allegro システム内部で定義されている定数。
デフォルトでは「＾」に設定されている。フォント内にない文字は、すべてこれで表現される。


文字列の幅を取得
int text_length(const FONT *f, const char *str);
テキストの幅(pixel)を返す。byte数ではないので注意。

文字列の高さを取得
int text_height(const FONT *f);
テキストの高さ(pixel)を返す。フォントが画像データとして扱っているから px なのです。


メモリを解放
void destroy_font(FONT *f);
フォントデータの解放。ただし、AllegroFont のようなテキスト補助ライブラリを利用する場合、
必ず拡張ライブラリにincludeされている関数を使って解放する必要がある。
この関数を併用して用いると競合し、クラッシュする場合があるので注意。

---

テキスト表示

通常表示 (左揃え)
void textout_ex(BITMAP *bmp, const FONT *f, const char *s, int x, y, color, bg);
テキストを(x,y) の位置に 表示する
(描画領域 , フォント , 文字列 , x座標 , y座標 , 文字色 , 背景色)

中央揃え
void textout_centre_ex(BITMAP *bmp, const FONT *f, const char *s, int x, y, color, bg);
　　　　　　　　　　に比べて中央よりに表示。

右揃え
void textout_right_ex(BITMAP *bmp, const FONT *f, const char *s, int x, y, color, bg);
　　　　　　　　　　　　　　　　　　　　　　　　　　　に比べて右よりに表示

間隔を開ける
void textout_justify_ex(BITMAP *bmp, const FONT *f, const char *s, int x1, x2, y, diff, color, bg);
文　字　を　一　定　の　間　隔　を　空　け　表　示　す　る 。
diff : スペースの最小値

Printf 書式で表示
void textprintf_ex(BITMAP *bmp, const FONT *f, int x, y, color, bg, const char *fmt, ...);
void textprintf_centre_ex(BITMAP *bmp, const FONT *f, int x, y, color, bg, const char *fmt, ...);
void textprintf_right_ex(BITMAP *bmp, const FONT *f, int x, y, color, bg, const char *fmt, ...);
void textprintf_justify_ex(BITMAP *bmp, const FONT *f, int x1, x2, y, diff, color, bg, const char *fmt, ...);
文字列中に、変数を含めて表示することができる。 printf()な書式で便利ですが長文に向かない。 (...文字列、文字列, )

Allegro は WAVE サウンドデータを再生する方法を 3種類もっている。 (※ MIDI を除く)
* Sound init routines ： 通常の サンプリング再生
* Digital sample routines ：ミキシング と Voice 再生
* Audio stream routines：波形加工 と ストリーム再生

これらの機能を利用するには、まずサウンドモジュールを有効にする必要がある。

サウンドモジュールを有効にする。
int install_sound(int digi, int midi, const char *cfg_path);

サウンドドライバに、DIGI_AUTODETECT や MIDI_AUTODETECT といったパラメータを渡してサウンドモジュールを有効にする。パラーメータは、 コンフィグファイルから読み込むことも出来るようだ。OS固有のドライバ(DIGI_CORE_AUDIO, MIDI_QUICKTIME等)については、マニュアルの the platform specific documentation for a list of the available drivers. が参考になる。

int digi
DIGI_NONE ：サウンド機能を使用しない
DIGI_AUTODETECT ：サウンドデバイスを 自動的に検出

int midi
MIDI_NONE ：MIDIを使用しない
MIDI_AUTODETECT ：MIDIデバイスを 自動的に検出

const char *cfg_path
コンフィグファイルのパス
NULL = コンフィグファイルを使用しない場合。

返値： 　　0 =　成功 　　-1 = 失敗 (allegro_error)
参考：サウンド録音 * Recording routines：

---

この項では、主にサンプル再生について説明する

Allegroでは、WAVE形式とVOC形式のファイルを利用することができる。複数の音を同時に鳴らせるので、効果音とBGMに分けて使えるかもしれない。

サンプルの準備
SAMPLE *spl;
サンプル(音データのこと)を用意する

WAVファイルを読み込む
SAMPLE *load_sample(const char *filename);
vocフォーマットあるいは wav フォーマットのファイルを読み込む。このwavファイルは、コンパイルされたAllegroアプリケーションと同じディレクトリに置かなければならない。

spl = load_sample("samples.wav");

サンプルを再生する
int play_sample(const SAMPLE *spl, int vol, int pan, int freq, int loop);
vol ： 音量 MIN 0--------255 MAX
pan ： 音の出る方向 LEFT 0 - 127 - 255 Right
freq： 周波数の調節 1000 = 通常再生、 2000 = 再生スピード2倍＆音高UP
loop： ループフラグを有効にすると adjust_sample().が呼び出されて loopフラグが変更されるか、stop_sample()されるまでループ再生される。
返値 が 正の数なら 再生に成功した事を示す。

play_sample( spl,127, 127 , 1000 , 1);
readkey();
play_sample( spl,127, 127 , 2000 , 1);
readkey();

このようにすると、同じ音楽が二重に再生され輪唱のようになる。
もし、再生途中で何かを変化させたいならadjust_sampleを利用する。

play_sample( spl,127, 127 , 1000 , 1);
readkey();
adjust_sample( spl,127, 127 , 2000 , 1);//途中から2倍速に
readkey();

再生中の変更
adjust_sample(const SAMPLE *spl, int vol, int pan, int freq, int loop);
この関数を使えば、再生中のサンプルのパラメータを調節することができる。
パラメータの並び方は 先ほどの play_sample関数と同じなので上のを説明を参照する。

例えば、ループフラグ (int loop )の設定を有効/無効にしたり、サンプリング 周波数 ( int freq )を変更すると 曲の途中で再生スピードを変えたりも出来る。 音量( int vol )を フェードしたりなど。もしサンプルが再生されていない場合は、何も変更されない。

再生の停止
void stop_sample(const SAMPLE *spl);
サンプル再生を停止する(リジュームは効かない)。音楽を二重に再生していた場合は
同一のSAMPLEストラクチャに由来するものをすべて停止する。

コードの例：

SAMPLE *spl,*spl3;
spl= load_sample("loop02.wav");
spl3= load_sample("loop03.wav");

play_sample( spl,127, 127 , 4000 , 1);
readkey();
adjust_sample( spl,127, 127 , 1000 , 1);
readkey();
play_sample( spl3,127, 127 , 500 , 1);
readkey();
stop_sample(spl);
readkey();

もっと高度なサウンド処理を行いたい場合。Voice control にサンプル(音)データを渡して再生やエフェクトをかける。 play_sample() 関数よりも柔軟な再生が可能。これらの関数は Audio stream 関数による再生にも対応している

サンプル ストラクチャの概要

typedef struct SAMPLE

int bits; - 8 or 16
int stereo; - sample type flag
int freq; - sample frequency
int priority; - 0-255 */
unsigned long len; - length (in samples)
unsigned long loop_start; - loop start position
unsigned long loop_end; - loop finish position

使用されるSAMPLEストラクチャの定数：

int priority;
Ranging 0-255 (default 128) ,割り振られる音の数？
　
unsigned long loop_start;
unsigned long loop_end;
ループ地点とループの終了地点

サンプルデータを 渡す
int allocate_voice(const SAMPLE *spl);
Voice control のために サンプルを 読み込む。
voice number,が返れば成功 、-1を返す場合はvoice データが存在しないことを意味する。
使い終わったあとは、 deallocate_voice() あるいは release_voice() でメモリを解放しなければならない。


メモリを解放する
void deallocate_voice(int voice);
使い終わったらメモリを解放する。


再生データの切り替え
void reallocate_voice(int voice, const SAMPLE *spl);
新たに他のサンプルデータに読み替えするにはこの関数を使う。
この関数を実行する事は
deallocate_voice(voice); voice = allocate_voice(sample);　
したことと同じ意味になる。

再生終了
void release_voice(int voice);
メモリは解放されるが音楽は流れ続ける。
deallocate_voice()と同じような機能を持つが微妙に違う。

再生データの情報を取得
SAMPLE *voice_check(int voice);
現在、Voice control されている サンプルデータをチェックする。
NULLが返ってきた場合は サンプルデータが有効になっていない事を示す。

再生する
void voice_start(int voice);
Voice control を有効にする。

一時停止する
void voice_stop(int voice);
voice_start が再び呼ばれるまで 再生を一時停止する。(リジューム)

再生位置の指定
void voice_set_position(int voice, int position);
サンプルの再生位置をセットする。

再生モードを指定する
void voice_set_playmode(int voice, int playmode);

PLAYMODE_PLAY 一度だけ再生する。(ループフラグなしの場合はデフォルト)
PLAYMODE_LOOP ループ再生する。 終わりに達すると、最初の位置に戻って再生する。
PLAYMODE_FORWARD ：終わりから逆再生する( もし backwardフラグがない場合はデフォルト)
PLAYMODE_BACKWARD： 逆再生ループが可能。
　　　　　　　　　　　　ループフラグとの併用時も開始位置を気にせずにループ可能？
PLAYMODE_BIDIR ：ループフラグと併用すると一方のループ地点に達したら再生方向を変更する。

音量を調節する
int voice_get_volume(int voice);
音量を 0-255.の範囲で取得

void voice_set_volume(int voice, int volume);
音量を 0-255.の範囲でセット

音データに対しエフェクトをかける
void voice_ramp_volume(int voice, int time, int endvol);
volume ramp処理の実行：クレッシェンド (だんだん強く) あるいは デミニュエンド(だんだん弱く)の効果を得る。 指定された時間(ミリ秒)の間に 現時点の音量から int endvol に音量を変動させる。音量のフェードを行う。

void voice_stop_volumeramp(int voice);
volume ramp処理の実行を中止する

int voice_get_frequency(int voice);
再生されている音のピッチを Hz 単位で得る。

void voice_sweep_frequency(int voice, int time, int endfreq);
frequency sweep処理：指定された時間(ミリ秒)の間に 現時点の周波数からint endfreq に周波数を変動させる グリッサンド効果を得る。

void voice_stop_frequency_sweep(int voice);
frequency sweep処理の実行を中止する。


int voice_get_pan(int voice);
パン：音の発せられる位置を取得する。
0 (左から聞こえる) 　127(中央から)　 255 (右から聞こえる).

void voice_set_pan(int voice, int pan);
パン：音の発せられる位置を指定する。
0 (左から聞こえる) 　127(中央から)　 255 (右から聞こえる).


void voice_sweep_pan(int voice, int time, int endpan);
pan sweep 処理：パン位置を変動する。

void voice_stop_pan_sweep(int voice);
pan sweep 処理の実行を停止する。


void voice_set_echo(int voice, int strength, int delay);
エコーに関する　パラメータを設定する。

void voice_set_tremolo(int voice, int rate, int depth);
トレモロに関する　パラメータを設定する。

void voice_set_vibrato(int voice, int rate, int depth);
ビブラートに関する　パラメータを設定する。

(仮)：Audio stream関数は 一般的なSAMPLE ストラクチャでは収まらないような大きなサウンドデータを再生したり、 巨大な音声ファイルからデータを部分的にロードしたり、波形データを生成してなにかしたい場合に使われる。

オーディオストリームの再生
AUDIOSTREAM *play_audio_stream(int len, bits, stereo, freq, vol, pan);
この関数は、新規にaudio stream とその再生を行う。 int len にはサンプルから構成されるフレーム(byte数ではない)毎に変換するデータの長さを指定する。 サンプルフレームは 1つ のモノラルデータ あるいは 2つの組から成るステレオデータである。

この長さは通常 (そうなるとは限らないが) 約1k のサイズで 2の累乗となる？。 バッファサイズが大きいと、わずかな更新で大きな効果を得られるが、実際にはデータを再生する間に遅延が発生してしまう結果となる。

bits パラメータは 8 または 16を指定しなければならない。
freq パラメータは 周波数のサンプリングレートを指定する。
vol と pan パラメータはそれぞれ 0-255の範囲で 設定する。
stereo パラメータは ステレオなら1を、それ以外なら0を指定する。

もしあなたが 再生中にピッチや音量、パンを調整したいなら stream->voice をパラメータとして voice_*() 関数 を利用することができる。
サンプルデータは、通常、 unsigned format.(0 -255)が使われる。

バッファサイズを求めるための公式は次のようになる。

bytes = len * (bits / 8) * (stereo ? 2 : 1);

メモリの解放
void stop_audio_stream(AUDIOSTREAM *stream);
audio stream に使ったメモリを解放する。

再生中の監視
void *get_audio_stream_buffer(AUDIOSTREAM *stream);
あなたはこの関数を audio stream 再生している間に一定の間隔で呼ばなければならない。
次のサンプリングデータが格納されたバッファを提供するために(もしストリーミングのためのバッファが小さければ、頻繁に呼ばれるべきである。)

もしこの関数が NULL を返すなら、ストリームはまだ多くのデータを再生しているので、あなたは何もしなくてもよい。 そして関数が 次に再生されるバッファ位置 といった数値を返すならば あなたは適切な数のサンプル(あなたが作成した数の)をアドレスにロードすべきである。

例えば、fread()関数を使用して次のデータをバッファに満たした後に 新しいデータが有効であるということを明確にするために free_audio_stream_buffer() 関数を呼び出しなさい。
注意：この関数は一定の間隔で呼び出す必要があるが、タイマーハンドラから 呼び出してはいけない。

再生位置をプログラムに告知
void free_audio_stream_buffer(AUDIOSTREAM *stream);
get_audio_stream_buffer() 関数がNULL 以外のアドレスを返したあとに、
その位置に新しいサンプルデータをロードされ再生される準備ができていることを示すためにはこの関数を呼びなさい。

(仮)
Allegroのファイル操作関数は大きく 3つに分類できます。PackFile と DATAFILE はAllegro固有ものです。

ディレクトリパス 操作系( 各OSのシステムに対応。主にパス置換、情報取得、検索機能。※)

PackFile形式の出入力(LZH圧縮)

DATAFILE形式のアーカイブファイルの出入力。DATファイル関連

※今の所 Allegroでは、プレーンテキストを読込むための汎用的なAPIは用意されていません。必要な人は自作して下さい。(一応テキストファイル読み込みとして、 コンフィグファイルの読み込みはサポートされてはいます。)

MacOSXでは、バンドル形式とそうでない場合で、ファイルの置き位置が違ってくることがあります。注意して下さい。


この章では、ディレクトリパス 操作系 と、PackFile形式の出入力の関数を紹介します。

ディレクトリパス 操作系

実行プログラムのあるディレクトリ名を取得する
void get_executable_name(char *buf, int size);
現在実行中のAllegro実行アプリケーション本体のある場所をフルパスで取得します。
「絶対パス名＋実行ファイル名」 が char *buf に入ります。size は割り当てるメモリの量。

//パス名を格納
char name[200];

get_executable_name(name, sizeof(name));
allegro_message("Running `%s'\n", name);

結果：
c://usrname/project/program.exe
user/project/build/program.app

ファイル名を差し替える
char *replace_filename(char *dest, const char *path, const char *filename, int size);
「絶対パス名＋ファイル名」のファイル名の部分を差し替えます。 size バイトぶんが dest にコピーされます。
どんな使い方をするかは次の例を見てください。

//パス名を格納する変数
char name[200];
...
get_executable_name(name, sizeof(name));// 実行ファイルのある場所を フルパスで取得
replace_filename(name, name, "sound.dat", sizeof(name));// sound.dat に差し替え

相対パス指定ではファイルを読み込まない場合もあります。replace_filename関数と get_executable_name関数を使って絶対パス指定でファイルを読み込ませることができます。
注意：この方法を使った場合、日本語が混じったファイルパスに置くと ダメみたいです。この問題が改善されるまでは気を付けてください。

char name[200];
get_executable_name(name, sizeof(name)); //例えば、 user/desktop/tetris/program.app が name に代入されます。
allegro_message("Running `%s'\n", name);

// ファイル読込み( MapLoad と TextLoad 関数はユーザが用意した関数で、
// C標準ライブラリの fopen 関数を使ってテキストファイルを読み込むというものです。
// 関数を fp= fopen( name , "r" ); というように使っています。 )


// ファイル名を差し替える replace_filename(name, name,"map.txt", sizeof(name)); MapLoad(name);// name に格納されている絶対パス名 user/desktop/tetris/map.txt で読み込みます

replace_filename(name, name,"story.txt", sizeof(name));
TextLoad(name);// name に格納されている絶対パス名 user/desktop/tetris/story.txt で読み込みます。

その他のファイルパス操作系関数

ファイルが存在するか調べる
int file_exists(const char *filename, int attrib, int *aret);
与えられたファイル名と属性(この章の最初を見ること)が一致するファイルが存在するかどうかを調べます。
また、int *aret が NULL以外が指定された場合には、一致したファイルにその属性を付加します。

例：
/* ファイルが存在するか調べる */
if (file_exists("franken.dat", 0, NULL))
allegro_message("It is alive!\n");

返値：
0以外 なら ファイルが存在することを表します。
0 なら、ファイルが見つからないか、指定した属性が一致しないかです。

ファイルが存在するか調べる(短縮形)
int exists(const char *filename);
file_exists()関数の短縮バージョン。アーカイブや読み取り専用のビットがセットされていても、普通のファイルとしてチェックします。 しかし、ディレクトリやシステムファイル等は隠されません。
返値：
0以外 - ファイルが存在する
0 - ファイルが存在しない

ファイルサイズを byte数で返す。
long file_size(const char *filename);
指定した名前のファイルの容量を byte数で返します。もし、ファイルが存在しない場合は 返値には0が返り、Allegroシステムのエラー変数errnoに エラーコードが記録されます。

ファイルの変更日時 を返す。
time_t file_time(const char *filename);
　 ファイルの変更日時を、1970年1月1日の00:00:00 世界標準時刻 からカウントされた秒数で返します。 ファイルが存在しなかったりエラーが発生した場合 0を返し、Allegroのエラー変数に エラーコードを記録します。

末尾の拡張子を置き換えて、「ファイル名+拡張子」 形式の名前にする。
char *replace_extension(char *dest, const char *filename, const char *ext, int size);
　 新しい拡張子を末尾に追加して、指定された「ファイル名+拡張子」 形式の名前に置き換えます。char *dest バッファに、最大int size byte 記録します。 もし、ファイルに拡張子が付いていない場合は char *ext に指定された拡張子名が補完されます。 この関数ではAllegroの内部処理のおかげで 、入力 と 結果 を同じ変数で済ませる事ができます。

例：
replace_extension(buf, "C:\\game\\prog.exe", "dat", sizeof(buf));

パスからファイル名の部分を返す。
char *get_filename(const char *path);
　 指定したファイルパスから、ファイル名の部分を返します。DOSやWindows環境下では `\(バックスラッシュ)' と `/(スラッシュ)' がディレクトリの区切りとして認識されます。 ただし、`/(スラッシュ)'は、他のプラットフォームでも区切りとして確認されることがあります。

例：
get_executable_name(name, sizeof(name));
allegro_message("Running `%s'\n", get_filename(name));

注意：Allegroは、検証中にはどんな出入力操作も行いません。なぜなら、ファイル名が含まれないディレクトリパス「/a/path/like/this/」であれば関数はNULL文字を返しますが。 しかし「/a/path/like/this」というディレクトリパスの場合、これがディレクトリとして正しいものであっても、ポインタとして「this」が返されるからです。
返値：
ディレクトリパスのファイル名の開始位置部分へのポインタ 、あるいは、有効なファイルが見つからない場合はディレクトリパスの開始位置へのポインタ(例えばUnix環境下でバックスラッシュを用いている場合)

---

# find_allegro_resource — ファイルを複数の場所で検索する機能を提供する
# append_filename — ファイル名とパスを連結する
# canonicalize_filename — どんなファイル名も 文字上の正規化された形式(canonical form)に変更する。
# fix_filename_case —ファイル名を大文字に変更 (DOSのみ)
# fix_filename_slashes — すべてのディレクトリ区切りを変更する。 (DOSのみ)

# is_relative_filename — ファイル名が相対パスなら TRUE を返す。 　
# get_extension — ファイル名の拡張子 を返す。 　
# put_backslash — パスの最後に、セパレータ(バックスラッシュ)を追加する。
# set_allegro_resource_path — Allegroリソースを検索する特殊パスを設定する。
# make_absolute_filename — 相対パスから絶対パス表記へ変換する。
# make_relative_filename — 絶対パスやファイル名から相対パス表記へ変換を試みる。

# al_findclose — 既にal_findfirst()関数によって検索されたものを閉じる。　
# al_findfirst — ファイル検索のためのローレベル(細かい指定ができる)関数。
# al_findnext — al_findfirst()関数による検索で次のファイルを検索する。
# delete_file — ディスクからファイルを取り除く。
# for_each_file_ex — 互いのファイルがワイルドカードにマッチした場合に callback()関数を実行する。 　

圧縮ファイル：AllegroのPackfile出入力について

AllegroのPackfileルーティンは奥村晴彦氏による LZSS compressorアルゴリズムに基づいていて、高速バッファ I/Oシステムを実行して圧縮ファイルの読み書きを行う。これはZIPやLHAのような圧縮専門プログラムの圧縮率には劣るが解凍速度は非常に早く、また必要なメモリが少なくて済む。

圧縮ファイルは常に、32bitの変数F_PACK_MAGICから始まり、F_NOPACK_MAGIC のファイルを自動検出する。 次に述べるFA _ * フラグ、 FA_RDONLY 、FA_HIDDEN 、FA_SYSTEM 、FA_LABEL 、FA_DIREC 、FA_ARCH が機能することが保証される。しかし、FA_SYSTEM, FA_LABEL, FA_ARCH といったフラグは DOS/Windowsだけの変数なのでこれらのフラグを使えば他のプラットホームでコンパイルすることはできなくなる。

' attrib ' パラメータ一覧
( パラメータに指定するフラグは '|' ( OR 演算子)で繋げることによっていくつも併用できる。)

FA_RDONLY ：DOS系の「読み取り専用」 やUnix系システムの 「書き込み不可」のようなフラグをディレクトリ・エントリに対して行う。
FA_HIDDEN ：DOS系の「.(ドット)」(Unix系の「.」,「..」を除く)で始まるファイル名を隠すフラグである。
FA_DIREC ： ディレクトリの代用となるフラグ。
0xFF ： すべて

' attrib ' パラメータが関数に渡されたとき、マッチしたファイルがそこに含まれているとフラグが立つ。すなわち一致するべきファイルの属性は、指定したフラグを含むかもしれないが、しかし明記していないフラグを含んではいけない。従って、' FA_DIREC | FA_RDONLY ' を渡したら、正常なファイルと、ディレクトリが「読み取り専用」でなければならない。しかし、隠しファイルではないファイルとディレクトリである。 もし、'FA_ARCH'フラグを渡した場合は、アーカイブ化されたファイルとされていないファイルが同時に含まれることになる。

' attrib ' パラメータを使用する関数の一例：
int file_exists(const char *filename, int attrib, int *aret);
int for_each_file_ex(const char *name, int in_attrib, int out_attrib, int (*callback)(const char *filename, int attrib, void *param), void *param);
int al_findfirst(const char *pattern, struct al_ffblk *info, int attrib);

なお、これらの関数を使わずに、C標準ライブラリのファイル出入力関数を使って、
ファイルを読み込むことも可能。

関連：
* Datafile routines
サンプルコード： expackf.c

PackFile ファイル出入力

主にPACKFILE ストラクチャが対象

pack_fopen — 各モードによるファイル読込み.

pack_fopen_chunk —ファイルを sub-chunkとして開く。

pack_fopen_vtable — ファイル構造を標準関数ではなくvtableの関数を使って開く。

pack_fclose — pack_fopen()関数で開いたファイルを閉じる

pack_fclose_chunk — 開いたsub-chunk を閉じる

ファイル読み込み
PACKFILE *pack_fopen(const char *filename, const char *mode);

指定したモードに従ってファイルを読み込む。

ファイル出入力フラグ：
'r' - ファイル読込みモード
'w' - ファイル書込みモード、存在するデータを上書きする。
'p' - 「Packed Mode」でファイルを読込む。データを書き込む時はそれが 圧縮され、自動的にファイルが開いている間は解凍されている。
このモードで 作成されたファイルは、このモードで読込まれない場合はゴミデータが生成される。
'!' - 通常モード(非圧縮モード)で書き込みを行なう。しかし ファイルの先頭に value F_NOPACK_MAGIC を追加した場合、
圧縮モードで書き込んで Allegroはそのデータが解凍する必要はないか自動的に検出作業を行う。

これらの代わりに、

F_READ
F_WRITE
F_READ_PACKED
F_WRITE_PACKED
F_WRITE_NOPACK

を指定することもできる。

返値：
PACKFILEストラクチャへのポインタ- 成功
NULL - 失敗

魔法のファイルネームについて。
"#" - #マーカーを使って「ファイル名.dat#パスまたはオブジェクトネーム」という形式のファイルパスを渡すと
exdat 関数によって保存されたDAT形式の任意のデータを読み出す事ができる。DATファイルの階層指定にも対応している。

' filename.dat#object_name '
' filename.dat#graphics/level1/mapdata '

また、もしそれから独立したオブジェクトを読み込もうと考えているなら、
オブジェクトごとに圧縮されるか、無圧縮のDAT形式のDatafileで保存しておきなさい。

(さもなければ、それが読み込まれた時に余分なデータを探すことになり?)
最終的に、特殊なAllegro-object types がDATからインポートしたファイルと同じ形式ではないと分かる。


Grabber から サンプリング音源 や ビットマップ関数のようなデータをインポートした時、それらは特殊なAllegro-object 形式に変換される。しかし「#」マーカー
ファイル構文が含まれていると、バイナリデータとしてオブジェクトを読み込む。これは 例えば、あなたがDatafileから画像を読み込む時に load_pcx関数を使いたいと思ったなら、BITMAPオブジェクトよりもバイナリブロックとしてインポートすべきであることを意味する。


vtableによるファイル読込み
PACKFILE *pack_fopen_vtable(const PACKFILE_VTABLE *vtable, void *userdata);
標準関数の代わりに、vtable で指定された機能を利用する新しい PACKFILE ストラクチャを作成する。 vtable と usedata は、PACKFILEが存在する限りは残さなければならない。 この時、pack_fopen_chunk()関数 を利用して、packfileの先頭に戻ってデータの塊(chunk)を開くことはできない。 また、pack_fopen_vtable()関数を使って開いたpackfileにpackfile_password()関数を適用して効果をもたらさない。

返値：
PACKFILEストラクチャへのポインタ- 成功
0 - 失敗


ファイルを閉じる
int pack_fclose(PACKFILE *f);
既に pack_fopen()関数によって読み込まれた PACKFILE *f ストリームを閉じる。これによりファイルが閉じたれたあとに、ファイル関連の操作をするとエラー(クラッシュ等)が発生したりするので注意する。

返値：
0 - 成功
errno. - 失敗した場合はエラー番号として内容が返る
この関数は、ファイル書き込み時のみ、failを返すことができる。(ファイル読み込み時には必ず0が返るため)


ファイル内検索
int pack_fseek(PACKFILE *f, int offset);
PACKFILE *f のファイル出入力位置を移動させる。 C標準のfseek()関数とは異なり、この関数は現在位置より前方しか対応しないので、オフセット int offset に負の値を指定することはできない。

返値：
0　- 成功
マイナス - エラー

PackFile データ出入力

PACKFILE ストラクチャ、
LZSS_PACK_DATA , LZSS_UNPACK_DATA ストラクチャが対象。

int lzss_read

int lzss_write

LZSS を使用してデータを読む
int lzss_read(PACKFILE *file, LZSS_UNPACK_DATA *dat, int s, unsigned char *buf);
データを dat から bufへ解凍します。ファイルの s バイトぶんまたは EOFまで達したデータが解凍されます。
返値:
バッファ buf へ追加されるbyte数を返します。

LZSS を使用してデータを書き込む
int lzss_write(PACKFILE *file, LZSS_PACK_DATA *dat, int size, unsigned char *buf, int last);
buf から、データを size byteぶん圧縮します。圧縮情報は dat に含まれます。圧縮されたバイトデータは、 file に保存されます。
返値:
0 - 成功
EOF - エラーが発生した

Pack File ストラクチャ

圧縮、解凍データに関するストラクチャ。

LZSS_PACK_DATA

create_lzss_pack_data — 作成

free_lzss_pack_data — 解放

LZSS_UNPACK_DATA

create_lzss_unpack_data —作成

free_lzss_unpack_data — 解放

圧縮のためのLZSS_PACK_DATAストラクチャを作成する。
LZSS_PACK_DATA *create_lzss_pack_data(void);
圧縮のためのLZSS_PACK_DATAストラクチャを作成する。これは、Packfile で LZSS圧縮に使うためのものです。
返値：
ストラクチャへのポインタ - ストラクチャが正常に作成された
NULL - 失敗した。
　
作成されたLZSS_PACK_DATAストラクチャを解放する。
void free_lzss_pack_data(LZSS_PACK_DATA *dat);
create_lzss_pack_data()関数によって作成されたLZSS_PACK_DATAストラクチャを解放します。


解凍のためのLZSS_UNPACK_DATAストラクチャを作成する。
LZSS_UNPACK_DATA *create_lzss_unpack_data(void);
解凍のためのLZSS_UNPACK_DATAストラクチャを作成する。これは、Packfile で LZSS解凍に使うためのものです。
返値：
ストラクチャへのポインタ - ストラクチャが正常に作成された
NULL - 失敗した。
　
作成されたLZSS_UNPACK_DATAトラクチャを解放する。
void free_lzss_unpack_data(LZSS_UNPACK_DATA *dat);
create_lzss_unpack_data()関数によって作成されたLZSS_UNPACK_DATAストラクチャを解放します。

---

# pack_feof — 非0が返った場合、ファイルの終端(eof)に達した事を意味する。
# pack_ferror — ファイルに対する出入力を行う時に発生したエラーをユーザに教える。　


# pack_fgets — ファイルに対する出入力(行単位で読む)
# pack_fputs — ファイルに対する出入力(文字列を書込む)
# pack_fread — ファイルに対する出入力( n bytes 読込む)
# pack_fseek — ファイルに対する出入力(ファイル位置を探し出す)
# pack_fwrite —ファイルに対する出入力( n bytes 書込む)

# pack_getc — ファイルに対する出入力(次の文字を得る)
# pack_putc — ファイルに対する出入力(　文字を書き込む)
# pack_igetl — pack_getc()関数のように, 32-bit Intel byte 形式の words データを得る
# pack_igetw — pack_getc()関数のように, 16-bit Intel byte 形式の words データを得る
# pack_iputl — pack_putc()関数のように, 32-bit Intel byte 形式の words データを書込む
# pack_iputw — pack_putc()関数のように, 16-bit Intel byte 形式の words データを書込む
# pack_mgetl — pack_getc()関数のように, 32-bit Motorola byte 形式の words データを得る
# pack_mgetw — pack_getc()関数のように, 16-bit Motorola byte 形式の words データを得る
# pack_mputl — pack_putc()関数のように, 32-bit Motorola byte 形式の words データを書き込む
# pack_mputw — pack_putc()関数のように, 16-bit Motorola byte 形式の words データを書き込む.

# packfile_password — packfileに暗号化されたパスワードを設定する。　

Allegro には、複数のファイルを1つのファイルにまとめて アーカイブする機能があります。(Packfile とは別の機能です。)

このAllegroのアーカイブ形式 Datafile を作成、編集するために GUIインターフェースを持つ Grabber 、そしてCUIインターフェースを持つ DAT という ツールが用意されています。

これらのツールは Allegro を解凍したディレクトリ内の tool というディレクトリを探せば見つかる。

Grabberはダブルクリックするか、コマンドラインで実行するとフルスクリーンモードで立ち上がります。 それに対して、DAT は、コマンドラインから、引数を渡して実行します。
以下は、CUIインターフェースを持つ DATツール についてのメモです。

DAT ツールは '-a' オプションを加える事で、アーカイブ機能を利用することができる。
この アーカイブモード を利用して、複数のリソースをひとつの .dat ファイルに固めることができる。

dat myfile.dat -a alien.pcx scream.wav

とコマンドを打てば、
alien.pcx と scream.wav が myfile.dat というアーカイブに追加される

dat ファイルにアーカイブされるデータには オブジェクトのタイプと、オブジェクト名、 プロパティ、データ自身 の情報が格納される。 このうち、引数に使われた ファイル名と 拡張子 によって オブジェクトのタイプとオブジェクト名が自動的に反映される。

最初の例では alien.pcx というファイルは オブジェクトのタイプ .pcx →「bitmap」、 オブジェクト名は 「alien」 というデータとしてアーカイブ内に格納される。

しかし 拡張子によっては、ビットマップあるいはスプライト 等様々な用途に用いられるものも存在する。 その場合は、'-t' フラグを使って そのデータが属するオプジェクトのタイプを 指定してやるとよい。

特定のオブジェクト のタイプを指定するには、'-t' フラグを使う。

dat myfile.dat -a alien.pcx -t RLE

pcx ファイルですが、 オプジェクト のタイプは RLE スプライトとして格納される。

ほかのオプションの説明。
'-c0' -無圧縮
'-c1' - ファイル個別に圧縮
'-c2' - アーカイブ全体を圧縮
'-d ' アーカイブの中から 指定したオブジェクト名のデータを削除する。
'-e ' アーカイブの中から指定したオブジェクト名のデータを取り出す。
名前にはワイルドカードが使える。-o オプションと一緒に使えば、
データを、ディレクトリやファイルに名前をつけて出力することができる。
'-h outputfile.h' アーカイブの中に格納されているデータの索引をヘッダファイルとして、出力する。
このファイルは データファイルを読み込む際に include することもできるらしい。

'-007 password' パスワードをセットする。

' PROP=value' プロパティ と値の組み合わせで、アーカイブ内のプロパティの値を変更できる。
my_object というオブジェクトの名前を what_a_silly_name という名前に変更する場合は

dat myfile.dat my_object NAME=what_a_silly_name

となる。

Allegro には、複数のファイルを1つのファイルにまとめて アーカイブする機能があります。(Packfile とは別の機能です。) このアーカイブは、DATAFILE形式と呼ばれ拡張子は.dat と定められています。 このアーカイブ は、Grabber や DAT と呼ばれるツール(Allegro解凍ディレクトリ内に用意されています。)を使って作成します。

dat ファイルは オブジェクトのタイプと、名前、と プロパティと、データそのもの に分かれていて、 作成したアーカイブ内のデータへは、Allegro プログラムからAPI を通じてアクセスすることができます。

DATAFILEの読み込み
DATAFILE *load_datafile(const char *filename);
データファイルの読み込み
DATAFILE *load_datafile_callback(const char *filename, void (*callback)(DATAFILE *d));
コールバック(ある関数が呼ばれた場合にそれを実行する仕組み)を使った読み込み。

メモリの解放
void unload_datafile(DATAFILE *dat);
メモリリークを回避する為に、使い終わったらメモリを解放する。
*dat に関連する すべてのデータが解放される。

アーカイブからデータをロード
DATAFILE *load_datafile_object(const char *filename, const char *objectname);
DATAFILEアーカイブから、特定のオブジェクト名をもつデータをロードする。
注意すべき点は、アーカイブファイル全体を圧縮していた場合は、読み込み処理は遅くなること。

読み込んだ特定のデータのメモリを解放
void unload_datafile_object(DATAFILE *dat);
データファイルから読み込んだ、特定のオブジェクト名のデータのメモリを解放する。

アーカイブ内を検索
DATAFILE *find_datafile_object(const DATAFILE *dat, const char *objectname);
すでに読み込んだデータファイルから、特定のオブジェクト名のものをポインタで返す。もしNULLを返した場合は、見つからなかったことを意味する。
この関数は、 '/' と '#' で区切られた データファイルパスの入れ子を認識する。


オブジェクトのプロパティを取得
const char *get_datafile_property(const DATAFILE *dat, int type);
データファイルから、指定したタイプのデータのプロパティを取得する。
int type は DAT_ID macro によって作成されたものを用いる。

オブジェクトのタイプを取得
Macro DAT_ID(a, b, c, d);
　４文字で指定されたデータファイル内のオブジェクトのタイプを返す。
例えば、下のように使う。
get_datafile_property(datob, DAT_ID('N','A','M','E'));

データファイルの使い方
Grabber によってアーカイブするか、あるいはコマンドラインからDAT を使って

dat myfile.dat -a COOL_PICTURE.bmp

のように アーカイブを作成した場合にAllegro からそれを利用する場合。

DATAFILE *dat;
BITMAP *bmp;

dat = load_datafile("myfile.dat");//アーカイブを読む
if (!dat) { return;}//エラー

// *dat の中に格納されている「 BITMAP」タイプの
// 「COOL_PICTURE」というオブジェクト名 の データを読む。
bmp = (BITMAP *)dat[COOL_PICTURE].dat;

項目がネストされている場合は、親ノード名の DATAFILEオブジェクトを
作って、そこから同じように指定するらしい。

DATAFILE *dat = load_datafile("whatever.dat");//
DATAFILE *nested = (DATAFILE *)dat[内包ファイル名].dat;
FONT *thefont = (FONT *)nested[NESTED_FILE_A_FONT].dat;

Allegroはまた、固定小数点 を持つ 型 の 数を扱う関数を提供する。 これらは、小数点切り上げや、他の型変数との変換、四則演算、三角関数 等の機能を提供する。

固定小数点数とは、小数点位置を固定し、「整数部」と「小数部」と、内部データが2つに分かれているものを指す。 (「fixed」type は 符号付き 32-bit 整数 として、整数部小数部を、それぞれword型(16bit)として格納されている。 整数部は上位word , 小数部分は下位word の順に格納されている)

この型 表現できる数は -32768 から 32767 の範囲で、小数位は下4〜5桁までの精度 の 数を表現することができるとのこと。 固定小数点数は、計算の精度よりも、高速な計算　が得意という特徴を持っている。


参考文献：

固定小数点数について

浮動小数点数について

端数処理について(四捨五入, 丸め 等)

整数→固定小数点数
fixed itofix(int x);
整数( int )型の変数 を 固定小数点( fixed )型に 変換する。
これは、x <<16 したのと同じことを意味する。

数値だけ並べた場合に手っ取り早く 固定小数点型の数に変換する場合に
は、左に16ビットシフトした x <<16 という形で用いられることがある。

　　整数部　　　　小数部
| 16ビット | 16ビット |
　　　　　　　　　　　　　　32
　　　　　32←←←←←←←←← 左16ビットシフト

例えばこのように書かれていた場合

/* 立方体の頂点座標。 行列関連の関数は 固定小数点型の値を扱う */
{ -32 << 16, -32 << 16, -32 << 16 },
{ -32 << 16, 32 << 16, -32 << 16 },
{ 32 << 16, 32 << 16, -32 << 16 },
：

は、次のようなことをしているのと同じ。

{ fixed itofix(-32) , fixed itofix(-32) , fixed itofix(-32 ) },
{ fixed itofix( -32) , fixed itofix( 32) , fixed itofix(-32) },
{ fixed itofix( 32 ), fixed itofix(32) , fixed itofix(-32) },
：

int型の数値だとこのようになる

{ -32 , -32 , -32 },
{ -32 , 32 , -32 },
{ 32 , 32 , -32 },
：

固定小数点数→整数
int fixtoi(fixed x);
固定小数点(fixed )型の変数 を 整数( int )型に変換する。
丸め が要求される。


床関数
int fixfloor(fixed x);
fixed x の値 未満で、最大の整数(int)値を返す。

xが、正の数の場合、小数点以下の切り捨てが行われる。
例： fixfloor( 1. 3 ); の結果は 、 1 となる。


天井関数
int fixceil(fixed x);
fixed x の値 以上で、最小の整数(int)値を返す。

xが、正の数の場合、小数点以下が 0 以外の場合、小数点 切り上げが行われる。
fixfloor( 1. 3 ); の結果は 、 2 となる。


浮動小数点→ 固定小数点
fixed ftofix(double x);
浮動小数点( idouble )型の変数 を 固定小数点( fixed )型に 変換する。


固定小数点→ 浮動小数点
double fixtof(fixed x);
固定小数点( fixed )型の変数 を浮動小数点( idouble )型に 変換する。

演算について

通常 整数は + -/ * 演算子を使って加算、減算、乗算や除算を行うことができる。ただし固定小数点数の場合には問題がでてくる。 例えば、32768 までしか入らない型 の変数に、演算結果として上限を超える 17764680 という数字が入ってしまうと、桁があふれて正確な 計算ができなくなってしまう。 このように、型が格納できる桁数を越えた値をとることを「オーバーフロー(桁あふれ)」という。

Allegro では オーバーフローから プログラムを保護するための監視機能がついた 四則演算関数が用意されていて オーバーフローが発生した場合には エラーNo.を報告し、格納できる値の最大値がセットされるとのこと。 もし、あなたがオーバーフローが起きたか知りたい場合は これらの関数を呼ぶ前にエラー変数を初期化 「 errno = 0 」 すること。

これらの関数は、演算子を使った計算に比べて処理速度が劣るが、オーバーフロー対策の手間を考えると効率が良い。

固定小数点数同士の乗算
fixed fixmul(fixed x, fixed y);

固定小数点数同士の除算
fixed fixdiv(fixed x, fixed y);

固定小数点数同士の加算
fixed fixadd(fixed x, fixed y);

固定小数点数同士の減算
fixed fixsub(fixed x, fixed y);

Fixed point trig

　 平方根, sin , cos,tan , inverse sin , inverse cos 関数 は テーブル参照によって値が求まるので高速である。そのため値の精度はそれなりのものしか期待できない。 一方 inverse tan は tan テーブルを参照しているため、他の関数より処理が遅いとのこと。

ラジアン(Radian) と 度数(Digree)。
角度を表現する方法には、主に二つの単位系が知られている。 ラジアンは、 180° = π と定めて扱う角度を定義する。 360° ならラジアンは 2π, 90°なら ラジアンは 1/2π となる。


参考文献：

ラジアン

三角関数

度数法とラジアン法の関係

単位変換

角度単位の変換 digree → radian
extern const fixed fixtorad_r;
この定数は、度 から、ラジアン形式に変換する。
fixtorad_r = π/180

y が 角度を表す 度数法の 角度 の場合。 y を この定数で乗算するとラジアンに変換できる。
x = fixmul(y, fixtorad_r); により
x 値 には ラジアン値として表される角度が返ってくる。


角度単位の変換 radian → digree
extern const fixed radtofix_r;
この定数は、ラジアン形式 から 度 に変換する。
radtofix_r = 180/π

xが　角度を表すラジアン値の場合。 x を この定数で乗算すると 度に 変換できる。
y = fixmul(x, radtofix_r); により
y値 には 固定小数点値として表される角度が返ってくる。

三角関数

三角関数： 角度(ラジアン)→ 二辺の比率 を求める
fixed fixsin(fixed r);
サイン (sin) … 正弦 テーブルを参照する。

fixed fixcos(fixed r);
コサイン(cos) … 余弦 テーブルを参照する。

fixed fixtan(fixed r);
タンジェント(tan) … 正接 テーブルを参照する。


逆三角関数：二辺の比率 →角度(ラジアン) を求める。
fixed fixasin(fixed x);
アークサイン (asin) … 逆正弦 テーブルを参照する。

fixed fixacos(fixed x);
アークコサイン(acos) … 逆余弦 テーブルを参照する。

fixed fixatan(fixed x);
アークタンジェント(atan) … 逆正接 テーブルを参照する。

fixed fixatan2(fixed y, fixed x);
アークタンジェント … 逆正接 を求める。libc の atan2() 関数と同じ処理。


平方根
fixed fixsqrt(fixed x);
ルート … 平方根を求める。


斜辺を求める
fixed fixhypot(fixed x, fixed y);
直角三角形の斜辺( hypotenuse )の長さを求める。 この関数は、三平方の定理に基づき √ (x^2 + y^2) で計算された結果を返す。

1^2 = sin^2θ + cos^2 θ


FIX Class !?
C++ を利用する場合の注意点。
あなたは、 fix class と fixed typedef を併用してはいけない。 x が class fix のオブジェクトである場合、fixsqrt(x) を呼ぶのは間違いで、 オーバーロードされた sqrt(x) または x.sqrt() のように呼ばなければならない。 らしい。