-Allegro4.9.xDocument -

Allegro 4.9.19 (5.0)概要

Allegro5では、簡易GUI、マルチウインドウ、イベントオブジェクト駆動、スレッド処理、半透明処理、OpenGL3.0、TrueType、UTF-8,16 に対応しています。音源はOgg vorbis、画像はjpg,png等, フォントはttf が使えます。しかし3Dでの日本語表示や、一般的な日本語入力変換についてはまだ全然ダメなので、工夫する必要があります。

◆ライセンスに関しては、AllegroはAllegro 9.6.4以降 zlibライセンスになったようです。
◆Allegro4.9.17：OSXにおいてmain()関数は特殊で、allegro-main アドオンにあるmain()より呼ばれる。またC++言語においてmain()関数のためのプロトタイプに「int main(int, char **)」を使わなければそのコードは、OSXではコンパイルできません。C言語やANSI-C言語形式のものは普通に動きます。
◆Allegro4.9.17：OSXにおいて Pythonのwrapperが動くようになった。また、al_run_main()でのPython wrapper がサポートされた。
◆Allegro4.9.14 にて iPhone用開発環境が追加された模様。

◆ライブラリの構造
[Allegro本体＆拡張アドオン OpenGL , TTF ] + [機能提供ライブラリ Ogg vorbis , OpenGL, libpng 等 ]

◆インストール
インストールには、これまでのConfigureの代わりにCmake というGUIアプリを使います。CmakeList.txt のあるディレクトリと作業ディレクトリを指定後、configure→generate。作業ディレクトリ内にmakefileが生成されるので、ターミナルからmakefileのあるディレクトリに移動してからmake します。途中Cmakeは、足りないライブラリを教えてくれるので、必要があればエントリ欄でファイルパスを指定したり、チェックボックスを取捨選択し、エントリ欄が赤く染まらなくならるまで、Configure→Generateします。ビルドとインストールが成功すると、サンプルプログラムやデモがコンパイルされているので、試してみて下さい。

←Generate 後、ターミナルからmakeする。
◆アドオン

Allegro5 では、OpenGL、TrueType用のアドオン(拡張ライブラリ)のソースはAllegro本体と一緒に用意されています。

そのため、機能提供ライブラリを、システムにインストールするだけで使えるようになります。

Allegroアドオンに必要な機能提供ライブラリはfreetype2, libsndfile ,libogg, libvorbis, libflac, libpng, libtiff, libjpeg , OpenGL/GLUT,OpenAL, libphysicsfs 等です。ただし、アドオンを使うためにすべての機能提供ライブラリをインストールする必要はありません。

(※PhysicsFSアドオンを利用するためのPhysicsFSライブラリのインストールにはCmakeが必要です、またwxWidgetsも必要です。しかしwxWidgetsを利用せずに、インストールしたい場合、wx用のテストプログラムをビルトさせないように、CMakeLists.txtの、PHYSFS_BUILD_WX_TEST 関連の部分を削除してからCmakeを使って下さい。)
◆アドオンの依存関係
Allegroはコアライブラリと、複数のアドオンから構成されています。

allegro_image → allegro
allegro_primitives → allegro
allegro_color → allegro

allegro_font → allegro_image → allegro_primitives → allegro
allegro_ttf → allegro_font → allegro_image → allegro

allegro_audio → allegro
allegro_flac → allegro_audio → allegro
allegro_vorbis → allegro_audio → allegro

allegro_memfile → allegro
allegro_physfs → allegro

allegro_native_dialog → allegro

◆インストール
インストールには、これまでのConfigureの代わりにCmake というGUIアプリを使います。CmakeList.txt のあるディレクトリと作業ディレクトリを指定後、configure→generate。作業ディレクトリ内にmakefileが生成されるので、ターミナルからmakefileのあるディレクトリに移動してからmake します。途中Cmakeは、足りないライブラリを教えてくれるので、必要があればエントリ欄でファイルパスを指定したり、チェックボックスを取捨選択し、エントリ欄が赤く染まらなくならるまで、Configure→Generateします。ビルドとインストールが成功すると、サンプルプログラムやデモがコンパイルされているので、試してみて下さい。

←Generate 後、ターミナルからmakeする。
インストールが済んだら。あとはプログラムから呼び出します。

Getting started guide

スタートガイド

◆Allegroを使う時の注意
AllegroのAPIを利用する前には、必ずal_init関数を呼んで初期化しなければいけません。一部のアドオンを利用する場合も、アドオンの初期化用の関数を呼び出す必要があります。例えば、al_init_image_addon, al_init_font_addon, al_init_ttf_addonなどです。

◆Windowを開く
al_create_display関数は、ウインドウを開いて、ALLEGRO_DISPLAYを返すでしょう。

画面表示をクリアするために、al_clear_to_color関数を呼びます。 ALLEGRO_COLOR パラメータを明確にするため al_map_rgba または al_map_rgba_f を使って画面の色数を設定します。

描画処理はバックバッファにおいて、実行されます。

Allegroでは、画面のちらつきを防ぐために、2つの画面を使っています(バックバッファとフロントファッファ)、バックバッファは実際に画面を表示する前の作業用に使われます。これを、どのような過程で表示されているか確かめるために、ユーザーから見えるような形で表示するには、al_flip_display関数を呼んでください。

◆画像イメージを表示する
ディスクにある画像を読込むためには、al_init_image_addon関数を呼び出し、I/O addon を初期化する必要があります。そして、al_load_bitmap関数を使って画像を読込み、そのデータはALLEGRO_BITMAP構造体へ格納されます。 al_draw_bitmap, al_draw_scaled_bitmap al_draw_rotated_scaled_bitmap関数はバックバッファを使って処理されます。これを、どのような過程で表示されているか確かめるために、ユーザーから見えるような形で表示するには、al_flip_display関数を呼んでください。

◆描画対象を変える
al_clear_to_color や al_draw_bitmap関数には、ビットマップデータの展開先(distination)パラメータを与えない(展開先は暗黙に決まっている)ことに注意してください。

Allegroは、現在のスレッドのために、"ターゲットビットマップ(Target bitmap)"と呼ばれる情報を記憶しています。また、バックバッファ表示もビットマップとして扱います。それで、al_get_backbuffer関数を使ってバックバッファの内容を取得し、それをターゲットビットマップへ表示させることができます。

他のビットマップは、al_create_bitmap関数によって作成することができますが、 al_set_new_bitmap_flags や al_set_new_bitmap_format関数を使ってオプションを設定してビットマップを作成することもできます。

◆イベントキューと入力
入力(Input)は、複数の"ソース"と呼ばれるものからやってきます。ソースとは、キーボード、マウス、ジョイスティック、タイマなどの「入力源」を意味します。

これらのソースから入力が発生した場合、それらは発行された"イベント"として集められ、イベントキュー(Event Queue)という待ち行列に追加されます。ユーザーはそのキューに関して調べたりすることができます。

イベントキューを作成するためには、al_create_event_queue関数を使い、そして、al_register_event_source を使って、どのようなソース(入力源)があるのか、キューに教えてください。

通常、al_get_keyboard_event_source、 al_get_mouse_event_source 、 al_get_joystick_event_source といった関数を使えばソースを取得できます。

イベントは、al_wait_for_event や al_get_next_event関数によって取得することができます。これについては、ALLEGRO_EVENTのイベントタイプと他のフィールド(イベントに関する詳細な情報)をチェックして、入力に対応する処理を書いてください。

また、Display はイベントソースとして扱われます(たとえば、それらがリサイズされた時に、イベントソースは、イベントを発行します)。あなたは、Displayを作成する前に、al_set_new_display_flags関数にALLEGRO_RESIZABLEフラグをセットする必要があるでしょう。次に、イベント待ち行列に、ソースとしてDisplay を登録する必要があるでしょう。そして、あなたがリサイズイベントを取得する時に、al_acknowledge_resize関数を呼び出してください。

タイマは、定期的に呼び出されるイベントソースです。登録すると、イベントが発生するたびに、キューに挿入されます。 al_install_timer関数によっていくつかを作成してください。

al_current_timeとal_rest関数は、時間をより直接的に扱うための手段です

◆何らかのテキスト表示する
何らかのテキストを表示表示したければ、まずal_init_font_addon関数を呼び出し、Font addon(フォントアドオン)を初期化してください。それから、al_load_font関数でビットマップフォントを読込んでください。テキストの表示にはal_draw_text または al_draw_textf関数が使えます。

TrueTypeフォントを使う場合は、al_init_ttf_addon関数で、TTF Font addonを初期化後に、al_load_ttf_font関数でフォントを読込んでください。

◆プリミティブ図形の描画
Primitives addon(プリミティブアドオン)は、円(al_draw_circle関数)や、三角形(al_draw_rectangle関数)、線 (al_draw_line関数)などを描画するための手軽な関数群です。

◆混色処理(Blending)
半透明や、薄め(tinted)に画像やプリミティブ図形を描画するには、al_set_blender関数を使って混色処理の状態設定を変更してください。 al_set_target_bitmap関数のように、これはAllegro内部の状態(現在のスレッドのための)を変更します。変更前の状態を一部を保存して、あとで復帰したいこともあるでしょう。このような便利な機能は al_store_state と al_restore_state関数として提供されています。

◆サウンド
サウンド機能を初期化するには、al_install_audio関数を使ってください。これによって無圧縮.wavファイルを読込む事ができます。他の形式が必要なら、例えば、al_init_ogg_vorbis_addon関数を使えば .ogg形式のファイルが読込めます。

それが済んだら単純に、al_reserve_samples関数を使って、同時再生可能な音響効果の数を指定します。次に、サウンドファイルを読込むために、al_load_sample 関数を使い、再生をするためにal_play_sample関数を使って下さい。

ディスクから大容量の音楽のデータ片をストリーミングするのにal_load_audio_stream関数が使えます。この機能は、全部のデータをあらかじめメモリ上に展開する必要はないでしょう。

もし、上記のことがあまりに単純な説明なので、Clipping やLatency(遅延時間)等の問題を考えてしまうあなたも、心配しないでください。 Allegroは、あなたがサウンドシステム上でちょうどいいくらいの制御手段を提供します。

前に書いたように、al_reserve_samples関数は、デフォルトミキサーと多くのサンプルのインスタンスを
セットアップするだけですが、あなたはそれを使う必要はありません。

代わりに「direct connection」をステレオセットで取得するために、あなたはALLEGRO_VOICE オブジェクトを使用するでしょう(利用可能にするには、そのようなVOICEオブジェクトが1つだけが保証されるプラットホームで、オーディオデータの特定の形式を必要とするかもしれません)。
したがって、すべての音が、最初に、そのようなVOICE(または、別のMIXER)オブジェクトに接続されるALLEGRO_MIXER
オブジェクトを通して送ることができて、それに与えられたすべてのサンプルデータを一緒に混ぜるでしょう。

あなたは、ALLEGRO_SAMPLE_INSTANCEを使用することで次に、ALLEGRO_AUDIO_STREAMを使用することでリアルタイムのサンプルデータを直接ミキサーか声にストリーミングするか、または完全な音を揺らがせることができます。後者は、単にALLEGRO_SAMPLEを示して、それをストリーミングするでしょう。

◆Not the end
私たちがまだ言及してさえいない多量のものがあります。

Enjoy! (楽しんでいってね！)

コンフィグ

コンフィグ - このファイルの形式は、古くはWindows環境上でアプリの設定を保存するための使われた.iniファイルに由来します。 (コンフィグとセクションと呼ばれる階層的なタグで管理され、テキストデータで記述してあります)
Allegroでは、ゲームのオプション設定(キーコンフィグや、画面設定)などの情報を保存するために使われています。

ALLEGRO_CONFIG

typedef struct ALLEGRO_CONFIG ALLEGRO_CONFIG;
typedef struct ALLEGRO_CONFIG_ENTRY ALLEGRO_CONFIG_ENTRY;
typedef struct ALLEGRO_CONFIG_SECTION ALLEGRO_CONFIG_SECTION;

●ALLEGRO_CONFIG 構造体
Allegro/include/Allegro5/internal/aintern_config.h で定義されてます。
ALLEGRO_CONFIG 構造体は、自己参照リスト型構造体を(セクションsection、エントリentry)を含んでいて、セクションには、セクション名、エントリにはキーと値の情報が格納されており、2つのポインタ head と nextによって、セクションやエントリ同士をそれぞれリング状に連結させる事が可能です。

●イテレータについて
イテレーターは反復子とも呼ばれ、繰返し処理をさらに抽象化した概念で、その構造の多くは共通して繰り返し処理を「対象の集合{ 対象へ繰り返す処理 } 」とシンプルに表現しています。これを実現する方法は、様々な方法があるので実体はわかりにくいかもしれません。言語によっては、Perlのforeach のように標準で実装されているものもあれば、言語の仕様になくても、ライブラリ側でこれを実装している事があります。Allegroでは、al_get_first_config_* 関数による、CONFIG項目の取得に、イテレータを利用しています。

ユーザー側からすると、背後にある複雑な仕組みを意識しないで、使う事ができます。

JavaScriptの例で申し訳ないですが、この文書を構築するJavaScript のコードでもイテレーター的なものが使われてます。例えばこの文書は、項目が多いのでJQueryを使い全ての<h2>タグに対しアンカーと【API一覧】リンクを自動的に生成しています。

/* イテレータ的な繰返し  */

/* JQueryでは  each()がイテレータで、function a() 内には
 for() や while() といった繰返し表現が見当たりません   */

 /* 全ての h2タグに対し{リンク生成}  */
$('h2').each(function a(){  文字列を抽出し、【API一覧】リンク生成     });
$( 対象の集合  ).each(function a(){   対象へ繰り返す処理     });

/* イテレータではない繰返し (適当なコード) */
var  h = getElementByTagNames('h2');
var output;
for ( var i =0  ; i<h.length  ; i++){ 
	  output+="<a href="+h[i].anchor+">"+ h[i].name+</a>";
	}

イテレータには、内部型と外部型があります。
Allegro のイテレーターは、Opaque型であることから、繰り返し処理は内部に隠蔽されていると考えられます。
また、Allegro Configure API における iterator には、グローバルセクション以下の階層に属するセクション情報の集合が入ると思われます。
やはり、実際の動作をつかむには、Allegroのサンプルコードを見るのが一番かもしれません。

●例
万歩計や、交通量やイベント等の来場者を数える、数取器に似ています。

まず、入場者を数えるカウンタのケース(関数)に、0〜9の数字書かれたドラム(ALLEGRO_CONFIG 構造体)と、カウントアップのボタン(イテレータ)をセットする。機器には3桁を表示する窓があり、ドラムの数字を表示します。
関数内では、「イテレータに1つ先の数字の場所を記憶させる」という仕組みを仕込んであり、外からは見えなくしてあります。
そのため関数を実行させるたび(ボタンを押すたびに)に、ドラムはイテレータの指す1つ先の絵柄へと回転(カウントアップ)を繰り返えそうとします。

ユーザーからは、関数を実行するたびに、3つの窓configure と section と entry から見える数字が刻々と変わっているように見えます。
たとえば、sectionが1回転するのにentryが5回転するように変化します。

●だいたいの仕組み(β版時点で)
ユーザーは、対象となるコンフィグ構造体と、イテレータとなるダブルポインタを関数に指定し、あとは関数を実行する度に次々とデータが取り出せるようです。

al_add_config_comment void al_add_config_comment(ALLEGRO_CONFIG *config,const char *section, const char *comment)

コンフィグセクションにコメントを追加する。セクション名が無い場合は新規作成する。グローバルセクションにするには、NULLまたは""を設定。 The comment may or may not begin with a hash character. Any newlines in the comment string will be replaced by space characters.

al_add_config_section void al_add_config_section(ALLEGRO_CONFIG *config, const char *name)

コンフィグにセクションを追加する。

al_create_config ALLEGRO_CONFIG *al_create_config(void)

空のコンフィグ構造体を作る

al_destroy_config void al_destroy_config(ALLEGRO_CONFIG *config)

コンフィグ構造体によるリソースを解放する。ただし、引数にNULLを渡した場合は何もしない。

al_get_config_value const char *al_get_config_value(const ALLEGRO_CONFIG *config,const char *section, const char *key)

ALLEGRO_CONFIG構造体が破壊されていない限り有効な内部文字バッファのポインタを得る。もし必要なら値をコピーすることができる。グローバルセクションの場合は、NULL または "" を設定. NULLを返すときは、キーまたはセクションが存在しないことを意味します。

al_merge_config ALLEGRO_CONFIG *al_merge_config(const ALLEGRO_CONFIG *cfg1, const ALLEGRO_CONFIG *cfg2)

2つのコンフィグ構造体を合体させ、新しいコンフィグを返す。コンフィグ'cfg2'の値は、'cfg1'により上書きされる。どちらの入力されたコンフィグ構造体はどちらも変更されます。 'cfg2'のコメント情報は保持されません。

al_merge_config_into void al_merge_config_into(ALLEGRO_CONFIG *master, const ALLEGRO_CONFIG *add)

あるコンフィグ構造体を別のコンフィグ構造体に追加します。コンフィグ'add'の値は、'master'の値を上書きします。'master'は変更されます。'add'側のコメント情報は保持されません。

al_load_config_file ALLEGRO_CONFIG *al_load_config_file(const char *filename)

コンフィグファイルを読み込み、エラーが発生した場合NULLを返す。

al_set_config_value

void al_set_config_value(ALLEGRO_CONFIG *config,
   const char *section, const char *key, const char *value)

コンフィグのセクション項目に値を設定する。もし存在しない場合は新規作成されます。もし値が既にキーを与えられていた場合、それは上書きされます。
グローバルセクションにするには引数をNULL または "" にする。

一貫した、コンフィグファイルの書式を保つため、値に付随した前後の空白スペース(leading and trailing whitespace)も削除されます。もし、値に空白スペースを含ませたい場合は、引用符で囲って、値を中に読み返す場合には削除して下さい。

al_save_config_file bool al_save_config_file(const ALLEGRO_CONFIG *config, const char *filename)

コンフィグファイルを書き出します。trueが返れば成功、falseが返った場合はエラー

al_get_first_config_section char const *al_get_first_config_section(ALLEGRO_CONFIG const *config, void **iterator)

この関数は、与えられたコンフィグファイルの一番最初のセクション名を返します。この関数は通常グローバルセクションにあたる文字列を返すでしょう。また、引数 'iterator' には、 al_get_next_config_section関数が、残りのセクションを繰返し走査するために使う、Opaque型イテレーター(反復子)が返されるでしょう。
　注意:渡された ALLEGRO_CONFIG 構造体に何らかの変更が加えられない限り、返された文字列とイテレーターは有効なままでいます。

al_get_next_config_section char const *al_get_next_config_section(void **iterator)

この関数は、与えられたコンフィグファイルの次にある項目名を返します。
引数 'iterator' には、先にal_get_first_config_section関数で取得したイテレータを指定しなければいけません、。

al_get_first_config_entry char const *al_get_first_config_entry(ALLEGRO_CONFIG const *config, char const *section, void **iterator)

特定のコンフィグで特定のセクションにおける最初のキーの名前を返します。イテレータは、al_get_first_config_section関数と似た働きを得ます。

　注意:渡された ALLEGRO_CONFIG 構造体に何らかの変更が加えられない限り、返された文字列とイテレーターは有効なままでいます。

al_get_next_config_entry char const *al_get_next_config_entry(void **iterator)

al_get_first_config_entry関数によって得られたイテレータのための、次のキーを返します。

Display画面

ALLEGRO_DISPLAY typedef struct ALLEGRO_DISPLAY ALLEGRO_DISPLAY;

開いた Allegro ディスプレイまたはウインドウを表すOpaque構造体

Display creation

al_create_display ALLEGRO_DISPLAY *al_create_display(int w, int h)

画面またはウインドウを設定する。画面パラメータは最後に呼び出されたal_set_newによって決まる。 display*. 無指定ならデフォルトパラメータが設定されます。新規画面が自動的に作成され、描画のための背面バッファも有効になります。エラーが発生したらNULLが返る。

al_destroy_display void al_destroy_display(ALLEGRO_DISPLAY *display)

画面構造体を破棄する。

al_get_num_display_formats int al_get_num_display_formats(void)

Returns the number of available display formats. Note that on some platforms this may return 0 unless there is a current display already. In that case, first create a small window using Allegro's standard settings to query the available formats and create your actual display later.

In pseudo-code:

display = al_create_display();
n = al_get_num_display_formats();
for (i = 0; i < n; i++) {
   /* Use al_get_display_format_option to inspect each available
    * format and select the one you want.
    */
}
al_destroy_display(display); 

/* Now create the real display. */
al_set_new_display_format(i);
real_display = al_create_display();

al_get_new_display_flags int al_get_new_display_flags(void)

新規作成された画面の現在のフラグを得ます.

al_get_new_display_refresh_rate int al_get_new_display_refresh_rate(void)

新規作成された画面の現在のリフレッシュレート値を得ます.

al_get_new_window_position void al_get_new_window_position(int *x, int *y)

新規された非fullscreen画面が置かれる位置を得ます。

al_set_new_display_option void al_set_new_display_option(int option, int value, int importance)

Sets an extra display option. Allegro itself will not care about those options itself, but you may want to specify them, for example if you want to use multisampling.

The 'importance' parameter can be either:

    * ALLEGRO_REQUIRE - The display will not be created if the setting can not be met.
    * ALLEGRO_SUGGEST - If the setting is not available, the display will be created anyway. FIXME: We need a way to query the settings back from a created display.
    * ALLEGRO_DONTCARE - If you added a display option with one of the above two settings before, it will be removed again. Else this does nothing.

The supported options are:
    * ALLEGRO_RED_SIZE
    * ALLEGRO_GREEN_SIZE
    * ALLEGRO_BLUE_SIZE
    * ALLEGRO_ALPHA_SIZE
    * ALLEGRO_COLOR_SIZE
    * ALLEGRO_RED_SHIFT
    * ALLEGRO_GREEN_SHIFT
    * ALLEGRO_BLUE_SHIFT
    * ALLEGRO_ALPHA_SHIFT: These settings can be used to specify the pixel layout the display should use.
    * ALLEGRO_ACC_RED_SIZE
    * ALLEGRO_ACC_GREEN_SIZE
    * ALLEGRO_ACC_BLUE_SIZE
    * ALLEGRO_ACC_ALPHA_SIZE: This and the preceding three settings can be used to define the required accumulation buffer size.
    * ALLEGRO_STEREO: Whether the display is a stereo display.
    * ALLEGRO_AUX_BUFFERS: Number of auxiliary buffers the display should have.
    * ALLEGRO_DEPTH_SIZE: How many depth buffer (z-buffer) bits to use.
    * ALLEGRO_STENCIL_SIZE: How many bits to use for the stencil buffer.
    * ALLEGRO_SAMPLE_BUFFERS: Whether to use multisampling (1) or not (0).
    * ALLEGRO_SAMPLES: If the above is 1, the number of samples to use per pixel. Else 0.
    * ALLEGRO_RENDER_METHOD: 0 if hardware acceleration is not used with this display.
    * ALLEGRO_FLOAT_COLOR: Whether to use floating point color components.
    * ALLEGRO_FLOAT_DEPTH: Whether to use a floating point depth buffer.
    * ALLEGRO_SINGLE_BUFFER: Whether the display uses a single buffer (1) or another update method (0).
    * ALLEGRO_SWAP_METHOD: If the above is 0, this is set to 1 to indicate the display is using a copying method to make the next buffer in the flip chain available, or to 2 to indicate a flipping or other method.
    * ALLEGRO_COMPATIBLE_DISPLAY: Indicates if Allegro's graphics functions can use this display. If you request a display not useable by Allegro, you can still use for example OpenGL to draw graphics.
    * ALLEGRO_UPDATE_DISPLAY_REGION: Set to 1 if the current display is capable of updating just a region, and 0 if calling al_update_display_region is equivalent to al_flip_display.
    * ALLEGRO_VSYNC: Set to 1 to tell the driver to wait for vsync in al_flip_display, or to 2 to force vsync off.

al_get_new_display_option


int al_get_new_display_option(int option, int *importance)

Retrieve an extra display setting which was previously set with al_set_new_display_option.

al_reset_new_display_options void al_reset_new_display_options(void)

This undoes any previous calls to al_set_new_display_option.

al_set_new_display_flags void al_set_new_display_flags(int flags)

画面を作成するための多様なフラグを設定します。フラグは、ビットフィールドを含んでいて、色々な組合せに対応します：

ALLEGRO_WINDOWED - ウインドウ画面モードを設定します

ALLEGRO_FULLSCREEN - フルスクリーン画面モードを設定します

ALLEGRO_FULLSCREEN_WINDOW  - ウインドウの幅と高さを、画面全体の大きさにします。ALLEGRO_FULLSCREENと異なり画面解像度の
　　　　　　　　　　　　　　　　　　変更は行われません。ディスプレイはデスクトップと同じピクセル寸法になります。
　　　　　　　　　　　　　　　　　　もし後でフルスクリーンモードに切り替えた場合に、widthとheightが使用されます。
　　　　　　　　　　　　　　　　　　Windows と X11 環境では、プラットフォームによって違いますが、
　　　　　　　　　　　　　　　　　　正確には、このフラグで作成されたフルスクリーンディスプレイのふるまいは
　　　　　　　　　　　　　　　　　　ALLEGRO_FULLSCREENとは違ったものとなるでしょう。その違いは alt-tabによる切替速度
　　　　　　　　　　　　　　　　　　や ウインドウ/フルスクリーン 切替えの早さが異なるかもしれません。

ALLEGRO_RESIZABLE - ウインドウ画面をリサイズ可能にします。 (ALLEGRO_WINDOWEDと併用した場合のみ)

ALLEGRO_OPENGL -  OpenGL 3Dレンダリング。これを有効にするには、グラフィックドライバがOpenGLに対応している必要があります。

ALLEGRO_DIRECT3D - Direct3Dレンダリングを有効にするには、Direct3Dドライバや対応デバイスが必要です(WIndows用)。
 

ALLEGRO_NOFRAME - 枠が無い(枠線やタイトルバーが無い)ウインドウを作ります。フルスクリーンモードでは意味をなしません。これをサポートしているかどうかはOSによります。

ALLEGRO_GENERATE_EXPOSE_EVENTS -  Exposéイベントを生成

0 を使う場合はデフォルトとなります。

al_set_new_display_refresh_rate void al_set_new_display_refresh_rate(int refresh_rate)

Sets the refresh rate to use for newly created displays. If the refresh rate is not available, al_create_display will fail. A list of modes with refresh rates can be found with al_get_num_display_modes and al_get_display_mode.

al_set_new_window_position void al_set_new_window_position(int x, int y)

Sets where the top left pixel of the client area of newly created windows (non-fullscreen) will be on screen. Negative values allowed on some multihead systems.

Display Operation

al_acknowledge_resize bool al_acknowledge_resize(ALLEGRO_DISPLAY *display)

ユーザーが、画面サイズを変更した時にリサイズイベントを受け取る時、現在リサイズが可能かどうかをグラフィックドライバに伝えるために、この関数を呼ばなければいけません。成功時にはtrueを返す。フルサイズバックバッファから切り取られた矩形の大きさを調節する.

al_flip_display void al_flip_display(void)

前面バッファと背面バッファをコピーまたは更新する。現在選択された表示のときに、以前に描かれた内容ががスクリーンの上で目に見えるようになるように描画されます。背面バッファに切り替わり、それゆえ描画内容が変更されるかもしれないが、前面バッファのビットマップがそれぞれ意味上は残っている。？？？？？？

	
Several display options change how this function behaves:
With ALLEGRO_SINGLE_BUFFER, no flipping is done. You still have to call this function to display graphics, depending on how the used graphics system works.
The ALLEGRO_SWAP_METHOD option may have additional information about what kind of operation is used internally to flip the front and back buffers.
If ALLEGRO_VSYNC is 1, this function will force waiting for vsync. If ALLEGRO_VSYNC is 2, this function will not wait for vsync. With many drivers the vsync behavior is controlled by the user and not the application, and ALLEGRO_VSYNC will not be set; in this case al_flip_display will wait for vsync depending on the settings set in the system's graphics preferences.

al_get_backbuffer ALLEGRO_BITMAP *al_get_backbuffer(void)

現在ある画面の背面バッファを、特殊なビットマップとして返す

al_get_current_display ALLEGRO_DISPLAY *al_get_current_display(void)

呼び出したスレッド内での、現在の画面を返す。

al_get_display_flags int al_get_display_flags(void)

現在の画面に対するフラグを得る

al_get_display_format int al_get_display_format(void)

現在の画面のピクセル形式を得る

al_get_display_height int al_get_display_height(void)

現在の画面の高さを得る。これはAllegro 4.x.にあった SCREEN_H定数と似たようなもの.

al_get_display_refresh_rate int al_get_display_refresh_rate(void)

現在の画面のリフレッシュレート値を得る

al_get_display_width int al_get_display_width(void)

現在の画面の幅を得る. Allegro 4.x.にあった SCREEN_W のようなもの.

al_get_frontbuffer ALLEGRO_BITMAP *al_get_frontbuffer(void)

現在の画面の前面バッファの内容を特殊ビットマップで返す.これはドライバによっては対応していないかもしれない.その場合はNULLを返す.

al_get_window_position void al_get_window_position(ALLEGRO_DISPLAY *display, int *x, int *y)

非フルスクリーン画面の位置を得るSee Also: al_set_window_position

al_inhibit_screensaver bool al_inhibit_screensaver(bool inhibit)

この関数にinhibit として、trueが渡された場合、ユーザーにスクリーンセーバの起動を抑制させることができます。 falseが渡された場合、システムをデフォルト状態(プログラムが起動時の状態)にリセットすることができます。戻り値は、この設定が成功した場合はtrue、失敗した場合は falseが戻ります。

al_resize_display bool al_resize_display(int width, int height)

現在の画面をリサイズします。戻り値は、それが成功した場合 true を返し、エラーが発生したらfalseを返します。この機能は、ALLEGRO_RESIZABLE フラグに関係なく、フルスクリーン、ウインドウモード両方とも働きます。大きさは、バックバッファ画面いっぱいの矩形として切り取られたものになります。

al_set_current_display bool al_set_current_display(ALLEGRO_DISPLAY *display)

現在の画面をスレッドに呼びます。また対象となるビットマップを、画面のバックバッファにセットします。成功した場合trueを返します。

al_set_display_icon void al_set_display_icon(ALLEGRO_BITMAP *icon)

現在ある画面(ウインドウに)関連づけられた(associated)アイコンを変更します。

Note:もし、それがOSで規定された基本的なサイズではない場合、拡大縮小されるでしょう。
TODO: Describe best practice for the size? TODO: Allow providing multiple icons in differet sizes?

al_get_display_option int al_get_display_option(int option)

Return an extra display setting of the current display.

al_set_window_position void al_set_window_position(ALLEGRO_DISPLAY *display, int x, int y)

Sets the position on screen of a non-fullscreen display.

al_set_window_title void al_set_window_title(AL_CONST char *title)

Set the title on a display.

al_toggle_display_flag


bool al_toggle_display_flag(int flag, bool onoff)

ディスプレイフラグのひとつを有効/無効にする。指定可能なフラグは al_set_new_display_flagと同じである。

しかしながら、一部のフラグは、ディスプレイが作成されてしまってから変更することができないので、注意していただきたい。
trueが返ればドライバは特定のフラグをトグルすることをサポートする、そうでなければfalse。あなたは指定したディスプレイプロパティが実際に変更されたかどうか探すために。 al_get_display_flags関数をつかうことができます。

al_update_display_region void al_update_display_region(int x, int y, int width, int height)

Does the same as al_flip_display, but tries to update only the specified region. With many drivers this is not possible, but for some it can improve performance. The ALLEGRO_UPDATE_DISPLAY_REGION option (see al_get_display_option) will specify the behavior of this function in the current display.

al_wait_for_vsync bool al_wait_for_vsync(void)

垂直回帰(CRTの発するビームが画面走査を完了し、ビームの走査開始位置を元の画面最上部へ戻すこと)が始まるまでに待機します。いくつかのドライバ/グラフィックカード/モニターの組み合わせではこれが失敗する場合もあるかもしれません。もしうまくいかなければfalseを返し、成功したらtrueを返します。

al_get_display_event_source ALLEGRO_EVENT_SOURCE *al_get_display_event_source(ALLEGRO_DISPLAY *display)

　関連イベントソースを検索してください。

Full Screen

ALLEGRO_DISPLAY_MODE typedef struct ALLEGRO_DISPLAY_MODE

【構造体】画面モード構造体。サポートしているフルスクリーン画面の情報を含む。

typedef struct ALLEGRO_DISPLAY_MODE {
   int width;          //     # スクリーンの幅
   int height;         //    # スクリーンの高さ
   int format;         //   # モードのpixel形式 
   int refresh_rate;   // # リフレッシュレート
} ALLEGRO_DISPLAY_MODE;

al_get_display_mode ALLEGRO_DISPLAY_MODE *al_get_display_mode(int index, ALLEGRO_DISPLAY_MODE *mode)

画面モードの取得。画面パラメータは、 al_get_num_display_modes と al_get_display_modeの間では変更すべきではない。. インデックス番号は0〜(al_get_num_display_modes-1)の間を取る. モードは、ALLEGRO_DISPLAY_MODE 構造体に割り当てる必要がある。この関数は失敗、および成功に関係して通過されたモードのパラメタでNULLを返すでしょう。

al_get_num_display_modes int al_get_num_display_modes(void)

現在セットされている画面パラメータで利用可能な画面の数を得ます. これは、 al_set_new_display_format, al_set_new_display_refresh_rate, and al_set_new_display_flagsでセットされたモードにマッチする数です.デフォルトのドライバのために、全てのモードをリストするには、画面パラメータに0をセットしてください。

Monitor

ALLEGRO_MONITOR_INFO typedef struct ALLEGRO_MONITOR_INFO

【構造体】モニタサイズと他のモニタに対する相対位置情報 x1, y1 will be 0, 0 が1番目の画面。もし他のモニタが左側や上側にあるなら、他のモニタはマイナス値をもつ。

typedef struct ALLEGRO_MONITOR_INFO
{
   int x1;
   int y1;
   int x2;
   int y2;
} ALLEGRO_MONITOR_INFO;

al_get_current_video_adapter int al_get_current_video_adapter(void)

新規のビデオアダプタのインデックスが作成され、そのインデックスを得ます。

al_set_current_video_adapter void al_set_current_video_adapter(int adapter)

新しい画面を作るために使うアダプタをセットします。アダプタはモニタに取り付けられてます。モニタに関する情報は al_get_num_video_adapters aや al_get_monitor_info関数を使って取得してください。

al_get_monitor_info void al_get_monitor_info(int adapter, ALLEGRO_MONITOR_INFO *info)

デスクトップ上のモニタ位置についての情報を得る adapter には、0〜 al_get_num_video_adapters()-1 の値が入る.See Also: ALLEGRO_MONITOR_INFO

al_get_num_video_adapters int al_get_num_video_adapters(void)

コンピュータに取り付けられている"アダプター"の総数を得る。コンピュータに取り付けられた各ビデオカードは1個以上のアダプターとみなされます。アダプターはそれゆえモニタに接続することが可能なビデオポートのことです。

Deferred drawing

al_hold_bitmap_drawing

void al_hold_bitmap_drawing(bool hold)

Deferred drawingモードを有効/無効にします。これは親ビットマップを共有する多くのビットマップの効率的な描画方法を想定します。

たとえばビットマップから同一の複製を作ったり、2D-RPGのマップのようにマップ部品画像(親ビットマップ)を元に、その組み合わせを画面に並べる使い方があります。

このような場合、サブビットマップで親ビットマップを共有しなければ、部品を表示するごとに沢山の呼び出しが発生するので非効率的になり処理がもたつきます。

Deferred drawingモードは、それが有効は間はビットマップ描画が可能で、唯一使用できるの関数が bitmap drawing 関数と font drawing関数です。描画結果はあなたがこのモードの維持を無効にするまで確定されません。そのため、この間に描画設定(blender:混色設定)を変更してしまった場合は想定外の結果がもたらされるので気をつけてください。

従ってこの機能を使う順序としては、

・ Deferred drawingモードを有効にする

・親ビットマップを共有するビットマップを使って効率よく描画する

・ Deferred drawingモードを無効にする
ということになってます。

また、このモードはビットマップとTruetype フォントで機能するので、何行にもわたる長文テキストを描画する必要があれば、 Deferred drawingモードを使うことで早く描画することができます。

al_is_bitmap_drawing_held

bool al_is_bitmap_drawing_held(void)

deferred bitmap drawing モードがON/OFFであるか関係なく、返ります。
Returns whether the deferred bitmap drawing mode is turned on or off.

イベントオブジェクト

typedef union ALLEGRO_EVENT ALLEGRO_EVENT;

An ALLEGRO_EVENT は、組み込みイベント構造体の集合体です。すなわち(i.e.)どんなイベントタイプのデータでも保持できるくらい大きなオブジェクトです。全てのイベントは次のような共通したフィールドに格納されています。

ALLEGRO_EVENT_TYPE          type;
ALLEGRO_EVENT_SOURCE *      any.source;
double                      any.timestamp;

type フィールドにアクセスすることにより、タイプ固有の情報にアクセスすることができます。 any.source　フィールドは、どのイベントソースがその指定(particular)のイベントを発生させたかを教えてくれます。 any.timestamp フィールドは、いつそのイベントが発生したのかを教えてくれます。これはal_current_time()を起点に参照されます。

ALLEGRO_EVENT_SOURCE typedef struct ALLEGRO_EVENT_SOURCE ALLEGRO_EVENT_SOURCE;

イベントソースはイベントを生成することができる、あらゆるオブジェクトです。イベントソースはたいてい、例えば( e.g. )ALLEGRO_KEYBOARD　のように異なった名前で参照されますが、一般的なイベントソースを受け入れる文脈で使用されると、ALLEGRO_EVENT_SOURCE としてキャストすることができます。

それぞれのイベントタイプの下に、複数のイベントが存在します。
イベント名 -  そのイベントが発生する条件


ALLEGRO_EVENT_JOYSTICK_AXIS - ジョイスティックの値が変化した。
フィールド： 
	joystick.stick 
	joystick.axis
	joystick.pos (-1.0〜1.0 の範囲をとる)

ALLEGRO_EVENT_JOYSTICK_BUTTON_DOWN - ジョイスティックのボタンが押された
フィールド:
	joystick.button.

	
ALLEGRO_EVENT_JOYSTICK_BUTTON_UP - ジョイスティックのボタンが離された
フィールド: 
	joystick.button.

ALLEGRO_EVENT_KEY_DOWN - キーボードのキーが押された
フィールド 
	keyboard.keycode
	keyboard.unichar
	keyboard.modifiers.
	keyboard.display

ALLEGRO_EVENT_KEY_REPEAT -  キーが押しっぱなしで入力された
Fields:
	keyboard.keycode (ALLEGROKEY*)
	keyboard.unichar (unicode character)
	keyboard.modifiers (ALLEGROKEYMOD*)
 

ALLEGRO_EVENT_KEY_UP - キーボードのキーが離された
Fields: 
	keyboard.keycode
	keyboard.display


ALLEGRO_EVENT_MOUSE_AXES -  1つまたは複数のマウス軸(xyz方向位置、加速度など)が変化した
Fields: 
	mouse.x
	mouse.y
	mouse.z
	mouse.dx
	mouse.dy,
	mouse.dz.
	mouse.display
	
	Note: al_set_mouse_xy 関数を呼び出すことはまた、マウス軸(axis)の値が変更されるでしょうが、そのような変更は代わりにALLEGRO_EVENT_MOUSE_WARPEDイベント
	によって伝達されます。
	Note:  al_set_mouse_axis関数の反応によってイベントが発生するならば、現時点のmouse.displayは、NULLかもしれません。 
	
	
ALLEGRO_EVENT_MOUSE_BUTTON_DOWN - マウスのボタンが押された
Fields: 
	mouse.x
	mouse.y
	mouse.z
	mouse.button.
	mouse.display

ALLEGRO_EVENT_MOUSE_BUTTON_UP - マウスのボタンが離された
Fields: 
	mouse.x
	mouse.y
	mouse.z
	mouse.button.
	mouse.display

ALLEGRO_EVENT_MOUSE_ENTER_DISPLAY - マウスカーソルが  プログラムによって開いたウインドウに入った
Fields: 
	mouse.x
	mouse.y
	mouse.z
	mouse.display
	
ALLEGRO_EVENT_MOUSE_WARPED 
マウスカーソルの位置を瞬間移動させるために、al_set_mouse_xy関数が呼ばれた。　
そうでなければ、このイベントはALLEGRO_EVENT_MOUSE_AXESと同じ意味です。　

ALLEGRO_EVENT_MOUSE_LEAVE_DISPLAY - マウスカーソルが  プログラムによって開いたウインドウから出た
Fields: 
	mouse.x
	mouse.y
	mouse.z
	mouse.display


ALLEGRO_EVENT_TIMER - タイマーカウントが増加した
Fields: 
	timer.count.


ALLEGRO_EVENT_DISPLAY_EXPOSE - その画面(または一部分)が表示された
Fields: 
	display.x
	display.y
	display.width
	display.height
 

ALLEGRO_EVENT_DISPLAY_RESIZE - そのウインドウがリサイズされた
Fields: 
	display.x
	display.y
	display.width
	display.height


ALLEGRO_EVENT_DISPLAY_CLOSE - ウインドウのクローズボタンが押された　


ALLEGRO_EVENT_DISPLAY_LOST -  いくつかのドライバが消失状態(ロスト)になった。(Direct3D環境で発生します)。これはレンダリング処理が不能であることを意味します。もし可能ならデバイスをレンダリング可能な状態に復帰するでしょう。このイベントを無視してプログラムを動作することはできますが、レンダリングが失敗するので画面効果はなにもありません。


ALLEGRO_EVENT_DISPLAY_FOUND -   ロストしたデバイスが再びレンダリング可能な状態に戻った。もう乱れた表示にはなりません。

ALLEGRO_EVENT_DISPLAY_SWITCH_OUT - そのウインドウがアクティブ状態ではなくなった。
これはユーザーが別のウインドウをクリックしたかタブ化 した場合に起きる

ALLEGRO_EVENT_DISPLAY_SWITCH_IN - そのウインドウが再びアクティブ状態に復帰した。

ALLEGRO_USER_EVENT typedef struct ALLEGRO_USER_EVENT ALLEGRO_USER_EVENT;

ユーザーイベントソースによって発行可能なイベント構造体です。これらにはpublicなフィールドがあります。

ALLEGRO_EVENT_SOURCE *source;
intptr_t data1;
intptr_t data2;
intptr_t data3;
intptr_t data4;

ALLEGRO_EVENT_QUEUE typedef struct ALLEGRO_EVENT_QUEUE ALLEGRO_EVENT_QUEUE;

イベントキュー(イベント待ち行列)はキューに登録されるイベントソースで発生したイベントを捕捉します。イベントは、それらが生成された順に格納されます。そのアクセスはFIFO(先入れ先出し)順で行われます。

ALLEGRO_EVENT_SOURCE typedef struct ALLEGRO_EVENT_SOURCE ALLEGRO_EVENT_SOURCE;

イベントソースは、イベントを発生することが出来る、あらゆるオブジェクトです。例えば、ALLEGRO_DISPLYが、イベントを発生させるとal_get_display_event_source関数によって、 ALLEGRO_DISPLAYオブジェクトからALLEGRO_EVENT_SOURCE ポインタを得ることができます。

あなたはカスタムイベントを発行する自身の「ユーザ」イベントソースを作成できます。

ALLEGRO_EVENT_TYPE

typedef unsigned int ALLEGRO_EVENT_TYPE;
enum

異なるイベントタイプを判別する為に利用される整数。

ALLEGRO_GET_EVENT_TYPE

#define ALLEGRO_GET_EVENT_TYPE(a, b, c, d)   AL_ID(a, b, c, d)

イベントタイプ識別子を作成します。これは32bit整数です。たいていは 8-bit 文字のコードから構成されます。
例えばユーザーが独自に「MY_EVENT_TYPE」というイベントを定義した場合：

#define MY_EVENT_TYPE   ALLEGRO_GET_EVENT_TYPE('M','I','N','E')

このように重複しないユニークなIDを作らなければいけません。そうすればサードパーティ製のコードと一緒に使った場合でもクラッシュすることはありません。なお、1024番未満のIDは Allegroやそのアドオンによって予約されています。

ALLEGRO_EVENT_TYPE_IS_USER

#define ALLEGRO_EVENT_TYPE_IS_USER(t)        ((t) >= 512)

A macro which evaluates to true if the event type is not a builtin event type, i.e. one of those described in ALLEGRO_EVENT_TYPE.

al_create_event_queue ALLEGRO_EVENT_QUEUE *al_create_event_queue(void)

空の新規イベントキュー(発生したイベントが実行待ちするためのリスト)を作成し、成功した場合オブジェクトへのポインタを返す。エラーならNULLを返します。

al_init_user_event_source void al_init_user_event_source(ALLEGRO_EVENT_SOURCE *src)

ユーザイベントを発行するためにイベントソースを割り当てます。イベントソースのためのスペースは既に割り当てられていなければいけません。
カスタムイベントソースを作成するその一つの方法として、ALLEGRO_EVENT_SOURCE を頭に、他の構造体から引き出す方法があります。

typedef struct THING THING;

struct THING {
ALLEGRO_EVENT_SOURCE event_source;
int field1;
int field2;
/* etc. */
};

THING *create_thing(void)
{
THING *thing = malloc(sizeof(THING));

if (thing) {
    al_init_user_event_source(&thing->event_source);
    thing->field1 = 0;
    thing->field2 = 0;
}

return thing;
}

この方法を使う利点は、THINGポインタがALLEGRO_EVENT_SOURCEポインタと同じになるということです。イベントソースによって放たれたイベントは、ソースフィールドとしてイベントソースポインタを持つでしょう(確実にチェックした後に、正しいイベントタイプか確実にチェックされます)。(簡単なキャストからTHINGにポインタを届けることができます)。
The advantage here is that the THING pointer will be the same as the ALLEGRO_EVENT_SOURCE pointer. Events emitted by the event source will have the event source pointer as the source field, from which you can get a pointer to a THING by a simple cast (after ensuring checking the event is of the correct type).

しかしながら、これは1つのテクニックにすぎません、それをあなたに強制するというものではありません。

al_destroy_event_queue void al_destroy_event_queue(ALLEGRO_EVENT_QUEUE *queue)

指定したイベントキューを破棄します。そのイベントキューに現在登録されている全てのイベントソースは、キューが破棄される前に自動的に登録解除されます。

al_destroy_user_event_source void al_destroy_user_event_source(ALLEGRO_EVENT_SOURCE *src)

al_create_user_event_source.によって作られたイベントソースを破棄する。

al_drop_next_event bool al_drop_next_event(ALLEGRO_EVENT_QUEUE *queue)

キューに次のイベントパケットを投下します。キューが空なら何も発生しません。イベントが投下された場合 trueを返します。

　 al_emit_user_event

bool al_emit_user_event(ALLEGRO_EVENT_SOURCE *src,
   ALLEGRO_EVENT *event, void (*dtor)(ALLEGRO_USER_EVENT *))

ユーザーイベントを放ちます。用いるイベントソースはal_init_user_event_source関数によって作成されなければいけません。渡されるイベントの一部のフィールドは変更されるかもしれません。もし戻り値にfalseが返った場合セットされたイベントソースはどのキューにも登録されてないので、従ってイベントはどのようなキューに渡されないでしょう。

参照カウントは、 dtor が非NULLならばイベントが実行されるでしょう。参照カウンタがゼロに落ちた場合 dtor はイベント引数のコピーとして呼び出されるでしょう。その場合関連したイベントソースは破棄しなければいけません。 dtorがNULLの場合は参照カウントは実行されないでしょう。

もし、al_get_next_event, al_peek_next_event, al_wait_for_event,等によって得た参照カウントを終えていたなら、 al_unref_user_event を呼ぶ必要があります。非参照カウントのユーザーイベント上では、call al_unref_user_eventは呼ぶ必要がないかもしれません、

al_destroy_event_queue void al_destroy_event_queue(ALLEGRO_EVENT_QUEUE *queue)

指定したイベントキューを破棄します。現時点で登録されている全てのイベントキューは、キューが破棄される前に自動的に登録が解除されるでしょう。

al_destroy_user_event_source void al_destroy_user_event_source(ALLEGRO_EVENT_SOURCE *src)

al_init_user_event_source関数によって初期化されたイベントソースを破棄します。

bool al_event_queue_is_empty bool al_event_queue_is_empty(ALLEGRO_EVENT_QUEUE *queue)

指定したイベントキューが空なら trueを返す

al_flush_event_queue void al_flush_event_queue(ALLEGRO_EVENT_QUEUE *queue)

全てのイベントを、キューから来たどんなものであっても投下する。

al_get_event_source_data intptr_t al_get_event_source_data(const ALLEGRO_EVENT_SOURCE *source)

イベントソースに関連づけられた抽象ユーザーデータを返します。もし、直前のデータが全く設定されてないければNULLを返します。

al_get_next_event bool al_get_next_event(ALLEGRO_EVENT_QUEUE *queue, ALLEGRO_EVENT *ret_event)

指定したイベントキューから、次のイベントパケットを取り出します。　そしてRET_EVENTコンテンツにコピーされます(trueが戻る)。オリジナルのイベントパケットはキューから削除されます。もしキューが空なら falseが返り、 RET_EVENT コンテンツは不指定化されます。

al_peek_next_event bool al_peek_next_event(ALLEGRO_EVENT_QUEUE *queue, ALLEGRO_EVENT *ret_event)

次のイベントパケットをコピーし、 RET_EVENTコンテンツに分け入れます。オリジナルのイベントパケットはイベントキューに残ったままです。もしキューが空なら falseが返り、 RET_EVENT コンテンツは不指定化されます。

　 al_register_event_source

void al_register_event_source(ALLEGRO_EVENT_QUEUE *queue,
   ALLEGRO_EVENT_SOURCE *source)

指定したイベントキューに、イベントソースを登録します。イベントソースは、色々なイベントキューに登録されたり、または何も登録されないかもしれません。同じイベントソースにもう一度登録しようとする場合は何もしません。

al_set_event_source_data void al_set_event_source_data(ALLEGRO_EVENT_SOURCE *source, intptr_t data)

抽象ユーザーデータをイベントソースに割り当てます。Allegroはいかなる内部データを使用することはありません。それは単に、ユーザーが自身のデータまたはオブジェクトをイベントに関連づけるための便利な方法ということを意味します。

Assign the abstract user data to the event source. Allegro does not use the data internally for anything; it is simply meant as a convenient way to associate your own data or objects with events. al_unref_user_event void al_unref_user_event(ALLEGRO_USER_EVENT *event)

ユーザー定義イベントを非参照します。 al_get_next_event, al_peek_next_event, al_wait_for_event等でイベント得た後にこれを行ないます。この関数は参照カウンタがないイベントには何もしません。 See also: al_emit_user_event.

al_unregister_event_source

void al_unregister_event_source(ALLEGRO_EVENT_QUEUE *queue,
   ALLEGRO_EVENT_SOURCE *source)

イベントキューからイベントソースを登録解除します。もし、イベントソースが実際に登録されていなければ何も起きません。イベントキュー内に、なにかイベントソースに由来するイベントが存在しているなら、この関数の実行後にはキューから消えるでしょう。

al_wait_for_event void al_wait_for_event(ALLEGRO_EVENT_QUEUE *queue, ALLEGRO_EVENT *ret_event)

指定のイベントキューに何か登録されるまで待ちます。もしRET_EVENTの内容がNULL以外になれば、キューから削除され、RET_EVENTにコピーされた最初のイベントパケットが入ったことになります。もしRET_EVENTがNULLなら、キューの先頭から最初のイベントパケットが取り去られたことを意味します。

al_wait_for_event_timed

bool al_wait_for_event_timed(ALLEGRO_EVENT_QUEUE *queue,
   ALLEGRO_EVENT *ret_event, float secs)

al_wait_for_event_until

bool al_wait_for_event_until(ALLEGRO_EVENT_QUEUE *queue,
   ALLEGRO_EVENT *ret_event, ALLEGRO_TIMEOUT *timeout)

TIMEOUT_MSECS は約何秒待つのかを決めます。待ち時間が尽きた場合falseを返します。そうでなければtrueを返します。

Time routines

ALLEGRO_TIMEOUT typedef struct ALLEGRO_TIMEOUT ALLEGRO_TIMEOUT;

timeout値を表示します。構造体のサイズが知られているので静的に割り当てられます。内容はprivateです。

al_current_time AL_FUNC(double, al_current_time, (void));

Allegroライブラリが初期化されてからの秒数を返します。返値は Allegroが初期化されていなければ undefinedを返します。その解決はドライバに依存しますが、通常はミリ秒かかります。

al_init_timeout AL_FUNC(void, al_init_timeout, (ALLEGRO_TIMEOUT *timeout, double seconds));

関数を呼び出してから何秒後にタイムアウトするかをtimeout値で設定します。

al_rest AL_FUNC(void, al_rest, (double seconds));

指定した秒数だけ待機します。現在動作中のスレッドを、与えられた時間、一時停止するようにシステムに伝えます。いくつかのOSでは10ミリ秒オーダーの精度で行います。

al_rest al_rest(0.000001)

10ミリ秒単位で停止するかもしれません、全てのCPUソースを使いきらずに、もっと簡単にプログラムを一時停止するには、次のセクションを見てください。

タイマー

ALLEGRO_TIMER typedef struct ALLEGRO_TIMER ALLEGRO_TIMER;

これは、タイマーオブジェクトを表示する抽象データです。したがって、ALLEGRO_EVENT_SOURCE*にイベントソースをcastedされることができるようにタイマーオブジェクトは作用します。

ALLEGRO_USECS_TO_SECS #define ALLEGRO_USECS_TO_SECS(x) (x / 1000000.0)

ミリ秒を秒に変換する。

ALLEGRO_MSECS_TO_SECS #define ALLEGRO_MSECS_TO_SECS(x) (x / 1000.0)

秒をミリ秒に変換する。

ALLEGRO_BPS_TO_SECS #define ALLEGRO_BPS_TO_SECS(x) (1.0 / x)

BPS(1秒間における拍=Beatを刻む時間)を、を秒に変換する。

ALLEGRO_BPM_TO_SECS #define ALLEGRO_BPM_TO_SECS(x) (60.0 / x)

BPM(1分間における拍=Beatのを刻む時間)を、を秒に変換する。

al_get_timer_count int64_t al_get_timer_count(const ALLEGRO_TIMER *timer)

タイマーのカウント値を返します。タイマーを始動または停止することができます。

al_get_timer_speed double al_get_timer_speed(const ALLEGRO_TIMER *timer)

タイマーのがどのくらいの速さで進むかを秒で返します。

al_install_timer ALLEGRO_TIMER* al_install_timer(double speed_secs)

新規タイマーをインストールします。もし成功したなら新規タイマーオブジェクトへのポインタが返ります。そうでなければNULLが返ります。そして　 speed_secs は、プラスの数で、tick毎秒を指定します。新規タイマーは、インストール時には停止しています。システムドライバは関数を呼び出す前にこれをインストールしなければいけません。 Usage note:典型的な粒度(マイクロプロセッサ処理の単位)はマイクロ秒オーダーではありますが、複数のドライバと同時にある場合はミリ秒かかるかもしれません。

al_set_timer_count void al_set_timer_count(ALLEGRO_TIMER *timer, int64_t new_count)

タイマーのカウント値を変更します。タイマーを始動または停止できます。COUNT値はプラス値マイナス値を取り得ますが、常に+1増加するでしょう。

al_set_timer_speed void al_set_timer_speed(ALLEGRO_TIMER *timer, double new_speed_secs)

タイマの速度、つまりタイマー始動時にのカウンタ増加率を設定してください。タイマーを始動するか、停止するときにこれができます。
タイマーが現在動作中なら、この変更は最終tickにおいて変化されます。
speed_secsは、ちょうどal_install_timerと同じ意味を持ちます。

al_start_timer void al_start_timer(ALLEGRO_TIMER *timer)

指定したタイマーを始動させます。これによりタイマーカウンタは一定率で増加し、イベントを生成開始します。既に始動しているタイマーにこれを適用した場合には何も起きません。

al_stop_timer void al_stop_timer(ALLEGRO_TIMER *timer)

指定したタイマーを停止します。タイマーカウンタは増加をやめ、イベント生成をやめるでしょう。既に停止しているタイマーにこれを適用した場合には何も起きません。

al_timer_is_started

bool al_timer_is_started(const ALLEGRO_TIMER *timer)

指定したタイマーが現在動作中ならtrueを返します。

al_uninstall_timer

void al_uninstall_timer(ALLEGRO_TIMER *timer)

指定したタイマーをアンインストールします。このときタイマーが動作中であれば自動的に停止します。イベントキューもまた、自動的に登録解除されるでしょう。タイマーがなければNULLを返すでしょう。

al_get_timer_event_source

ALLEGRO_EVENT_SOURCE *al_get_timer_event_source(ALLEGRO_TIMER *timer)

関連イベントソースを検索してください。

スレッド

Allegro 4.9は、シンプルなクロスプラットフォーム対応のスレッディングインターフェースを含んでいます。これは、2つのスレッディングAPI 層から構成されます。これらは Windowsスレッドと POSIXスレッド(pthreads)です。全てのプラットフォームに一貫して、正しい意味に即して実行させるは難しいのです、従って、以下にある機能の動作は、別のプラットフォームでは(いつもより)微妙に違いが発生するでしょう。最善策は、他のプラットフォームでも意味が通るコードを意識し、プラットフォームに依存しかけた、きわどいケース(edge cases)のコードを書く事を避けることです。

system

al_install_system bool al_install_system(int version, int (*atexit_ptr)(void (*)(void)))

Allegroシステムを初期化します。この関数を呼ぶ前には、他のAllegro関数を呼ぶことは全くできません(1つか2つの例外はあります)。 version パラメータには、いつも、ALLEGRO_VERSION_INTを指定して下さい。 atexit_ptr がNULL以外だったり既にしていない場合、 atexit 関数に、al_uninstall_system() が登録されます。もし、この関数によって正常に呼び出される、または既に初期化されていた場合trueを返します。もしAllegroが使用できない場合はfalseを返します。

al_init #define al_init() (al_install_system(ALLEGRO_VERSION_INT, atexit))

al_install_systemに似ていますが、ただし、自動的に用途は現在の編集単位で目に見えるatexit機能をインストールします。

al_uninstall_system void al_uninstall_system(void)

Allegroシステムを終了する。 Note: al_uninstall_system() は、対応する al_install_system() が無くても呼び出すことが出来ます。例えば atexit()から.

al_get_allegro_version uint32_t al_get_allegro_version(void)

Allegro(コンパイル済)システムのバージョン番号を返す。 packed into a single integer as groups of 8 bits in the form (major ＜＜24) | (minor ＜＜ 16) | (revision ＜＜8) | release.

このようなコードを使って、取り出します:

id に入れるフラグ指定

uint32_t version = al_get_allegro_version();
int major = version >> 24;
int minor = (version >> 16) & 255;
int revision = (version >> 8) & 255;
int release = version & 255;

The release number is 0 for an unofficial version and 1 or greater for an official release. For example "5.0.2[1]" would be the (first) official 5.0.2 release while "5.0.2[0]" would be a compile of a version from the "5.0.2" branch before the official release.

al_get_standard_path ALLEGRO_PATH *al_get_standard_path(int id)

システムパス(ディレクトリの場所)を取得。失敗した場合はNULLを返す。

id に入れるフラグ指定

ALLEGRO_PROGRAM_PATH            ………………実行ファイルのあるディレクトリパス
ALLEGRO_TEMP_PATH                    ………………一時ファイルのためのディレクトリ パス
ALLEGRO_SYSTEM_DATA_PATH   ……………… システム用のデータパス 
ALLEGRO_USER_DATA_PATH         ……………… 各ユーザー用のデータパス
ALLEGRO_USER_HOME_PATH        ………………ユーザーのホームディレクトリまでのパス 
ALLEGRO_USER_SETTINGS_PATH  ……………ユーザーごとにセッティングファイルのあるディレクトリパス 
ALLEGRO_SYSTEM_SETTINGS_PATH …………システムのセッティングファイルのあるディレクトリパス 
ALLEGRO_EXENAME_PATH          ………………実行ファイルまでのフルパス

al_install_system bool al_install_system(int (*atexit_ptr)(void (*)(void)))

Allegroシステムの初期化。もし、atexit_ptrが NULL以外で、行なわれていなければ、 al_uninstall_system() 関数がatexit関数として登録されます。

al_set_appname void al_set_appname(const char *appname)

global application nameを設定する。 Application nameは、al_get_path 関数によってアプリケーションファイルのあるフルパスを構築するために使われます。プログラムの最初で、[al_init] または al_install_system の前に、1度だけ呼ばなければいけません、そして再設定してはいけません。

al_set_orgname void al_set_orgname(const char *orgname)

global organization nameを設定します Organization name は、 al_get_path 関数によってアプリケーションファイルのあるフルパスを構築するために使われます。プログラムの最初で、[al_init] または al_install_system の前に、1度だけ呼ばなければいけません、そして再設定してはいけません。

al_get_appname AL_CONST char *al_get_appname(void)

global application nameを得る。

al_get_orgname AL_CONST char *al_get_orgname(void)

global organization name 文字列を得る。

al_get_system_driver ALLEGRO_SYSTEM *al_get_system_driver(void)

現在の activeなシステムドライバを返します。またはNULL　

al_get_system_config

ALLEGRO_CONFIG *al_get_system_config(void)

Allegroに何らかのシステムがインストールされていれば返します。そうでなければ NULLが返ります。　
この関数は主にAllegroとそのアドオンを設定するのに使われます。

State

ALLEGRO_STATE typedef struct ALLEGRO_STATE

al_store_state/al_restore_state関数を通してアクセス可能な Opaque型構造体

ALLEGRO_STATE_FLAGS enum ALLEGRO_STATE_FLAGS {

ビットの組合せとしてal_store_state/al_restore_state関数に渡されることができるフラグ。以下のフラグは、以下のal_set_/al_get_calls と一致(corresponding)している設定を保存(store)するか、回復(restore)します

ALLEGRO_STATE_NEW_DISPLAY_PARAMETERS - new_display_format, new_display_refresh_rate, new_display_flags
ALLEGRO_STATE_NEW_BITMAP_PARAMETERS - new_bitmap_format, new_bitmap_flags
ALLEGRO_STATE_DISPLAY - current_display
ALLEGRO_STATE_TARGET_BITMAP - target_bitmap
ALLEGRO_STATE_BLENDER - blender
ALLEGRO_STATE_NEW_FILE_INTERFACE - new_file_interface
ALLEGRO_STATE_BITMAP -  ALLEGRO_STATE_NEW_BITMAP_PARAMETERS と ALLEGRO_STATE_TARGET_BITMAP と同じ
ALLEGRO_STATE_ALL - 上記すべて

al_get_errno int al_get_errno(void)

一部のAllegroの関数は、エラーコードを返すことと同様にエラー番号をセットします。

呼び出しているスレッドにセットされる最後のエラー番号を得るために、この関数を呼んで下さい。 al_set_errno void al_set_errno(int errnum)

呼び出しているスレッドにエラー番号をセットします。

al_restore_state void al_restore_state(ALLEGRO_STATE const *state)

所定のALLEGRO_STATEオブジェクトから、現在のスレッドの状態の一部を元に戻します。

al_store_state void al_store_state(ALLEGRO_STATE *state, int flags)

所定のALLEGRO_STATEオブジェクトから、現在のスレッドの状態の一部を保存します。フラグのパラメータは、ALLEGRO_STATE_FLAGSのもとで記述されるビットの組合せで指定することができます。

Memory

al_set_memory_management_functions

void al_set_memory_management_functions(

   void *(*malloc)(void *opaque, size_t size),

   void *(*malloc_atomic)(void *opaque, size_t size),

   void (*free)(void *opaque, void *ptr),

   void *(*realloc)(void *opaque, void *ptr, size_t size),

   void *(*debug_malloc)(int line, const char *file, const char *func, void *opaque, size_t size),

   void *(*debug_malloc_atomic)(int line, const char *file, const char *func, void *opaque, size_t size),

   void (*debug_free)(int line, const char *file, const char *func,   void *opaque, void *ptr),

   void *(*debug_realloc)(int line, const char *file, const char *func, void *opaque, void *ptr, size_t size),  void *user_opaque)

メモリ管理機能のカスタマイズは、ライブラリによって使われます。デフォルトの機能はあらゆるNULLな関数ポインタの代わりに使われます。デフォルトのデバッグ用 variant は、単に非デバッグ variant を呼びます。

malloc_atomic - は、ポインタを含まないオブジェクトのための   malloc()代替です。

user_opaque - は、すべての関数に渡すことができるでしょう。

Path

Allegroでは、任意のファイル名を伴った、0個以上から構成されるディレクトリコンポーネント(ディレクトリ部)と任意のドライブを'path'と定義します。ファイル名は、ドットによって、basename と拡張子(extension)に分けることができます。basenameは、ファイル名の一番最初からドット文字(.)の直前までのことをいいます。もしbasenameだけでドット文字が存在しない場合は、全てファイル名として扱われます。拡張子(extension)はドット文字からファイル名の最後までのすべてのものをいいますl。

●ディレクトリコンポーネント:  Directory
●ファイル名表記:  
	filename = basename +  .ext (拡張子)
	または filename =  basename (拡張子なしの場合)

●ファイルパスの例……ディレクトリコンポーネントとファイル名の組合せ:
	./basename.ext
	Dir/Dir/Dir/Dir/basename.ext
	../Dir/Dir/Dir/Dir/Dir/Dir/
	Drive/basename.ext

al_append_path_component void al_append_path_component(ALLEGRO_PATH *path, const char *s)

ディレクトリコンポーネントを追加する。

al_clone_path ALLEGRO_PATH *al_clone_path(const ALLEGRO_PATH *path)

Allegroのファイルパス構造体 (ALLEGRO_PATH)の複製を作ります。失敗した場合はNULLを返します。

al_join_paths bool al_join_paths(ALLEGRO_PATH *path, const ALLEGRO_PATH *tail)

2つのファイルパス構造体を連結します。最初に渡した引数のものが変更されます。もし引数 tail に絶対パスを渡してしまった場合、この関数は何もしません。

tail のファイル名はそれが空文字列であっても、pathファイル名を上書きするでしょう。

Tail のドライブ名は無視されます
もし tail が相対パスなら、'path' が連結され trueが返り、失敗した場合はfalseが返る。

al_create_path ALLEGRO_PATH *al_create_path(const char *str)

文字列から、ファイルパス構造体を作成します。空のパスにするには文字列をNULLにするかもしれません。

al_create_path_for_directory ALLEGRO_PATH *al_create_path_for_directory(const char *str)

これは、al_create_path と同じですが、ディレクトリパスを文字列として解釈(interpret)します。(ディレクトリが対象なので)ファイル名部分は常に空になります。

al_drop_path_tail void al_drop_path_tail(ALLEGRO_PATH *path)

最後のディレクトリコンポーネントを落とします。

al_is_path_present bool al_is_path_present(const ALLEGRO_PATH *path)

指定したファイルパスがシステムにあるなら1を返す。0なら存在しない。-1ならエラー。

al_destroy_path void al_destroy_path(ALLEGRO_PATH *path)

ファイルパス構造体を破棄します。 NULLを渡した場合はなにもしません。

al_get_path_basename const char *al_get_path_basename(const ALLEGRO_PATH *path)

ベースネーム(basename)を返します。すなわち、拡張子を取り去ったファイル名のことです。もしファイル名に拡張子が無ければ、ファイル名全部がベースネームとなります。もし、ファイル名部分が全くなければ、空文字列が返ります。

返されるポインタは、ファイル名部分のパスが何らかの方法で編集されるまで、または破棄されるまでの間のみ有効です。

al_get_path_drive const char *al_get_path_drive(const ALLEGRO_PATH *path)

ファイルパスのある、ドライブレターを返します。なければNULLが返ります。

「ドライブレター」は、Windows上でのみ使われ、たいてい"c:"のような文字列ですが、ネットワーク上のファイルを示す場合に、"\\Computer Name" のように UNC (Uniform Naming Convention) syntax が頭に追加される場合もあります。

al_get_path_extension const char *al_get_path_extension(const ALLEGRO_PATH *path)

ファイルパス文字列の、拡張子が始まる文字へポインタを返します。すなわち最後のドット('.')の前です。もし、ドットが無い場合、空文字列が返ります。

返されるポインタは、ファイル名部分のパスが何らかの方法で編集されるまで、または破棄されるまでの間のみ有効です。

al_get_path_filename const char *al_get_path_filename(const ALLEGRO_PATH *path)

ファイルパス(例えばbasename)にファイル名があればそれを返します。なければ空文字列を返します。
返されるポインタは参照されるファイルパスが何らかの理由で変更されない限り有効です。

al_get_path_component const char *al_get_path_component(const ALLEGRO_PATH *path, int i)

引数として与えたファイルパスのインデックスで 0番目から数えて i 番目のディレクトリを返します。もし引数iに -1 番目という指定をしたならば逆から数えることになります。存在するディレクトリ数を外れた番号を指定するとエラーとなります。

al_insert_path_component void al_insert_path_component(ALLEGRO_PATH *path, int i, const char *s)

ディレクトリパスの i 番目に挿入します。もし i (インデックス)にマイナスの数字を指定した場合、逆から数えることになります。

↓以下の範囲から外れた番号を指定するとエラーとなります。
( 0 <= i <= al_get_path_num_components(path) )

al_make_path_absolute bool al_make_path_absolute(ALLEGRO_PATH *path)

与えられたファイルパスが相対パスならば、現在作業中のディレクトリ名の先頭を付けます。その反対はできません。

al_make_path_canonical bool al_make_path_canonical(ALLEGRO_PATH *path)

渡された絶対パス文字列にある ".."(直上のディレクトリ) エントリ部分を削除します。また全ての'.'(カレントディレクトリ)エントリも削除します。これは、"x/../y" 部分を破壊しないことに注意して下さい。これは意図的なものです。

　もしあなたのシステム上に、/bar/baz へ参照する /foo というシンボリックリンクがある場合、 /foo/../quux というファイルパスは、実際には/quux ではなく、 /bar/quux を表します。 ../を削除するかどうかはあなた次第です。

canonical(正規化)とは、データの冗長な部分を解決して、システムに合うものにする処理です。

al_get_path_num_components int al_get_path_num_components(const ALLEGRO_PATH *path)

ファイルパスの番号を返します。ディレクトリコンポーネントは、パスの最終部分(the filename)を含みません。

al_remove_path_component void al_remove_path_component(ALLEGRO_PATH *path, int i)

i 番目のディレクトリコンポーネントを削除します。もし引数 i に -1のようなマイナス値を与えた場合、パスコンポーネントの最後から数えます。もしリスト外の値を入れた場合はエラーとなります。

al_replace_path_component void al_replace_path_component(ALLEGRO_PATH *path, int i, const char *s)

i 番目のディレクトリコンポーネントを別の文字列で置き換えます。もし引数 i に -1のようなマイナス値を与えた場合、パスコンポーネントの最後から数えます。もしリスト外の値を入れた場合はエラーとなります。

al_set_path_drive void al_set_path_drive(ALLEGRO_PATH *path, const char *drive)

ファイルパスにドライブレターをセットします。drive に NULLを渡した場合、ドライブレター部分は削除されることになります。

al_set_path_filename void al_set_path_filename(ALLEGRO_PATH *path, const char *filename)

ファイルパスに、任意なファイル名(例えば basename)を設定します。filename にはNULLを指定することもできます。

al_set_path_extension bool al_set_path_extension(ALLEGRO_PATH *path, char const *extension)

ファイルパスを与えられた拡張子で置き換えます。すなわち、前方のドットを含めて最後までを拡張子で置き換えます。ファイルパスに拡張子がなければ与えられた拡張子を追加します。もしファイルパスにfilename部が含まれなければ falseを返します。
Returns: 与えられたパスにファイル名部分が含まれていない場合はfalseを返す。 (例えばファイル名部部分が空文字列である場合)

al_get_path_tail const char *al_get_path_tail(const ALLEGRO_PATH *path)

ディレクトリコンポーネントの最後を返します。もしそれが無ければNULLを返します。

al_path_cstr const char *al_path_cstr(const ALLEGRO_PATH *path, char delim)

ファイルパスを表す文字列を得ます。

ディレクトリ階層を区切るセパレータに delim を指定し、文字列化したファイルパスを格納するのに len byte 用意することができます。現在使っている環境のセパレータを使う場合は、ALLEGRO_NATIVE_PATH_SEP 定数を使って下さい。

返されるポインタは、ファイル名部分のパスが何らかの方法で編集されるまで、または破棄されるまでの間のみ有効です。

File I/O

File I/Oは主にファイルの出入力機能を提供する関数です。(←→ 対する、filesystem hook (ファイルシステムフック)は、ディレクトリやファイルパスに関する機能を提供します。)

ALLEGRO_FILE

typedef struct ALLEGRO_FILE ALLEGRO_FILE;

ファイルを開くためのデータのOpague型オブジェクト。これはディスク上にあるファイルや、仮想ファイルにおいて可能です。

ALLEGRO_FILE_INTERFACE

typedef struct ALLEGRO_FILE_INTERFACE;

ディスク上または仮想ファイルの、ファイルタイプを扱うための関数ポインタを含む構造体で、詳しくはal_set_new_file_interfaceの項目を参照下さい。

ALLEGRO_SEEK

enum {

    * ALLEGRO_SEEK_SET - シーク位置をファイルの戦闘へ移動する　
    * ALLEGRO_SEEK_CUR - シーク位置を現在の位置へ移動する　 
    * ALLEGRO_SEEK_END - シーク位置をファイルの最後へ移動する

al_fopen

ALLEGRO_FILE *al_fopen(const char *path, const char *mode)

ファイル(real /virtual)を作成したり、開いたりするために、ファイルパス(場所)とモードを指定します。カレントファイルインターフェースは、開いたファイルに対して使われます。

'path' - 開く対象ファイルの存在するパス(場所)

'mode' -  ファイルを開くモード(  読出し"r" ,  書込み "w", etc.)

ストリームタイプと、ストリングモードに依存している場合、ファイルは"text"モードで開かれるでしょう。このとき、改行(newline)の取り扱いには、特に注意しなければいけません。

たとえば、DOSやWindowsプラットフォームにおけるデフォルトである stdio-based streamを使って、OS固有の改行コード「CR+LF」の位置を探すために、 al_fgetc関数を呼び出しすと、ファイル中の2byte(CR+LF) がある場所を、単に1キャラクタ('')で返すでしょう。

しかし、'' と出力したときは、2byteぶんが代わりに書き出されるでしょう。(ちなみに、'' という文字列は、LF と同等に定義されません。)

改行コードの変換( Newline translations)は、テキストファイルに対しては便利ですが、バイナリファイルに対しては悲惨をもたらします。これを避けるには、オープン-ファイル-ストリームへの引数に、バイナリモードを意味する「b」を含む指定が必要です。たとえば「rb」とか「wb」です。
See also: al_set_new_file_interface.

al_fclose void al_fclose(ALLEGRO_FILE *f)

指定したファイルを閉じます。

al_fread size_t al_fread(ALLEGRO_FILE *f, void *ptr, size_t size)

'size' byteの情報を、ファイルエントリ'fp' から、ポインタ'ptr'へ、読み込みます。
そして、実際に読み込んだbyte数を返します。

al_fwrite size_t al_fwrite(ALLEGRO_FILE *f, const void *ptr, size_t size)

'size' byteの情報を、ポインタ'ptr' から、ファイルエントリ'fp' へ書き出します。
そして、実際に書き出したbyte数、または0を返します。

この関数は、ファイルの終わりを示す EOFと他のエラーを見分けません。al_feof 関数と al_ferror 関数を使用して、それらより見分けてください。

　
al_fflush bool al_fflush(ALLEGRO_FILE *f)

どんな一時データであっても、ファイルエントリ 'fp'へ書き出します。
trueが返れば、成功、falseなら失敗し、erronoにエラー番号がセットされます。

　
al_ftell int64_t al_ftell(ALLEGRO_FILE *f)

現在扱っているファイルの(読込み/書出し位置である)カレント位置を返します。
エラーなら-1が返り、erronoにエラー番号がセットされます。

一部のOS環境では、大容量のファイルをサポートしないかもしれません。

al_fseek bool al_fseek(ALLEGRO_FILE *f, int64_t offset, int whence)

ファイルの'whence' を基準に 'offset' 離れた位置をシークします。

'whence' に指定できるフラグ
* ALLEGRO_SEEK_SET - ファイルの最初からシークする
* ALLEGRO_SEEK_CUR - ファイルのカレント位置からシークする
* ALLEGRO_SEEK_END - ファイルの最後尾からシークする

成功ならtrueが返り、エラーならerronoにエラー番号がセットされます。

一部のOS環境では、大容量のファイルをサポートしないかもしれません。

al_feof bool al_feof(ALLEGRO_FILE *f)

ファイル fp が、EOF (end-of-file indicator )を持っていた場合、trueを返す。 ( 例えばこのようなエラー、われわれは、ファイルの端を越えてデータを読もうとしました。)

注意点は、もし、われわれがファイル終端に居た場合には、この関数はtrueを返さないという事です。
(ファイルの終端まで読込んでない場合にこの関数を使えば良いのです。)

次に挙げるコードは、ファイルがぴったり2byteある場合でも、正しく2byteを読込みます：

int b1 = al_fgetc(f);
int b2 = al_fgetc(f);
if (al_feof(f)) {
/* 少なくとも、 1byte を読んだ段階でエラーが発生した場合、次のerror関数へ報告がくる */
report_error();
}

al_ferror bool al_ferror(ALLEGRO_FILE *f)

なんらかのソートする前にエラーがある場合に、trueを返します。

al_fungetc int al_fungetc(ALLEGRO_FILE *f, int c)

Ungets は、ファイルから得られる、シングルバイト文字列です。もし、ファイルに何も書き込まない場合、文字列データは、エントリのバッファへ戻されます。

al_fsize int64_t al_fsize(ALLEGRO_FILE *f)

ファイルサイズを返します。失敗した場合は -1が返ります。

al_fgetc int al_fgetc(ALLEGRO_FILE *f)

エントリ f を読込み、その次にある byte データを返します。 EOF が返ればファイルの終わり、またはエラーが発生したことを意味します。

al_fputc int al_fputc(ALLEGRO_FILE *f, int c)

シングルバイト文字列c を、エントリ f へ書き出します。

Parameters: * c - 書き出す byteデータの値
* f - 書き出すファイルエントリ

エラーなら EOFを返す。

al_fread16le

int16_t al_fread16le(ALLEGRO_FILE *f)

リトルエンディアン形式(LSB first)で、16bit word データを読込みます。
Returns:16-bit wordデータ、またはエラーの場合は EOFを返す。

al_fread16be

int16_t al_fread16be(ALLEGRO_FILE *f)

ビッグエンディアン形式(MSB first)で、16bit word データを読込みます。
Returns:16-bit wordデータ、またはエラーの場合は EOFを返す。

al_fwrite16le

size_t al_fwrite16le(ALLEGRO_FILE *f, int16_t w)

リトルエンディアン形式(LSB first)で、16bit word データを書き込みます。
書き込んだbyte数を返す：2なら成功、2未満ならエラー。

al_fwrite16le

size_t al_fwrite16le(ALLEGRO_FILE *f, int16_t w)

ビッグエンディアン形式(MSB first)で、16bit word データを書き込みます。
書き込んだbyte数を返す：2なら成功、2未満ならエラー。

al_fread32le

int32_t al_fread32le(ALLEGRO_FILE *f　)

リトルエンディアン形式(LSB first)で、32bit word データを読込みます。
　 Returns:読込みに成功したなら 32-bit wordデータを返します。またはエラーの場合に EOF(-1)を返します。また-1は有効な返り値なので、ファイルの終端に早まって達したのかどうか、al_feof、またはal_ferror関数を使用して、エラーが発生したかのどうかチェックしてください。

al_fread32be

int32_t al_fread32be(ALLEGRO_FILE *f)

ビッグエンディアン形式(MSB first)で、32bit word データを読込みます。
Returns:読込みに成功したなら 32-bit wordデータを返します。またはエラーの場合に EOF(-1)を返します。また-1は有効な返り値なので、ファイルの終端に早まって達したのかどうか、al_feof、またはal_ferror関数を使用して、エラーが発生したかのどうかチェックしてください。

al_fwrite32le

size_t al_fwrite32le(ALLEGRO_FILE *f, int32_t l)

リトルエンディアン形式(LSB first)で、32bit word データを書き込みます。
書き込んだbyte数を返す：4なら成功、4未満ならエラー。

al_fwrite32le

size_t al_fwrite32be(ALLEGRO_FILE *f, int32_t l)

ビッグエンディアン形式(MSB first)で、32bit word データを書き込みます。
書き込んだbyte数を返す：4なら成功、4未満ならエラー。

al_fgets

char *al_fgets(ALLEGRO_FILE *f, char *buf, size_t max)

buf に与えられた、改行(newline) または EOF(end-of-file)で終わるbyte文字列ぶん読込みます。行末の改行や終端も文字列データに含まれています。1byteぶんが、NULLターミネータのために予約されているので、実質 max -1 バイトまで読込まれます。

Parameters:
* f - 読込むファイル
* buf - 埋めるバッファ
* max - バッファサイズの最大値

成功したら、buf のポインタを返します。エラーが発生するか指定byte数に達する前にファイルが終わてしまった場合は、 NULLが返ります。

al_fget_ustr

ALLEGRO_USTR *al_fget_ustr(ALLEGRO_FILE *f)

buf に与えられた、改行(newline) または EOF(end-of-file)で終わるbyte文字列ぶん読込みます。行末の改行や終端も文字列データに含まれています。1byteぶんが、NULLターミネータのために予約されているので、実質 max -1 バイトまで読込まれます。

処理が成功したら、新規 ALLEGRO_USTR構造体へのポインタを返します。ここで発生した構造体は、最終的には al_ustr_free関数で解放しなければいけません。また、エラーが発生するか指定byte数に達する前にファイルが終わてしまった場合は、 NULLが返ります。

al_fputs

int al_fputs(ALLEGRO_FILE *f, char const *p)

ファイルに文字列を書き出します。この関数は、戻り値のことを考えなければ、以下のコードと同等です。

al_fwrite(f, p, strlen(p));

パラメータ等

Parameters:
* f - 書き出すファイルハンドル
* p - 書き出す文字列

非マイナス値の整数が返れば成功、エラーならEOFが返ります。注意：この関数は、al_fopenに渡されたストリームタイプとモードに依存します。文字列中の改行文字は、自動的にOS固有の end-of-line sequencesに変換されるかもしれません。(例えば LFが CR/LF に変換) 　

Standard I/O specific routines

al_fopen_fd

ALLEGRO_FILE *al_fopen_fd(int fd, const char *mode)

標準出入力(stdio)ルーチンを使って、オープンファイルディスクリプタ上で操作する ALLEGRO_FILEオブジェクトを作成します。詳しくは、 fdopen()関数の 'mode' 引数に関する記述を参照して下さい。
成功すると、 ALLEGRO_FILEオブジェクトを返します。エラーの場合はNULLが返ります。エラーについては、Allegro errono に番号がセットされ、ファイルディスクリプとは閉じられないでしょう。Allegroでファイルディスクリプタを閉じるには、 al_fclose関数を使うべきなので。close()関数を使ってはいけません。

al_make_temp_file

ALLEGRO_FILE *al_make_temp_file(const char *template, ALLEGRO_PATH **ret_path)

'template'引数に与えられたファイル名を元にランダムな名前をつけた一時ファイルを作成します。

'template' 引数には、作成するファイル名の名前を決める文字列であり、必ず1つまたはそれ以上の「英大文字(capital X)」を含まなければいけません。これらは、ランダムな英数文字に置き換えられます。なお、この引数にはファイルパス区切り文字列(￥、/、：)を入れないで下さい。

成功すると、ALLEGRO_FILE 構造体を開きます。失敗の場合NULLが返ります。

Alternative file streams

デフォルトでは、Allegroのファイル出入力(file I/O)ルーチンは C言語ライブラリの I/Oルーチンを利用しています。したがって、ローカルファイルシステム上のファイルに働きます。しかし、他のファイルストリームの出入力によって、ファイルが上書きされうる場合もあります。たとえば、 zipファイル内にあるファイルや、メモリ区画に対して行なう場合です。

ここに、 ALLEGRO_FILEオブジェクトを stdio を使わずに取得する方法があります。
There are two ways to get an ALLEGRO_FILE that doesn't use stdio. An addon library may provide a function that returns a new ALLEGRO_FILE directly, after which, all al_f* calls on that object will use overridden functions for that type of stream.

もう一つは、al_set_new_file_interface 関数を、カレントスレッドのためのal_fopen関数呼び出しをフォローする関数に変更する方法です。

al_set_new_file_interface

void al_set_new_file_interface(const ALLEGRO_FILE_INTERFACE *file_interface)

ALLEGRO_FILE_INTERFACE テーブルを呼ぶためのスレッドをセットして下さい。これは後でal_fopen関数を呼び出す為のハンドラを変更するでしょう。
See also: al_store_state, al_restore_state.

al_set_standard_fs_interface void al_set_standard_fs_interface(void)

Return the ALLEGRO_FS_INTERFACE table to the default, for the calling thread.

al_get_new_file_interface

const ALLEGRO_FILE_INTERFACE *al_get_new_file_interface(void)

スレッドを呼び出すために、ALLEGRO_FILE_INTERFACEテーブルへのポインタを返します。
See also: al_store_state, al_restore_state.

File system

ALLEGRO_FS_ENTRY typedef struct ALLEGRO_FS_ENTRY ALLEGRO_FS_ENTRY;

Opaque型のファイルシステムエントリ(filesystem entry)構造体です。以下「エントリ」は、ファイルまたはディレクトリのことを表します。(al_fs_entry_isdir または al_fs_entry_isfile関数をチェックして下さい)この構造体には、ユーザーがアクセス可能なメンバ変数はありません。

ALLEGRO_FS_INTERFACE typedef struct ALLEGRO_FS_INTERFACE {

基本的な"ファイルシステム"の一部を含む構造体です。[al_set_new_fs_interface] を使えば、自作の関数をstdio(標準出入力)の代わりにすることができます。

ALLEGRO_FILE_MODE enum {

ファイルシステムのモードとタイプ

Filesystem modes/types
    * ALLEGRO_FILEMODE_READ - 読込み可能
    * ALLEGRO_FILEMODE_WRITE - 書き込み可能
    * ALLEGRO_FILEMODE_EXECUTE - 実行可能
    * ALLEGRO_FILEMODE_HIDDEN - 隠し属性
    * ALLEGRO_FILEMODE_ISFILE -  エントリがなんらかのファイルである
    * ALLEGRO_FILEMODE_ISDIR - エントリがディレクトリである

ファイル操作

al_create_fs_entry ALLEGRO_FS_ENTRY *al_create_fs_entry(const char *path)

'path' に指定したALLEGRO_FS_ENTRYオブジェクトを作成します。 'path'には、作成したいファイルまたはディレクトリ名を指定します。NULLを渡せばなにもしません。

al_destroy_fs_entry void al_destroy_fs_entry(ALLEGRO_FS_ENTRY *fh)

もしファイルが開いていれば、fsエントリハンドルを破棄します。NULLを渡せばなにもしません。

al_get_fs_entry_name

const ALLEGRO_PATH *al_get_fs_entry_name(ALLEGRO_FS_ENTRY *e)

Returns the entry's filename path. Note that the path will not be an absolute path if the entry wasn't created from an absolute path. Also not that the filesystem encoding may not be known and the conversion to UTF-8 could in very rare cases cause this to return an invalid path. Therefore it's always safest to access the file over its ALLEGRO_FS_ENTRY and not the path. On success returns a read only path structure, which you must not modify or destroy. Returns NULL on failure; errno is set to indicate the error.

al_update_fs_entry

bool al_update_fs_entry(ALLEGRO_FS_ENTRY *e)

Updates file status information for a filesystem entry. File status information is automatically updated when the entry is created, however you may update it again with this function, e.g. in case it changed. Returns true on success, false on failure. Fills in errno to indicate the error.

al_get_fs_entry_mode uint32_t al_get_fs_entry_mode(ALLEGRO_FS_ENTRY *e)

エントリのモードのフラグを返します。　 See also: al_get_errno
See the ALLEGRO_FILE_MODE enum for valid flags.

al_get_fs_entry_atime time_t al_get_fs_entry_atime(ALLEGRO_FS_ENTRY *e)

fsエントリのpathが最後にアクセスされた時刻を返します。

al_get_fs_entry_ctime time_t al_get_fs_entry_ctime(ALLEGRO_FS_ENTRY *e)

fsエントリのpathが作成された時刻を返します。

al_get_fs_entry_mtime time_t al_get_fs_entry_mtime(ALLEGRO_FS_ENTRY *e)

fsエントリのpathが最後に更新されてからの秒数を返します。

al_get_entry_size off_t al_get_entry_size(ALLEGRO_FS_ENTRY *e)

指定したfsエントリのpathのサイズを返します。 See Also: al_fs_entry_size

al_fs_entry_exists

bool al_fs_entry_exists(ALLEGRO_FS_ENTRY *e)

ファイルシステム上に、指定したエントリが存在するかチェックする trueが返るなら存在する。falseなら存在しない。もしエラーが発生した場合は errnoに番号が返る

al_fs_entry_is_file bool al_fs_entry_is_file(ALLEGRO_FS_ENTRY *e)

もし、エントリが正当なファイルならばtrueを返す。

al_fs_entry_is_directory bool al_fs_entry_is_directory(ALLEGRO_FS_ENTRY *e)

もしエントリが正当なディレクトリであればtrueを返す。

al_remove_fs_entry bool al_remove_fs_entry(ALLEGRO_FS_ENTRY *e)

指定したpathのエントリをファイルシステムにあるかチェックします。
without creating an ALLEGRO_FS_ENTRY object explicitly.

al_filename_exists bool al_filename_exists(const char *path)

指定したpathのエントリをファイルシステムからUnlinkします。
成功したならtrueを、そうでなければfalseを返します。
エラーはerrnoに表示されます。

al_remove_filename bool al_remove_filename(const char *path)

Delete the given path from the filesystem, which may be a file or an empty directory. This is the same as al_remove_fs_entry, except it expects the path as a string. Returns true on success, and false on failure. Allegro's errno is filled in to indicate the error.

ディレクトリ

al_open_directory bool al_open_directory(ALLEGRO_FS_ENTRY *e)

ファイルエントリオブジェクト(ディレクトリ)を開きます。エントリ(ディレクトリ)をal_read_directory関数で読込む前に、必ずこの関数を使ってディレクトリを開いて下さい。
また、エントリを使い終わったら、al_close_directory 関数を呼んでディレクトリを閉じる必要があります。
成功するとtrueを返します。

al_read_directory ALLEGRO_FS_ENTRY *al_read_directory(ALLEGRO_FS_ENTRY *e)

指定したディレクトリのエントリe の内容をを読込みます。これ以上エントリがない場合やエラーが起きた場合NULLを返す。
読み込んだあとは、al_close_directory 関数を呼び、クローズしてください。

al_close_directory bool al_close_directory(ALLEGRO_FS_ENTRY *e)

以前に開かれたディレクトリエントリオブジェクトを閉じます。
成功するとtrueを返し、失敗時にはfalseが返ります。このときエラーを捕捉する errono変数にエラー番号を記録します。

al_get_current_directory ALLEGRO_PATH *al_get_current_directory(void)

現在作業中のディレクトリまでのパスを返します。
失敗時にはNULLが返ります。
エラーはerrnoに表示されます。
Possible Errors: * ERANGE - buffer is not large enough

al_change_directory bool al_change_directory(const char *path)

現在作業中のディレクトリを指定した path に変更します。
成功すると trueを返し、失敗時には-1が返ります。

al_make_directory bool al_make_directory(const char *path)

'path'に指定したパス名のディレクトリを、ディスク上に作成します。
エラーの場合falseが返ります。このときエラーを捕捉する errono変数にエラー番号を記録します。

その他

Alternative filesystem functions

Allegroのデフォルトでは、ディレクトリにアクセスするような機能は、各OS固有のファイルシステム関数を使っています。しかし、あなたの作ったゲーム関連ファイルが、独自の圧縮ファイル内に記録されるようになっているのであれば、自作のファイル操作関数を使用することもできます。(一般的なZIP形式であれば、Allegroは、physfs addon として圧縮ファイル内のファイルへのアクセス機能を提供していますので、これをご利用下さい。)

ALLEGRO_FS_INTERFACE

typedef struct ALLEGRO_FS_INTERFACE ALLEGRO_FS_INTERFACE;

The available functions you can provide for a filesystem. They are:

   ALLEGRO_FS_ENTRY *  fs_create_entry   (const char *path);
   void                fs_destroy_entry  (ALLEGRO_FS_ENTRY *e);
   const ALLEGRO_PATH *fs_entry_name     (ALLEGRO_FS_ENTRY *e);
   bool                fs_update_entry   (ALLEGRO_FS_ENTRY *e);
   uint32_t            fs_entry_mode     (ALLEGRO_FS_ENTRY *e);
   time_t              fs_entry_atime    (ALLEGRO_FS_ENTRY *e);
   time_t              fs_entry_mtime    (ALLEGRO_FS_ENTRY *e);
   time_t              fs_entry_ctime    (ALLEGRO_FS_ENTRY *e);
   off_t               fs_entry_size     (ALLEGRO_FS_ENTRY *e);
   bool                fs_entry_exists   (ALLEGRO_FS_ENTRY *e);
   bool                fs_remove_entry   (ALLEGRO_FS_ENTRY *e);

   bool                fs_open_directory (ALLEGRO_FS_ENTRY *e);
   ALLEGRO_FS_ENTRY *  fs_read_directory (ALLEGRO_FS_ENTRY *e);
   bool                fs_close_directory(ALLEGRO_FS_ENTRY *e);

   bool                fs_filename_exists(const char *path);
   bool                fs_remove_filename(const char *path);
   ALLEGRO_PATH *      fs_get_current_directory(void);
   bool                fs_change_directory(const char *path);
   bool                fs_make_directory(const char *path);

al_set_fs_interface void al_set_fs_interface(const ALLEGRO_FS_INTERFACE *fs_interface)

スレッドを呼ぶための、ALLEGRO_FS_INTERFACE テーブルをセットします。
See also: al_store_state, al_restore_state.

al_get_fs_interface const ALLEGRO_FS_INTERFACE *al_get_fs_interface(void)

スレッド呼び出しのために、有効なALLEGRO_FS_INTERFACE テーブルへのポインタを返します。
See also: al_store_state, al_restore_state.

OpenGL

al_get_opengl_extension_list ALLEGRO_OGL_EXT_LIST *al_get_opengl_extension_list(void)

現在の画面でAllegroがサポートしているOpenGL拡張機能のリストを返します。 Allegroはal_get_opengl_extension_list->extension_listによって返された構造体に、知る限りの拡張機能に関する情報を置くでしょう。

例:

if (al_get_opengl_extension_list->extension_list()
        ->ALLEGRO_GL_ARB_multitexture) {
    use it
}

その拡張機能が、現在の画面で利用可能ならばtrue、そうでなければfalseを返します。

これは、AllegroからOpenGL表示を取得した後に、OpenGL拡張機能の定義と関数が必要かどうかチェックする時に使って下さい。Windows環境下では、これはWGL拡張機能、Unix環境下ではGLX拡張機能が動作するでしょう。

例えば、手動で拡張機能をチェックし関数ポインタをあなた自身でロードする場合(Allegro利用者の多くはそれに含まれませんが)al_is_opengl_extension_supported関数と al_get_opengl_proc_address 関数を代わりに使います。

al_get_opengl_proc_address void *al_get_opengl_proc_address(AL_CONST char *name)

OpenGLシンボルのアドレス取得を助けます。

Example:
ARBのマルチテクスチャ機能を実現する glMultiTexCoord3fARB 関数を使う方法：

// 関数型を定義する 
   ALLEGRO_DEFINE_PROC_TYPE(void, MULTI_TEX_FUNC,
      (GLenum, GLfloat, GLfloat, GLfloat));
// 関数ポインタを宣言する
   MULTI_TEX_FUNC glMultiTexCoord3fARB;
//関数のアドレスを得る
   glMultiTexCoord3fARB = (MULTI_TEX_FUNC) al_get_opengl_proc_address(
      "glMultiTexCoord3fARB");

もし、glMultiTexCoord3fARB が NULL以外なら、あたかもOpenGLコアライブラリ内に定義されている関数のようにそれを使うことができます。もし、プログラムに可搬性をもたせるなら、ALLEGRO_DEFINE_PROC_TYPEマクロは、必須です。

Parameters: name - リンクしたいシンボル名　
Return value: 利用可能なシンボルへのポインタ。 そうでなければNULL

al_get_opengl_texture GLuint al_get_opengl_texture(ALLEGRO_BITMAP *bitmap)

指定したビットマップオブジェクトが、内部でOpenGLテクスチャID を利用可能であれば、OpenGLテクスチャIDを返す。そうででなければ、 0を返す。

Example:
bitmap = al_load_bitmap("my_texture.png");
texture = al_get_opengl_texture(bitmap);
if (texture != 0)
    glBind(GL_TEXTURE_2D, texture);

al_get_opengl_texture_size void al_get_opengl_texture_size(ALLEGRO_BITMAP *bitmap, int *w, int *h)

テクスチャとして使用されたビットマップのサイズを検索します。これは、OpenGLが唯一がサポートする2の累乗サイズ(2,4,8,16,64,128,256,512,1024...)、またはサブビットマップによって、異なった結果を得る場合があります。

Retrieves the size of the texture used for the bitmap. This can be different from the bitmap size if OpenGL only supports power-of-two sizes or if it is a sub-bitmap.

OpenGLテクスチャの種類

al_get_opengl_texture_position

void al_get_opengl_texture_position(ALLEGRO_BITMAP *bitmap, int *u, int *v)

使われているテクスチャ中の u/v座標をビットマップの左/上角に返します。
Returns the u/v coordinates for the top/left corner of the bitmap within the used texture, in pixels.

al_get_opengl_fbo

GLuint al_get_opengl_fbo(ALLEGRO_BITMAP *bitmap)

OpenGL フレームバッファオブジェクト(FBO)を利用するためにビットマップへ内部的に与えられる idを返します。他に 0 が返ります。
FBOは、 al_set_target_bitmap関数を呼び出した時、ビットマップに作成されます。

　 al_remove_opengl_fbo

void al_remove_opengl_fbo(ALLEGRO_BITMAP *bitmap)

If the bitmap has an OpenGL FBO created for it (see al_set_target_bitmap), it is freed. It also is freed automatically when the bitmap is destroyed. それがOpenGL フレームバッファオブジェクト(FBO)を持っているビットマップ(al_set_target_bitmap関数を参照)であれば、それを解放します。
また、これはビットマップが破棄(destroy)される時にも自動的に行われます。　

　 al_is_opengl_extension_supported int al_is_opengl_extension_supported(AL_CONST char *extension)

この関数は、OpenGL拡張機能が現在の画面で利用可能かどうかを決定するための助けとなります。

Example:
 int packedpixels = al_is_opengl_extension_supported("GL_EXT_packed_pixels");

packedpixels がtrue の場合、安全にpacked pixels拡張機能に関する定数を使うことができます。 Parameters:extension - 必要な拡張機能名 Return value: trueなら利用可能、そうでなければfalse が返る。

al_get_opengl_version float al_get_opengl_version(void)

現在動作中の画面において、クライアントの(現在プログラムが動作しているコンピュータ上で利用されている)OpnGLのバージョンナンバーを返します。返り値は、OpenGL"1.0" なら　1.0、OpenGL "1.2.1" なら 1.21を返します。

有効なOpenGL文脈を働かせるには、この関数の存在が必要ですこれはal_create_display()を使う前に、呼び出すことはできないことを意味します。

OpenGL configuration

allegro5.cfgに、以下のセクションを追加すると、AllegroによるどのようなOpenGL拡張機能の検出も無効にすることができます。　

[opengl_disabled_extensions]
GL_ARB_texture_non_power_of_two=0
GL_EXT_framebuffer_object=0

セクションにリストした拡張機能は、すべて「利用可能ではない(not available)」ものとして扱われます。(各拡張機能の指定が0、またはどのような値を設定するかは重要ではありません) 　

Primitive addon

プリミティブ図形(円や直線、三角形四角形など)を描画するためのAPI

General

al_get_allegro_primitives_version uint32_t al_get_allegro_primitives_version(void)

このアドオンのバージョンを返す。

High Level Drawing Routines

al_draw_line

void al_draw_line(float x1, float y1, float x2, float y2,
   ALLEGRO_COLOR color, float thickness)

現在描画ターゲットとなっているビットマップに対して、線を引く

    * x1, y1, x2, y2 - 始点と終点
    * color -線の色
    * thickness - 線の太さ。0以下の値を指定すると極細になる。

al_draw_triangle

void al_draw_triangle(float x1, float y1, float x2, float y2,
   float x3, float y3, ALLEGRO_COLOR color, float thickness)

三角形の輪郭線を描画する。

Parameters:
    * x1, y1, x2, y2, x3, y3 - 三角形の各角を構成する3つの座標 
    * color - 三角形の輪郭色
    * thickness - アウトラインの太さ、0を渡すと非常に細い線を描画する。

al_draw_filled_triangle

void al_draw_filled_triangle(float x1, float y1, float x2, float y2,
   float x3, float y3, ALLEGRO_COLOR color)

塗りのある三角形を描画する。

Parameters:    * x1, y1, x2, y2, x3, y3  - 三角形の各角を構成する3つの座標 
    * color - 三角形の色

al_draw_rectangle

void al_draw_rectangle(float x1, float y1, float x2, float y2,
   ALLEGRO_COLOR color, float thickness)

長方形の輪郭線を描画

Parameters:    * x1, y1, x2, y2 - 長方形を構成する、左上角と右下角の座標
    * color - 長方形の輪郭色
    * thickness - アウトラインのの太さ、0を渡すと非常に細い線を描画する。

al_draw_filled_rectangle

void al_draw_filled_rectangle(float x1, float y1, float x2, float y2,
   ALLEGRO_COLOR color)

塗りのある長方形を描画する

Parameters:    * x1, y1, x2, y2  - 長方形を構成する、左上角と右下角の座標
    * color - 長方形の色

al_draw_rounded_rectangle

void al_draw_rounded_rectangle(float x1, float y1, float x2, float y2,
   float rx, float ry, ALLEGRO_COLOR color, float thickness)

角丸長方形の輪郭線を描画する

Parameters:
    * x1, y1, x2, y2 - 角丸長方形を構成する、左上角と右下角の座標
    * color - 輪郭色
    * rx, ry - 角丸の曲率
    * thickness - 線の太さ。0以下の値を指定すると極細になる。

al_draw_filled_rounded_rectangle

void al_draw_filled_rounded_rectangle(float x1, float y1, float x2, float y2,
   float rx, float ry, ALLEGRO_COLOR color)

塗りのある角丸長方形を描画する

Parameters:
    * x1, y1, x2, y2 - 角丸長方形を構成する、左上角と右下角の座標
    * color - 塗りの色
    * rx, ry - 角丸の曲率

al_calculate_arc

void al_calculate_arc(float* dest, int stride, float cx, float cy,
   float rx, float ry, float start_theta, float delta_theta, float thickness,
   int num_segments)

楕円的な円弧を計算し、buffに、計算した位置をセットします。そうでなければ2倍くらい必要です。 thicknessが0以下の場合、num_pointsの数だけ点がvbuffに必要です。そうでなければ2倍くらい必要です。

Parameters: 
　 * dest - 出力する頂点を記憶するバッファへのポインタ
　 * stride - 連続した[successive]組の[pairs of ]座標間の距離 ( を byte で指定) ,  strideは 扇形のニ辺の幅を表す？
    * cx, cy - 円弧の中心座標
    * rx, ry - 円弧の半径(x方向/y方向)
    * start_theta - 円弧が開始する位置の角度
    * delta_theta - 円弧の角張っているほうの長さ (マイナス値を渡すと方向が切り替わります。)
    * thickness - 円弧の厚み 
    * num_points - 計算する点の数

al_draw_ellipse

void al_draw_ellipse(float cx, float cy, float rx, float ry,
   ALLEGRO_COLOR color, float thickness)

楕円の輪郭線を描きます。

Parameters:    * cx, cy - 楕円の中心座標 
    * rx, ry - 楕円の半径
    * color - 楕円の輪郭色
    * thickness - 楕円のアウトラインの太さ、0を渡すと非常に細い線を描画する。

al_draw_filled_ellipse

void al_draw_filled_ellipse(float cx, float cy, float rx, float ry,
   ALLEGRO_COLOR color)

塗られた楕円を描きます。

Parameters:    * cx, cy - 楕円の中心座標 
    * rx, ry - 楕円の半径
    * color - 楕円の色

al_draw_circle

void al_draw_circle(float cx, float cy, float r, ALLEGRO_COLOR color,
   float thickness)

円の輪郭線を描画する。

Parameters:    * cx, cy - 円の中心点
    * r - 円の半径
    * color - 円の輪郭の色 
    * thickness - 円の輪郭線の厚み　0以下の場合非常に細い線になる。

al_draw_filled_circle void al_draw_filled_circle(float cx, float cy, float r, ALLEGRO_COLOR color)

塗りのある円を描画する。

Parameters:    * cx, cy - 円の中心点
    * r -  円の半径
    * color - 円の色

al_draw_arc

void al_draw_arc(float cx, float cy, float r, float start_theta,
   float delta_theta, ALLEGRO_COLOR color, float thickness)

円弧を描く

Parameters:    * cx, cy - 円弧の中心
    * r - 円弧の半径
    * color - 円弧の色　
    * start_theta - 開始角度 
    * delta_theta - 円弧の角張っている部分、(ここにマイナス値を与えると方向が切り替わる。)
    * thickness - 円の厚み 0を渡すと細い円になる

al_calculate_spline

void al_calculate_spline(float* dest, int stride, float points[8],
   float thickness, int num_segments)

4つのコントロールポイントを持ったスプライン曲線を計算する。もしthiknessが0以下の値をとるなら、展開(destination)に必要な num_segmentsの数は逆に2倍以上になる。

Parameters:    *dest - 展開用のバッファへのポインタ 
    * points - 4つのコントロールポイントの4組の座標が入る
    * start - バッファのうちで最初に計算する頂点のインデックス
    * thickness - スプライン曲線の厚み 
    * num_segments - 計算する点の数

al_draw_spline void al_draw_spline(float points[8], ALLEGRO_COLOR color, float thickness)

4つのコントロールポイントを持ったスプラインリボンを描画する。

Parameters:    * points - 4つのコントロールポイントの4組の座標が入る
    * color - スプライン曲線の色
    * thickness - スプライン曲線の厚み 0以下なら極細。

al_calculate_ribbon

void al_calculate_ribbon(float* dest, int dest_stride, const float *points,
   int points_stride, float thickness, int num_segments)

リボン(ひも)として与えられた点の配列を計算します。リボンは通っている点のすべてを通るでしょう。もしthiknessが0以下なら、vbuffに必要な num_segmentsの数は逆に2倍以上になる。

Parameters:
    * dest - 展開バッファ
   * dest_stride - 距離をbyte で指定。 展開バッファ内にある連続した組の座標間の距離
   * points -  4つのコントロールポイントの4組の座標が入る
    *points_stride - 距離をbyte で指定。 points バッファ内の、連続した組の座標間の距離
    * thickness - スプラインリボンの厚み 
    * num_segments - 計算する点の数

al_draw_ribbon

void al_draw_ribbon(float *points, ALLEGRO_COLOR color, float thickness,
   int num_segments)

リボンとして与えられた点の配列を描画します。リボンは通っている点のすべてを通るでしょう。

Parameters:    * points -4つのコントロールポイントの4組の座標が入る
    * color - スプラインの色
    * thickness -  スプライン曲線の厚み 0以下なら極細。

Low Level Drawing Routines

al_draw_prim

int al_draw_prim(ALLEGRO_VERTEX* vtxs, ALLEGRO_BITMAP* texture,
   int start, int end, int type)

頂点バッファに渡された座標を部分集合とする図形を描画します。また古いビデオカードでも動作できるように、テクスチャ画像のサイズは縦横それぞれ 2の冪乗(べきじょう)になるような値(2,8,16,32,64,128...)であることが推奨されます。

Parameters:
    * texture - テクスチャに使うビットマップを指定。0を渡した場合、陰影のあるプリミティブしか使われない。 
    * start, end - 頂点バッファの部分集合から開始点と終了点を指定する
    * type - 描画するプリミティブの型を指定する
Returns:描画されたプリミティブの数

al_draw_indexed_prim

int al_draw_indexed_prim(ALLEGRO_VERTEX* vtxs, ALLEGRO_BITMAP* texture,
   const int* indices, int num_vtx, int type)

頂点バッファに渡された部分集合を描画。この関数は、どの頂点を使用したらよいかを指定するのにインデックス配列を使用します。また古いビデオカードでも動作できるように、テクスチャ画像のサイズは縦横それぞれ 2の冪乗(べきじょう)になるような値(2,8,16,32,64,128...)であることが推奨されます。

Parameters:
    * texture -テクスチャに使うビットマップを指定。0を渡した場合、陰影のあるプリミティブしか使われない。 
    * vtxs- 利用する頂点バッファ
    * indices - 頂点バッファのインデックスリスト一式 
    * num_vtx -インデックス配列から描画したいリストの数。
    * type - 描画するプリミティブの型を指定する
Returns: 描画したプリミティブの数

al_get_allegro_color 未確認

Converts an ALLEGRO_COLOR into a ALLEGRO_PRIM_COLOR.

Parameters:
    * col - ALLEGRO_COLOR to convert
See Also: ALLEGRO_PRIM_COLOR, al_get_allegro_color

al_get_prim_color 未確認

Converts an ALLEGRO_PRIM_COLOR into a ALLEGRO_COLOR.

Parameters:
    * col - ALLEGRO_PRIM_COLOR to convert
See Also: ALLEGRO_PRIM_COLOR, al_get_allegro_color

al_draw_soft_triangle

void al_draw_soft_triangle(

   ALLEGRO_VERTEX* v1, ALLEGRO_VERTEX* v2, ALLEGRO_VERTEX* v3, uintptr_t state,

   void (*init)(uintptr_t, ALLEGRO_VERTEX*, ALLEGRO_VERTEX*, ALLEGRO_VERTEX*),

   void (*first)(uintptr_t, int, int, int, int),

   void (*step)(uintptr_t, int), 

   void (*draw)(uintptr_t, int, int, int))

ソフトウエアラスタライザーと、ユーザー提供のピクセル関数を使って三角形を描画します。
これらの関数が何をしているのかを理解するための助けとして、 addons/primitives/tri_soft.c. のソースコードファイルに書かれている様々なシェーディングルーチンの実装を参考にして下さい。

三角形は、上から下にかけて2つのセグメント(segments,断片)で描画されます。
これらのセグメントは、三角形の中央にある頂点から、垂直に輪郭線を描画(delineate)しています。→／|＼
(意訳：もし三角形の山頂が底辺に向かってペタンと潰れて、三点が一直線上にあるような極端な三角形を描画する場合、どちらかのセグメントは欠けるかもしれません。)
(直訳:それぞれの断片2つの頂点が共線(colinear)を形成していたらどちらかのセグメントは欠けている(absent)かもしれません)
(原文:One of each segment may be absent if two vertices are horizontally collinear.)

( ※幾何学で、複数の任意の点 A,B,C...が同一直線上にあることを、共線(colinear)にあるといいます。)

Parameters:
     * v1, v2, v3 -  三角形の2つの頂点
    * state -  ユーザーが提供する構造体へのポインタを指定します。この構造体はすべてのピクセル関数へと渡されます。

    * init - この関数は何らかの描画が実行する前に1度だけ呼ばれます。渡された3つの点はクリッピングによって変更されるかもしれません。
    * first - この関数は三角形のセグメントひとつごとに、二回呼ばれます。この関数には4つの引数を渡します。最初の2つは、最初に描画されたセグメントのピクセルの座標を表します。 The second two are the left minor and the left major steps, respectively. They represent the sizes of two steps taken by the rasterizer as it walks on the left side of the triangle. From then on, the each step will either be classified as a minor or a major step, corresponding to the above values.
    * step - スキャンライン処理毎に呼ばれます。最後のパラメータに1をセットした場合、ステップは minor step になります。 0の場合は major step になります。 
    * draw - スキャンライン処理毎に呼ばれます。この関数は、最初の2つのパラメータ (xとyに対応する)から、3番目のパラメータ(終了地点のx値)へ達するまで、左から右へ移動しながら走査線(スキャンライン)を描くと予想されます。すべての座標が包括的です。

al_draw_soft_line

void al_draw_soft_line(ALLEGRO_VERTEX* v1, ALLEGRO_VERTEX* v2, uintptr_t state,

   void (*first)(uintptr_t, int, int, ALLEGRO_VERTEX*, ALLEGRO_VERTEX*),

   void (*step)(uintptr_t, int),

   void (*draw)(uintptr_t, int, int))

Draws a line using the software rasterizer and user supplied pixel functions. For help in understanding what these functions do, see the implementation of the various shading routines in addons/primitives/line_soft.c. The line is drawn top to bottom.

Parameters:

    * v1, v2 - The two vertices of the line
    * state - A pointer to a user supplied struct, this struct will be passed to all the pixel functions
    * first - The function is called before drawing the first pixel of the line. It is passed the coordinates of this pixel, as well as the two vertices above. The passed vertices may have been altered by clipping.
    * step - Called once per pixel. The second parameter is set to 1 if the step is a minor step, and 0 if this step is a major step. Minor steps are taken only either in x or y directions. Major steps are taken in both directions diagonally. In all cases, the the absolute value of the change in coordinate is at most 1 in either direction.
    * draw - Called once per pixel. The function is expected to draw the pixel at the two coordinates passed to it.

Transformations

変形行列を扱う。

Transfomations al_copy_transform void al_copy_transform(ALLEGRO_TRANSFORM* src, ALLEGRO_TRANSFORM* dest)

変形行列(transformation)のコピーを作る。

Parameters:
    * src - コピー元
    * dest - コピー先、結果が入る

al_use_transform void al_use_transform(ALLEGRO_TRANSFORM* trans)

プリミティブ描画のために使う変形行列をセットします。この変形行列を利用することであらゆる描画処理が変化することでしょう。

Parameters:
    * trans - 適用する変形行列

al_get_current_transform

const ALLEGRO_TRANSFORM* al_get_current_transform()

al_use_transform関数によってセットされた現時点の変形状態を返す。

void al_invert_transform void al_invert_transform(ALLEGRO_TRANSFORM *trans)

渡された行列の逆行列に変換します。もし変換行列が特異に近い(singular , 逆行列を持たないものに近い)ならば、返された行列は無効であるかもしれません。もし逆行列があるかどうか調べたいならばal_check_inverse関数を使用してください。

Parameters:
   * trans - 対象となる行列

　 al_check_inverse

int al_check_inverse(const ALLEGRO_TRANSFORM *trans, float tol)

与えられた誤差を使って、逆行列を持っているかチェックすることができます。誤差には、ほとんどのアプリケーションが十分に行えるような 0 と 0.001 の間をとる小さな値を指定するべきです。変形行列を構成するために、プリミティブアドオンを利用しているなら、たいていこのチェックが余計なものであることに注意してください。 The only thing that would cause the transformation to not have an inverse is if you applied a 0 (or very small) scale to the transformation. As long as the scale is comfortably above 0, the transformation is invertible. あなたが手動で変化の値をいじくるなら、これはもちろん適用されません。

Parameters:

    * trans - チェック対象の変形行列
    * tol - 誤差(Tolerance)

al_identity_transform void al_identity_transform(ALLEGRO_TRANSFORM* trans)

変形行列を恒等変換(identity化)する。

Parameters:
   * trans - 変更する対象

al_build_transform

void al_build_transform(ALLEGRO_TRANSFORM* trans, float x, float y,
   float sx, float sy, float theta)

いくつかパラメータを与えることで、変形行列を生成します。 scale, rotate, translate,を除いて、このメソッドは高速です。

Parameters: 
   * trans - 変更する対象 
    * x, y - 移動(Translation)
    * sx, sy - 拡大縮小
    * theta - 回転

al_translate_transform void al_translate_transform(ALLEGRO_TRANSFORM* trans, float x, float y)

変形行列に移動(transform)を適用する。

Parameters:
    * trans - 適用する対象
    * x, y - 移動量

al_rotate_transform void al_rotate_transform(ALLEGRO_TRANSFORM* trans, float theta)

変形行列に回転(rotate)を適用する。

 Parameters:
   * trans - 適用する対象
   * theta - 回転角度

al_scale_transform

void al_scale_transform(ALLEGRO_TRANSFORM* trans, float sx, float sy)

変形行列に拡大縮小(scale)を適用する。

Parameters:
    * trans - 適用する対象
    * sx, sy - 拡大率

al_transform_coordinates

void al_transform_coordinates(AL_CONST ALLEGRO_TRANSFORM* trans, float* x, float* y)

1組の頂点座標x,yに対して行列transを適用する。

Parameters:
    * trans - 使用する変形行列 
    * x, y - 適用する頂点の座標

al_transform_transform void al_transform_transform(ALLEGRO_TRANSFORM* trans, ALLEGRO_TRANSFORM* trans2)

変形行列の合成？

Parameters:
    * trans - 使用する変形行列 
    * trans2 - 影響される変形行列

Structures and Types

ALLEGRO_PRIM_COLOR

typedef struct {

OpenGLと Direct3Dのバックエンド両方に理解可能な方法で定義された色を表す特種な構造体です。あなたはこの構造体の内部フィールドへアクセスする必要はなく、代わりに、ALLEGRO_PRIM_COLOR構造体と ALLEGRO_COLOR 構造体と変換する2つの関数を使う事になります。

ALLEGRO_VERTEX typedef struct {

一般的な頂点の型には、4つの色成分とシングルテクスチャのためのテクスチャ座標、3D法線、3D位置といったものがあります。 ALLEGRO_VBUFFER構造体内の頂点へは、al_set_vbuff_〜関数を使って、この構造体内部の値を操作しなければいけません。

    * x, y, z - 頂点の位置データ。2Dプリミティブ図形として扱いたい場合は、 z=0に設定します。
    * r, g, b, a -色成分
    * nx, ny, nz - 法線(Normal)座標
    * u, v - テクスチャ座標

ALLEGRO_TRANSFORM

typedef struct ALLEGRO_TRANSFORM ALLEGRO_TRANSFORM;

この構造体は、4x4行列から構成される一般的な変形行列を定義します。2D平面での変形には、この行列の小さな範囲である左上の2x2行列、そして最も右にある2x1行列の合計6つの値のみ利用されます。

Field:
    * m - float型の4x4行列

ALLEGRO_VERTEX_DECL

typedef struct ALLEGRO_VERTEX_DECL ALLEGRO_VERTEX_DECL;

頂点宣言。このOpaque型構造体は、ユーザ定義されたカスタム頂点形式とレイアウトに関する情報を記述する責任(Responsible)があります。それは、専用の関数によって生成され、また破壊されます。

ALLEGRO_VERTEX_ELEMENT

typedef struct ALLEGRO_VERTEX_ELEMENT ALLEGRO_VERTEX_ELEMENT;

頂点の、とある要素についての情報が記述される小さな構造体です。例えば頂点の位置、またはその色などです。これらの構造体は、頂点宣言を作成するために al_create_vertex_decl関数によって、使われます。このような使われ方は、一般に配列で発生します。(そのような配列の最後の要素には、属性フィルードが配列の終端であることを意味する0が格納されています。→{0,0,0} )

ここに、ALLEGRO_VERTEX構造について説明する宣言を作成するコードの例があります:

 ALLEGRO_VERTEX_ELEMENT elems[] = {
   {ALLEGRO_PRIM_POSITION, ALLEGRO_PRIM_FLOAT_2, offsetof(ALLEGRO_VERTEX, x)},
   {ALLEGRO_PRIM_TEX_COORD_PIXEL, ALLEGRO_PRIM_FLOAT_2, offsetof(ALLEGRO_VERTEX, u)},
   {ALLEGRO_PRIM_COLOR_ATTR, 0, offsetof(CUSTOM_VERTEX, color)},
   {0, 0, 0}
};
ALLEGRO_VERTEX_DECL* decl = al_create_vertex_decl(elems, sizeof(ALLEGRO_VERTEX));

この構造体のフィールド

 
  Fields:
    * attribute -   この属性が意味することを指定する、 ALLEGRO_PRIM_ATTR 列挙体のメンバ。 
    * storage - この属性がどう保存されるかを指定するALLEGRO_PRIM_STORAGE列挙体のメンバ。 
    * offset - 	カスタム頂点構造体のオフセット開始位置を byte数で指定してください。C言語の offsetof関数 はここで非常に役に立ちます。

ALLEGRO_PRIM_TYPE enum ALLEGRO_PRIM_TYPE {

このaddonが描画可能なプリミティブ図形(Primitves)のタイプ。

    * ALLEGRO_PRIM_POINT_LIST - ポイントのリスト、各頂点はポイントを定義します。
    * ALLEGRO_PRIM_LINE_LIST -  バラバラの頂点から構成される線分の連続→ ／／／　
    * ALLEGRO_PRIM_LINE_STRIP - 連続する頂点から構成される折れ線→／＼／＼　
    * ALLEGRO_PRIM_LINE_LOOP - LINE_STRIPに似てますが、最初と最後の頂点もループ状に繋がっています。
    * ALLEGRO_PRIM_TRIANGLE_LIST - 離れた三角形を構成する頂点群のリスト→ △▽
    * ALLEGRO_PRIM_TRIANGLE_STRIP - 三角形が繋がった形の頂点群
    * ALLEGRO_PRIM_TRIANGLE_FAN - 1つの頂点を共有する三角形が集合して扇型を構成するような頂点群

ALLEGRO_PRIM_ATTR typedef enum ALLEGRO_PRIM_ATTR

カスタム頂点において格納する可能性のある、頂点属性のタイプを示す列挙体です。
　

	*  ALLEGRO_PRIM_POSITION -   サポートされた様式ならどんなものでも格納可能な、位置情報 
	* ALLEGRO_PRIM_COLOR_ATTR -  ALLEGRO_PRIM_COLOR に格納された色情報。ALLEGRO_VERTEX_ELEMENTの格納フィールドは無視されます。　
	* ALLEGRO_PRIM_TEX_COORD -  ALLEGRO_PRIM_FLOAT_2とALLEGRO_PRIM_SHORT_2だけに格納可能な、テクスチャ座標の情報。これらの座標はテクスチャの幅と高さによってノーマライズされます、つまり、座標(1、1)がテクスチャの右下隅に対応することを意味します。
	* ALLEGRO_PRIM_TEX_COORD_PIXEL - ALLEGRO_PRIM_FLOAT_2とALLEGRO_PRIM_SHORT_2だけに格納可能な、テクスチャ座標の情報。これらの座標はピクセル単位で計測されます。

 
 画素の座標に関する注意： OpenGLでは、テクスチャ座標(0、0)は画素の左上隅に対応します。 これは実際の画素が抽出した丸め誤差への支払われるべきものが(0、0)画素の先端、そして/または、左への画素であるかもしれないので、いくつかのドライバを混乱させます。
もしあなたが、正確な画素の制御を必要とするなら 、このエラーを起きにくくするために、al_draw_prim関数に(0.5, 0.5)を与えることで、テクスチャ座標をずらすことが賢明です。
  例えば、画素(5、10)を示すために、あなたはuとvに、それぞれ5.5と10.5を設定するでしょう。

ALLEGRO_PRIM_STORAGE typedef enum ALLEGRO_PRIM_STORAGE

カスタム頂点において格納する可能性のある、データ格納属性のタイプを示す列挙体です。

    * ALLEGRO_PRIM_FLOAT_2 - 2組のfloat型変数
    * ALLEGRO_PRIM_FLOAT_3 - 3組のfloat型変数
    * ALLEGRO_PRIM_SHORT_2 - 3組のshort型変数

ALLEGRO_VERTEX_CACHE_SIZE #define ALLEGRO_VERTEX_CACHE_SIZE 256

ソフトウェアレンダラのための transformation vertex cache のサイズ。多くの頂点を関数に渡す場合にこの定数をしておけば、プリミティブのレンダリング速度はアップするでしょう。

ALLEGRO_PRIM_QUALITY #define ALLEGRO_PRIM_QUALITY 10

2次曲線によるプリミティブのクオリティ定義。この10という値は、誤差約0.5ピクセル未満の精度を表します。

Mouse

ALLEGRO_MOUSE_STATE typedef struct ALLEGRO_MOUSE_STATE

Public fields (read only):
    * x - マウスカーソルの x座標
    * y - マウスカーソルの y座標
    * w, z - マウスホイールの位置(2D 'ball')
buttons - 押されたマウスのボタン

al_create_mouse_cursor

ALLEGRO_MOUSE_CURSOR *al_create_mouse_cursor(ALLEGRO_BITMAP *bmp,
   int x_focus, int y_focus)

ビットマップによるマウスカーソルを作成。画面に効果が生じる Return value:成功した場合にはカーソルへのポインタが返る。失敗した場合はNULLが返る。

al_destroy_mouse_cursor void al_destroy_mouse_cursor(ALLEGRO_MOUSE_CURSOR *cursor)

マウスカーソルを破棄する。カーソルが作成されていた場合に、画面に効果が生じる XXX that's terrible and should be changed
カーソルに変化がなければNULL

al_get_mouse_cursor_position bool al_get_mouse_cursor_position(int *ret_x, int *ret_y)

この情報が利用可能なプラットフォームにおいて、この関数はデスクトップに対するマウスカーソルの全体的な位置を返します。通常この機能は使われません。ウインドウを動かしたりする特殊なケースを除いてこの情報が役に立たないためです。 Return value:情報の取得に成功したらtrue, 失敗したらfalseを返す。

al_get_mouse_num_axes unsigned int al_get_mouse_num_axes(void)

マウスの軸の数を返します。

al_get_mouse_num_buttons unsigned int al_get_mouse_num_buttons(void)

マウスのボタンの数を返します。

al_get_mouse_state void al_get_mouse_state(ALLEGRO_MOUSE_STATE *ret_state)

指定したマウスの状態を取得します。

al_get_mouse_state_axis int al_get_mouse_state_axis(ALLEGRO_MOUSE_STATE *ret_state, int axis)

マウス軸の状態を取得します。

al_install_mouse bool al_install_mouse(void)

マウスを使えるようにするために、マウスドライバを有効にします。 Return value:成功した場合はtrueが。既にドライバが有効になっていた場合はなにもせずtrueを返します。

al_is_mouse_installed bool al_is_mouse_installed(void)

trueが返っていた場合は、マウスドライバは有効になっていることを表します。

al_mouse_button_down bool al_mouse_button_down(ALLEGRO_MOUSE_STATE *state, int button)

指定したマウスボタン button が、stateで指定した状態であれば、trueを返します。

al_set_mouse_axis bool al_set_mouse_axis(int which, int value)

指定したマウス軸 which に、指定した値valueを与えます。
For now:マウス軸の番号は、0(X軸)または1(Y軸)
Return value:成功したらtrue、失敗したらfalse

al_set_mouse_cursor bool al_set_mouse_cursor(ALLEGRO_MOUSE_CURSOR *cursor)

指定したマウスカーソルを画面にセットします。既にマウスが作成されている必要があります。 XXX that's terrible and should be changed
カーソルはデフォルトでは 'shown'(反対は'hidden')が設定しており、変更はすぐに反映されます。
Return value:成功したらtrue、失敗したらfalse

al_set_mouse_w bool al_set_mouse_w(int w)

マウスホイール位置に、値をセットします。 Return value:成功したらtrue、失敗したらfalse

al_set_mouse_xy bool al_set_mouse_xy(int x, int y)

マウスカーソルの位置を、指定した座標(x,y)にワープさせます。
Return value:成功したらtrue、失敗したらfalse 成功した場合、 ALLEGRO_EVENT_MOUSE_WARPED イベントも発生します。 XXX: This should be relative to an ALLEGRO_DISPLAY.

al_set_mouse_z bool al_set_mouse_z(int z)

マウスホイールの位置に、値をセットします。
Return value:成功したらtrue、失敗したらfalse

al_set_system_mouse_cursor bool al_set_system_mouse_cursor(ALLEGRO_SYSTEM_MOUSE_CURSOR cursor_id)

現在表示されているマウスカーソルに、OSで使われているカーソルを適用します。(WindowならWindows用の、OSXなら OSXで使用されているカーソル)
もしカーソルが現在'shown'( 'hidden'の反対)状態にあるならすぐに変更されます。また、指定したカーソルの種類が、現在動作中のOSに存在しない場合、別のカーソルが代用されます。
対応するマウスカーソルの種類(通常カーソル、リサイズ、手のひら、時間待ち等)

ALLEGRO_SYSTEM_MOUSE_CURSOR_DEFAULT
ALLEGRO_SYSTEM_MOUSE_CURSOR_ARROW
ALLEGRO_SYSTEM_MOUSE_CURSOR_BUSY
ALLEGRO_SYSTEM_MOUSE_CURSOR_QUESTION
ALLEGRO_SYSTEM_MOUSE_CURSOR_EDIT
ALLEGRO_SYSTEM_MOUSE_CURSOR_MOVE
ALLEGRO_SYSTEM_MOUSE_CURSOR_RESIZE_N
ALLEGRO_SYSTEM_MOUSE_CURSOR_RESIZE_W
ALLEGRO_SYSTEM_MOUSE_CURSOR_RESIZE_S
ALLEGRO_SYSTEM_MOUSE_CURSOR_RESIZE_E
ALLEGRO_SYSTEM_MOUSE_CURSOR_RESIZE_NW
ALLEGRO_SYSTEM_MOUSE_CURSOR_RESIZE_SW
ALLEGRO_SYSTEM_MOUSE_CURSOR_RESIZE_SE
ALLEGRO_SYSTEM_MOUSE_CURSOR_RESIZE_NE
ALLEGRO_SYSTEM_MOUSE_CURSOR_PROGRESS
ALLEGRO_SYSTEM_MOUSE_CURSOR_PRECISION
ALLEGRO_SYSTEM_MOUSE_CURSOR_LINK
ALLEGRO_SYSTEM_MOUSE_CURSOR_ALT_SELECT
ALLEGRO_SYSTEM_MOUSE_CURSOR_UNAVAILABLE

al_show_mouse_cursor bool al_show_mouse_cursor(void)

マウスカーソルを表示させます。
Return value:マウスカーソルが表示されたらtrue(または既に表示状態にあるなら)、そうでなければfalseを返す。

al_hide_mouse_cursor bool al_hide_mouse_cursor(void)

この関数を呼び出したスレッドのマウスカーソルを隠します。マウスカーソルの見た目には影響はありません。ただ見えなくなるだけです。 Return value:成功したらtrue(既にマウスが隠れていた場合も)、そうでなければfalseが返ります。

al_uninstall_mouse void al_uninstall_mouse(void)

マウスドライバを無効にする。このとき、自動的にイベントキューに登録されたマウスイベントも解除されます。この関数は、Allegroが終了(shut down)する際にも自動的に呼び出されます。

al_get_mouse_event_source

ALLEGRO_EVENT_SOURCE *al_get_mouse_event_source(void)

マウス関連イベントソースを検索してください。NULLが返る場合は、マウスサブシステムはインストールされていません。

Keyboard

ALLEGRO_KEYBOARD typedef struct ALLEGRO_KEYBOARD ALLEGRO_KEYBOARD;

この抽象データは、物理的なキーボードのキーを表します。また、キーボードオブジェクトは、ALLEGRO_EVENT_SOURCE〜にキャスト可能なイベントソースです。

ALLEGRO_KEYBOARD_STATE typedef struct ALLEGRO_KEYBOARD_STATE

この構造体は、特定の瞬間のキーボードの状態を保持する、スナップショット"snapshot"として使われます。これら情報は、以下に挙げる読み込み可能なデータフィールドに含まれます: display - 状態が保存された時点でキーボードのフォーカスが当たっているものを指します。全くフォーカスが当たっていない場合はNULLを指します。キーの状態を直接読み取ることは出来ません。読み取るには al_key_down関数を使って下さい。

キーコード一覧

ALLEGRO_KEY_A ... ALLEGRO_KEY_Z, ALLEGRO_KEY_0 ... ALLEGRO_KEY_9, ALLEGRO_KEY_PAD_0 ... ALLEGRO_KEY_PAD_9, ALLEGRO_KEY_F1 ... ALLEGRO_KEY_F12, ALLEGRO_KEY_ESCAPE, ALLEGRO_KEY_TILDE, ALLEGRO_KEY_MINUS, ALLEGRO_KEY_EQUALS, ALLEGRO_KEY_BACKSPACE, ALLEGRO_KEY_TAB, ALLEGRO_KEY_OPENBRACE, ALLEGRO_KEY_CLOSEBRACE, ALLEGRO_KEY_ENTER, ALLEGRO_KEY_SEMICOLON, ALLEGRO_KEY_QUOTE, ALLEGRO_KEY_BACKSLASH, ALLEGRO_KEY_BACKSLASH2, ALLEGRO_KEY_COMMA, ALLEGRO_KEY_FULLSTOP, ALLEGRO_KEY_SLASH, ALLEGRO_KEY_SPACE, ALLEGRO_KEY_INSERT, ALLEGRO_KEY_DELETE, ALLEGRO_KEY_HOME, ALLEGRO_KEY_END, ALLEGRO_KEY_PGUP, ALLEGRO_KEY_PGDN, ALLEGRO_KEY_LEFT, ALLEGRO_KEY_RIGHT, ALLEGRO_KEY_UP, ALLEGRO_KEY_DOWN, ALLEGRO_KEY_PAD_SLASH, ALLEGRO_KEY_PAD_ASTERISK, ALLEGRO_KEY_PAD_MINUS, ALLEGRO_KEY_PAD_PLUS, ALLEGRO_KEY_PAD_DELETE, ALLEGRO_KEY_PAD_ENTER, ALLEGRO_KEY_PRINTSCREEN, ALLEGRO_KEY_PAUSE, ALLEGRO_KEY_ABNT_C1, ALLEGRO_KEY_YEN, ALLEGRO_KEY_KANA, ALLEGRO_KEY_CONVERT, ALLEGRO_KEY_NOCONVERT, ALLEGRO_KEY_AT, ALLEGRO_KEY_CIRCUMFLEX, ALLEGRO_KEY_COLON2, ALLEGRO_KEY_KANJI, ALLEGRO_KEY_LSHIFT, ALLEGRO_KEY_RSHIFT, ALLEGRO_KEY_LCTRL, ALLEGRO_KEY_RCTRL, ALLEGRO_KEY_ALT, ALLEGRO_KEY_ALTGR, ALLEGRO_KEY_LWIN, ALLEGRO_KEY_RWIN, ALLEGRO_KEY_MENU, ALLEGRO_KEY_SCROLLLOCK, ALLEGRO_KEY_NUMLOCK, ALLEGRO_KEY_CAPSLOCK ALLEGRO_KEY_EQUALS_PAD, ALLEGRO_KEY_BACKQUOTE, ALLEGRO_KEY_SEMICOLON2, ALLEGRO_KEY_COMMAND

修飾キーのフラグ

    ALLEGRO_KEYMOD_SHIFT
    ALLEGRO_KEYMOD_CTRL
    ALLEGRO_KEYMOD_ALT
    ALLEGRO_KEYMOD_LWIN
    ALLEGRO_KEYMOD_RWIN
    ALLEGRO_KEYMOD_MENU
    ALLEGRO_KEYMOD_ALTGR
    ALLEGRO_KEYMOD_COMMAND
    ALLEGRO_KEYMOD_SCROLLLOCK
    ALLEGRO_KEYMOD_NUMLOCK
    ALLEGRO_KEYMOD_CAPSLOCK
    ALLEGRO_KEYMOD_INALTSEQ
    ALLEGRO_KEYMOD_ACCENT1
    ALLEGRO_KEYMOD_ACCENT2
    ALLEGRO_KEYMOD_ACCENT3
    ALLEGRO_KEYMOD_ACCENT4

al_get_keyboard_state void al_get_keyboard_state(ALLEGRO_KEYBOARD_STATE *ret_state)

RET_STATEで指定されているキーコードの状態を捕捉します。

al_install_keyboard bool al_install_keyboard(void)

キーボードドライバを有効にし、Allegroでキーボードを使えるようにします。もし成功したらtrue、もしドライバが既に有効になっていたら、trueを返しますが何もしません。

al_is_keyboard_installed bool al_is_keyboard_installed(void)

キーボードが有効になっているか調べます。 al_install_keyboardの呼び出しが成功していれば、trueを返す。

al_key_down bool al_key_down(const ALLEGRO_KEYBOARD_STATE *state, int keycode)

もし、stateに指定したキーが、押されていた場合、trueを返します。

al_keycode_to_name const char *al_keycode_to_name(int keycode)

キーコードを代入すると、対応するキーの名前を返します。

al_set_keyboard_leds bool al_set_keyboard_leds(int leds)

キーボードのLED表示の状態を上書きします。デフォルトのふるまいをさせるなら、-1をセットします。ーボードドライバはLED表示を変更することが出来ない場合falseが返ります。

al_uninstall_keyboard void al_uninstall_keyboard(void)

キーボードドライバを無効にします。このとき、イベントキューに登録されていたキーボードイベントも自動的に解除されます。この関数は、Allegroが終了(shut down)する時に自動的に呼び出されます。

al_get_keyboard_event_source ALLEGRO_EVENT_SOURCE *al_get_keyboard_event_source(void)

キーボード関連イベントソースを検索してください。NULLが返る場合は、キーボードサブシステムはインストールされていません。

Joystick

ALLEGRO_JOYSTICK typedef struct ALLEGRO_JOYSTICK ALLEGRO_JOYSTICK;

これはジョイスティックを表す抽象データです。ジョイスティックオブジェクトは ALLEGRO_EVENT_SOURCE〜にキャストすることができるイベントソースです。

ALLEGRO_JOYSTICK_STATE typedef struct ALLEGRO_JOYSTICK_STATE

これは、ジョイスティックの軸やボタンの状態の状態を保持するスナップショット"snapshot"として使われます。全てのでーたは読み取り専用です。

struct {
      float axis[num_axes];             // -1.0 to 1.0 
} stick[num_sticks];
int button[num_buttons];                // 0 to 32767

ALLEGRO_JOYFLAGS

enum
    * ALLEGRO_JOYFLAG_DIGITAL - デジタル入力を提供するスティック
    * ALLEGRO_JOYFLAG_ANALOGUE - アナログスティック
(this enum is a holdover from the old API and may be removed)

al_get_joystick ALLEGRO_JOYSTICK *al_get_joystick(int num)

システムで有効になっているジョイスティックの数を得る。成功したらジョイスティックオブジェクトへのポインタが返る。そうでなければNULLが返る。もし、ジョイスティックが直前に 'gotten'(で、まだ離されていない)ならば、直前に呼び出されたポインタが返されます。

al_get_joystick_axis_name const char *al_get_joystick_axis_name(const ALLEGRO_JOYSTICK *joy, int stick, int axis)

指定した軸の名前を返します。もし軸が存在しなければNULLを返します。

al_get_joystick_button_name const char *al_get_joystick_button_name(const ALLEGRO_JOYSTICK *joy, int button)

指定したボタンの名前を返します。もしそのようなボタンが存在しなければNULLを返します。

al_get_joystick_name const char *al_get_joystick_name(ALLEGRO_JOYSTICK *joy)

指定したジョイスティックの名前を返します。

al_get_joystick_number int al_get_joystick_number(ALLEGRO_JOYSTICK *joy)

joystick の数を返す。例えば、al_get_joystick(i) の"i" は同じjoystickオブジェクトを返します。
Return the joystick number, i.e. 'i' such that al_get_joystick(i) returns the same joystick object.

al_get_joystick_state void al_get_joystick_state(ALLEGRO_JOYSTICK *joy, ALLEGRO_JOYSTICK_STATE *ret_state)

ジョイスティックの現在の状態を取得します。

al_get_joystick_stick_flags int al_get_joystick_stick_flags(const ALLEGRO_JOYSTICK *joy, int stick)

"stick"に指定したフラグを返します。もしstickが存在しなければNULLを返します。

al_get_joystick_stick_name const char *al_get_joystick_stick_name(const ALLEGRO_JOYSTICK *joy, int stick)

"stick"に指定した名前を返します。もしstickが存在しなければNULLを返します。

al_get_joystick_num_axes int al_get_joystick_num_axes(const ALLEGRO_JOYSTICK *joy, int stick)

"stick"に指定した軸の番号を返します。もしstickが存在しなければ0を返します。

al_get_joystick_num_buttons int al_get_joystick_num_buttons(const ALLEGRO_JOYSTICK *joy)

ジョイスティックにあるボタンの数を返します。

al_get_joystick_num_sticks int al_get_joystick_num_sticks(const ALLEGRO_JOYSTICK *joy)

指定したジョイスティックのスティックの数を返します。

al_install_joystick bool al_install_joystick(void)

ジョイスティックドライバを有効にして、Allegroでジョイスティックを使えるようにします。もし、既にジョイスティックドライバが有効な場合、trueを返します。

al_get_num_joysticks int al_get_num_joysticks(void)

システム上にあるジョイスティックの数を返します(OSによって、これは正確でないかもしれません)。ジョイスティックドライバがインストールされていない場合は0を返す。

al_release_joystick void al_release_joystick(ALLEGRO_JOYSTICK *joy)

'gotten'しているジョイスティックオブジェクトを解放します。

al_uninstall_joystick void al_uninstall_joystick(void)

ジョイスティックドライバを無効にします。 ALLEGRO_JOYSTICK オブジェクトは自動的に解放されます。既にドライバが無効になっている場合は、何もしません。この関数は、Allegroが終了(shut down)する場合にも、自動的に呼び出されます。

al_get_joystick_event_source ALLEGRO_EVENT_SOURCE *al_get_joystick_event_source(ALLEGRO_JOYSTICK *joystick)

関連イベントソースを検索してください。

Graphics

ALLEGRO_COLOR struct ALLEGRO_COLOR

An ALLEGRO_COLOR 構造体について、デバイスに依存しない方法は、al_map_rgb関数等(et. al.)や、 al_unmap_rgb関数などを使い多様な表現形式に変換することです。

al_map_rgb

ALLEGRO_COLOR al_map_rgb(
   unsigned char r, unsigned char g, unsigned char b)

色成分 r, g, b (範囲は 0-255)を入力したものをALLEGRO_COLORオブジェクトに変換します。 255の場合は透明になります。 See also: al_map_rgba, al_map_rgba_f, al_map_rgb_f

al_map_rgb_f ALLEGRO_COLOR al_map_rgb_f(float r, float g, float b)

色成分 r, g, b (範囲は 0.0f-1.0f)を入力したものをALLEGRO_COLORオブジェクトに変換します。 1.0の場合は透明になります。 See also: al_map_rgba, al_map_rgb, al_map_rgba_f

al_map_rgba

ALLEGRO_COLOR al_map_rgba(
   unsigned char r, unsigned char g, unsigned char b, unsigned char a)

色成分 r, g, b,a (範囲は 0-255)を入力したものをALLEGRO_COLORオブジェクトに変換します。 See also: al_map_rgb, al_map_rgba_f, al_map_rgb_f

al_map_rgba_f ALLEGRO_COLOR al_map_rgba_f(float r, float g, float b, float a)

色成分 r, g, b,a (範囲は 0.0f-1.0f)を入力したものをALLEGRO_COLORオブジェクトに変換します。 See also: al_map_rgba, al_map_rgb, al_map_rgb_f

al_unmap_rgb

void al_unmap_rgb(ALLEGRO_COLOR color,
   unsigned char *r, unsigned char *g, unsigned char *b)

指定したALLEGRO_COLOR構造体の色成分(R,G,B)を取得します。alpha成分は無視され、それぞれ0-255の範囲で返されるでしょう。 See also: al_unmap_rgba, al_unmap_rgba_f, al_unmap_rgb_f

al_unmap_rgb_f void al_unmap_rgb_f(ALLEGRO_COLOR color, float *r, float *g, float *b)

指定したALLEGRO_COLOR構造体の色成分(R,G,B)を取得します。alpha成分は無視され、それぞれ0.0f-1.0fの範囲で返されるでしょう。 See also: al_unmap_rgba, al_unmap_rgb, al_unmap_rgba_f

al_unmap_rgba

void al_unmap_rgba(ALLEGRO_COLOR color,
   unsigned char *r, unsigned char *g, unsigned char *b, unsigned char *a)

指定したALLEGRO_COLOR構造体の色成分(R,G,B,A)を取得します。各成分はそれぞれ0-255の範囲で返されるでしょう。 See also: al_unmap_rgb, al_unmap_rgba_f, al_unmap_rgb_f

al_unmap_rgba_f

void al_unmap_rgba_f(ALLEGRO_COLOR color,
   float *r, float *g, float *b, float *a)

指定したALLEGRO_COLOR構造体の色成分(R,G,B,A)を取得します。各成分はそれぞれ0.0f-1.0fの範囲で返されるでしょう。 See also: al_unmap_rgba, al_unmap_rgb, al_unmap_rgb_f

Locking and pixel formats

ALLEGRO_LOCKED_REGION typedef struct ALLEGRO_LOCKED_REGION {

ビッドマップを手動で編集したり、読込みたいと思っている人は、最初にロック処理が必要です。 ALLEGRO_LOCKED_REGION構造体は、ロックされたビットマップ領域を表します。これは、メモリビットマップを含むどんなビットマップを動作させるときにも呼び出されるでしょう。

typedef struct ALLEGRO_LOCKED_REGION {
        void *data; // ビットマップデータ
        int format; // ピクセルデータ格納形式
        int pitch;  // シングルラインのbyteサイズ 
                    // pitchは、 pixel_size*bitmap->wよりも大きな値になるでしょう。
                    // i.e. 余裕を持って設定します。
}

ALLEGRO_PIXEL_FORMAT enum ALLEGRO_PIXEL_FORMAT {

Pixel formatsについて。
ピクセルデータ格納形式は、メモリ上に展開されたピクセル各々のビットの並びです。色成分が高位ビットから低位ビットまで指定されます。例えば、ARGB_8888形式における不明瞭な真っ赤な画素は0xFFFF0000です。

Note:ピクセルデータ格納形式は、エンディアンから独立しています。すなわち、上記の例では
(pixel & 0x00ff0000) >> 16
という式から、いつでも赤い色成分を取り出すことができます。

リトルエンディアン(LSB)(IntelのCPU)は、2bytes以上のデータを転送する時に、
下位→上位の順で記録送信する。(00000001←下位 00000000 ←上位)

ビッグエンディアン(MSB)(PowerPC等)は、2bytes以上のデータを転送する時に、
上位→下位の順で記録送信する。(00000000←上位 00000001←下位)

しかし、次のコードは当てになりません:
*(pixel + 2)
これは、リトルエンディアンシステムの上で赤い成分を返しますが、ビッグエンディアンシステム上では、逆から読み出すので緑色の成分を返してしまうでしょう。

また、Allegroの命名規則とOpenGLの命名規則は違うことに注意して下さい。 GL_RGBA8形式が、単に色成分の並びや、エンディアンの扱いを含めた正確な配置を定義しているかは、別々に指定されます。通常OpenGLの、GL_RGBA8 は、リトルエンディアンシステム上においては、Allegroの ALLEGRO_PIXEL_ABGR_8888に対応するので、扱いには注意が必要しょう。 ( RGBA と ABGR が反転していることに注意).
ALLEGRO_PIXEL_FORMAT_ABGR_8888_LEは、 ABGR_8888とは違い、各色成分の並び順は、RGBA になっています。これは、ビッグエンディアン環境のシステム上でのみ効果がある指定で、リトルエンディアン環境ではただのエイリアスとしてしか働きません。

* ALLEGRO_PIXEL_FORMAT_ANY - グラフィックドライバに形式を選択させます。これはプログラム開始時のデフォルトです。
* ALLEGRO_PIXEL_FORMAT_ANY_NO_ALPHA - アルファ(透明)の設定を除いて、グラフィックドライバに形式を選択させます。
* ALLEGRO_PIXEL_FORMAT_ANY_WITH_ALPHA - アルファ(透明)の設定を含めて、グラフィックドライバに形式を選択させます。
* ALLEGRO_PIXEL_FORMAT_ANY_15_NO_ALPHA - 15bit形式、アルファなしで、(上に同じ〃)

* ALLEGRO_PIXEL_FORMAT_ANY_16_NO_ALPHA - 16bit形式、アルファなしで、(上に同じ〃)
* ALLEGRO_PIXEL_FORMAT_ANY_16_WITH_ALPHA - 16bit形式、アルファ含めて、(上に同じ〃)
* ALLEGRO_PIXEL_FORMAT_ANY_24_NO_ALPHA -24bit形式、アルファなしで、(上に同じ〃)

* ALLEGRO_PIXEL_FORMAT_ANY_32_NO_ALPHA - 32bit形式、アルファなしで、(上に同じ〃)
* ALLEGRO_PIXEL_FORMAT_ANY_32_WITH_ALPHA - 32bit形式、アルファ含めて、(上に同じ〃)
* ALLEGRO_PIXEL_FORMAT_ARGB_8888 - 32 bit
* ALLEGRO_PIXEL_FORMAT_RGBA_8888 - 32 bit
* ALLEGRO_PIXEL_FORMAT_ARGB_4444 - 16 bit
* ALLEGRO_PIXEL_FORMAT_RGB_888 - 24 bit
* ALLEGRO_PIXEL_FORMAT_RGB_565 - 16 bit
* ALLEGRO_PIXEL_FORMAT_RGB_555 - 15 bit
* ALLEGRO_PIXEL_FORMAT_RGBA_5551 - 16 bit
* ALLEGRO_PIXEL_FORMAT_ARGB_1555 - 16 bit
* ALLEGRO_PIXEL_FORMAT_ABGR_8888 - 32 bit
* ALLEGRO_PIXEL_FORMAT_XBGR_8888 - 32 bit
* ALLEGRO_PIXEL_FORMAT_BGR_888 - 24 bit
* ALLEGRO_PIXEL_FORMAT_BGR_565 - 16 bit
* ALLEGRO_PIXEL_FORMAT_BGR_555 - 15 bit
* ALLEGRO_PIXEL_FORMAT_RGBX_8888 - 32 bit
* ALLEGRO_PIXEL_FORMAT_XRGB_8888 - 32 bit
* ALLEGRO_PIXEL_FORMAT_ABGR_F32 - 128 bit
* ALLEGRO_PIXEL_FORMAT_ABGR_8888_LE

Bitmap creation

ALLEGRO_BITMAP typedef struct ALLEGRO_BITMAP ALLEGRO_BITMAP;

ビットマップ(2Dイメージ)を表している、データの抽象タイプ。

al_clone_bitmap ALLEGRO_BITMAP *al_clone_bitmap(ALLEGRO_BITMAP *bitmap)

ビットマップオブジェクトの正確なコピーを作ります。格納形式は違う場合もあります。

al_create_bitmap ALLEGRO_BITMAP *al_create_bitmap(int w, int h)

現在設定されているフラグとピクセルデータ格納形式で、新規ビットマップを作成します。異なるピクセルデータ格納形式で、ビットマップ同士またはメモリ上/画面表示ビットマップ間のblitting処理をすると、重くなる可能性があります。

もし、ALLEGRO_MEMORY_BITMAPフラグを設定しない場合、この関数は、現在表示されている画面上にビットマップオブジェクトを作成します。メモリ上で計算する方法よりも、別の画面にBlittingする処理は遅いかもしれません。

画面上に表示されるタイプのビットマップを作成した場合、その寸法には制限が生じる可能性があります。例えば、DirectXまたはOpenGLのバックエンドはたいてい利用可能なテクスチャサイズの最大寸法が決められています。

そのため、巨大な寸法のビットマップを作ろうとして失敗し、より小さなビットマップを作らなければいけないかもしれません。 See Also: al_set_new_bitmap_format, al_set_new_bitmap_flags

al_create_sub_bitmap

ALLEGRO_BITMAP *al_create_sub_bitmap(ALLEGRO_BITMAP *parent,
   int x, int y, int w, int h)

親ビットマップの任意の座標を起点に指定したサイズの領域を、サブビットマップを作成します。これは、親ビットマップの描画領域と共有しており、親ビットマップの該当領域が変われば、サブビットマップにもそれが反映されるようになります。

もし、サブビットマップが親ビットマップの内部に完全に収まらないなら、自動的に切り取られます。また親ビットマップのクリップ領域は無視されます。この関数は、サブビットマップが無かったり、作成することが出来ない場合は NULLを返します。

※親ビットマップを破棄しても、サブビットマップは破棄されないことに注意して下さい。このサブビットマップは破棄されませんが無効になり、もう使用されるべきではありません。

al_destroy_bitmap void al_destroy_bitmap(ALLEGRO_BITMAP *bitmap)

指定したビットマップオブジェクトを破棄します。使われてた全てのリソースが解放されます。何もさせたくなければ、NULLポインタを指定します。

al_get_new_bitmap_flags int al_get_new_bitmap_flags(void)

新規作成したビットマップに使用されているフラグを返します。

al_get_new_bitmap_format int al_get_new_bitmap_format(void)

新規作成されたビットマップのピクセル格納形式を返します。

al_set_new_bitmap_flags void al_set_new_bitmap_flags(int flags)

新規ビットマップに、フラグを設定します。有効なフラグは以下の通り：

    * ALLEGRO_MEMORY_BITMAP - 
	ビットマップファイルまたは、al_create_memory_bitmap関数で作成したビットマップ形式を適用します。 
	このフラグが特に指定されなくてもドライバがフォーマットを決め、al_create_bitmap関数が代わりに利用します。
	XXX al_create_memory_bitmap doesn't exist any more

*ALLEGRO_KEEP_BITMAP_FORMAT - 
	画像ファイルを読み込む場合のみ使われます。
	その結果、同種の画像形式を持つファイルに対して
	ALLEGRO_BITMAP フラグが強制的に適用されます。
	
*ALLEGRO_FORCE_LOCKING - 
	ビットマップに、このフラグがセットしてある場合、常に画像データはロックされ、
	Allegroのプリミティブ描画ルーチンを使用して描画します。
	これは厳しい動作要求に対しては使用されるべきではありませんが、デバッグ時に役立つ場合があります。
	しかしながら、ビットマップが、ロック処理だけのためにアクセスされるだけであると分かっているなら、
	不必要なFBOが OpenGLドライバーによって作成されないでしょう。

*ALLEGRO_NO_PRESERVE_TEXTURE - 
	通常システムは、グラフィックドライバがビットマップデータ上の内容を紛失しないよう、
	データ保全に対策にあらゆる努力がなされます。しかし、これらの処理は少なからず
	遅延時間を生み出してしまうかもしれません。もしも、一時的なバッファのように、
	ビットマップ上のデータがさしも重要ではない場合、このフラグをAllegroに伝えることで、
	Allegroはこのフラグ指定後に作成されたビットマップデータ上のデータ保全をしないように設定します。
	これによって、プログラムの速度向上を図る事ができます。
	
*ALLEGRO_ALPHA_TEST - 
	このフラグは、ドライバヒントのみ行います。このフラグを付けて作成したビットマップにおいては、
	アルファブレンディング(alpha blending)の代わりに、アルファテスティング(alpha testing)を
	ドライバに行わせます。アルファテスティングは通常より高速で、
	もしもビットマップのアルファ値(0)レベルの値があるなら優先的に判別します。
	(アルファテストとは、任意のアルファ値をしきい値として、それを描画するかどうかを決定することです)。

	※このフラグは今のところ広く実装されていません(例えばメモリビットマップのみ)


	
This is a driver hint only. It tells the graphics driver to do alpha testing instead of alpha blending on bitmaps created with this flag.
Alpha testing is usually faster and preferred if your bitmaps have only one level of alpha (0). 
This flag is currently not widely implemented (i.e., only for memory bitmaps).

al_set_new_bitmap_format void al_set_new_bitmap_format(int format)

新規作成したビットマップに、ピクセル格納形式を設定します。これはal_set_new_display_format関数で使う変数と同じ形式です。デフォルトでは0: ディスプレイドライバは自分で最適の形式を選択する。に設定されています。

Bitmap properties

al_get_bitmap_flags int al_get_bitmap_flags(ALLEGRO_BITMAP *bitmap)

ユーザーが作成したビットマップのフラグを取得する。

al_get_bitmap_format int al_get_bitmap_format(ALLEGRO_BITMAP *bitmap)

指定したビットマップのピクセル格納形式を調べる。

al_get_bitmap_height int al_get_bitmap_height(ALLEGRO_BITMAP *bitmap)

指定したビットマップの高さ(ピクセル)を得る。

al_get_bitmap_width int al_get_bitmap_width(ALLEGRO_BITMAP *bitmap)

指定したビットマップの横幅(ピクセル)を得る

al_get_pixel ALLEGRO_COLOR al_get_pixel(ALLEGRO_BITMAP *bitmap, int x, int y)

指定したビットマップの座標(x,y)にある色の値を取得します。

al_get_target_bitmap ALLEGRO_BITMAP *al_get_target_bitmap(void)

現在描画ターゲットになっているビットマップを返します。

al_is_bitmap_locked bool al_is_bitmap_locked(ALLEGRO_BITMAP *bitmap)

ビットマップが既にロックされているかを返します。

al_is_compatible_bitmap bool al_is_compatible_bitmap(ALLEGRO_BITMAP *bitmap)

Direct3D と OpenGLでは、複数ウインドウにおいて同じテクスチャ画像を共有させて表示させることができます。残念ながら一般に、al_create_bitmap関数によって作成されたALLEGRO_BITMAP オブジェクトは単一の ALLEGRO_DISPLAY として関連づけられています。
この関数は、ビットマップが別のウインドウの画面にあっても、現在のウインドウの画面と互換性をもったビットマップかどうかを調べるのに使います。
指定したビットマップが互換性がある(compatible : キャッシュされたテクスチャが使われる )ならtrue、そうでなければfalseを返します(その場合は、描画処理が遅くなるでしょう)。
この関数が役立つ時は、あなたが複数ウインドウで動くアプリケーションを作っていて、同じビットマップを双方のウインドウに高速に描画する必要がある場合です。

al_is_sub_bitmap bool al_is_sub_bitmap(ALLEGRO_BITMAP *bitmap)

指定したビットマップがサブビットマップならtrueを、そうでなければfalseを返す。

Drawing operations

al_clear_to_color void al_clear_to_color(ALLEGRO_COLOR color)

画面全体を色で塗りつぶす。ただしクリップされた矩形領域にのみ限定される。

al_draw_bitmap void al_draw_bitmap(ALLEGRO_BITMAP *bitmap, float dx, float dy, int flags)

指定したビットマップを、ターゲットとなるビットマップ上の、dx, dy の位置にそのまま描画します。(拡大縮小、回転などのエフェクトは、かけません) どのビットマップの上に描画するかはal_set_target_bitmap関数の説明を見て下さい。

オプションとして、引数 flags にフラグの組合せを与えることができます。:
  ALLEGRO_FLIP_HORIZONTAL - y軸方向にビットマップを反転させます。 
ALLEGRO_FLIP_VERTICAL - x軸方向にビットマップを反転させます。

al_draw_bitmap_region

void al_draw_bitmap_region(ALLEGRO_BITMAP *bitmap, float sx, float sy,
    float sw, float sh, float dx, float dy, int flags)

出力元のビットマップの任意の領域(sx,sy)-(sx+sw, sy+sh)を、ターゲットとなるビットマップの(dx,dy)に描画する。

    * sx - 出力元(source)のx座標
    * sy - 出力元(source)のy座標
    * sw - 領域の横寸法 (width of region to blit)
    * sh - 領域の縦寸法 (height of region to blit)
    * dx - ターゲット(出力先)ビットマップのx座標( destination x)
    * dy - ターゲット(出力先)ビットマップのy座標( destination y)
    * flags -   al_draw_bitmap関数と同じオプション

al_draw_pixel void al_draw_pixel(float x, float y, ALLEGRO_COLOR color)

座標(x, y)に、ドットを1つ打ちます。この関数は、al_put_pixel 関数とは違い、色の混合(blending)をすることが出来ます。

    * x - 出力先の座標(destination x)
    * y - 出力先の座標(destination y)
    * color - ピクセルの色

al_draw_rotated_bitmap

void al_draw_rotated_bitmap(ALLEGRO_BITMAP *bitmap, float cx, float cy,
    float dx, float dy, float angle, int flags)

現在描画ターゲットとなっているビットマップを回転させます。ビットマップは、引数 angle にラジアンを設定することで、時計回りに回転します。ビットマップ内の点cx/cyは、dx/dyへ描画され、ビットマップは点の周りで回転します。

    * cx - center x
    * cy - center y
    * dx - destination x
    * dy - destination y
    * angle - 回転角度
    * flags - al_draw_bitmap関数と同じオプション

al_draw_rotated_scaled_bitmap

void al_draw_rotated_scaled_bitmap(ALLEGRO_BITMAP *bitmap, float cx, float cy,
    float dx, float dy, float xscale, float yscale, float angle,
    int flags)

al_draw_rotated_bitmap関数と似ていますが、この関数は、回転しながら拡大縮小もできます。ビットマップ内の点cx/cyは、dx/dyへ描画され、ビットマップは点の周りで回転します。

    * cx - center x
    * cy - center y
    * dx - destination x
    * dy - destination y
    * xscale - x軸に対してどのくらい拡大縮小させるか (例えば 2 の場合２倍の大きさに拡大する)
    * yscale - y軸に対してどのくらい拡大縮小させるか
    * angle - 回転角度 
    * flags - al_draw_bitmap関数と同じオプション

al_draw_scaled_bitmap

void al_draw_scaled_bitmap(ALLEGRO_BITMAP *bitmap, float sx, float sy,
    float sw, float sh, float dx, float dy, float dw, float dh, int flags)

現在描画ターゲットとなっているビットマップへ、任意の寸法(dw,dh)に拡大縮小したビットマップを描画します。

    * sx - source x
    * sy - source y
    * sw - source width
    * sh - source height
    * dx - 出力先の座標 x
    * dy - 出力先の座標 y
    * dw - 拡大縮小後の横幅
    * dh - 拡大縮小後の縦幅
    * flags - same as for al_draw_bitmap

al_put_pixel void al_put_pixel(int x, int y, ALLEGRO_COLOR color)

描画ターゲットのビットマップに、ドットを打ちます。

al_get_pixel_size int al_get_pixel_size(int format) al_get_pixel_format_bits int al_get_pixel_format_bits(int format) al_lock_bitmap

ALLEGRO_LOCKED_REGION *al_lock_bitmap(ALLEGRO_BITMAP *bitmap, int format, int flags)

読み書きするためにビットマップ全体(entire)をロックします。もしビットマップが、表示型ビットマップの場合、ビットマップのロック解除後にシステムメモリから更新されます(読み取り専用にロックされた場合を除いて)。 locked_region must は、既に割り当てられたALLEGRO_LOCKED_REGION 構造体を指定すべきです。ビットマップをロック出来ない場合はNULLを返します。例えばビットマップが直前にロックされており、ロック解除されなかった場合です。

オプションフラグ:
    *ALLEGRO_LOCK_READONLY - ロックした領域は書込みしないでしょう。これはビットマップがビデオテクスチャであるなら、
	ビデオカードにデータをアップロードする代わりに、ロック後に破棄することで、高速に動作する場合があります。

    *ALLEGRO_LOCK_WRITEONLY - ロックした領域は読込みされないでしょう。 これはビットマップがビデオテクスチャであるなら、
	ビデオカードから読む必要なないデータがある場合、より高速に動作する場合があります。ビットマップを再びロック解除するまえに、
	全部ピクセルデータを処理する必要があるので、このフラグの使用には、十分注意してください。
	
	* ALLEGRO_LOCK_READWRITE -  領域に対する読み書き両方をロックします。

引数 'format'はバッファに返すデータのピクセル形式を指定します。それは、内部的ビットマップに格納されたデータと同じ形式でロックするためには、al_get_bitmap_format(bitmap)関数を ALLEGRO_PIXEL_FORMAT フラグを使用して呼び出してください。　通常、ネイティブ形式でのロックは、より高速でしょう。

Note:
ビットマップがロックされている間は、それに対していかなる描画処理も行うことができません。(例外は al_put_pixel関数とal_draw_pixel 関数です)。

al_lock_bitmap_region

ALLEGRO_LOCKED_REGION *al_lock_bitmap_region(ALLEGRO_BITMAP *bitmap,
    int x, int y,
    int width, int height,
    ALLEGRO_LOCKED_REGION *locked_region,
    int flags)

al_lock_bitmap関数と似ていますが、これはビットマップの特定のエリアのみをロックします。もし画面表示型ビットマップの場合、ロック解除した時にテクスチャのその領域だけが描画が更新されます。あなたが設定する領域だけをロックして描画を更新するのは、ビットマップ全体をロックする方法より高速でしょう。 See Also: al_lock_bitmap

Blending mode

al_get_blender

void al_get_blender(int *op, int *src, int *dst, ALLEGRO_COLOR *color)

現在有効になっているブレンダー(混色処理機能)を調べます。興味がなければ、 NULLを渡すこともできます、

al_get_separate_blender

void al_get_separate_blender(int *op, int *src, int *dst,
   int *alpha_op, int *alpha_src, int *alpha_dst, ALLEGRO_COLOR *color)

現在有効になっているブレンダー(混色処理機能)を返します。興味が無ければ NULLを渡すこともできます。

al_set_blender void al_set_blender(int op, int src, int dst, ALLEGRO_COLOR color)

関数に、混色処理をセットします。混色処理(blending)とは、描画処理の際に入力元(source) と出力先(destination)の色を合成するという意味です。

仮に(assume)、入力元の色(例えば、長方形を描画する時の色、または、ビットマップに描画された色)は、 RGB/Alphaの色成分: sr, sg, sb, saがあるとします。 (※もしビットマップに透明度を司るalpha成分がない場合、その色は不透明です。8bitで255または浮動小数点で1.0)

そして、この色は、すでに存在する、出力先の色: dr, dg, db, da へ塗り重ねられるとします。色がRGB成分(赤,緑,青,透明度)で表される時、既に紙の上に色(dr,dg,db,da)が塗ってあるとして、そこに筆で、別の色(sr,sg,sb,sa)を塗り重ねるとどんな結果になるか？ということです。

ピクセルを描画するための概念的な公式は、op パラメータに指定されたオプションに依存されます。

混色の公式:  Allegroでピクセルを描画する時に使われる公式  
r = dr * dst + sr * src
g = dg * dst + sg * src
b = db * dst + sb * src
a = da * dst + sa * src

Blending 関数: 有効(valid)な値　

	    *ALLEGRO_ADD
       r = dr * dst + sr * src
       g = dg * dst + sg * src
       b = db * dst + sb * src
       a = da * dst + sa * src

    *ALLEGRO_DEST_MINUS_SRC

       r = dr * dst - sr * src
       g = dg * dst - sg * src
       b = db * dst - sb * src
       a = da * dst - sa * src

    * ALLEGRO_SRC_MINUS_DEST  
       r = sr * src - dr * dst
       g = sg * src - dg * dst
       b = sb * src - db * dst
       a = sa * src - da * dst

src パラメータにわたす事ができる有効な値
　
    * ALLEGRO_ZERO
       src = 0
       dst = 0

* ALLEGRO_ONE
       src = 1
       dst = 1

    * ALLEGRO_ALPHA
       src = sa
       dst = sa

    * ALLEGRO_INVERSE_ALPHA
       src = 1 - sa
       dst = 1 - sa

色のパラメータは混合色を指定します。それは上の混合操作をする前に、入力元の色で乗算(multipled)されます。

混色処理の指定の例: 例えば、デフォルト(アルファブレンディング)を使う場合の例(実際はこれだけでは動きません)
al_set_blender(ALLEGRO_ALPHA, ALLEGRO_INVERSE_ALPHA, {1, 1, 1, 1})


半透明にしたい場合は次のように変更します。
al_set_blender(ALLEGRO_ALPHA, ALLEGRO_INVERSE_ALPHA, {1, 1, 1, 0.5})


加法混色を適用するには次のように変更します。
al_set_blender(ALLEGRO_ONE, ALLEGRO_ONE, {1, 1, 1, 1})


 入力先の色を出力先に、(alpha値を含めて)無加工のまま出力する場合
al_set_blender(ALLEGRO_ONE, ALLEGRO_ZERO, {1, 1, 1, 1})

al_set_separate_blender

void al_set_separate_blender(int src, int dst, int alpha_src,
   int alpha_dst, ALLEGRO_COLOR color)

al_set_blender関数に似ていますが、アルファチャンネルを別々の操作で混色を行います。

Clipping

al_get_clipping_rectangle /* XXX this seems like it belongs in bitmap_new.c */ void al_get_clipping_rectangle(int *x, int *y, int *w, int *h)

現在描画ターゲットとなっているビットマップがクリップされている領域を取得します。

/* XXX this seems like it belongs in bitmap_new.c */ void al_set_clipping_rectangle(int x, int y, int width, int height)

描画ターゲットとなるビットマップまたは画面を、切り抜きします。デフォルトではビットマップ全体を切り抜きします。

al_put_blended_pixel

void al_put_blended_pixel(int x, int y, ALLEGRO_COLOR color)

al_put_pixel関数に似ていますが、描画されるピクセルは、現在の混色(blend)設定に基づいて描画されます。

al_set_target_bitmap void al_set_target_bitmap(ALLEGRO_BITMAP *bitmap)

指定したビットマップを描画対象にします。以降描画ルーチンはこのビットマップに対して、プリミティブ図形や画像のblittingを行います。
描画対象を通常スクリーンに戻したい場合にはバックバッファ(al_get_backbuffer参照)を選択してください。
OpenGL に関する事項:
フレームバッファオブジェクト (FBOs) の使用を許可するとOpenGLは直接ビットマップに描画することができます(とても高速です)。しかしながら、それぞれ作成されたFBOは、追加リソースを必要とします。従ってFBOが(テクスチャと共に)作成された時に、それが自動的にそれぞれの非メモリビットマップに割り当てられません。

Framebuffer objects (FBOs) allow OpenGL to directly draw to a bitmap, which is very fast. However, each created FBO needs additional resources, therefore an FBO is not automatically assigned to each non-memory bitmap when it is created (as is done with textures).

OpenGL 表示を使用するとき、FBOは以下の条件がすべてそろった場合のみビットマップに作成されるでしょう。

*GL_EXT_framebuffer_object OpenGL 拡張機能が利用可能である
*メモリビットマップではないビットマップを使用。　
*現時点でビットマップはロックされてないこと。

一度 FBOが作成されると、関連づけられたビットマップが破棄されるか、明示的(explicitely) にal_remove_opengl_fbo関数を呼び出さない限り、FBOは保持されます。

以下の例では、FBOは全く作成されないでしょう:

lock = al_lock_bitmap(bitmap);
al_set_target_bitmap(bitmap);
al_put_pixel(x, y, color);
al_unlock_bitmap(bitmap);

上の例は、FBOは作成されず、al_put_pixel関数が、ロックされたビットマップ上で使用を許可されました。
しかしながら、次の例では、FBOは作成されます:

al_set_target_bitmap(bitmap);
al_draw_line(x1, y1, x2, y2, color);

And an OpenGL command will be used to directly draw the line into the bitmap's associated texture. そして、OpenGLコマンドは、直接ビットマップの関連づけられたテクスチャに線を描画するのに使用されるでしょう。

al_unlock_bitmap void al_unlock_bitmap(ALLEGRO_BITMAP *bitmap)

直前にロックしたビットマップやその領域のロックを解除します。画面表示型のビットマップの場合、テクスチャはシステムメモリーから更新されるでしょう。（読込み専用にロックされている場合はなにもしない）

Graphics utility functions

al_convert_mask_to_alpha void al_convert_mask_to_alpha(ALLEGRO_BITMAP *bitmap, ALLEGRO_COLOR mask_color)

指定したマスクカラー(mask_color)をビットマップのアルファチャンネルに変換します。これを使えば、古い Allegro4.2時代で使っていた、ビットマップ上の魔法のピンク色RGB(255,255,0) 領域をアルファチャンネル化することができます。

Ａudio addon

メモ
ここでいう「サンプル(SAMPLE)」とは、実際の音楽から採取してデジタルデータとして使えるように標本化した音データの事です。

●用語の整理：ビット深度、サンプリング周波数、チャンネル設定について。
※サンプリングの品質は、録音時に値を高品質に設定するのは効果はあります。しかし元のデータが良くないのに再生時に値を高品質に設定しても音が良くなるとは限りません。

/	音声データ	画像データ(比較参考用)
データの表現幅	bit depth -ビット深度 CD:16bit, DVD:24bit 標本(サンプル)データの音の表現幅	色深度 (8bit:256色,12bit:4096色, 15bit:32768色, 16bit: 65536色, 24bit:1677万色 )
品質	Frequency -サンプリング周波数(Hz) (サンプリングレート) 電話:8kHz , CD-DA: 44.1kHz, DVD: 48,96 kHz 音声の波形をデジタル化する時に標本(サンプル)を採取する頻度。この値が高いほど、人の耳に聞こえない高音まで録音される。人間の耳の可聴域は20Hz〜20kHz。	画像解像度モニタ:72,96dpi,印刷物:350dpi,ネガ/ポジ:1200dpi 画像をスキャナなどでデジタル化する時に設定する、正方形1インチ当たりの領域に分布するピクセル数。この値が多ければ、人間の目で見ても画像のドットの粗は分からなくなる。
チャンネル	Cannel -チャンネル(音を流す場所の数) モノラル :1 , ステレオ:2 , サラウンド: 5.1 ステレオは左右から音が聞こえる。	カラーチャンネル(色版の数) モノクロ:1, ダブルトーン:(1〜4) ,RGB:3, CMYK:4 αチャンネル(半透明度/合成用) アルファチャンネルは、既存のチャンネルに追加して使用される、専用域のチャンネル
様々な補正	Gain-ゲイン: 音量増幅補正 Pan - パン: 左右の音量バランスの調整	ガンマ補正、データの入力とモニタ出力が自然な色になるように調整すること。他には、ゲイン補正もあるらしい。

チャンネルは出力データの伝送路。チャンネルが重なり合うことで、音声データは音を空間的に表現し、画像データは様々な色を表現することができます。　

●どんな時にミキサー(Mixer)が必要になりますか？
再生するサンプルデータに対して、再生スピードの変更やgain補正、panの調整を行ないたい場合にミキサーが役立ちます。sampleとvoiceオブジェクトの間に挟むようにミキサーをアタッチして下さい。

ALLEGRO_AUDIO_DEPTH enum ALLEGRO_AUDIO_DEPTH {

サンプリングの、ビット深度とタイプの増減を表します
 Mixersは、の32bit符号あり浮動小数点(float)形式で(-1〜+1)までの範囲を使うことができます。
符号なしの値は、深度値にビットフラグが適用されます。
    * ALLEGRO_AUDIO_DEPTH_INT8
    * ALLEGRO_AUDIO_DEPTH_INT16
    * ALLEGRO_AUDIO_DEPTH_INT24
    * ALLEGRO_AUDIO_DEPTH_FLOAT32
    * ALLEGRO_AUDIO_DEPTH_UNSIGNED

For convenience:

    * ALLEGRO_AUDIO_DEPTH_UINT8
    * ALLEGRO_AUDIO_DEPTH_UINT16
    * ALLEGRO_AUDIO_DEPTH_UINT24

ALLEGRO_AUDIO_DRIVER_ENUM enum ALLEGRO_AUDIO_DRIVER_ENUM {

どのサウンドドライバを使うかを指定します。OSによって使えないドライバもあるので、 
可能であれば常にALLEGRO_AUDIO_DRIVER_AUTODETECT (ドライバを自動的に調べる)
の指定を使うことをお勧めします。

    * ALLEGRO_AUDIO_DRIVER_AUTODETECT
    * ALLEGRO_AUDIO_DRIVER_OPENAL
    * ALLEGRO_AUDIO_DRIVER_ALSA
    * ALLEGRO_AUDIO_DRIVER_DSOUND
    * ALLEGRO_AUDIO_DRIVER_OSS

ALLEGRO_AUDIO_PAN_NONE #define ALLEGRO_AUDIO_PAN_NONE (-1000.0f)

ALLEGRO_AUDIOPROP_PANプロパティのための特別な値。この値を指定すると、オリジナルの音源にあるパンニング(Panning)効果を無効にしてsampleを再生します。パンニングは左右どちらから音が聞こえるかの設定設定です(ステレオの場合)

ALLEGRO_AUDIO_PROPERTY enum ALLEGRO_AUDIO_PROPERTY {

al_*_get_* and al_*_set_* 関数に渡す様々なフラグ。全てのタイプが全ての関数に適応するとは限らない。

    * ALLEGRO_AUDIOPROP_DEPTH
    * ALLEGRO_AUDIOPROP_CHANNELS
    * ALLEGRO_AUDIOPROP_FREQUENCY
    * ALLEGRO_AUDIOPROP_PLAYING
    * ALLEGRO_AUDIOPROP_ATTACHED
    * ALLEGRO_AUDIOPROP_LENGTH
    * ALLEGRO_AUDIOPROP_BUFFER
    * ALLEGRO_AUDIOPROP_LOOPMODE
    * ALLEGRO_AUDIOPROP_SPEED
    * ALLEGRO_AUDIOPROP_POSITION
    * ALLEGRO_AUDIOPROP_GAIN
    * ALLEGRO_AUDIOPROP_PAN
    * ALLEGRO_AUDIOPROP_FRAGMENTS
    * ALLEGRO_AUDIOPROP_USED_FRAGMENTS
    * ALLEGRO_AUDIOPROP_QUALITY
    * ALLEGRO_AUDIOPROP_TIME

ALLEGRO_CHANNEL_CONF enum ALLEGRO_CHANNEL_CONF {

Speaker configuration (mono, stereo, 2.1, 3, etc).

    * ALLEGRO_CHANNEL_CONF_1
    * ALLEGRO_CHANNEL_CONF_2
    * ALLEGRO_CHANNEL_CONF_3
    * ALLEGRO_CHANNEL_CONF_4
    * ALLEGRO_CHANNEL_CONF_5_1
    * ALLEGRO_CHANNEL_CONF_6_1
    * ALLEGRO_CHANNEL_CONF_7_1

ALLEGRO_MIXER typedef struct ALLEGRO_MIXER ALLEGRO_MIXER;

ミキサーは、ストリームデータを受け取り、シングルバッファの中へ混ぜて一緒にする、streamの一種です。 (A mixer is a type of stream which mixes together attached streams into a single buffer.)

ALLEGRO_MIXER_QUALITY enum ALLEGRO_MIXER_QUALITY {

    * ALLEGRO_MIXER_QUALITY_POINT
    * ALLEGRO_MIXER_QUALITY_LINEAR

ALLEGRO_PLAYMODE enum ALLEGRO_PLAYMODE {

サンプル(音データ) とストリーム() のループモード

    * ALLEGRO_PLAYMODE_ONCE
    * ALLEGRO_PLAYMODE_LOOP
    * ALLEGRO_PLAYMODE_BIDIR

ALLEGRO_SAMPLE

ここでいう「SAMPLE」とは、実際の音楽から採取してデジタルデータとして使えるように標本化した音データです。

ALLEGRO_SAMPLE_ID typedef struct {

ALLEGRO_SAMPLE_ID構造体は、 al_play_sample関数によって再生するsample を表します。
後で、そのsampleの再生を停止したければ、al_stop_sample関数を使うことができます。

ALLEGRO_SAMPLE typedef struct ALLEGRO_SAMPLE ALLEGRO_SAMPLE;

ALLEGRO_SAMPLEオブジェクトは、あらかじめ定義されたデジタルオーディオのために必要なデータを格納します。
これは再生位置、ループの開始/終了地点、ループモードに関連する(pertaining)情報などを保持しています。
ALLEGRO_SAMPLE は、複数のsampleを同時に再生することができます。

オブジェクトは、ユーザー指定のPCMデータ・バッファを保持し、そのフォーマットはオブジェクトが作成される際のものです。

ALLEGRO_SAMPLE_INSTANCE typedef struct ALLEGRO_SAMPLE_INSTANCE ALLEGRO_SAMPLE_INSTANCE;

ALLEGRO_SAMPLE_INSTANCEオブジェクトはあらかじめ定義されたサウンド効果を再生できるインスタンスを表します。このデータは、ループの有無、ループの開始/終了位置、再生地点等の関連情報を格納します。

ALLEGRO_SAMPLEオブジェクトからのデータを使うインスタンス(分身)なので、複数のインスタンスが同じALLEGRO_SAMPLEから作成されることもあります。インスタンスが存在している間は、その参照元であるALLEGRO_SAMPLEを破壊してはいけません。

　再生するには、ALLEGRO_SAMPLE_INSTANCE オブジェクトを、

ALLEGRO_VOICE オブジェクト　
ALLEGRO_VOICE オブジェクトにアタッチする、　　ALLEGRO_MIXERオブジェクト　
ALLEGRO_VOICE オブジェクトにアタッチする、別のALLEGRO_MIXERオブジェクト

いずれかに取り付ける(アタッチする)必要があります。

( To be played, an ALLEGRO_SAMPLE_INSTANCE object must be attached to an ALLEGRO_VOICE object, or to an ALLEGRO_MIXER object which is itself attached to an ALLEGRO_VOICE object (or to another ALLEGRO_MIXER object which is attached to an ALLEGRO_VOICE object, etc))
An ALLEGRO_SAMPLE_INSTANCE object uses the following fields:

XXX much of this will probably change soon

　
*ALLEGRO_AUDIOPROP_DEPTH (enum)
- オブジェクト作成時のビット深度を得ます。この値はオブジェクト作成後には変更できないかもしれません。　
*ALLEGRO_AUDIOPROP_CHANNELS (enum)
-オブジェクト作成時のチャンネル設定を得ます。この値はオブジェクト作成後には変更できないかもしれません。　
*ALLEGRO_AUDIOPROP_FREQUENCY (long)
- オブジェクト作成時の周波数(Hz)を得ます。この値はオブジェクト作成後には変更できないかもしれません。再生スピードをかえたい場合には ALLEGRO_AUDIOPROP_SPEEDの項目を参照ください。
*ALLEGRO_AUDIOPROP_PLAYING (bool)
- オブジェクトの再生状態を取得/設定することができます。デフォルトでは「停止」状態です。これはオブジェクト自身を単に設定するだけで実際に再生するわけではないことに注意してください。実際にインスタンスを再生する場合は、インスタンスをVoice オブジェクトに直接的・間接的にアタッチしなければいけません。(アタッチの例. sample->voice, sample->mixer->voice, sample->mixer->...->voice).
*ALLEGRO_AUDIOPROP_ATTACHED (bool)
- オブジェクトのアタッチ状態を取得します (インスタンスが何らかのオブジェクト(MixerやVoice)にアタッチしている場合はtrueを返す。そうでなければ false を返す。). この設定に falseを指定すると既になにかアタッチされている場合それが取り外されます。これに直接true に設定することはできません。　
*ALLEGRO_AUDIOPROP_LENGTH (long)
- オブジェクトのチャンネル毎におけるサンプルのデータバッファの状態を取得/設定することができます。もしデータの長さが変更されるとき、あなたは確実に現在のバッファが十分な大きさになるようにしなければいけません。オブジェクトが再生状態である間は、バッファの大きさを変更することはできません。
*ALLEGRO_AUDIOPROP_BUFFER (ptr)
- オブジェクトのデータバッファの状態を取得/設定することができます。オブジェクトが再生状態である間は、この情報の取得/設定はできません。
*ALLEGRO_AUDIOPROP_LOOPMODE (enum)
- オブジェクトのループ再生状態を取得/設定することができます。しかしオブジェクトがVoiceオブジェクトにアタッチしている場合はこの設定変更は失敗するかもしれません。そしてオーディオドライバはループモードの要求をサポートしません。
*ALLEGRO_AUDIOPROP_SPEED (float)
-オブジェクトの再生スピードに関する情報を取得/設定することができます。マイナス値は、逆再生を意味します。もし値が0に限りなく近ければ設定は失敗します。　
*ALLEGRO_AUDIOPROP_POSITION (long)
- オブジェクトの再生位置を取得/設定することができます。この値はチャンネル毎のサンプルになります。
*ALLEGRO_AUDIOPROP_GAIN (float)
-オブジェクトのゲイン情報を取得/設定することができます。ゲイン効果は親Mixerオブジェクトへミキシングを行う時だけ有効です。直接Voiceオブジェクトへアタッチした場合は何の効果もありません。
*ALLEGRO_AUDIOPROP_PAN (float)
-オブジェクトのパン情報を取得/設定することができます。 (-1.0 〜 1.0 = 左〜右). パン効果は親Mixerオブジェクトへミキシングを行う時だけ有効です。直接Voiceオブジェクトへアタッチした場合は何の効果もありません。
　
　音が中央で揺らぐとき、一定の音響出力レベルを維持するために、両方の前部スピーカーから等しく出力されますが、音量レベルは3dB(オリジナルの約0.707 )減少します。オリジナルと同じ音量レベルで音を中央に集中して再生したい場合は、ALLEGRO_AUDIOPROP_PAN プロパティを ALLEGRO_AUDIO_PAN_NONE にします。

ALLEGRO_AUDIO_STREAM

typedef struct ALLEGRO_AUDIO_STREAM ALLEGRO_AUDIO_STREAM;

ALLEGRO_AUDIO_STREAMオブジェクトは、生成された音源をリアルタイムにサウンドデバイスへ流すことに使われます。 ALLEGRO_SAMPLE_INSTANCE オブジェクトのように、それらの再生のための必要情報を格納するので、何回も同時に再生することはできません。( As with ALLEGRO_SAMPLE_INSTANCE objects, they store information necessary for playback, so you may not play one multiple times simultaneously. )

また、それらは直接ALLEGRO_VOICE オブジェクトにアタッチするか、最終的にALLEGRO_VOICEオブジェクトへ接続される ALLEGRO_MIXERオブジェクトにアタッチする必要があります。

再生している間、あなたはALLEGRO_AUDIOPROP_USED_FRAGMENTSをチェックして、次に、ALLEGRO_AUDIOPROP_BUFFERを通してバッファを詰め替えながら、定期的に新しいデータをバッファに提供しなければいけません。あなたが新しいデータの提供に遅れてしまえば、新しいデータが提供されるまで、オブジェクトは沈黙します。

ストリームを供給し終わったなら、必ず al_drain_stream()関数を呼んで後始末をして下さい。

もしストリームが al_load_audio_stream関数によって生成され、ループ設定が未指定でファイルの末端まで達したなら、　それはまたALLEGRO_EVENT_AUDIO_STREAM_FINISHEDイベントを発生させることができます。

ALLEGRO_AUDIO_STREAM オブジェクトは次のデータをもっています。:

ALLEGRO_AUDIOPROP_DEPTH (enum) - Same as ALLEGRO_SAMPLE
ALLEGRO_AUDIOPROP_CHANNELS (enum) - Same as ALLEGRO_SAMPLE
ALLEGRO_AUDIOPROP_FREQUENCY (enum) - Same as ALLEGRO_SAMPLE
ALLEGRO_AUDIOPROP_ATTACHED (bool) - Same as ALLEGRO_SAMPLE
ALLEGRO_AUDIOPROP_PLAYING (bool) - Same as ALLEGRO_SAMPLE, 
 例外がありALLEGRO_AUDIO_STREAMオブジェクトがデフォルトで「再生」になってます。
ALLEGRO_AUDIOPROP_LOOPMODE (enum) - Same as ALLEGRO_SAMPLE
ALLEGRO_AUDIOPROP_SPEED (float) - Same as ALLEGRO_SAMPLE,  ただし、マイナス値を指定することはできません。 
ALLEGRO_AUDIOPROP_GAIN (float) - Same as ALLEGRO_SAMPLE.

ALLEGRO_AUDIOPROP_LENGTH (long) - 独立したバッファフラグメントの
 1チャンネルあたりの長さを取得します。これはオブジェクト作成後には変更されることはないでしょう。 

ALLEGRO_AUDIOPROP_BUFFER (ptr) -これは、データをためるための、
 次に必要なバッファフラグメントを取得します。バッファが一杯になった後に、
 この値は同時にポインタに、新しいデータの準備ができていることを知らせるポインタをセットします。 

ALLEGRO_AUDIOPROP_FRAGMENTS (long) -　これはオブジェクトが作成された際の
 バッファフラグメントの数を取得します。
 これはオブジェクト作成後には変更されることはないでしょう。 

ALLEGRO_AUDIOPROP_USED_FRAGMENTS (long) - これは、データが最充填され待機している
 バッファフラグメントの数を取得します。 ALLEGRO_AUDIOPROP_BUFFERが
 待機バッファフラグメントを検索する時、この値は減少します。
 あなたはこの値を変更することはできません。

ALLEGRO_VOICE

ALLEGRO_VOICE typedef struct ALLEGRO_VOICE ALLEGRO_VOICE;

mixer か sample データは、voice 構造体へされます。 1つのシステム/ハードウェアvoice につき、1つの ALLEGRO_VOICE 構造体があるのが理想的です。

Setting up

al_install_audio int al_install_audio(ALLEGRO_AUDIO_DRIVER_ENUM mode)

Allegro で音源を扱えるようにする。

Parameters: * mode - see ALLEGRO_AUDIO_DRIVER_ENUM 0が返れば初期化に成功、非0の場合は失敗 XXX the return value seems a bit out of place See also: al_reserve_samples.

al_uninstall_audio void al_uninstall_audio(void)

使い終わったら。破棄

al_is_audio_installed bool al_is_audio_installed(void)

al_install_audio関数の呼び出しに成功している場合、 trueが返る

al_reserve_samples bool al_reserve_samples(int reserve_samples)

蓄積された 'reserve_samples' で指定した数の sample データがデフォルトmixerにアタッチされます。 al_install_audio関数は最初に呼ばれなければいけません。

もし、デフォルトmixerが一つもセットされていなければ、この関数はデフォルトのmixerを使って、voice構造体を作成するでしょう。
成功したらtrueを返し、エラーの場合は falseを返します。

Voice functions

al_create_voice

ALLEGRO_VOICE *al_create_voice(unsigned long freq,
  ALLEGRO_AUDIO_DEPTH depth, ALLEGRO_CHANNEL_CONF chan_conf)

voice構造体を作成し、デジタルサウンドドライバからvoiceを割り当てます。サウンドドライバのallocate_voice関数は、voiceの周波数 freq、ビット深度depth、チャンネル設定chan_conf の引数と現在のvoiceに適用します。もしvoiceに設定を作成出来ない場合は失敗です。そのような場合はミキサーを使ってください。

al_destroy_voice void al_destroy_voice(ALLEGRO_VOICE *voice)

voiceを破棄し、デジタルドライバから割当を解除します。voiceがNULLの場合、何もしません。

al_detach_voice void al_detach_voice(ALLEGRO_VOICE *voice)

voiceからサンプルまたはミキサーストリームを解除します。

al_attach_stream_to_voice

int al_attach_stream_to_voice(ALLEGRO_AUDIO_STREAM *stream,   ALLEGRO_VOICE *voice)

voiceにオーディオストリームをアタッチします。同様のルールがal_attach_sample_to_voice関数にもいえます。これはドライバーがストリームが使用するバッファのカウントとバッファサイズに従ったvoiceを作成することができないなら、失敗するかもしれません。

al_attach_mixer_to_voice int al_attach_mixer_to_voice(ALLEGRO_MIXER *mixer, ALLEGRO_VOICE *voice)

ミキサーをvoiceにアタッチします。これと同じルールはal_attach_sample_to_voice関数でも適用されます。(ビット深度の要求を除く)

al_attach_sample_to_voice

int al_attach_sample_to_voice(ALLEGRO_SAMPLE_INSTANCE *spl,   ALLEGRO_VOICE *voice)

サンプルをvoiceにアタッチして、それを再生することを許可します。サンプルの音量やループモードは無視され、voice同じ周波数とビット深度(including signed-ness)に揃えられます。この関数は選択されたドライバがサンプルデータのプリローディングをサポートしていなければ失敗するでしょう、

al_get_voice_frequency unsigned int al_get_voice_frequency(const ALLEGRO_VOICE *voice)

voice のサンプリング周波数(Hz)を返す。例えば44100

al_get_voice_channels ALLEGRO_CHANNEL_CONF al_get_voice_channels(const ALLEGRO_VOICE *voice)

voice のチャンネル設定を返す。
See also: ALLEGRO_CHANNEL_CONF.

al_get_voice_depth ALLEGRO_AUDIO_DEPTH al_get_voice_depth(const ALLEGRO_VOICE *voice)

voice のビット深度を返す。
See also: ALLEGRO_AUDIO_DEPTH.

al_get_voice_playing bool al_get_voice_playing(const ALLEGRO_VOICE *voice)

voice が現在再生しているならtrueを返す。

al_set_voice_playing bool al_set_voice_playing(ALLEGRO_VOICE *voice, bool val)

voiceが再生を切り替える。対象 voiceには sampleまたはmixerオブジェクトをアタッチしてなければいけません。
成功ならtrue、失敗ならfalseを返す。

al_get_voice_position unsigned long al_get_voice_position(const ALLEGRO_VOICE *voice)

voiceが非ストリーミングオブジェクト(sampleオブジェクトなど)をアタッチしているとき、voice のsampleの再生位置を返します。そうでなければゼロを返します。

al_set_voice_position bool al_set_voice_position(ALLEGRO_VOICE *voice, unsigned long val)

再生位置を設定します。この関数は、voiceに非ストリーミングオブジェクト(sampleオブジェクトなど)をアタッチしているときのみ利用できます。成功ならtrue、失敗ならfalseを返す。

Sample functions

al_create_sample

ALLEGRO_SAMPLE *al_create_sample(void *buf, unsigned long samples,
   unsigned long freq, ALLEGRO_AUDIO_DEPTH depth,
   ALLEGRO_CHANNEL_CONF chan_conf, bool free_buf)

与えられたバッファから、sample構造体を作成します。もし free_buf フラグに trueを指定した場合は、sample 構造体を解放した時に、バッファも破棄させることができます。

al_destroy_sample void al_destroy_sample(ALLEGRO_SAMPLE *spl)

samle 構造体を解放します。もし、それが作成時 free_bufフラグにtrueが指定されている場合はバッファも一緒に破棄します。
あらかじめ、このALLEGRO_SAMPLEに参照付けられた、あらゆるALLEGRO_SAMPLE_INSTANCE構造体も破棄されなければいけません。

al_play_sample

 bool al_play_sample(ALLEGRO_SAMPLE *spl, float gain, float pan, float speed,
   int loop, ALLEGRO_SAMPLE_ID *ret_id)

デフォルトのmixerを通じてsampleを再生します。これには、al_reserve_samples関数を先に呼ばなければいけません。
成功したらtrue 、失敗したらfalseが返る。予約されたsampleが利用されるので、再生は失敗するかもしれません。

al_stop_sample void al_stop_sample(ALLEGRO_SAMPLE_ID *spl_id)

al_play_sampl関数によって再生を開始した、任意の sampleを停止します。

al_stop_samples void al_stop_samples(void)

al_play_sample関数によって再生したすべてのsampleを停止します。

al_create_sample_instance

ALLEGRO_SAMPLE_INSTANCE *al_create_sample_instance(ALLEGRO_SAMPLE *sample_data)

sample stream を作成し、データを提供します。これは再生前に voice またはmixer にアタッチしなければいけません。引数にNULLを指定することができます。その後でal_set_sample関数を使ってデータをセットできます。

al_destroy_sample_instance

void al_destroy_sample_instance(ALLEGRO_SAMPLE_INSTANCE *spl)

あらゆる sample stream からアタッチを取り消し、解放します。(sampleデータは解放されません！)

al_play_sample_instance

int al_play_sample_instance(ALLEGRO_SAMPLE_INSTANCE *spl)

sample データのインスタンスを再生します。成功したらtrue 、失敗したらfalseが返る。.

al_play_stop_instance

bool al_stop_sample_instance(ALLEGRO_SAMPLE_INSTANCE *spl)

sample データの再生を中止します。

al_get_sample_instance_channels

ALLEGRO_CHANNEL_CONF al_get_sample_instance_channels(
   const ALLEGRO_SAMPLE_INSTANCE *spl)

チャンネル設定を返します
See also: ALLEGRO_CHANNEL_CONF.

al_get_sample_instance_depth ALLEGRO_AUDIO_DEPTH al_get_sample_instance_depth(const ALLEGRO_SAMPLE_INSTANCE *spl)

オーディオのbit深度を返します
See also: ALLEGRO_AUDIO_DEPTH.

al_get_sample_instance_frequency unsigned int al_get_sample_instance_frequency(const ALLEGRO_SAMPLE_INSTANCE *spl)

サンプリング周波数を返します

al_get_sample_instance_length unsigned long al_get_sample_instance_length(const ALLEGRO_SAMPLE_INSTANCE *spl)

sample instance の再生時間の長さを返します。

al_set_sample_instance_length bool al_set_sample_instance_length(ALLEGRO_SAMPLE_INSTANCE *spl, unsigned long val)

sample instance の再生時間の長さをセットします。成功したらtrue、失敗ならfalse。再生中のsample instance に、この関数を使うと処理は失敗するでしょう。

al_get_sample_instance_position unsigned long al_get_sample_instance_position(const ALLEGRO_SAMPLE_INSTANCE *spl)

sample instance の再生位置を取得します。

al_set_sample_instance_position bool al_set_sample_instance_position(ALLEGRO_SAMPLE_INSTANCE *spl, unsigned long val)

sample instance の再生を設定します。
成功したらtrue、失敗ならfalse。

al_get_sample_instance_speed float al_get_sample_instance_speed(const ALLEGRO_SAMPLE_INSTANCE *spl)

再生スピードを返します。

al_set_sample_instance_speed bool al_set_sample_instance_speed(ALLEGRO_SAMPLE_INSTANCE *spl, float val)

再生スピードを設定します。
成功したらtrue、失敗ならfalse。もしsample instance にvoiceオブジェクトが(mixerを通さずに)直接アタッチしていた場合、失敗するでしょう。

al_get_sample_instance_gain float al_get_sample_instance_gain(const ALLEGRO_SAMPLE_INSTANCE *spl)

再生時のゲイン設定値を返す。

al_set_sample_instance_gain bool al_set_sample_instance_gain(ALLEGRO_SAMPLE_INSTANCE *spl, float val)

再生時のゲインを設定する。
成功したらtrue、失敗ならfalse。もしsample instance にvoiceオブジェクトが(mixerを通さずに)直接アタッチしていた場合、失敗するでしょう。

al_get_sample_instance_pan float al_get_sample_instance_pan(const ALLEGRO_SAMPLE_INSTANCE *spl)

パン設定を取得する。

al_set_sample_instance_pan bool al_set_sample_instance_pan(ALLEGRO_SAMPLE_INSTANCE *spl, float val)

sample intcetance再生時のパン(Pan)の値を設定します。パンは音の出るバランスを調整します。
引数 val に-1.0 を指定することは、左側のスピーカーからのみ音が出ます。+1.0では右から。そして0.0では両方のスピーカーからバランスよく音が出ます。

Sampleデータが左から右までパンされるとき、一定の音響出力レベルが維持されます。結果として、0.0のパン値は元のレベルより3dB ソフトなSampleを再生するでしょう。オリジナルの出力レベルでパンを無効にしてSample データを再生するには、値に、ALLEGRO_AUDIO_PAN_NONEをセットしてください。

成功したらtrueを返し、失敗時にはfalseを返します。もしsample instance にvoiceオブジェクトが(mixerを通さずに)直接アタッチしていた場合、失敗するでしょう。

↓良くわからない
(直訳：音響に詳しい奴はそれについて、よりよく説明するべきです; 私はそれを実行するだけでした。また、これは適切にパンするより呼ばれたバランスをコントロールであるかもしれません。(また、私たちは2個以上のチャンネルで何もまだ試みていません。) (原文：A sound guy should explain that better; I only implemented it. Also this might be more properly called a balance control than pan. Also we don't attempt anything with more than two channels yet.)

al_get_sample_instance_time float al_get_sample_instance_time(const ALLEGRO_SAMPLE_INSTANCE *spl)

再生スピードを1.0とした時の sample instanceの再生時間を秒で返します。

al_get_sample_instance_playmode ALLEGRO_PLAYMODE al_get_sample_instance_playmode(const ALLEGRO_SAMPLE_INSTANCE *spl)

再生モードを返します。

al_set_sample_instance_playmode bool al_set_sample_instance_playmode(ALLEGRO_SAMPLE_INSTANCE *spl, ALLEGRO_PLAYMODE val)

再生モードを設定します。. 成功したらtrueを返し、失敗時にはfalseを返します。

al_get_sample_instance_playing bool al_get_sample_instance_playing(const ALLEGRO_SAMPLE_INSTANCE *spl)

その sample instanceが再生中ならtrueを返す。

al_set_sample_instance_playing bool al_set_sample_instance_playing(ALLEGRO_SAMPLE_INSTANCE *spl, bool val)

sample instanceの再生を切り替えます。成功したらtrueを返し、失敗時にはfalseを返します。

al_get_sample_instance_attached bool al_get_sample_instance_attached(const ALLEGRO_SAMPLE_INSTANCE *spl)

　 sample instance になんらかのオブジェクトをアタッチします。

al_detach_sample_instance bool al_detach_sample_instance(ALLEGRO_SAMPLE_INSTANCE *spl)

　sample instanceにアタッチしているあらゆるオブジェクトを取り外します。

al_get_sample ALLEGRO_SAMPLE *al_get_sample(ALLEGRO_SAMPLE_INSTANCE *spl)

再生しているsample instanceのデータを返します。

al_set_sample

int al_set_sample(ALLEGRO_SAMPLE_INSTANCE *spl, ALLEGRO_SAMPLE *data)

この関数は、単に再生中のsampleデータを別のものに変更します。
しかし内部では、全くややこしい処理(involved process)をこなします。
最初に、sampeが既に再生中であれば停止します。
次に、データがNULLであれば、親(あれば)からアタッチが解除されます。
データがNULLでなければ、一旦アタッチが解除された後、親(あれば)それに再アタッチします。
これは古いsampleデータと新しいsampleデータが、同じビット深度(depth)、チャンネル設定、サンプリング周波数 (frequency)が同じ場合には必要ありません。
また、再アタッチ処理はいつも成功するとは限りません。

この関数がうまく処理をこなせば、sampleは停止したままになります。また再生地点とループ〜ループ終了地点に関する情報はリセットされてデフォルト状態になります。ループモードは変更されないままになります。

成功すると0を返し、0以外なら失敗です。失敗時には、そのsample再生は停止してその親からアタッチは解除されます。

Mixer functions

al_create_mixer

ALLEGRO_MIXER *al_create_mixer(unsigned long freq,
   ALLEGRO_AUDIO_DEPTH depth, ALLEGRO_CHANNEL_CONF chan_conf)

他のサンプルストリームやミキサーにアタッチするためにミキサーストリームを作成します。これは、要求された周波数とチャンネルのカウントをバッファにいれて合成するでしょう。浮動小数変数を使ったミキシングは現在サポートされています。

al_destroy_mixer void al_destroy_mixer(ALLEGRO_MIXER *mixer)

ミキサーストリームを破棄します。

al_get_default_mixer

ALLEGRO_MIXER *al_get_default_mixer(void)

デフォルトのミキサーを返します。

al_set_default_mixer bool al_set_default_mixer(ALLEGRO_MIXER *mixer)

デフォルトmixerをセットします。この時al_play_sample関数によって再生されているなら、すべてのsampleは停止されるでしょう。もし、あなたが自身のmixerを使っているなら、al_reserve_samples関数を呼ぶ前にこの関数を呼ぶべきです。
成功するとtrueを返し、失敗時にはfalseを返します。

al_restore_default_mixer bool al_restore_default_mixer(void)

Allegroのデフォルトミキサーに戻し(restore)ます。al_play_sample関数によって再生されていた全サンプルデータが停止します。成功するとtrueを返し、失敗時にはfalseを返します。

al_attach_mixer_to_mixer int al_attach_mixer_to_mixer(ALLEGRO_MIXER *stream, ALLEGRO_MIXER *mixer)

ミキサーを別のミキサーにアタッチする。 al_attach_sample_to_mixer apply関数でも同じルールです。両方のミキサーを同時に使用すると警告されます。

al_attach_sample_instance_to_mixer

 bool al_attach_sample_instance_to_mixer(ALLEGRO_SAMPLE_INSTANCE *spl,ALLEGRO_MIXER *mixer)

サンプルインスタンスにミキサーをアタッチします。成功ならtrue、失敗ならfalseが返る。

al_attach_stream_to_mixer int al_attach_stream_to_mixer(ALLEGRO_AUDIO_STREAM *stream, ALLEGRO_MIXER *mixer)

ストリームオブジェクトにミキサーをアタッチします。成功ならtrue、失敗ならfalseが返る。

al_get_mixer_frequency unsigned int al_get_mixer_frequency(const ALLEGRO_MIXER *mixer)

ミキサーのサンプリング周波数を返します。

al_set_mixer_frequency bool al_set_mixer_frequency(ALLEGRO_MIXER *mixer, unsigned long val)

ミキサーのサンプリング周波数をセットします。

al_get_mixer_channels ALLEGRO_CHANNEL_CONF al_get_mixer_channels(const ALLEGRO_MIXER *mixer)

ミキサーのチャンネル設定を返します。

al_get_mixer_depth ALLEGRO_AUDIO_DEPTH al_get_mixer_depth(const ALLEGRO_MIXER *mixer)

ミキサーの音深度を返します。

al_get_mixer_quality ALLEGRO_MIXER_QUALITY al_get_mixer_quality(const ALLEGRO_MIXER *mixer)

ミキサーのquality設定を返します。
See also: ALLEGRO_MIXER_QUALITY.

al_set_mixer_quality bool al_set_mixer_quality(ALLEGRO_MIXER *mixer, ALLEGRO_MIXER_QUALITY val)

ミキサーのqualityを設定します。
Returns true on success, false on failure.

al_get_mixer_playing bool al_get_mixer_playing(const ALLEGRO_MIXER *mixer)

もし、trueを返す場合は、ミキサーは再生中です。

al_set_mixer_playing bool al_set_mixer_playing(ALLEGRO_MIXER *mixer, bool val)

ミキサーの再生をするかどうか切り替えます。
trueが返るなら成功、falseなら失敗。

al_get_mixer_attached bool al_get_mixer_attached(const ALLEGRO_MIXER *mixer)

ミキサーに何かオブジェクトがアタッチされていれば、trueを返します。

al_detach_mixer bool al_detach_mixer(ALLEGRO_MIXER *mixer)

ミキサーにアタッチされているあらゆるものを分離します。

al_set_mixer_postprocess_callback

int al_set_mixer_postprocess_callback(ALLEGRO_MIXER *mixer,
   postprocess_callback_t postprocess_callback, void *pp_callback_userdata)

音源がミックスされたアタッチ済みのストリームを呼び出す、後処理フィルタ関数を設定します。バッファの形式はミキサーが作成したものになります。また、サンプルとユーザデータはポインタとして渡されます。

Stream functions

al_create_audio_stream

ALLEGRO_AUDIO_STREAM *al_create_audio_stream(size_t buffer_count, unsigned long samples,
   unsigned long freq, ALLEGRO_AUDIO_DEPTH depth,
   ALLEGRO_CHANNEL_CONF chan_conf)

指定した値で、ALLEGRO_AUDIO_STREAMオブジェクトを作成します。ストリームはデフォルトでは「再生」に設定してあります。
それらにはバッファからのオーディオデータが供給されるでしょう。(バッファは多くのデータの断片(fragments)に分けられます)。

Parameter Meaning

パラメータ	意味
fragment_count	どのくらいの断片(fragments)数をオーディオストリームに使用するかを決めます。通常はオーディオバッファを半分に分けた二個の断片のみ必要です。しかしそれは断片の半分が再生を終えたときだけが、新しいデータが供給される唯一のタイミングであることを意味します。もし、多くの断片を使用すると普通いくつかのサンプルの大きさよりも少ない断片を使用するので、新しいバッファを満たすことができる(小さな)断片が常に存在するでしょう。「注意」の項目を参考にしてください。
freq	周波数単位はヘルツ(Hz)
depth	ALLEGRO_AUDIO_DEPTH の為に記載された値の一つを指定
chan_conf	ALLEGRO_CHANNEL_CONFの為に記載された値の一つを指定

各パラメータ fragment_count、 samples、 freq をうまく指定しなければ直接オーディオの遅延に影響を及ぼします。
遅延(秒)は次の式で表現できます：

delay = fragment_count * samples / freq

これはAllegroストリーミングのみの遅延です。実際には、サウンドドライバそして/またはハードウェアによって引き起こされた遅延も加味されるかもしれません。

注意: Byteで表現される断片サイズが分かっているなら、あなたはこのようにして、サンプルのサイズを得ることができます:

sample_size = al_get_channel_count(chan_conf) * al_get_depth_size(depth);
samples = bytes_per_fragment / sample_size;

完全なバッファのサイズは以下の通りです：

buffer_size = bytes_per_fragment * fragment_count

al_destroy_audio_stream void al_destroy_audio_stream(ALLEGRO_AUDIO_STREAM *stream) al_drain_audio_stream void al_drain_audio_stream(ALLEGRO_AUDIO_STREAM *stream)

ユーザーによって、サンプルデータが、ストリームにもう渡されることがなくなった場合に使います。この関数は、すべての未定のバッファの再生を終了させるために待機させます。ストリーム再生の状態はfalseに変化するでしょう。

al_rewind_audio_stream bool al_rewind_audio_stream(ALLEGRO_AUDIO_STREAM *stream)

streamingファイルの再生地点を最初に巻き戻します。この関数がtrueを返せば成功です。
現在、この関数はAllegro のacodec APIのal_load_audio_stream、al_load_audio_stream_f 関数によって作成されたstream再生においてのみ働くかもしれません。

al_get_audio_stream_frequency unsigned int al_get_audio_stream_frequency(const ALLEGRO_AUDIO_STREAM *stream)

stream再生のサンプリング周波数を返します。

al_get_audio_stream_channels ALLEGRO_CHANNEL_CONF al_get_audio_stream_channels(const ALLEGRO_AUDIO_STREAM *stream)

stream再生のチャンネル設定を返します。

al_get_audio_stream_depth ALLEGRO_AUDIO_DEPTH al_get_audio_stream_depth(const ALLEGRO_AUDIO_STREAM *stream)

stream再生の音深度を返します。

al_get_audio_stream_length unsigned long al_get_audio_stream_length(const ALLEGRO_AUDIO_STREAM *stream) al_get_audio_stream_speed float al_get_audio_stream_speed(const ALLEGRO_AUDIO_STREAM *stream)

stream再生スピードの値を返します。

al_set_audio_stream_speed bool al_set_audio_stream_speed(ALLEGRO_AUDIO_STREAM *stream, float val)

stream再生スピードの値を設定します。

trueが返れば成功、falseなら失敗。もしsample instanceにvoiceオブジェクトが(mixerを通さずに)直接アタッチしていた場合、この関数の処理は失敗するでしょう。

al_get_audio_stream_gain float al_get_audio_stream_gain(const ALLEGRO_AUDIO_STREAM *stream)

再生時のゲイン(gain)値を返します。

al_set_audio_stream_gain bool al_set_audio_stream_gain(ALLEGRO_AUDIO_STREAM *stream, float val)

再生時のゲイン(gain)値を設定します。
成功したらtrueを返し、失敗時にはfalseを返します。もしsample instance にvoiceオブジェクトが(mixerを通さずに)直接アタッチしていた場合、失敗するでしょう。

al_get_audio_stream_pan float al_get_audio_stream_pan(const ALLEGRO_AUDIO_STREAM *stream)

stream再生時のパン(Pan)の値を返します。

al_set_audio_stream_pan bool al_set_audio_stream_pan(ALLEGRO_AUDIO_STREAM *stream, float val)

stream再生(sample intcetance)時のパン(Pan)の値を設定します。パンは音の出るバランスを調整します。
引数 val に-1.0 を指定することは、左側のスピーカーからのみ音が出ます。+1.0では右から。そして0.0では両方のスピーカーからバランスよく音が出ます。

成功したらtrueを返し、失敗時にはfalseを返します。もしsample instance にvoiceオブジェクトが(mixerを通さずに)直接アタッチしていた場合、失敗するでしょう。

al_get_audio_stream_playing bool al_get_audio_stream_playing(const ALLEGRO_AUDIO_STREAM *stream)

streamが再生しているならtrueを返す。

al_set_audio_stream_playing bool al_set_audio_stream_playing(ALLEGRO_AUDIO_STREAM *stream, bool val)

streamが再生しているかどうかを切り替えます。
成功ならtrue、失敗ならfalseを返す。

al_get_audio_stream_playmode ALLEGRO_PLAYMODE al_get_audio_stream_playmode(const ALLEGRO_AUDIO_STREAM *stream)

stream再生モードを返す。

al_set_audio_stream_playmode bool al_set_audio_stream_playmode(ALLEGRO_AUDIO_STREAM *stream, ALLEGRO_PLAYMODE val)

stream再生モードを設定します。
成功ならtrue、失敗ならfalseを返す

al_get_stream_attached bool al_get_audio_stream_attached(const ALLEGRO_AUDIO_STREAM *stream)

streamオブジェクトに何かオブジェクトをアタッチします。

al_detach_audio_stream bool al_detach_audio_stream(ALLEGRO_AUDIO_STREAM *stream)

streamオブジェクトにアタッチしている、あらゆるオブジェクトを外します。

al_get_audio_stream_fragment bool al_get_audio_stream_fragment(const ALLEGRO_AUDIO_STREAM *stream, void **val)

この関数は、Allegroのオーディオストリーミングを使用するとき、ストリームに絶え間なく新しいSampleデータを供給するために使われるでしょう。ストリームに新規データが準備できている場合この関数はtrueを返すでしょう。そして val にはオーディをデータが満たされるべき内部バッファのアドレスが含まれるでしょう。バッファの長さと形式はal_create_audio_stream関数と共に指定しておくか、ここに記される多様な関数によって検索してください。

バッファが一旦一杯になったら、あなたは、al_set_audio_stream_fragment関数に val を渡しAllegroに合図を送らなければいけません。
注意：、新しい断片が準備出来ている時には、いつもALLEGRO_EVENT_STREAM_EMPTY_FRAGMENT イベントが発生するでしょう。もしストリームからイベントを捕捉しようとするならこれが利用できます。

al_set_audio_stream_fragment bool al_set_stream_buffer(ALLEGRO_AUDIO_STREAM *stream, void *val)

この関数は[al_get_audio_stream_buffer]がバッファが新しいデータで満たしたことを示すあらゆる正常なコール( successfull call )のために、呼び出される必要があります。This function needs to be called for every successfull call of [al_get_audio_stream_buffer] to indicate that the buffer is filled with new data.

al_get_audio_stream_fragments bool al_get_audio_stream_fragment(ALLEGRO_AUDIO_STREAM *stream)

このストリームが使用した断片(fragments)の数を返します。これは新規ストリームが作成されるときにal_create_audio_stream関数に渡すのと同じ値です。

al_get_available_audio_stream_fragments unsigned int al_get_available_audio_stream_fragments(const ALLEGRO_AUDIO_STREAM *stream)

ストリームにおける利用可能な断片(fragments)数を返します。そこで [al_get_audio_stream_buffer]を使うことが出来ます。

al_seek_audio_stream_secs bool al_seek_audio_stream_secs(ALLEGRO_AUDIO_STREAM *stream, double time)

streaming ファイルの再生位置を、指定した時間にセットします。trueが返れば成功です。現在、この関数はAllegro のacodec APIのal_load_audio_stream, al_load_audio_stream_f、そして特定のフォーマット指定の関数によって作成されたstream再生においてのみ働くかもしれません。

al_get_audio_stream_position_secs double al_get_audio_stream_position_secs(ALLEGRO_AUDIO_STREAM *stream)

streamファイルの再生位置を秒単位で返します。現在、この関数はAllegro のacodec APIのal_load_audio_stream 関数によって作成されたstream再生においてのみ働くかもしれません。

al_get_audio_stream_length_secs double al_get_audio_stream_length_secs(ALLEGRO_AUDIO_STREAM *stream)

streamファイルの収録時間を秒で返します。現在、この関数はAllegro のacodec APIのal_load_audio_stream,al_load_audio_stream_f、そして特定のフォーマット指定がある関数によって作成されたstream再生においてのみ働くかもしれません。

al_set_audio_stream_loop_secs bool al_set_audio_stream_loop_secs(ALLEGRO_AUDIO_STREAM *stream, double start, double end)

streamファイルの区間ループ(start〜end 間)の位置をセットします。現在、この関数はAllegro のacodec APIのal_audio_stream_from_file関数によって作成されたstream再生においてのみ働くかもしれません。

al_register_sample_loader

bool al_register_sample_loader(const char *ext,
   ALLEGRO_SAMPLE *(*loader)(const char *filename))

al_load_sample関数のためのハンドラを登録します。ハンドラとして与えられる自作の関数は与えられた拡張子を持つファイルからSampleデータをロードするために使用されます。このとき拡張子は「.」ドットを含む文字列で、大文字小文字には鈍感(case-insensitively)です。引数loader には、非登録エントリのためにNULLが指定されることがあるかもしれません。
成功なら true 、エラーならfalse が返る。もし存在しないエントリを非登録しようとするとfalseが返ります。

al_register_sample_loader_f

bool al_register_sample_loader_f(const char *ext,
   ALLEGRO_SAMPLE *(*loader)(ALLEGRO_FILE* fp))

al_load_sample_f 関数のためのハンドラを登録します。
(以下略)al_register_sample_loader の説明を参考に。

al_register_sample_saver

bool al_register_sample_saver(const char *ext,
   bool (*saver)(const char *filename, ALLEGRO_SAMPLE *spl))

al_save_sample 関数のためのハンドラを登録します。The given function will be used to handle the saving of sample files with the given extension. The extension should include the leading dot ('.') character. It will be matched case-insensitively. The saver argument may be NULL to unregister an entry.
Returns true on success, false on error. Returns false if unregistering an entry that doesn't exist.

al_register_sample_saver_f

bool al_register_sample_saver_f(const char *ext,
   bool (*saver)(ALLEGRO_FILE* fp, ALLEGRO_SAMPLE *spl))

al_save_sample_f 関数のためのハンドラを登録します。
(以下略)al_register_sample_saver の説明を参考に。

al_register_audio_stream_loader

bool al_register_audio_stream_loader(const char *ext,
   ALLEGRO_AUDIO_STREAM *(*stream_loader)(const char *filename,
      size_t buffer_count, unsigned int samples))

al_load_audio_stream関数のためのハンドラを登録します。
The given function will be used to open streams from files with the given extension. The extension should include the leading dot ('.') character. It will be matched case-insensitively. The stream_loader argument may be NULL to unregister an entry. Returns true on success, false on error. Returns false if unregistering an entry that doesn't exist.

al_register_audio_stream_loader_f

bool al_register_audio_stream_loader_f(const char *ext,
   ALLEGRO_AUDIO_STREAM *(*stream_loader)(ALLEGRO_FILE* fp,
      size_t buffer_count, unsigned int samples))

al_load_audio_stream_f関数のためのハンドラを登録します。

al_load_sample ALLEGRO_SAMPLE *al_load_sample(const char *filename)

いくつかの異なるオーディオファイル形式を、拡張子に基づいて読み込みます。
一部の形式(OggVorbis等)は、ライブラリをコンパイルする前に外部ライブラリ(libogg、libvorbis)をインストールしておく必要があります。

この関数は読み込んだファイル全体のデータをメモリに格納してしまうことに注意してください。(時間がかかるかもしれません)
必要なときにファイルを読み込むためには、al_load_audio_stream関数を使ってください。
成功なら Sampleデータが、失敗ならNULL が返る。
See also: al_register_sample_loader, al_load_sample_wav

al_load_sample_f ALLEGRO_SAMPLE *al_load_sample_f(ALLEGRO_FILE* fp, const char *ident)

ALLEGRO_SAMPLEの中のALLEGRO_FILE ストリームからファイルイメージをロードします。ファイル形式は引数 ident に渡された値によって決定されます。値はドット「.」から始まる拡張子が該当します。
この関数は読み込んだファイル全体のデータをメモリに格納してしまうことに注意してください。(時間がかかるかもしれません)
必要なときにファイルを読み込むためには、al_load_audio_stream_f関数を使ってください。
成功なら Sampleデータが、失敗ならNULL が返る。
See also: al_register_sample_loader, al_load_sample_wav

al_load_audio_stream

ALLEGRO_AUDIO_STREAM *al_load_audio_stream(const char *filename, size_t buffer_count,
   unsigned int samples)

オーディオファイルを、それが必要な時に応じてディスクから読み込みます。通常のストリームと違って、この機能によって返されるデータは、ユーザーによって送る(fed)必要はなく、それが必要になった時にライブラリが自動的にそのファイルを読み込むでしょう。ストリームは Sampleのあるbuffer_count バッファを含むでしょう。

ストリームを使用するには、voice オブジェクトに接続( attach)しなければいけません。詳細はALLEGRO_AUDIO_STREAMの項目を参照ください。

この関数がファイルのロードに成功した場合、そのストリームを返す。NULLが返るなら失敗。　
See also: al_register_audio_stream_loader, al_load_audio_stream_wav

al_load_audio_stream_f

ALLEGRO_AUDIO_STREAM *al_load_audio_stream_f(ALLEGRO_FILE* fp, const char *ident,
   size_t buffer_count, unsigned int samples)

必要な時にALLEGRO_FILE ストリームからオーディオファイルをロードします。通常のストリームと異なって、この関数によって返されたものは、ユーザによって食べさせられる必要はありません。ライブラリはそれが必要な時に、さらにファイルを自動的に読むでしょう。ストリームはサンプルのサンプルがあるbuffer_countバッファを含むでしょう。

ファイル形式は引数 ident に渡された値によって決定されます。値はドット「.」から始まる拡張子が該当します。
ストリームは、VOICEオブジェクトにアタッチして使わなければいけません。ALLEGRO_AUDIO_STREAM 定数の項目で詳細を読んで下さい。

成功なら Sampleデータが、失敗ならNULL が返る。
See also: al_register_sample_loader, al_load_sample_wav

al_save_sample bool al_save_sample(const char *filename, ALLEGRO_SAMPLE *spl)

ファイルにSampleデータを書き出します。この関数は現在、拡張子'.wav'の wav形式のみをサポートしています。
成功なら true 、エラーならfalse が返る。
See also: al_register_audio_stream_loader, al_save_sample_wav

al_save_sample_f

bool al_save_sample_f(ALLEGRO_FILE *fp, const char *ident, ALLEGRO_SAMPLE *spl)

ALLEGRO_FILE、ファイルストリームにSampleデータを書き出します。この関数は現在、拡張子'.wav'の wav形式のみをサポートしています。
成功なら true 、エラーならfalse が返る。
See also: al_register_audio_stream_loader_f, al_save_sample_wav_f

al_load_wav ALLEGRO_SAMPLE *al_load_wav(const char *filename)

PCM .wav ファイルのデータをSampleデータとしてロードします。
成功なら Sampleデータが、失敗ならNULL が返る。
See also: al_load_wav_f

al_load_wav_f ALLEGRO_SAMPLE *al_load_wav_f(ALLEGRO_FILE *fp)

PCM .wav ファイルのデータをALLEGRO_FILE ストリームからロードします。
成功なら Sampleデータが、失敗ならNULL が返る。
See also: al_load_wav_f

al_save_sample_wav

bool al_save_wav(const char *filename, ALLEGRO_SAMPLE *spl)

Sampleデータを PCM .wavファイル形式で保存します
成功なら true 、エラーならfalse が返る。
See also: al_save_sample, al_save_wav_f

al_save_wav_f

bool al_save_wav_f(ALLEGRO_FILE *pf, ALLEGRO_SAMPLE *spl)

ALLEGRO_FILE ストリームからきたデータを PCM .wavファイル形式で保存します
成功なら true 、エラーならfalse が返る。
See also: al_save_sample,al_save_wav

al_load_wav_audio_stream

ALLEGRO_AUDIO_STREAM *al_load_wav_audio_stream(const char *filename,
   size_t buffer_count, unsigned int samples)

al_load_audio_streamと似ていますが、ファイルはPCM .wav fileとして仮定します。 Like al_audio_stream_from_file but assumes the file is PCM .wav file.

al_load_wav_audio_stream_f

ALLEGRO_AUDIO_STREAM *al_load_wav_audio_stream(const char *filename,
   size_t buffer_count, unsigned int samples)

al_load_audio_stream_fと似ていますが、ファイルはPCM .wav fileとして仮定します。 Like al_audio_stream_from_file but assumes the file is PCM .wav file.

Ａudio Codec addons

flac形式とoggborbis 形式を扱います。

al_init_flac_addon bool al_init_flac_addon(void)

この関数は、 al_load_sample_flac を al_load_sample に登録して、 ".flac"拡張子のファイルを扱えるようにするためのもです。これを使うには、ヘッダに a5_flac.h をincludeし、コンパイル時に a5_flacライブラリをリンクする必要があります。

成功ならtrueが返る。

al_load_sample_flac ALLEGRO_SAMPLE *al_load_sample_flac(const char *filename)

Loads a sample in FLAC format. See also: al_load_sample

al_init_ogg_vorbis_addon bool al_init_ogg_vorbis_addon(void)

この関数は al_load_sample_ogg_vorbisを al_load_sampleに、そして al_load_audio_stream_ogg_vorbisを al_load_audio_stream へ登録し、(Vorbisデータを含むと思われる) 拡張子'.ogg'を持つファイルを扱えるようにします。これを使うには、a5_vorbis.hヘッダファイルをincludeに書き、コンパイル時には a5_vorbisライブラリをリンクする必要があるでしょう。
成功ならtrueが返る。

al_load_sample_ogg_vorbis ALLEGRO_SAMPLE *al_load_sample_ogg_vorbis(const char *filename)

Ogg Vorbis 形式のデータをSampleオブジェクトとしてロードします。 See also: al_load_sample

al_load_audio_stream_ogg_vorbis

ALLEGRO_STREAM *al_load_audio_stream_ogg_vorbis(const char *filename,
    size_t buffer_count, unsigned int samples)

Ogg Vorbis 形式のデータをStreamオブジェクトとしてロードします。

Font addons

al_destroy_font void al_destroy_font(ALLEGRO_FONT *f)

フォント構造体によって使われたメモリを破棄します。これは現在 vtable によって制御されています。

al_grab_font_from_bitmap

ALLEGRO_FONT *al_grab_font_from_bitmap(
   ALLEGRO_BITMAP *bmp,
   int ranges_n, int ranges[])

Allegroビットマップから、字体を取得するためのテーブルを作成します。(おそらくマップチップのように、画像ファイルに描かれたビットマップの文字をフォントに割当てて利用可能にするするのかもしれない)

Allegroビットマップから字体を取得するための手綱を繰りなさい。(Work horse for grabbing a font from an Allegro bitmap.)

Parameters: 
- bmp:  ビットマップに描かれた文字  (TODO: 予想される形式 - 不透明の黄色の背景 , 全て同じ高さ(幅は可変の場合もある)の透明なグリッド内に字体を収めます。白色で、アンチエイリアスのかかった字体も可能)
 - n: ビットマップのユニコード範囲 
 - ranges: 'n' に対応する、それぞれ、最初と最後の文字にあたるユニコードポイント を指定します。(2つの値が格納された配列を渡す)

具体例:

/*使用するユニコード範囲が1つの場合  */
int ranges[] = {32, 126};
al_font_grab_font_from_bitmap(bitmap, 1, ranges)

/*使用するユニコード範囲が4つの場合  */
int ranges[] = {
    0x0020, 0x007F,  /* ASCII */
    0x00A1, 0x00FF,  /* Latin 1 */
    0x0100, 0x017F,  /* Extended-A */
    0x20AC, 0x20AC}; /* Euro */
al_font_grab_font_from_bitmap(bitmap, 4, ranges)

最初の例では、空白スペース(32) から始まり、チルダ文字(126)に終わる、印刷可能な95のASCII文字のための字体を取得するでしょう。２番目の例では、 ASCII 96文字に加え、次にLatin 1領域にある、95文字、そしてExtended-A領域にある128文字、最後に、ヨーロッパの文字を配置します。 (このやり方は、 Allegro4 のフォントでも見つかります.)

al_init_font_addon void al_init_font_addon(void)

フォント機能の初期化

al_shutdown_font_addon void al_shutdown_font_addon(void)

フォントアドオンをシャットダウンさせます。これはプログラムの終了時に自動的に行われます。しかしユーザーがこれを行いたい場合はこの関数を呼ぶことが出来ます。

al_load_font ALLEGRO_FONT *al_load_font(const char *filename, void *param)

ディスク上からフォントを読込む。もしそれに失敗した場合はビットマップフォントの読み込みを試みます。

al_load_bitmap_font ALLEGRO_FONT *al_load_bitmap_font(const char *fname, void *param)

Allegroビットマップフォント形式のインポートルーチン

al_register_font_loader.

bool al_register_font_loader(char const *extension,
   ALLEGRO_FONT *(*load_font)(char const *filename, int size, int flags))

Allegroに新しいフォントファイルの形式を指定して、このフォントを読込ませます。拡張子は「.」から始まる文字列で、大文字小文字には鈍感(case-insensitively)です。引数 load_font には、非登録エントリへのNULLを渡すことがあるかもしれません。
trueが返るなら成功。falseならエラー。存在しないエントリを非登録しようとするとfalseが返ります。

al_get_font_line_height int al_get_font_line_height(const ALLEGRO_FONT *f)

指定したフォントの文字の高さが何ピクセルあるか返します。

al_get_text_width int al_get_text_width(const ALLEGRO_FONT *f, const char *str, int count)

特定のフォントの文字列の長さが何ピクセルあるか計算します。

al_draw_text

void al_draw_text(const ALLEGRO_FONT *font, float x, float y, int flags, char const *text)

Null 終端処理が施された文字列 char を、指定したフォント f で、ビットマップ上の座標( x,y) の位置に表示します。

The flags parameter can be 0 or one of the following flags:

    * ALLEGRO_ALIGN_LEFT -  テキストを左寄せで表示します  (same as 0).
    * ALLEGRO_ALIGN_CENTRE - テキストを座標(x,y)を中心に中央寄せで表示します
    * ALLEGRO_ALIGN_RIGHT - テキストを座標(x,y)を基準に、右寄せで表示します

al_draw_ustr

void al_draw_ustr(const ALLEGRO_FONT *font, float x, float y, int flags,
   const ALLEGRO_USTR *ustr)

al_draw_text関数と似ていますが、ALLEGRO_USTR(ユニコード文字列) のための関数です。

al_draw_justified_text

void al_draw_justified_text(const ALLEGRO_FONT *font, float x1, float x2,
   float y, float diff, int flags, const char *text)

al_draw_text関数と似ていますが、指定した領域に、文字列を均等配置してテキストを表示します。

al_draw_justified_ustr

void al_draw_justified_ustr(const ALLEGRO_FONT *font, float x1, float x2,
   float y, float diff, int flags, const ALLEGRO_USTR *ustr)

al_draw_text関数と似ていますが、ALLEGRO_USTR のための関数です。

al_draw_textf

void al_draw_textf(const ALLEGRO_FONT *font, float x, float y, int flags,
   const char *format, ...)

これはC言語標準ライブラリにある、printf()形式と同じ方法で文字列、テキストを出力します、指定可能なフラグについては、al_draw_text を参照。

al_draw_justified_textf

void al_draw_justified_textf(const ALLEGRO_FONT *f, float x1, float x2, float y,
   float diff, int flags, const char *format, ...)

書式はprintf 風で、文字列を均等配置して表示フラグについては、al_draw_justified_textと al_draw_textf を参照して下さい。

al_get_text_dimensions

void al_get_text_dimensions(const ALLEGRO_FONT *f,
   char const *text,
   int *bbx, int *bby, int *bbw, int *bbh, int *ascent, int *descent)

時々、al_get_text_width 関数と al_get_font_line_height 関数を使って正確な配置ができない場合もあるので、それを解決する情報を挙げます。

戻り値(すべてPixel 単位です):
x, y - バウンディングポックスの左上の角からのオフセット位置です。
w, h - バウンディングボックスの寸法です( h は descentも含めた高さとなる)。
ascent -フォントのAscent(一般的な大文字小文字、ABCVWXYZ,abczといった文字の高さがこれにあたる)。
descent - フォントのDescent(一部の小文字、gqpjy の下部に突き出た部分に該当する高さ)。

下の図のXは指定したテキストを描画し始める座標とすると、ascent , descent そして文字の高さ(height)は次のような関係で表されます。描画地点X(x, y)の座標をそれぞれマイナス値に指定すると、画面の上端、左端を越えた画面外を起点に、字体(glyphs) を表示することに注意して下さい。

X------------------------
    /\         |        |
   /  \        |        |
  /____\       ascent   |
 /      \      |        |
/        \     |        height
----------------        |
               |        |
               descent  |
               |        |
-------------------------

al_get_ustr_dimensions

void al_get_ustr_dimensions(const ALLEGRO_FONT *f,
   ALLEGRO_USTR const *ustr,
   int *bbx, int *bby, int *bbw, int *bbh, int *ascent, int *descent)

上の ALLEGRO_USTR 版

al_load_ttf_font ALLEGRO_FONT *al_load_ttf_font(char const *filename, int size, int flags)

FreeTypeライブラリを使って、True Type フォントファイルを読込みます。

FreeType の FAQを引用すると、以下の種類のフォント形式をサポートしています。
TrueType形式, OpenType形式, Type1形式, CID形式, CFF形式, Windows FON/FNT形式, X11のPCF形式、等…

sizeパラメータは、フォントを描画時の文字の大きさを、ピクセル単位で指定して下さい。標準のフォントサイズは、1EMあたりの単位で測定されます、代わりに、字体全体の高さを基準にサイズを指定したい場合には、マイナス値を与えて下さい。

Note: テキストを複数の文字サイズで表示したい場合は、複数回、そのたびに異なったサイズ・パラメータ、フォントをロードさせて下さい。

この関数でサポートするフラグ(flags)には以下のものがあります。:
* ALLEGRO_TTF_NO_KERNING - カーニング対応のフォントであっても、カーニングを使用しない。

al_init_ttf_addon bool al_init_ttf_addon(void)

al_init_font_addon関数の後にこの関数を呼ぶことで、
al_load_ttf_font関数で提供された.ttfと他の形式をal_load_font関数に認識させてください。

Color addon

al_color_cmyk ALLEGRO_COLOR al_color_cmyk(float c, float m, float y, float k) al_color_cmyk_to_rgb

void al_color_cmyk_to_rgb(float cyan, float magenta, float yellow,
    float key, float *red, float *green, float *blue)

al_color_hsl ALLEGRO_COLOR al_color_hsl(float h, float s, float l) al_color_hsl_to_rgb

void al_color_hsl_to_rgb(float hue, float saturation, float lightness,
   float *red, float *green, float *blue)

Parameters: 範囲0〜1がとる値は、0.25や0.5 という指定が可能です(float型変数のため)

    * hue - 色相を表す角度を値 0〜360°の範囲で指定する。
    * saturation - 彩度の値。これは  0〜1  の範囲で指定する。
    * lightness - 明度の値。これは 0〜1  の範囲で指定する。
    * red, green, blue - RGB色価の値をそれぞれ 0〜1の範囲を指定する。

al_color_hsv ALLEGRO_COLOR al_color_hsv(float h, float s, float v) al_color_hsv_to_rgb

void al_color_hsv_to_rgb(float hue, float saturation, float value,
   float *red, float *green, float *blue)

Parameters:

    * hue - 色相を表す角度を値 0〜360°の範囲で指定する。
    * saturation - 彩度の値。これは  0〜1  の範囲で指定する。
    * lightness - 明度の値。これは 0〜1  の範囲で指定する。
    * red, green, blue - RGB色価の値をそれぞれ 0〜1の範囲を指定する。

al_color_html ALLEGRO_COLOR al_color_html(char const *string) al_color_html_to_rgb

void al_color_html_to_rgb(char const *string,
   float *red, float *green, float *blue)

al_color_rgb_to_html

void al_color_rgb_to_html(float red, float green, float blue,
    char *string)

Parameters:
    * red, green, blue - 色成分(color components)値をそれぞれ 0〜1  の範囲で指定する。
    * string - 書き込まれる結果が入る8byteの文字列 例えば #FF0000 などの16進数表記の色が入る。

Example:
 char html[8]; 
al_color_rgb_to_html(1, 0, 0, html);
↑ 現在、変数htmlの中身は"#ff0000"という文字列になっています。

al_color_name ALLEGRO_COLOR al_color_name(char const *name) al_color_name_to_rgb bool al_color_name_to_rgb(char const *name, float *r, float *g, float *b)

Parameters:
    * name - 色の名称 (小文字)を指定する.
    * r, g, b - もし、下に書かれた色名が認識された場合、対応する正確なRGB色価をそれぞれ0〜1の範囲で返します。

認識可能な色名:

aliceblue, antiquewhite, aqua, aquamarine, azure, beige, bisque, black, blanchedalmond, blue, blueviolet, brown, burlywood, cadetblue, chartreuse, chocolate, coral, cornflowerblue, cornsilk, crimson, cyan, darkblue, darkcyan, darkgoldenrod, darkgray, darkgreen, darkkhaki, darkmagenta, darkolivegreen, darkorange, darkorchid, darkred, darksalmon, darkseagreen, darkslateblue, darkslategray, darkturquoise, darkviolet, deeppink, deepskyblue, dimgray, dodgerblue, firebrick, floralwhite, forestgreen, fuchsia, gainsboro, ghostwhite, goldenrod, gold, gray, green, greenyellow, honeydew, hotpink, indianred, indigo, ivory, khaki, lavenderblush, lavender, lawngreen, lemonchiffon, lightblue, lightcoral, lightcyan, lightgoldenrodyellow, lightgreen, lightgrey, lightpink, lightsalmon, lightseagreen, lightskyblue, lightslategray, lightsteelblue, lightyellow, lime, limegreen, linen, magenta, maroon, mediumaquamarine, mediumblue, mediumorchid, mediumpurple, mediumseagreen, mediumslateblue, mediumspringgreen, mediumturquoise, mediumvioletred, midnightblue, mintcream, mistyrose, moccasin, avajowhite, navy, oldlace, olive, olivedrab, orange, orangered, orchid, palegoldenrod, palegreen, paleturquoise, palevioletred, papayawhip, peachpuff, peru, pink, plum, powderblue, purple, purwablue, red, rosybrown, royalblue, saddlebrown, salmon, sandybrown, seagreen, seashell, sienna, silver, skyblue, slateblue, slategray, snow, springgreen, steelblue, tan, teal, thistle, tomato, turquoise, violet, wheat, white, whitesmoke, yellow, yellowgreen

これらは、http://en.wikipedia.org/wiki/X11_color_names から引用されたもので X11で使われる色名よりもCSSで使われる色名が重なっています。 Returns: もし、リストにある名前が渡されていた場合 0を返し、そうでなければ 1を返す。

al_color_rgb_to_cmyk

void al_color_rgb_to_cmyk(float red, float green, float blue,
   float *cyan, float *magenta, float *yellow, float *key)

K(黒)成分を0とした CMYKの色は、次の公式によって、RGBの各色で表現することができます。:
C = 1 - R
M = 1 - G
Y = 1 - B
K = 0

この関数は、Kの色成分の最大値と最小値に関して代替の色を表現するでしょう。

al_color_rgb_to_hsl

void al_color_rgb_to_hsl(float red, float green, float blue,
   float *hue, float *saturation, float *lightness)

0〜1までの範囲を取る RGB 3つの値の組合せを与えることで、これを色相[Hue](0〜360°)と彩度[Saturation](0〜1)、明度[Lightness](0〜1)から構成されるHSL形式の色表現に変換します。

al_color_rgb_to_hsv

void al_color_rgb_to_hsv(float red, float green, float blue,
   float *hue, float *saturation, float *value)

0〜1までの範囲を取る RGB 3つの値の組合せを与えることで、これを色相[Hue](0〜360°)と彩度[Saturation](0〜1)、色価[Value](0〜1)から構成されるHSV形式の色表現に変換します。

al_color_rgb_to_name char const *al_color_rgb_to_name(float r, float g, float b)

0.0〜1.0までの範囲を取る RGB 3つの値の組合せを与えると、それに対応する色名を返します。

al_color_rgb_to_yuv

void al_color_rgb_to_yuv(float red, float green, float blue,
   float *y, float *u, float *v)

YUV形式は、輝度信号[Y]と、輝度と青色成分との差[U]、輝度と赤色成分との差[V]で表現する形式で、TVなどのAV機器で利用される。

al_color_yuv ALLEGRO_COLOR al_color_yuv(float y, float u, float v) al_color_yuv_to_rgb

void al_color_yuv_to_rgb(float y, float u, float v,
    float *red, float *green, float *blue)

Image I/O addon

al_init_iio_addon bool al_init_iio_addon(void)

IIO アドオンを初期化します。

al_register_bitmap_loader

bool al_register_bitmap_loader(const char *extension,
   ALLEGRO_BITMAP *(*loader)(const char *filename))

al_load_bitmap関数のためのハンドラを登録します。このハンドラとして指定した関数は、特定のビットマップ形式の拡張子ファイルをロードするために使用されるでしょう。引数extension には、「.」ドットから始まる文字列を指定します。これは大文字と小文字の違いに鈍感(case-insensitively)です。引数 loader にはエントリが登録されていない場合はNULLを指定するかもしれません。

成功したらtrueを返す。エラーならfalse。もし存在しないエントリを非登録する場合もfalseを返します。

al_register_bitmap_saver

bool al_register_bitmap_saver(const char *extension,
   bool (*saver)(const char *filename, ALLEGRO_BITMAP *bmp))

(上の項目を参考に)
al_save_bitmap関数のためのハンドラを登録します。引数として与えられる自作の関数は、extension で示される拡張子を持つビットマップファイルをロードする機能を持たなければいけません。extension で示される拡張子は「.」ドットから始まり、大文字小文字に鈍感(case-insensitively)です。 The saver argument may be NULL to unregister an entry. Returns true on success, false on error. Returns false if unregistering an entry that doesn't exist.

al_register_bitmap_loader_f

bool al_register_bitmap_loader_f(const char *extension,
   ALLEGRO_BITMAP *(*loader_f)(ALLEGRO_FILE *fp))

(上の項目を参考に)
al_load_bitmap_f関数のためのハンドラを登録します。引数として与えられる自作の関数は、extension で示される拡張子を持つビットマップファイルをロードする機能を持たなければいけません。extension で示される拡張子は「.」ドットから始まり、大文字小文字に鈍感(case-insensitively)です。 The fs_loader argument may be NULL to unregister an entry. Returns true on success, false on error. Returns false if unregistering an entry that doesn't exist.

al_register_bitmap_saver_f

bool al_register_bitmap_saver_f(const char *extension,
   bool (*saver_f)(ALLEGRO_FILE *fp, ALLEGRO_BITMAP *bmp))

(上の項目を参考に)
al_save_bitmap_f関数のためのハンドラを登録します。引数として与えられる自作の関数は、extension で示される拡張子を持つビットマップファイルをロードする機能を持たなければいけません。extension で示される拡張子は「.」ドットから始まり、大文字小文字に鈍感(case-insensitively)です。 The saver_entry argument may be NULL to unregister an entry. Returns true on success, false on error. Returns false if unregistering an entry that doesn't exist.

al_load_bitmap ALLEGRO_BITMAP *al_load_bitmap(const char *filename)

指定したファイル名のイメージファイルを読込んで新規 ALLEGRO_BITMAPを作成します。ファイル形式は拡張子によって判断します。 See Also: al_set_new_bitmap_format, al_set_new_bitmap_flags

al_load_bitmap_f

ALLEGRO_BITMAP *al_load_bitmap_f(ALLEGRO_FILE *fp, const char *ident)

ALLEGRO_FILE ストリームから画像データを、ALLEGRO_BITMAPへロードします。ファイルのタイプは、'ident' パラメータによって決まります。このパラメータには、ドット"." に続く拡張子を含む文字列を指定します。

al_save_bitmap bool al_save_bitmap(const char *filename, ALLEGRO_BITMAP *bitmap)

ALLEGRO_BITMAP の内容を、指定したファイル名のイメージファイルに保存します。ファイル形式は拡張子によって判断します。

al_save_bitmap_f

bool al_save_bitmap_f(ALLEGRO_FILE *fp, const char *ident,
   ALLEGRO_BITMAP *bitmap)

ビットマップの内容をALLEGRO_FILE ストリームへ保存します。ファイルのタイプは、'ident' パラメータによって決まります。このパラメータには、ドット"." に続く拡張子を含む文字列を指定します。

各フォーマット専用の関数もあります

al_load_bmp ALLEGRO_BITMAP *al_load_bmp(const char *filename)

PCXファイルを読込んで新規 ALLEGRO_BITMAPを作成します。ビットマップはal_create_bitmap関数によって作られます。

al_load_bmp_f ALLEGRO_BITMAP *al_load_bmp_f(ALLEGRO_FILE *f)

特定のファイルフォーマットを扱うバージョン。

al_load_jpg ALLEGRO_BITMAP *al_load_jpg(char const *filename)

JPEGファイルを読込んで新規 ALLEGRO_BITMAPを作成します。ビットマップはal_create_bitmap関数によって作られます。

al_load_jpg_f

al_load_bmp_f 関数の項目を見てください。

al_load_pcx ALLEGRO_BITMAP *al_load_pcx(const char *filename)

PCXファイルを読込んで新規 ALLEGRO_BITMAPを作成します。ビットマップはal_create_bitmap関数によって作られます。

al_load_pcx_f

al_load_bmp_f 関数の項目を見てください。

al_load_png ALLEGRO_BITMAP *al_load_png(const char *filename)

PNGファイルを読込んで新規 ALLEGRO_BITMAPを作成します。ビットマップはal_create_bitmap関数によって作られます。

al_load_png_f

al_load_bmp_f 関数の項目を見てください。

al_load_tga ALLEGRO_BITMAP *al_load_tga(const char *filename)

TGAファイルを読込んで新規 ALLEGRO_BITMAPを作成します。ビットマップはal_create_bitmap関数によって作られます。

al_load_tga_f

al_load_bmp_f関数の項目を見てください。

al_save_bmp iint al_save_bmp(const char *filename, ALLEGRO_BITMAP *bmp)

ALLEGRO_BITMAP の内容をPCX形式で保存します。

al_load_bmp_f bool al_save_bmp_f(ALLEGRO_FILE *f, ALLEGRO_BITMAP *bmp)

al_save_bitmap_f 関数の項目を見てください。

al_save_jpg int al_save_jpg(char const *filename, ALLEGRO_BITMAP *bmp)

ALLEGRO_BITMAP の内容を JPEG形式で保存します。

al_save_jpg_f

al_save_bmp_f 関数の項目を見てください。

al_save_pcx int al_save_pcx(const char *filename, ALLEGRO_BITMAP *bmp)

ALLEGRO_BITMAP の内容をPCX形式で保存します。

al_save_pcx_f

al_save_bmp_f 関数の項目を見てください。

al_save_png int al_save_png(const char *filename, ALLEGRO_BITMAP *bmp)

ALLEGRO_BITMAP の内容をPNG形式で保存します。

al_save_png_f

al_save_bmp_f 関数の項目を見てください。

al_save_tga int al_save_tga(const char *filename, ALLEGRO_BITMAP *bmp)

ALLEGRO_BITMAP の内容をTGA形式で保存します。

al_save_tga_f

al_save_bmp_f 関数の項目を見てください。

al_get_allegro_image_version uint32_t al_get_allegro_image_version(void)

ALLEGRO_BITMAPアドオンのバージョンを返します。バージョン形式の詳細はal_get_allegro_version 関数と同じです

UTF8

ここに、Unicode/UCS、特に(in particular)UTF-8エンコードに関する概略を説明します。
コードの「点」と、「文字」との関係について説明します。
pos パラメータは、文字列中の相対位置のことで、文字コードのcode pointを表示するのとは何の関係もありません。
Explain about (half-open intervals)について説明します.

Types

ALLEGRO_USTR - Allegro Uincode Strings：Allegroユニコード文字列を格納する構造体。 typedef struct ALLEGRO_USTR ALLEGRO_USTR;
ALLEGRO_USTR_INFO -Allegro Unicode Strings Information : ユニコード文字列の情報を格納する構造体。 typedef struct ALLEGRO_USTR_INFO ALLEGRO_USTR_INFO; 　

Creating and destroying strings

al_ustr_new ALLEGRO_USTR *al_ustr_new(const char *s)

引数で渡された、C言語で一般的に使われる文字列(C文字列) s のコピーからALLEGRO_USTR(Allegroユニコード文字列)を、新規作成します。使い終わったら必ず、al_ustr_free関数によって破棄しなければいけません。

al_ustr_new_from_buffer ALLEGRO_USTR *al_ustr_new_from_buffer(const char *s, size_t size)

引数で渡された、C文字列 s のコピーからAllegroユニコード文字列を、新規作成します。このとき、文字列 s のバッファサイズを size として渡します。使い終わったら必ず、al_ustr_free関数によって破棄しなければいけません。

al_ustr_newf ALLEGRO_USTR *al_ustr_newf(const char *fmt, ...)

C言語の printf関数の書式と同じ書式で、新規ユニコード文字列を作成します。 Notes:

"%s" は、 ALLEGRO_USTR 文字列ではなく、与えられたC文字列を引数に取る指示子です。そのため、どうしてもALLEGRO_USTRを渡したい場合は al_cstr関数を使って、NULL終端文字付きのC文字列に変換しなければいけません。

もし、文字列の途中にNULL文字列が合った場合、それ以降の内容は無視されるでしょう。

"%c" は、UTF-8エンコーディングされたコードではなく、1バイト文字(Single byte char)を出力する指示子です。これはACII文字(127未満の値)やその他の文字(128〜255値)を出力するためにあります。

UTF-8符号化されたコードポイント値を挿入するには、al_utf8_encode関数を使ってメモリバッファに入れてから"%s"指示子を使って下さい。このとき、バッファは、NULL文字列を返すことを忘れないでください。

al_ustr_free void al_ustr_free(ALLEGRO_USTR *us)

以前に割り当てていたAllegroユニコード文字列を破棄する。

al_cstr const char *al_cstr(const ALLEGRO_USTR *us)

渡されたユニコード文字列中のデータを指すポインタ(char *)を得る。このポインタは、参照元の文字列が変更されたり破棄されない間は有効です。

ただし、このポインタを、C文字列を引数に取る関数へ渡してしまうと、次のような警告が表示されるかもしれません：

ALLEGRO_USTRs are allowed to contain embedded NUL ('\0') bytes.
 That means al_ustr_size(u) and strlen(al_cstr(u)) may not agree.


ALLEGRO_USTRに、NULL終端文字を埋め込むことができます。
これは al_ustr_size(u)関数や strlen(al_cstr(u))関数では許されないかもしれないことを意味します。

ALLEGRO_USTRの最後尾に、NULL終端文字列が存在しない場合があるかもしれません。例えば、動的に作成される文字列の終わりには、いつもNULL終端文字列がありますが、別の文字列の途中やメモリ領域を参照している文字列は、NULL終端処理れないものがあるでしょう。

al_ustr_to_buffer void al_ustr_to_buffer(const ALLEGRO_USTR *us, char *buffer, int size)

与えられた size byteぶんの文字列の内容をあらかじめ割り当てられた buffer へ書き込みます。結果は終端文字列0 が付くでしょう。

al_cstr_dup char *al_cstr_dup(const ALLEGRO_USTR *us)

Allegorユニコード文字列のコピーから、NULL終端処理( NUL('\0') terminated )された、C文字列を複製します。返されるいかなる文字列にも、NULL終端文字が現れるでしょう。複製された文字列は、使い終わったら必ず、al_ustr_free関数によって破棄しなければいけません。

この関数は、処理に失敗したら、NULLが返ります。 [after we introduce al_free it should be freed with al_free]

al_ustr_dup ALLEGRO_USTR *al_ustr_dup(const ALLEGRO_USTR *us)

Allegroユニコード文字列のコピーから、Allegroユニコード文字列を複製します。複製された文字列が返ります。複製された文字列は、使い終わったら必ず、al_ustr_free関数によって破棄しなければいけません。

al_ustr_dup_substr ALLEGRO_USTR *al_ustr_dup_substr(const ALLEGRO_USTR *us, int start_pos, int end_pos)

Allegroユニコード文字列から、(start_pos から end_pos)の間にある内容を連結した文字列のコピーを返します。作成された文字列は、NULL終端処理され、使い終わったら必ず、al_ustr_free関数によって破棄しなければいけません。

Predefined strings

al_ustr_empty_string ALLEGRO_USTR *al_ustr_empty_string(void)

静的な空文字列を作成します。この文字列は読取り(read only)専用です

Creating strings by referencing other data

al_ref_cstr ALLEGRO_USTR *al_ref_cstr(ALLEGRO_USTR_*INFO *info, const char *s)

C文字列の参照ストレージ文字列を作成する。(例えばサイズ)に関する情報が、 info パラメータで指定したALLEGRO_USTR_INFO構造体へ記憶されます。文字列がそれ自身に割り当てられた格納領域をもっていないので、あなたがスタックにinfo構造体を割り当てるなら、明示的に"解放"作業をする必要はありません。

文字列は、参照元のC文字列が破棄されるまで有効です。

Example:
ALLEGRO_USTR_*INFO info;ALLEGRO_USTR *us = al_ref_cstr(&info, "my string");

al_ref_buffer ALLEGRO_USTR *al_ref_buffer(ALLEGRO_USTR_*INFO *info, const char *s, size_t size)

al_ref_cstr関数に、似ていますが、これは渡されたパラメータの文字列データのサイズを指定します。したがって文字列の一部やメモリの任意の領域だけに参照を行なうことができます。

文字列は、参照元のC文字列が消えるまで有効です。

al_ref_ustr ALLEGRO_USTR *al_ref_ustr(ALLEGRO_USTR_*INFO *info, const ALLEGRO_USTR *us, int start_pos, int end_pos)

別の文字列参照ストレージから、読取専用の文字列を作成します。文字列(例えばサイズ)に関する情報は、info パラメータで指定したALLEGRO_USTR_*INFO構造体へ記憶されます。文字列はそれ自身いかなる割当ても無いので、別のストリングの格納に参照をつける書き込み禁止ストリングを作成してください。ストリング(例えば、サイズ)の情報はインフォメーションパラメタによって示された構造に格納されます。文字列がそれ自身に割り当てられた格納領域をもっていないので、あなたがスタックにinfo構造体を割り当てるなら、明示的に"解放"作業をする必要はありません。

参照範囲は、(start_pos　〜 end_pos)です.

この文字列は、参照元の文字列が変更されるか破棄されるまで有効です。

Sizes and offsets

al_ustr_size size_t al_ustr_size(const ALLEGRO_USTR *us)

文字列の長さを byte数で返します。これは、空文字列か、7ビットのASCII文字群のみデータを含む場合、これは文字列のコード・ポイントの数と等しいです

al_ustr_length size_t al_ustr_length(const ALLEGRO_USTR *us)

その文字列の、コードポイント値を返します。

al_ustr_offset int al_ustr_offset(const ALLEGRO_USTR *us, int index)

文字列 us の最初のbyteを基準に index 番目にある文字のオフセット(相対位置)を返します。もし、index に 0　を指定すると、文字列の一番最初の文字が返ります。もしindesにマイナス値を指定すると、文字列の終端を基準に逆から数えられます。そのため-1は文字列中の最終文字(code point)が返ります。

もし、渡された文字列 us を構成する文字数を越える index 値が渡されても、文字列 us の最後の文字(code point)が返ります。

al_ustr_next bool al_ustr_next(const ALLEGRO_USTR *us, int *pos)

文字列 us 中の、*posの指す位置の次にある文字(code point)のオフセットbyteを検索します。なお、*posは文字列の最初の文字(code point)の位置を指している必要はありません。

成功するとtrueが返り、*posの指す位置が移動し、検索されたオフセット位置へ更新されます。反対に、*posが既に文字列の終端を指していた場合、*posの指す位置は変更されず、falseが返ります。

この関数は、単に目的のbyte位置を探すためにあります。探し出したオフセット位置が、有効な文字(code point)の始まりであるかどうかはチェックしません。もし、不正なUTF-8文字列を扱っているなら、無効な数バイトを飛ばしてしまう可能性もあります。

al_ustr_prev bool al_ustr_prev(const ALLEGRO_USTR *us, int *pos)

文字列 us 中の、*posの指す位置の直前にある文字(code point)のオフセットbyteを検索します。なお、*posは文字列の最初の文字(code point)の位置を指している必要はありません。

成功するとtrueが返り、*posの指す位置が移動し、検索されたオフセット位置へ更新されます。反対に、*posが既に文字列の終端を指していた場合、*posの指す位置は変更されず、falseが返ります。

　この関数は、単に目的のbyte位置を探すためにあります。探し出したオフセット位置が、有効な文字(code point)の始まりであるかどうかはチェックしません。もし、無効なUTF-8文字列を扱っているなら、無効な数バイトを飛ばしてしまう可能性もあります。

Getting code points

al_ustr_get int32_t al_ustr_get(const ALLEGRO_USTR *ub, int pos)

与えられたAllegroユニコード文字列 ub の最初から pos 番目にある文字(code point)を返します。

成功すると、コードポイント値(code point value)が返ります。もし、pos に範囲外(例えば文字列の終端を過ぎた)の指定を行なってしまった場合 -1を返します。無効のbyte列がある等のエラーが発生すると-2が返ります。

al_ustr_get_next int32_t al_ustr_get_next(const ALLEGRO_USTR *us, int *pos)

与えられたAllegroユニコード文字列 ub の最初から pos 番目にある文字(code point)を検索してから、次の文字(code point)を返します。

成功すると、コードポイント値(code point value)が返ります。もし、pos に範囲外(例えば文字列の終端を過ぎた)の指定を行なってしまった場合 -1を返します。無効のbyte列がある等のエラーが発生すると-2が返ります。

al_ustr_next関数によって、無効のバイト列が飛ばされていた場合、次の文字への参照結果にも隔たりが発生するかもしれません。

al_ustr_prev_get int32_t al_ustr_prev_get(const ALLEGRO_USTR *us, int *pos)

与えられたAllegroユニコード文字列 ub の最初から pos 番目の直前の文字(code point)を検索して返します。(※プリインクリメント)

成功すると、コードポイント値(code point value)が返ります。もし、pos に範囲外(例えば文字列の終端を過ぎた)の指定を行なってしまった場合 -1を返します。無効のbyte列がある等のエラーが発生すると-2が返ります。

al_ustr_next関数によって、無効のバイト列が飛ばされていた場合、直前の文字への参照結果にも隔たりが発生するかもしれません。

Inserting into strings

al_ustr_insert bool al_ustr_insert(ALLEGRO_USTR *us1, int pos, const ALLEGRO_USTR *us2)

ユニコード文字列 us1 の pos 番目の位置へ、ユニコード文字列 us2を挿入します。 posには、0未満の値を指定できません。もし、posが us1の終端を越えた範囲を指していた場合、文字列の終端からpos番目の間はNULL終端文字('\0')で埋められるでしょう。

成功した場合trueが返り、エラーだとfalseが返ります。

al_ustr_insert_cstr bool al_ustr_insert_cstr(ALLEGRO_USTR *us, int pos, const char *s)

al_ustr_insert関数と似ていますが、 al_ustr_insert_cstr関数は、C文字列を挿入します。

al_ustr_insert_chr size_t al_ustr_insert_chr(ALLEGRO_USTR *us, int pos, int32_t c)

ユニコード文字列の pos 番目の文字を起点に、文字(code point)を挿入します。posには、0未満の値を指定できません。もし、posが usの終端を越えた範囲を指していた場合、文字列の終端からpos番目の間はNULL終端文字('\0')で埋められるでしょう。

この関数は、成功すると、挿入された文字のbyte数が返り、エラーが発生した場合は0が返ります。

Appending to strings

al_ustr_append bool al_ustr_append(ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2)

ユニコード文字列us1の終端に、ユニコード文字列us2を追加する。
成功するとtrue、エラーが発生するとfalseを返します。

al_ustr_append_cstr bool al_ustr_append_cstr(ALLEGRO_USTR *us, const char *s)

ユニコード文字列us の終端に、C文字列を追加する。
成功するとtrue、エラーが発生するとfalseを返します。

al_ustr_append_chr size_t al_ustr_append_chr(ALLEGRO_USTR *us, int32_t c)

ユニコード文字列us の終端に、文字(code point)を追加する。
追加された byte数を返す、エラーが発生するとfalseを返します。

al_ustr_appendf bool al_ustr_appendf(ALLEGRO_USTR *us, const char *fmt, ...)

この関数は、ユニコード文字列usの終端に、指定された書式で文字列を追加する。 fmt には、printf形式の文字列が入ります。これについてはal_ustr_newf関数の説明にある、 "%s" と "%c" 指定子を見てください。

成功するとtrue、エラーが発生するとfalseを返します。

al_ustr_vappendf bool al_ustr_vappendf(ALLEGRO_USTR *us, const char *fmt, const va_list ap)

al_ustr_appendf関数とは違い、fmtには、文字列ではなく、数値リストを直接渡します。これについてはal_ustr_newf関数の説明にある、 "%s" と "%c" 指定子を見てください。

成功するとtrue、エラーが発生するとfalseを返します。

Removing parts of strings

al_ustr_remove_chr bool al_ustr_remove_chr(ALLEGRO_USTR *us, int pos)

ユニコード文字列の pos 番目から始まる文字(code point)を削除します。成功するとtrueを返します。

もし、posの指定する場所が、文字列の範囲外または、有効な文字コードで始まらない場合はfalseが返り、文字列は変更されません。

al_ustr_remove_range bool al_ustr_remove_range(ALLEGRO_USTR *us, int start_pos, int end_pos)

ユニコード文字列の指定範囲部分( start_pos 〜 end_pos)を削除します。start_pos と end_posは、共に文字列の範囲外をとるかもしれませんが、(文字列の最初=0)0未満の値は指定できません。

成功するとtrue、エラーが発生するとfalseを返します。

al_ustr_truncate bool al_ustr_truncate(ALLEGRO_USTR *us, int start_pos)

ユニコード文字列 us の、start_pos番目の文字より前方部分を切り取り(truncate)ます。 start_pos には、文字列の終端まで指定できますが(何の効果もないです)、(文字列の最初=0)0未満の値を指定することは出来ません。

成功するとtrue、エラーが発生するとfalseを返します。

al_ustr_ltrim_ws bool al_ustr_ltrim_ws(ALLEGRO_USTR *us)

ユニコード文字列 us から、文字列の先頭にある空白文字(leading whitspace)を削除します。これは C言語の isspace()関数によって定義されています。

成功するとtrue、関数に空文字列が渡されていた場合はfalseを返します。

al_ustr_rtrim_ws bool al_ustr_rtrim_ws(ALLEGRO_USTR *us)

文字列の前後(trailing)にあるうち、「右側」にある空白文字を削除します。これは C言語の isspace()関数によって定義されています。

成功するとtrue、関数に空文字列が渡されていた場合はfalseを返します。

al_ustr_trim_ws bool al_ustr_trim_ws(ALLEGRO_USTR *us)

文字列の先頭(leading)と前後(trailing)にある空白文字を削除します。

成功するとtrue、関数に空文字列が渡されていた場合はfalseを返します。

Assigning one string to another

al_ustr_assign bool al_ustr_assign(ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2)

ユニコード文字列us1 を別のユニコード文字列 us2で上書きします。
成功するとtrue、失敗するとfalseを返します。

al_ustr_assign_substr bool al_ustr_assign_substr(ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2, int start_pos, int end_pos)

ユニコード文字列us1 を別のユニコード文字列 us2 のstart_pos番目から end_pos 番目の範囲の部分文字列で上書きします。
なお、end point は、us2の終端に押し込められます
成功するとtrue、失敗するとfalseを返します。

al_ustr_assign_cstr bool al_ustr_assign_cstr(ALLEGRO_USTR *us1, const char *s)

ユニコード文字列 us1 をC文字列 s の内容で上書きします。
成功するとtrue、失敗するとfalseを返します。

Replacing parts of string

al_ustr_set_chr size_t al_ustr_set_chr(ALLEGRO_USTR *us, int start_pos, int32_t c)

ユニコード文字列 us の start_pos 位置の文字を、コード c で表現される文字で置き換えます。 posには、0未満の値を指定できません。もし、posがユニコード文字列usの範囲を超えた場所を指定する場合、間はNULL文字列('\0') で埋められます。

もし、posが有効な文字(code poin)から開始できない場合、エラーが発生し、文字列は変更されません。

成功すると、書き込まれたbyte数が返ります。たとえば相対的にフォローされる文字数(code point)。エラーが発生した場合、0が返ります。

al_ustr_replace_range bool al_ustr_replace_range(ALLEGRO_USTR *us1, int start_pos1, int end_pos1, const ALLEGRO_USTR *us2)

ユニコード文字列 us1の範囲(start_pos〜 end_pos)番目を別のユニコード文字列us2 で置き換えます。 start_posは0未満を指定できません。もし、start_posが文字列 us1の範囲外を指定していた場合、start_pos から end_pos間で文字列の終端から外れた部分は、NULL終端文字 ('\0') で埋められます。

成功するとtrue、エラーが発生するとfalseを返します。

Searching

al_ustr_find_chr int al_ustr_find_chr(const ALLEGRO_USTR *us, int start_pos, int32_t c)

ユニコード文字列 us の検索位置 start_pos(を含む)位置から、指定したコード c でエンコードされた文字を検索します。

見つかった位置を返します。もし何も見つからなかった場合は、-1を返します。

al_ustr_rfind_chr int al_ustr_rfind_chr(const ALLEGRO_USTR *us, int end_pos, int32_t c)

ユニコード文字列 us の検索位置 end_pos(を含まない)位置から、逆方向に、指定したコード c でエンコードされた文字を検索します。

見つかった位置を返します。もし何も見つからなかった場合は、-1を返します。

al_ustr_find_set int al_ustr_find_set(const ALLEGRO_USTR *us, int start_pos, const ALLEGRO_USTR *accept)

この関数は、ユニコード文字列 us の start_pos 番目以降を検索しユニコード文字列 accept があるかどうかを検索します。マッチした最初の文字列が該当します。

もし、見つかった場合はその位置を返します。そうでなければ-1を返します。

al_ustr_find_set_cstr int al_ustr_find_set_cstr(const ALLEGRO_USTR *us, int start_pos, const char *accept)

al_ustr_find_set関数と似ていますが、al_ustr_find_set_cstr関数は、ユニコード文字列から指定されたC文字列があるかを検索します。

al_ustr_find_cset int al_ustr_find_cset(const ALLEGRO_USTR *us, int start_pos, const ALLEGRO_USTR *reject)

この関数は、ユニコード文字列 usの、start_point番目の位置を基準に検索します。引数reject にマッチしない文字(code point)を検索します。言い換えると、マッチしない補集合を検索するのに使われます。

# 文字の全体集合(a,b,c,d,e)のうち、集合(c,d)とすると、それに当てはまらない補集合が(a,b,e)となります。おそらく、us=a,b,c,d,e 、start_pos=1 , reject=c,d の場合 b,e が返ると思われる。
見つかった位置を返します。もし何も見つからなかった場合は、-1を返します。

al_ustr_find_cset_cstr int al_ustr_find_cset_cstr(const ALLEGRO_USTR *us, int start_pos, const char *reject)

al_ustr_find_cset関数に似てますが、引数 rejectには、C文字列を渡します

al_ustr_find_str int al_ustr_find_str(const ALLEGRO_USTR *haystack, int start_pos, const ALLEGRO_USTR *needle)

ユニコード文字列 haystack のstart_pos を含む位置からユニコード文字列 needle を検索します。検索対象が発見されたオフセット位置を返します。もし何も見つからなかった場合は、-1を返します。

al_ustr_find_cstr int al_ustr_find_cstr(const ALLEGRO_USTR *haystack, int start_pos, const char *needle)

al_ustr_find_str関数と似てますが、引数 needleには、C文字列を渡します。

al_ustr_rfind_str int al_ustr_rfind_str(const ALLEGRO_USTR *haystack, int end_pos, const ALLEGRO_USTR *needle)

ユニコード文字列 haystack のend_pos を含まない位置から、逆方向に、(文字列の一番後方で)発見された needle を検索します。検索対象が発見されたオフセット位置を返します。もし何も見つからなかった場合は、-1を返します。

al_ustr_rfind_cstr int al_ustr_rfind_cstr(const ALLEGRO_USTR *haystack, int end_pos, const char *needle)

al_ustr_rfind_str関数と似てますが、引数 needleには、C文字列を渡します。

al_ustr_find_replace bool al_ustr_find_replace(ALLEGRO_USTR *us, int start_pos, const ALLEGRO_USTR *find, const ALLEGRO_USTR *replace)

ユニコード文字列 us 内の、start_posを起点に、発見されたすべての対象を置換します。検索文字列 find には空文字を指定できません。成功するとtrue、エラーの場合はfalseを返します。

al_ustr_find_replace_cstr bool al_ustr_find_replace_cstr(ALLEGRO_USTR *us, int start_pos, const char *find, const char *replace)

al_ustr_find_replace関数と似てますが、引数 find とreplace には、C文字列を渡します。

Comparing

al_ustr_equal bool al_ustr_equal(const ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2)

2つの文字列が同じであれば、trueを返します。この関数は、語順が重要ではない場合、al_ustr_compare関数を使うよりも効率的です。

al_ustr_compare int al_ustr_compare(const ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2)

この関数は、ユニコード文字列 us1 と us2 を文字コード(code point value)値で比較します。もし2つの文字列が同じなら 0が返ります。正の値が返れば us1は us2 よりも後にある文字である。そうでなければマイナス値が返ります。これはロケール固有のソーティング規則を考慮に入れません。そのためには、別のライブラリを使用する必要があるでしょう。

al_ustr_ncompare int al_ustr_ncompare(const ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2, int n)

al_ustr_compare関数に似ていますが、双方の文字列を構成する最初のコードだけを比較します。 2つの文字列が同じであれば、trueを返します。 us1 が us2より後にあるなら正の数、そうでなければマイナス値が返ります。

al_ustr_has_prefix bool al_ustr_has_prefix(const ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2)

もしユニコード文字列 us1 の最初が us2で始まる文字列(接頭詞がus2)ならtrueを返します。

al_ustr_has_prefix_cstr bool al_ustr_has_prefix_cstr(const ALLEGRO_USTR *us1, const char *s2)

もしユニコード文字列 us1 の最初が s2で始まる文字列(接頭詞がs2)ならtrueを返します。

al_ustr_has_suffix bool al_ustr_has_suffix(const ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2)

もしユニコード文字列 us1 の終わりが us2で終わる文字列(接尾詞がus2)ならtrueを返します。

al_ustr_has_suffix_cstr bool al_ustr_has_suffix_cstr(const ALLEGRO_USTR *us1, const char *s2)

もしユニコード文字列 us1 の終わりが s2で終わる文字列(接尾詞がs2)ならtrueを返します。

UTF-16 conversion

al_ustr_new_from_utf16 ALLEGRO_USTR *al_ustr_new_from_utf16(uint16_t const *s)

UTF-16形式でエンコードされた 0終端文字列を含む、新規文字列 s を作成します。文字列は、使い終えたら、al_ustr_free 関数で破棄します。

al_ustr_size_utf16

size_t al_ustr_size_utf16(const ALLEGRO_USTR *us)

UTF-16形式でエンコードされた 0終端文字列を含む文字列 s のコピーを作ります。文字列は、使い終えたら、al_ustr_free 関数で破棄します。 UTF-16形式でエンコードするのに必要なbyte数が返ります。文字列は、使い終えたら、al_ustr_free 関数で破棄します。たいていは、 al_ustr_encode_utf16関数で割り当てるデータサイズを決める前に呼び出します。

al_ustr_encode_utf16

size_t al_ustr_encode_utf16(const ALLEGRO_USTR *us, uint16_t *s,   size_t n)

与えられたUTF-16形式のバッファへ入れた文字列をエンコードします。書き出されたbyte数が返ります。パラメータ n に指定された byte数以上が返ることはありません。エンコードを完了するために最低限必要なbyte数は、 al_ustr_size_utf16関数によって得た結果が該当します。もしパラメータ nがそれより小さければ、 0終端文字列で埋められた結果が返るでしょう。　

Low-level UTF-8 routines

al_utf8_width size_t al_utf8_width(int c)

UTF-8でエンコードされたコード・ポイントを指定し、そのbyte数を返します。これは正規コード・ポイントであれば1〜4byteの値をとります。そうでなければ0が返ります。

al_utf8_encode size_t al_utf8_encode(char s[], int32_t c)

バッファ s に入れられた UTF-8文字のコードポイントをエンコードします。バッファはエンコーディングされるデータが充分入る大きさを確保しておきます(1〜4byte程度)
このルーチンは、0x10FFFF を越えるコード・ポイントのエンコードを拒絶します(UTF-8文字コードで表現可能な範囲の限界です)。
これはal_utf8_width関数と同じく、書き込まれたbyte数を返します。

Low-level UTF-16 routines

al_utf16_width size_t al_utf16_width(int c)

UTF-16でエンコードされたコード・ポイントを指定し、そのbyte数を返します。これは正規コード・ポイントであれば2〜4byteの値をとります。そうでなければ0が返ります。

al_utf16_encode size_t al_utf16_encode(uint16_t s[], int32_t c)

バッファ s に入れられた UTF-16文字のコードポイントをエンコードします。バッファはエンコーディングされるデータが充分入る大きさを確保しておきます(2〜4byte程度)
このルーチンは、0x10FFFF を越えるコード・ポイントのエンコードを拒絶します(UTF-16文字コードで表現可能な範囲の限界です)。
これはal_utf16_width関数と同じく、書き込まれたbyte数を返します。

Native dialogs support

ALLEGRO_NATIVE_FILE_DIALOG typedef struct ALLEGRO_NATIVE_FILE_DIALOG ALLEGRO_NATIVE_FILE_DIALOG;

ファイルを開いたり、保存したりする時にユーザーが使用するファイルダイアログを扱います。 WindowsにはWindows用にデザインされたファイルダイアログがあります。 MacOSXにも同じく、MacOSX用にデザインされたファイルダイアログがあります。これは、各OS固有のファイルダイアログ(以下ネイティブダイアログと呼びます)を扱うためのOpaque型構造体です。利用するには1度、ダイアログを開かせるだけです。

al_create_native_file_dialog

ALLEGRO_NATIVE_FILE_DIALOG *al_create_native_file_dialog(

    ALLEGRO_PATH const *initial_path,

    char const *title,

    char const *patterns,

    int mode)

OSネイティブのファイルダイアログを作成します。
Parameters:

initial_path: 
最初に検索するパスとファイル名 、 NULLにもできます。

title:
ダイアログウインドウに付けるタイトル。

patterns: 
セミコロンで区切られた、マッチパターンのリスト。ファイルパターンではなく、MIMEの種類が関連している場合 "." パターンを常に含むべきです。
もし、ダイアログによってサポートされるファイルパターンがなければ、そのパラメータは無視されます。

mode:
0, または下に挙げるフラグの組み合わせを指定する。

'mode'パラメータに指定可能なフラグ一覧: ネイティブダイアログが対応していれば実行されます。

ALLEGRO_FILECHOOSER_FILE_MUST_EXIST: 
新規名称の入力不可、既存ファイルを選択するためのダイアログ。 そうでなければ無視されます。

ALLEGRO_FILECHOOSER_SAVE: 
ファイル保存用のための専用ダイアログがあれば使用します。(例えば、新規ディレクトリ作成機能付) そうでなければ無視されます。 

ALLEGRO_FILECHOOSER_FOLDER: 
ファイルの代わりにフォルダを選択用のダイアログがあれば、それを使います。

ALLEGRO_FILECHOOSER_PICTURES:
画像を選択するためのダイアログが用意されていればそれを使います。なければ無視されます。

ALLEGRO_FILECHOOSER_SHOW_HIDDEN:
もしOSがサポートしているなら、不可視ファイルを見えるようにします。

ALLEGRO_FILECHOOSER_MULTIPLE: 
もしOSがこれをサポートしているなら複数ファイルを選択できるようにします。

戻り値について
ネイティブダイアログを取り扱い、表示させるために、al_show_native_file_dialogフラグを渡すと、パスを検索した結果が返ってきます。それが済んだら、al_destroy_native_file_dialog関数を呼んでオブジェクトを破棄してください。

al_show_native_file_dialog void al_show_native_file_dialog(ALLEGRO_NATIVE_FILE_DIALOG *fd)

ダイアログウインドウを表示します。この関数は、戻り値が返るまで、他のスレッドをブロックします。そのため、 al_create_thread関数でスレッドを生成するか、スレッド内で呼び出すかする必要があります。

al_get_native_file_dialog_count int al_get_native_file_dialog_count(const ALLEGRO_NATIVE_FILE_DIALOG *fc)

選択されたファイルの数を返します。もし、ダイアログをキャンセルした場合、 0が返ります。

al_get_native_file_dialog_path

const ALLEGRO_PATH *al_get_native_file_dialog_path(

   const ALLEGRO_NATIVE_FILE_DIALOG *fc, size_t i);

選択されたファイルパスのうちのひとつを返します。

al_destroy_native_file_dialog void al_destroy_native_file_dialog(ALLEGRO_NATIVE_FILE_DIALOG *fd)

ネイティブダイアログに使われた全てのリソースを解放します。ネイティブダイアログを使い終わったら必ずこの関数を使って破棄してください。

al_show_native_message_box

int al_show_native_message_box(
    char const *title, char const *text, char const *buttons,
    int flags)

ネイティブダイアログGUIのメッセージボックスを表示させます。これは、例えば最初の表示が失敗した時に、エラーメッセージを表示したい時に使われます。 ALLEGRO_DISPLAYがアクティブである(そうすることができます)限り、通常この関数を使用するべきではありません。
メッセージボックスは、OKボタンひとつと、OSネイティブのダイアログボックスが使われます。もし、ボタンパラメータをNULL以外にすると、文章がかかれた特殊なボタンになります。これらはボタンは垂直線(|)によって分割されています。

Flags	
ALLEGRO_MESSAGEBOX_WARN	   警告(Warning)に関するメッセージ。異なったアイコン表示(または何か別の効果)が起きるかもしれません。
ALLEGRO_MESSAGEBOX_ERROR	エラー(Error)に関するメッセージ 。
ALLEGRO_MESSAGEBOX_QUESTION	質問(Question)に関するメッセージ
ALLEGRO_MESSAGEBOX_OK_CANCEL	OKボタンの代わりに、キャンセルボタンを表示します。また、buttonsにNULL以外を指定すると、ボタンは無視されます。
ALLEGRO_MESSAGEBOX_YES_NO	OKボタンの代わりに Yes/No ボタンを表示させます。   buttonsにNULL以外を指定すると、ボタンは無視されます。

Returns:
* 0 ：選択肢を選ばずに、ダイアログウインドウを閉じた。
* 1 ： OK や、Yesボタンが押された。
* 2 ：Cancel や、NO ボタンが押された。

もし、buttons に複数の項目を表示(NULL以外を指定)させた場合、上の法則とは違う結果になります。
ボタンの数に応じて、返ってくる値が変わります。なお押されたボタンの番号は1から始まります。

例として、次のコードを挙げて説明します

Example:

  button = al_show_native_message_box("Fullscreen?",
     "Do you want to run this game in fullscreen mode?",
     "Never|Always|Not this time|Only this time",
     ALLEGRO_MESSAGEBOX_QUESTION);
 
 /* 日本語 */
  button = al_show_native_message_box("フルスクリーン？",
     "あなたは、フルスクリーンモードでこのゲームを実行したいですか？",
     "全くしない|いつも|今回はしない|今回だけ",
     ALLEGRO_MESSAGEBOX_QUESTION);


 /*
   *   ダイアログには、「あなたは、フルスクリーンモードでこのゲームを実行したいですか？」の文章と、
   * 「全くしない」「いつも」「今回はしない」「今回だけ」…  4つの選択ボタンが表示されるでしょう。
   *　もしボタンを押すと 変数button には、押したボタンに対応する値が返ります。左から順番に、 それぞれ 1/2/3/4 が返るでしょう。
   *   もし、選択肢を選ばずに、ウインドウを閉じた場合はbutton には0が返ります。
   */

Miscellaneous

ALLEGRO_PI #define ALLEGRO_PI 3.14159265358979323846;

C99 コンパイラは、 M_PI のような π(円周率)のマクロ定数の定義を持たないので、これをその代わりに使うことができます。 M_PIはC/C++標準の定数ではないため。例えばVisualC++ で M_PIが使えないそうです。

PhysicsFS(ｱｰｶｲﾌﾞ操作)

PhysicsFS(フィジックス -ファイルシステム)とは、Zipなど様々なアーカイブに対して、抽象アクセスを提供するためのライブラリです。詳しい情報は、http://icculus.org/physfs/ を参照して下さい。

PhysicsFSライブラリのインストールにはCmakeが必要です、またwxWidgetsも必要です。しかしwxWidgetsをインストールしてなくてインストールしたい場合、wx用のテストプログラムをビルトさせないように、CMakeLists.txtの、PHYSFS_BUILD_WX_TEST 関連の部分を削除してからCmakeでConfigureするとビルドできます。

このアドオンは、Allegroの file I/O API を通して PhysicsFSライブラリから、ファイルの読み書き(ディスク又はアーカイブ内)を可能にするものです。例えば、zipファイル内の画像であっても、I/O addon を使って普通のファイルを操作するように、それをロードさせることができるという意味です。

それには、まずPhysicsFSをセットアップする必要があります。最初に、al_set_physfs_file_interface関数を呼び出して下さい。必ずそれが済んでから al_fopen関数や、al_fopenを呼び出す他の関数を使って下さい。するとPhysicsFSアドオンを通して、ファイルをALLEGRO_FILEとして開くことができます。

al_set_physfs_file_interface void al_set_physfs_file_interface(void)

この関数を呼び出した後なら、 al_fopen呼び出しに続けて、PHYSFS_open()を操作することができます。それ以降、al_fopen関数によって返されたファイルに対する操作は、PhysicsFSを通して実行されるでしょう。

他のfile I/Oバックエンドを記憶したり、状態を元のal_fopenの機能へ戻したりするには、 al_store_state/al_restore_state関数を使って下さい。

OS固有の機能

Windows

これら関数を使いたければ

<allegro_windows.h>

をインクルードする。

al_win_get_window HWND al_win_get_window(ALLEGRO_DISPLAY *display)

固定小数点(fixed)

al_fixed

typedef int32_t al_fixed;

A fixed point number.

Allegroはまた、小数点の位置が固定された固定小数点(fixed point numbers)型の数を扱うための関数を提供し、それらは type al_fixed によって符号付き32bit 整数型として定義されます。その内部は「整数部(Integer;High-word)」と「小数部(Fraction;Low-word)」として使用され、それぞれ-32768〜32767までの範囲と小数点以下第4〜5位までの精度が与えられています。

固定小数点型の数は、割り当て(assigned)たり、比較(compared)したり、加算(added)したり、減算(subtracted)したり、符号を反転(negated)させたり、 (累乗による乗算または除算のために)ビットシフト(shifted)させることができます。

もしあなたが、他の型例えば整数か浮動小数点値と一緒に使うための変換ルーチンを作ろうとする場合、注意が必要です。

fixed_point_1 + fixed_point_2  (固定小数点型同士の加算)という書き方はOKです。
fixed_point + integer (固定小数点型+整数型)という書き方はNGです。

固定小数点型の変数と使う唯一の利点は、動作に浮動小数点コプロセッサ(FPU)を使用しないことです。これは大昔の i386とi486 を搭載する時代のPCでは、整数型変数の操作と同程度またはそれ以上の処理速度を発揮していました。
しかしPentium クラスのプロセッサが台頭してくるにつれて、この利点は薄れていきました。
あなたのプログラムが必要な演算方式に依存していて、特定のPCでの動作を目的とするなら浮動小数点型(floating point numbers)を使用するのは固定小数点型(fixed type)を使うよりも高速かもしれません。多くの埋め込み型プロセッサは、FPUを持たないので、そこで固定小数点型による手法が役立ちます。

al_itofix al_fixed al_itofix(int x);

整数型(integer) を固定小数点型(fixed point)に変換します。　これは x<<16という演算と同じです。ただし、オーバーフロー(32767より大きな整数を変換しようとすると発生し正確な計算ができなくなること。桁あふれ)、やアンダーフロー(-32768未満の数を変換しようとすると発生) などのエラーはデバッグビルド時でさえ検出されないので、使用の際には、十分注意してください。この値は単に「ラップアラウンド(wrap around)」されています。
Example:

    al_fixed number;

    /* この変換は OK  */
    number = al_itofix(100);
    assert(al_fixtoi(number) == 100);

    number = al_itofix(64000);

    /*  デバッグビルド時のチェックで失敗する  */
    assert(al_fixtoi(number) == 64000);

返り値：オーバーフローを無視した、固定小数点型に変換された整数の値。

al_fixtoi int al_fixtoi(al_fixed x);

固定小数点型を整数に変換します。必要に応じて、最も近い整数値に丸められ(rounding)ます。
丸めるとは、小数点の端数を切り上げたり、切り下げたりして、近似値で表現すること。
Example:

    int result;

    /* これは retult に33 という値が入る   */
    result = al_fixtoi(al_itofix(100) / 3);

    /* しかし、これは17 という値に丸められる */
    result = al_fixtoi(al_itofix(100) / 6);

al_fixfloor int al_fixfloor(al_fixed x);

床関数。与えられた固定小数点型(fixed) x の値未満で、最大の整数(int)値を返す。 (負の無限大になるように四捨五入)
33.3333 → 33
16.6667 → 16
Example:

	
    int result;

    /*これは retult に33 という値が入る */
    result = al_fixfloor(al_itofix(100) / 3);

    /* これは16 という値に切り下げられる */
    result = al_fixfloor(al_itofix(100) / 6);

al_fixceil int al_fixceil(al_fixed x);

天井関数。与えられた固定小数点型(fixed) x 以上で最小の整数(int)を返します。 (正の無限大になるように四捨五入)

33.3333 → 34
16.6667 → 17
Example:

    int result;

    /*これは retult に34 という値が入る  */
    result = al_fixceil(al_itofix(100) / 3);

    /* これは17 という値に切り上げられる */
    result = al_fixceil(al_itofix(100) / 6);

al_ftofix al_fixed al_ftofix(double x);

浮動小数点型(floating point)の値を固定小数点型(fixed point)に変換します。 al_itofix関数と異なり、この関数は、型変換でオーバーフローした端数を固定し、発生したAllegroのerrorno(エラー番号)をERANGEへセットします。
Example:

    al_fixed number;

    number = al_itofix(-40000);
    assert(al_fixfloor(number) == -32768);

    number = al_itofix(64000);
    assert(al_fixfloor(number) == 32767);
    assert(!al_get_errno()); /* エラーが起きるでしょう */

Return value: 浮動小数点型変数から、固定小数点型変数へ変換します。このときオーバーフローによる溢れた桁を固定し (Allegroのerrnoがセットされ)ます。

al_fixtof double al_fixtof(al_fixed x);

固定小数点型変数を浮動小数点型変数へ変換します。
Example:

    float result;

    /* result には33.33333 が入るでしょう　 */
    result = al_fixtof(al_itofix(100) / 3);

    /*  result には16.66666 が入るでしょう */
    result = al_fixtof(al_itofix(100) / 6);

al_fixmul al_fixed al_fixmul(al_fixed x, al_fixed y);

固定小数点型の値は、普通に * や / 演算子と共に整数を乗算したり除算したりすることができます。もっとも、二つの固定小数点型の値を掛け合わせるためにはこの関数を使わなければいけません。
オーバーフローが起こると、Allegroのerrnoが用意され、そして、返す事ができる最大の値を返すでしょうが、操作がうまくいった場合にはerrnoをクリアしません。これは、オーバーフロー発生しないかテストするならal_fixmul関数と呼ぶ前に、al_set_errno(0)関数を呼ぶべきであることを意味します。
Example:

	
    al_fixed result;

    /*  result には30000 が入るでしょう*/
    result = al_fixmul(al_itofix(10), al_itofix(3000));

    /* このケースではオーバーフローが起き、errono(エラー番号)がセットされます。*/
    result = al_fixmul(al_itofix(100), al_itofix(3000));
    assert(!al_get_errno());

Return value: xをyに掛けた結果を固定小数点型で返します。　オーバーフローが発生した場合 Allegroの errno に ERANGE がセットされます。

al_fixdiv al_fixed al_fixdiv(al_fixed x, al_fixed y);

普通に / 演算子を使って整数を割る事ができます。もっとも、2つの固定小数点型の値を除算するなら、この関数を使わなければいけません。ゼロ除算がが起こると、Allegroのerrnoが用意がされ、そして、返す事ができる最大の値を返すでしょうが、操作がうまくいった場合にはerrnoをクリアしません。これは、ゼロ除算が発生しないかテストするならal_fixdiv関数と呼ぶ前に、al_set_errno(0)関数を呼ぶべきであることを意味します。

Example:

	
    al_fixed result;

    /*  result には0.06060 が入るでしょう    */
    result = al_fixdiv(al_itofix(2), al_itofix(33));

    /*  result には0 が入るでしょう  */
    result = al_fixdiv(0, al_itofix(-30));

    /* エラー番号がセットされ、  resultには -32768 が入るでしょう */
    result = al_fixdiv(al_itofix(-100), al_itofix(0));
    assert(!al_get_errno()); /* This will fail. */

Return value:yをxを割るという結果を固定小数点型で返します。もしy にゼロを指定した場合、可能な限りの最大値を返し、Allegroは errno に　ERANGE を設定します。

al_fixadd al_fixed al_fixadd(al_fixed x, al_fixed y);

固定小数点型同士の加算を行います。固定小数点と整数の加算を、＋演算子を使って行う事ができますが、それはオーバーフローに対する保護がありません。オーバーフロー対策を心配するなら、あなたは代わりにこの関数を使用するべきです。整数演算子を使用するより遅いのですが、オーバーフローが起こると、Allegroのerrno が捕捉されるでしょう。 It is slower than using integer operators, but if an overflow occurs it will set Allegro's errno and clamp the result, rather than just letting it wrap.
Example:

    al_fixed result;

    /* result には5035が 入るでしょう*/
    result = al_fixadd(al_itofix(5000), al_itofix(35));

    /* エラー番号がセットされ、  resultには -32768 が入るでしょう*/
    result = al_fixadd(al_itofix(-31000), al_itofix(-3000));
    assert(!al_get_errno()); /* This will fail. */

Return value: xに y を足した結果を固定小数点型で返します。もしオーバーフローが発生した場合、Allegroは errno に　ERANGE を設定します。

al_fixsub al_fixed al_fixsub(al_fixed x, al_fixed y);

固定小数点型同士の減算を行います。固定小数点と整数の減算を、−演算子を使って行う事ができますが、それはアンダーフローに対する保護がありません。アンダーフロー対策を心配するなら、あなたは代わりにこの関数を使用するべきです。整数演算子を使用するより遅いのですが、アンダーフローが起こると、Allegroのerrno が捕捉されるでしょう。 It is slower than using integer operators, but if an overflow occurs it will set Allegro's errno and clamp the result, rather than just letting it wrap.
Example:

	
    al_fixed result;

    /*  result には4965が 入るでしょう */
    result = al_fixsub(al_itofix(5000), al_itofix(35));

    /* エラー番号がセットされ、  resultには -32768 が入るでしょう　*/
    result = al_fixsub(al_itofix(-31000), al_itofix(3000));
    assert(!al_get_errno()); /* This will fail. */

Return value: x から y を差し引いた結果を固定小数点型で返します。もしアンダーフローが発生した場合、Allegroは errno に　ERANGE を設定します。

Fixed point trig

固定小数点による平方根(square root)、sin、cos、tan、inverse sin、inverse cos関数は、とりわけ正確ではないが、とても高速な検索テーブルを実装しています。現在、inverse tan を求める場合に限り、反復的な検索を行うため、他のものより処理が遅いです。
あと原文では関数名と説明文の用語が統一されていないことがあるので注意。インバースサイン(inverse sine) = アークサイン(arc sine)。 atan() = arc tangentの意
　優れたFPUの搭載されたPC上でこれらを使う場合は、いつも遅いかもしれません。

Allegroでは角度を、バイナリ形式で正円を256、直角を64などとして表現します。この方式は、範囲ゼロの中で正円に角度を保つために、ビット演算子(bitwise) 'and' が使えるという利点があります。

al_fixtorad_r const al_fixed al_fixtorad_r = (al_fixed)1608;

この定数はバイナリ形式での角度表現で、でラジアンの固定小数点数に固定小数点数を変換するのに使用できる比率を与えます。　

Example:

    al_fixed rad_angle, binary_angle;

    /* バイナリ形式による角度で64(=90度) をセットする  */
    binary_angle = 64;

    /* 今度はそれを、 ラジアン形式( 約1.57)に変換します。 */
    rad_angle = al_fixmul(binary_angle, al_fixtorad_r);

al_radtofix_r const al_fixed al_radtofix_r = (al_fixed)2670177;

この定数はバイナリ角度形式でラジアンの固定小数点型の値を固定小数点型に変換するのに使用できる比率を与えます。　
Example:

	
    al_fixed rad_angle, binary_angle;
    ...
    binary_angle = al_fixmul(rad_angle, radtofix_r);

al_fixsin al_fixed al_fixsin(al_fixed x);

検索テーブルを使い、与えられた値に対する正弦を得ます。与えられる値は固定小数点型で、バイナリ形式での角度表現でなければいけません。
Example:

    al_fixed angle;
    int result;

    /* バイナリ形式での角度表現で  90 度をセット   */
    angle = al_itofix(64);

    /*  sin 90度 */
    result = al_fixtoi(al_fixsin(angle));
    assert(result == 1);

Return value:与えられた固定小数点型バイナリ形式の角度に対するサインを返します。　角度はラジアン形式で返るでしょう。

al_fixcos al_fixed al_fixcos(al_fixed x);

検索テーブルを使い、与えられた値に対する余弦を得ます。与えられる値は固定小数点型で、バイナリ形式での角度表現でなければいけません。
Example:

    al_fixed angle;
    float result;

    /* バイナリ形式での角度表現で  45 度をセット  */
    angle = al_itofix(32);

    /* cos45度 は約  0.7071. */
    result = al_fixtof(al_fixcos(angle));
    assert(result > 0.7 && result < 0.71);

Return value: 与えられた固定小数点型バイナリ形式の角度に対するコサインを返します。角度はラジアン形式で返るでしょう。

al_fixtan al_fixed al_fixtan(al_fixed x);

検索テーブルを使い、与えられた値に対する正接を得ます。与えられる値は固定小数点型で、バイナリ形式での角度表現でなければいけません。
Example:

    al_fixed angle, res_a, res_b;
    float dif;

    angle = al_itofix(37);
    /*   (angle) == sin(angle) / cos(angle) の証明   */
    res_a = al_fixdiv(al_fixsin(angle), al_fixcos(angle));
    res_b = al_fixtan(angle);
    dif = al_fixtof(al_fixsub(res_a, res_b));
    printf("Precision error: %f\n", dif);

Return value: 与えられた固定小数点型バイナリ角度に対するtanを返します。返り値はラジアンになるでしょう。

al_fixasin al_fixed al_fixasin(al_fixed x);

この関数は、検索テーブルで求め、与えられた値に対するインバースサインを得ます。与えられる値は固定小数点型でなければいけません。インバースサインは、 -1〜1までの領域のみ定義されます。範囲を超えた値を入力した場合はAllegroのerronoをEDOM に設定し、ゼロを返します。　
Example:

	
    float angle;
    al_fixed val;

    /* 　 `val' に バイナリ表現での直角(64)を設定する  */
    val = al_fixasin(al_itofix(1));

    /*  `angle' に 0.2405 を設定する */
    angle = al_fixtof(al_fixmul(al_fixasin(al_ftofix(0.238)), al_fixtorad_r));

    /* エラーの引き金 */
    val = al_fixasin(al_ftofix(-1.09));
    assert(!al_get_errno());

　 Return value: 固定小数点型バイナリ形式の角度に対する、インバースサインを返します。範囲外の入力は、0と認識されます。この関数のすべては、-64〜64までの値を返すでしょう。

al_fixacos al_fixed al_fixacos(al_fixed x);

この関数は、検索テーブルで求め、与えられた値に対するインバースコサインを得ます。与えられる値は固定小数点型でなければいけません。インバースコサインは、 -1〜1までの領域のみ定義されます。範囲を超えた値を入力した場合はAllegroはerronoをEDOM に設定し、ゼロを返します。
Example:

    al_fixed result;

    /* バイナリ角度表現で128をセットする  */
    result = al_fixacos(al_itofix(-1));

Return value: 固定小数点型バイナリ形式の角度に対する、インバースコサインを返します。範囲外の入力は、0と認識されます。この関数のすべては、0〜128までの値を返すでしょう。　

al_fixatan al_fixed al_fixatan(al_fixed x)

この関数は、検索テーブルで求め、与えられた値に対するインバースタンジェントを得ます。与えられる値は固定小数点型でなければいけません。　インバースタンジェントは x に逆正接する値です。　
Example:

	
    al_fixed result;

    /* バイナリ形式で 13 度 */
    result = al_fixatan(al_ftofix(0.326));

Return value: 固定小数点型のバイナリフォーマット角度 x として測定された、固定小数点型の値のインバースタンジェントを返します。

al_fixatan2 al_fixed al_fixatan2(al_fixed y, al_fixed x)

これはlibc atan2()ルーチンの固定小数点型変数対応バージョンです。それはy/xに関するアークタンジェントを計算しますが、両方の引数のサインは、結果の四分円を決定するのに使用されます、そして、xにはゼロ指定することが可能です。この機能は、極座標にデカルト座標を変換するために役に立ちます。
Example:

	
    al_fixed result;

    /* 　result  には バイナリ形式 64 度がセットされる。 */
    result = al_fixatan2(al_itofix(1), 0);

    /* result  には バイナリ形式 -109 度がセットされる。 */
    result = al_fixatan2(al_itofix(-1), al_itofix(-2));

    /* エラー発生 */
    result = al_fixatan2(0, 0);
    assert(!al_get_errno());

Return value: y/xに関するアークタンジェントを返します。与えるバイナリ角度は-128 〜128 まで。もしx、y両方とも0の場合 AllegroはerronoをEDOM に設定し、ゼロを返します。

al_fixsqrt al_fixed al_fixsqrt(al_fixed x)

これはxの負でない平方根を見つけます。 xがマイナス値ならば、 AllegroはerronoをEDOM に設定し、そして、関数はゼロを返します。

　 al_fixhypot al_fixed al_fixhypot(al_fixed x, al_fixed y)

固定小数点型変数を使い、斜辺(x*x+y*yの平方根)を返します。これは誤りがはるかに小さいので、自分で手動で公式について計算するより良いはずです。

Allegro4.9x 暫定ドキュメント

Allegro 4.9.19 (5.0)概要

Getting started guide

コンフィグ

Display画面

Display creation

Display Operation

Full Screen

Monitor

Deferred drawing

イベントオブジェクト

Time routines

タイマー

スレッド

関連用語の補足

system

State

Memory

Path

File I/O

Standard I/O specific routines

Alternative file streams

File system

ファイル操作

ディレクトリ

その他

Alternative filesystem functions

OpenGL

Primitive addon

General

High Level Drawing Routines

Low Level Drawing Routines

Transformations

Structures and Types

Mouse

Keyboard

Joystick

Graphics

Locking and pixel formats

Bitmap creation

Bitmap properties

Drawing operations

Blending mode

Clipping

Graphics utility functions

Ａudio addon

ALLEGRO_SAMPLE

ALLEGRO_AUDIO_STREAM

ALLEGRO_VOICE

Setting up

Voice functions

Sample functions

Mixer functions

Stream functions

Ａudio Codec addons

Font addons

Color addon

Image I/O addon

各フォーマット専用の関数もあります

UTF8

関連用語の補足

Types

Creating and destroying strings

Predefined strings

Creating strings by referencing other data

Sizes and offsets

Getting code points

Inserting into strings

Appending to strings

Removing parts of strings

Assigning one string to another

Replacing parts of string

Searching

Comparing

UTF-16 conversion

Low-level UTF-8 routines

Low-level UTF-16 routines

Native dialogs support

Miscellaneous

PhysicsFS(ｱｰｶｲﾌﾞ操作)