mimi_sdl開発ガイド
必須の処理
開始処理/終了処理
mimi_sdl_init_all()で、すべてのSDLライブラリが初期化されます。
/************************************************ * NAME: mimi_sdl_init_all * DESC: 総初期化処理 * RETN: MIMI_SDL_OK --- 成功 * MIMI_SDL_NG --- 失敗 ************************************************/ mimi_sdl_res mimi_sdl_init_all();
mimi_sdl_init()やmimi_sdl_audio_init()などで、特定のライブラリのみを初期化することもできますが、使う機会はほとんど無いでしょう。
終了する場合は、mimi_sdl_quit_all()を使用します。
/************************************************ * NAME: mimi_sdl_quit_all * DESC: 総終了処理 ************************************************/ void mimi_sdl_quit_all();
メイン処理関数
mimi_sdlでは通常のmain()関数の他にメインの処理関数を用意します。
メイン処理関数の名前は任意ですが、引数や関数の型は決まっています。
- 引数 void*
- 型 int
メイン処理関数を作成したら、mimi_sdl_main()の引数にセットします。
/************************************************ * NAME: mimi_sdl_main * DESC: アプリケーションメイン関数の設定 * ARGS: function --- メイン関数 * data --- メイン関数引数 ************************************************/ void mimi_sdl_main(int (*function)(void *), void *data);
少し分かりにくいので、例を示します。
#include "mimi_sdl.h"
int gamemain(void* pointer);
/************************************************
* NAME: main
* DESC: アプリケーションメイン
* ARGS: argc --- 引数の数
* argv --- 引数
* RETN: 0
************************************************/
int main(int argc, char* argv[]){
/* SDL起動 */
mimi_sdl_init_all();
/* メイン処理を開始する */
/* (イベントループが開始されます) */
mimi_sdl_main(gamemain, NULL);
/* SDL終了 */
mimi_sdl_quit_all();
return 0;
}
/************************************************
* NAME: gamemain
* DESC: ゲームメイン関数
* ARGS: pointer --- 引数
* RETN: 0
************************************************/
int gamemain(void* pointer){
/* 省略 */
return 0;
}
gamemain()というのが、メイン処理関数です。この関数をmimi_sdl_main()の第一引数に、gamemain()の引数をmimi_sdl_main()の第二引数にセットします。
これにより、mimi_sdl_main()からgamemain()が呼び出されます。このとき、バックグラウンドでイベントループが動きますので、ウインドウの閉じるボタンを押されたときの処理などを書く手間が省けます。また、キーボード入力待ち関数が使用できるようになります。
なお、メイン処理関数を抜ける場合は、必ずイベントループ停止関数を呼んでください。
/************************************************ * NAME: mimi_sdl_stop_events * DESC: イベントループ停止処理 ************************************************/ void mimi_sdl_stop_events();
よって先ほど示したプログラムは次のように書かなければなりません。
#include "mimi_sdl.h"
int gamemain(void* pointer);
/************************************************
* NAME: main
* DESC: アプリケーションメイン
* ARGS: argc --- 引数の数
* argv --- 引数
* RETN: 0
************************************************/
int main(int argc, char* argv[]){
/* SDL起動 */
mimi_sdl_init_all();
/* メイン処理を開始する */
/* (イベントループが開始されます) */
mimi_sdl_main(gamemain, NULL);
/* SDL終了 */
mimi_sdl_quit_all();
return 0;
}
/************************************************
* NAME: gamemain
* DESC: ゲームメイン関数
* ARGS: pointer --- 引数
* RETN: 0
************************************************/
int gamemain(void* pointer){
/* 省略 */
mimi_sdl_stop_events();
return 0;
}
ここまででmimi_sdlを使うに当たっての必須事項の説明が終了しました。
以降、mimi_sdlの便利な関数群を説明していきます。
mimi_sdl関数群
キー入力待ち関数
入力されたキーがSDLKeyの形で返されます。
/************************************************ * NAME: mimi_sdl_wait_key * DESC: キーボード入力待ちイベント * この関数が呼ばれてから押されたキーを * 取得する。 * RETN: 押されたSDLKey ************************************************/ SDLKey mimi_sdl_wait_key();
画像表示
外部の画像ファイルを画面上に表示します。
/************************************************ * NAME: mimi_sdl_show_image * DESC: イメージ表示処理 * ARGS: filename --- イメージファイル * x --- X座標 * y --- Y座標 ************************************************/ void mimi_sdl_show_image(char* filename, int x, int y);
画像ファイルは、bmp, pnm, png, jpg, xpm, lbm, pcx, gif, tga, tiffに対応しています。
座標はピクセル単位の左上基準。画面は左上が0,0です。
例えばimage.pngというファイルを左上に表示したい場合は次のようにします。
mimi_sdl_show_image("image.png", 0, 0);
画面クリア処理
任意の色で画面をクリアします。
/************************************************ * NAME: mimi_sdl_cls * DESC: サーフェスクリア処理 * ARGS: r --- 赤強度(0-255) * g --- 緑強度(0-255) * b --- 青強度(0-255) ************************************************/ void mimi_sdl_cls(unsigned char r, unsigned char g, unsigned b);
例えば青でクリアしたい場合は次のようにします。
mimi_sdl_cls(0, 0, 255);
デフォルトフォント設定
外部のフォントをデフォルトフォントに設定します。
/************************************************ * NAME: mimi_sdl_open_default_font * DESC: デフォルトフォントオープン処理 * ARGS: font --- フォント * size --- フォントサイズ * RETN: MIMI_SDL_OK --- 成功 * MIMI_SDL_NG --- 失敗 ************************************************/ mimi_sdl_res mimi_sdl_open_default_font(char* filename, int size);
設定されたフォントはmimi_sdl_print()などで使用されます。
テキスト表示処理
テキストを画面に表示します。テキスト情報以外にも色や表示位置も指定できるものがあります。
/************************************************ * NAME: mimi_sdl_print * DESC: テキスト表示処理 * ARGS: text, ... --- テキスト * NOTE: 書き込む座標、文字色、フォントはそれぞれ * mimi_sdl_locate * mimi_sdl_set_textcolor * mimi_sdl_set_default_font * で指定する。 ************************************************/ void mimi_sdl_print(char* text, ...);
/************************************************ * NAME: mimi_sdl_println * DESC: テキスト表示処理(改行処理付き) * ARGS: text, ... --- テキスト * NOTE: 書き込む座標、文字色、フォントはそれぞれ * mimi_sdl_locate * mimi_sdl_set_textcolor * mimi_sdl_set_default_font * で指定する。 ************************************************/ void mimi_sdl_println(char* text, ...);
/************************************************ * NAME: mimi_sdl_print_with_location * DESC: テキスト表示処理 * ARGS: x --- X座標 * y --- Y座標 * text, ... --- テキスト * NOTE: 文字色、フォントはそれぞれ * mimi_sdl_set_textcolor * mimi_sdl_set_default_font * で指定する。 ************************************************/ void mimi_sdl_print_with_location(int x, int y, char* text, ...);
/************************************************ * NAME: mimi_sdl_print_with_rgb * DESC: テキスト表示処理 * ARGS: text, ... --- テキスト * NOTE: 書き込む座標、フォントはそれぞれ * mimi_sdl_locate * mimi_sdl_set_default_font * で指定する。 ************************************************/ void mimi_sdl_print_with_rgb(unsigned char r, unsigned char g, unsigned b, char* text, ...);
/************************************************ * NAME: mimi_sdl_println_with_rgb * DESC: テキスト表示処理(改行処理付き) * ARGS: text, ... --- テキスト * NOTE: 書き込む座標、フォントはそれぞれ * mimi_sdl_locate * mimi_sdl_set_default_font * で指定する。 ************************************************/ void mimi_sdl_println_with_rgb(unsigned char r, unsigned char g, unsigned b, char* text, ...);
/************************************************ * NAME: mimi_sdl_print_with_color * DESC: テキスト表示処理 * ARGS: text, ... --- テキスト * NOTE: 書き込む座標、フォントはそれぞれ * mimi_sdl_locate * mimi_sdl_set_default_font * で指定する。 ************************************************/ void mimi_sdl_print_with_color(SDL_Color color, char* text, ...);
/************************************************ * NAME: mimi_sdl_print_with_color * DESC: テキスト表示処理(改行処理付き) * ARGS: text, ... --- テキスト * NOTE: 書き込む座標、フォントはそれぞれ * mimi_sdl_locate * mimi_sdl_set_default_font * で指定する。 ************************************************/ void mimi_sdl_println_with_color(SDL_Color color, char* text, ...);
/************************************************ * NAME: mimi_sdl_print_with_all_parameters * DESC: テキスト表示処理 * ARGS: font --- フォントオブジェクト * color --- 表示色 * x --- X座標 * y --- Y座標 * text, ... --- テキスト ************************************************/ void mimi_sdl_print_with_all_parameters(TTF_Font* font, SDL_Color color, int x, int y, char* text, ...);
hello worldと出力するには次のようにします。
mimi_sdl_print("hello world");
また、printf()で使うような書式を利用して変数を表示することも可能です。
mimi_sdl_print("%d + %d = %d", 1, 2, 1 + 2);
色、表示位置は別関数からも設定することができます。
/************************************************ * NAME: mimi_sdl_set_textcolor * DESC: テキスト色設定処理 * ARGS: r --- 赤強度(0-255) * g --- 緑強度(0-255) * b --- 青強度(0-255) ************************************************/ void mimi_sdl_set_textcolor(unsigned char r, unsigned char g, unsigned b);
/************************************************ * NAME: mimi_sdl_locate * DESC: カーソル位置設定処理 * ARGS: x --- X座標 * y --- Y座標 ************************************************/ void mimi_sdl_locate(int x, int y);
座標はピクセル単位、左上が0,0です。
改行処理について
mimi_sdl_println()などの関数では、文末で自動改行します。
改行後の開始位置は、横は文頭の位置(mimi_sdl_locate()などで指定したx座標の位置)、縦はフォントサイズを基準とした高さになります。
この行高さはフォントサイズに対する倍率としてmimi_sdl_set_line_height_ratio()で設定できます。
/************************************************ * NAME: mimi_sdl_set_line_height_ratio * DESC: 行高さの設定 * ARGS: ratio --- 行高さの倍率(1:フォントと同じ) ************************************************/ void mimi_sdl_set_line_height_ratio(double ratio);
デフォルトは1.5です。
音楽再生/停止
ファイル名を指定して、音楽の再生/停止をします。音楽は自動リピートします。
/************************************************ * NAME: mimi_sdl_play_music * DESC: 音楽再生処理 * ARGS: ファイル名 * RETN: MIMI_SDL_OK --- 成功 * MIMI_SDL_NG --- 失敗 ************************************************/ mimi_sdl_res mimi_sdl_play_music(char* filename);
/************************************************ * NAME: mimi_sdl_stop_music * DESC: 音楽停止処理 ************************************************/ void mimi_sdl_stop_music();
音量調整
/************************************************ * NAME: mimi_sdl_volume_music * DESC: 音楽音量設定 * ARGS: volume --- 音量(0 - 128) ************************************************/ void mimi_sdl_volume_music(int volume);
スリープ
指定時間プログラムを止めます。バックグラウンドの処理は続行します。
/************************************************ * NAME: mimi_sdl_sleep * DESC: スリープ処理 * ARGS: スリープ時間(ミリ秒) ************************************************/ void mimi_sdl_sleep(int arg);
ウインドウタイトル設定
/************************************************ * NAME: mimi_sdl_set_title * DESC: ウインドウタイトル設定 * ARGS: title --- ウインドウタイトル ************************************************/ void mimi_sdl_set_title(char* title);
効果音再生/停止 (proto-2 以降)
効果音を再生します。
/************************************************ * NAME: mimi_sdl_play_sound * DESC: 効果音再生処理 * ARGS: channel --- チャンネル * filename --- ファイル名 * RETN: MIMI_SDL_OK --- 成功 * MIMI_SDL_NG --- 失敗 ************************************************/ mimi_sdl_res mimi_sdl_play_sound(int channel, char* filename);
効果音の再生にはファイル名とチャンネルを使用します。チャンネルを変えることにより、別の効果音を同時に再生できます。複数の音声をかぶせて再生するということも可能です。
使用できるチャンネル数は、mimi_sdl_count_total_sound_channels()で取得します。
/************************************************ * NAME: mimi_sdl_count_total_sound_channels * DESC: 合計チャンネル数取得 * RETN: 合計チャンネル数 ************************************************/ int mimi_sdl_count_total_sound_channels();
例えば、mimi_sdl_count_total_sound_channels()で8が返されたら、チャンネルは0から7までの数字を指定することができます。
チャンネル数のデフォルトは8です。これを変更するには、mimi_sdl_init_all()を呼ぶ前に、mimi_sdl_set_total_sound_channels()で設定してください。
/************************************************ * NAME: mimi_sdl_set_total_sound_channels * DESC: 効果音のチャンネル数を設定する * ARGS: channels --- チャンネル数 * NOTE: mimi_sdl_audio_init(), mimi_sdl_init_all() * を呼ぶ前に呼ぶこと。 * デフォルトは8 ************************************************/ void mimi_sdl_set_total_sound_channels(int channels);
効果音はループせずにそのまま停止します。
途中で停止させたい場合は、mimi_sdl_stop_sound()で停止させます。
/************************************************ * NAME: mimi_sdl_stop_sound * DESC: 効果音停止処理 * ARGS: channel --- チャンネル(-1で全チャンネル) * RETN: MIMI_SDL_OK --- 成功 * MIMI_SDL_NG --- 失敗 ************************************************/ mimi_sdl_res mimi_sdl_stop_sound(int channel);
周波数について
デフォルトは22050Hzとなっています。変更する場合は、mimi_sdl_init_all()の前に、mimi_sdl_set_audio_frequency()を使用します。
/************************************************ * NAME: mimi_sdl_set_audio_frequency * DESC: オーディオの周波数を設定する * ARGS: frequency --- 周波数 * NOTE: mimi_sdl_audio_init(), mimi_sdl_init_all() * を呼ぶ前に呼ぶこと。 * 周波数のデフォルトは 22050 Hz ************************************************/ void mimi_sdl_set_audio_frequency(int frequency);
マウスイベント (proto-3 以降)
マウスボタンを押したときのイベントとマウスボタンを離したときのイベントの2つをキャッチします。
/************************************************ * NAME: mimi_sdl_wait_mouse_down * DESC: マウスボタン押下待ちイベント * この関数が呼ばれてから押されたボタンと * その位置を取得する。 * ARGS: *x --- ボタンが押されたx座標の位置 * *y --- ボタンが押されたy座標の位置 * RETN: 押されたSDL_BUTTON * (SDL_BUTTON_LEFT, * SDL_BUTTON_MIDDLE, * SDL_BUTTON_RIGHT, * SDL_BUTTON_WHEELUP, * SDL_BUTTON_WHEELDOWN) ************************************************/ int mimi_sdl_wait_mouse_down(int* x, int* y);
/************************************************ * NAME: mimi_sdl_wait_mouse_up * DESC: マウスボタン押下待ちイベント * この関数が呼ばれてから離されたボタンと * その位置を取得する。 * ARGS: *x --- ボタンが離されたx座標の位置 * *y --- ボタンが離されたy座標の位置 * RETN: 押されたSDL_BUTTON * (SDL_BUTTON_LEFT, * SDL_BUTTON_MIDDLE, * SDL_BUTTON_RIGHT, * SDL_BUTTON_WHEELUP, * SDL_BUTTON_WHEELDOWN) ************************************************/ int mimi_sdl_wait_mouse_up(int* x, int* y);
mimi_sdl_wait_key()と同じく、マウスのボタンが押される/離されるまで処理が戻りません。
レイヤー機能 (proto-4 以降)
mimi_sdlでは複数の画像(SDL_Surface)をレイヤーという形で保持できます。
レイヤーへのアクセスはインデックスを用いて行います。(デフォルト0 ～ 7)
画面に描画する際は、インデックス0から順に描画されます。使用していないレイヤーや、非表示設定のレイヤーは描画されません。
レイヤーへの画像のセット
mimi_sdl_put_image_on_layer()を使います。
/************************************************ * NAME: mimi_sdl_put_image_on_layer * DESC: レイヤーに画像を配置する * ARGS: file --- ファイル名 * index --- レイヤーインデックス * x --- 横位置 * y --- 縦位置 * RETN: MIMI_SDL_OK --- 成功 * MIMI_SDL_NG --- 失敗 ************************************************/ mimi_sdl_res mimi_sdl_put_image_on_layer(char* file, int index, int x, int y);
レイヤーに画像を配置します。すでにレイヤーが存在する場合は、そのレイヤーのx,yの位置に新たに画像を配置します。レイヤーが存在しない場合は作成します。
xとyはレイヤー上の座標であり、レイヤーそのものの画面に対する座標でないことに注意してください。
レイヤーの描画
mimi_sdl_show_all_layers()で全レイヤーの描画が行われます。
/************************************************ * NAME: mimi_sdl_show_all_layers * DESC: レイヤー描画処理 * ARGS: index --- インデックス ************************************************/ void mimi_sdl_show_all_layers();
非表示設定されているレイヤーは描画されません。
特定のレイヤーを描画するには、mimi_sdl_show_layer()を使います。
/************************************************ * NAME: mimi_sdl_show_layer * DESC: レイヤー描画処理 * ARGS: index --- インデックス ************************************************/ void mimi_sdl_show_layer(int index);
おなじく、非表示設定されているレイヤーは描画されません。
レイヤーの表示、非表示設定
mimi_sdl_set_layer_visible()で設定します。
/************************************************ * NAME: mimi_sdl_set_layer_visible * DESC: レイヤー表示/非表示設定 * ARGS: index --- インデックス * flag --- 表示/非表示 ************************************************/ void mimi_sdl_set_layer_visible(int index, mimi_sdl_flag flag);
デフォルトは全レイヤーMIMI_SDL_FLAG_ON(表示)です。
レイヤー数の設定
/************************************************ * NAME: mimi_sdl_set_layer_size * DESC: レイヤーサイズ設定 * ARGS: size --- サイズ * NOTE: mimi_sdl_init()等を呼ぶ前に呼ぶこと。 ************************************************/ void mimi_sdl_set_layer_size(int size);
mimi_sdlを開始する前(mimi_sdl_init()などを呼ぶ前)に呼んでください。
デフォルトは8(インデックスとして0～7が設定可能)です。
レイヤーインデックス交換
/************************************************ * NAME: mimi_sdl_exchange_layer_index * DESC: レイヤーインデックス交換 * ARGS: index1 --- インデックス1 * index2 --- インデックス2 * NOTE: MIMI_SDL_OK --- 成功 * MIMI_SDL_NG --- 失敗 ************************************************/ mimi_sdl_res mimi_sdl_exchange_layer_index(int index1, int index2);
レイヤーインデックス(レイヤーの上下。画面から見たら、前に表示されるか、後ろに表示されるか)を入れ替えます。
レイヤー塗りつぶし処理
/************************************************ * NAME: mimi_sdl_paint_layer * DESC: レイヤー塗りつぶし処理 * ARGS: index --- インデックス * r --- 赤強度(0-255) * g --- 緑強度(0-255) * b --- 青強度(0-255) * NOTE: MIMI_SDL_OK --- 成功 * MIMI_SDL_NG --- 失敗 ************************************************/ mimi_sdl_res mimi_sdl_paint_layer(int index, unsigned char r, unsigned char g, unsigned b);
レイヤーを指定された色で塗りつぶします。
レイヤー位置設定
/************************************************ * NAME: mimi_sdl_set_layer_pos * DESC: レイヤーポジション設定 * ARGS: index --- インデックス * x --- x座標 * y --- y座標 * NOTE: MIMI_SDL_OK --- 成功 * MIMI_SDL_NG --- 失敗 ************************************************/ mimi_sdl_res mimi_sdl_set_layer_pos(int index, int x, int y);
画面に対する、レイヤーの位置を設定します。
レイヤーテキスト描画処理
指定されたレイヤーにテキストを描画する処理です。
/************************************************ * NAME: mimi_sdl_print_on_layer * DESC: テキストレイヤーセット処理 * ARGS: index --- レイヤーインデックス * text, ... --- テキスト * NOTE: 書き込む座標、文字色、フォントはそれぞれ * mimi_sdl_locate * mimi_sdl_set_textcolor * mimi_sdl_set_default_font * で指定する。 ************************************************/ void mimi_sdl_print_on_layer(int index, char* text, ...);
/************************************************ * NAME: mimi_sdl_print_on_layer_with_location * DESC: テキストレイヤーセット処理 * ARGS: index --- レイヤーインデックス * x --- X座標 * y --- Y座標 * text, ... --- テキスト * NOTE: 文字色、フォントはそれぞれ * mimi_sdl_set_textcolor * mimi_sdl_set_default_font * で指定する。 ************************************************/ void mimi_sdl_print_on_layer_with_location(int index, int x, int y, char* text, ...);
/************************************************ * NAME: mimi_sdl_print_on_layer_with_color * DESC: テキストレイヤーセット処理 * ARGS: index --- レイヤーインデックス * color --- 色 * text, ... --- テキスト * NOTE: 書き込む座標、フォントはそれぞれ * mimi_sdl_locate * mimi_sdl_set_default_font * で指定する。 ************************************************/ void mimi_sdl_print_on_layer_with_color(int index, SDL_Color color, char* text, ...);
/************************************************ * NAME: mimi_sdl_print_on_layer_with_rgb * DESC: テキストレイヤーセット処理 * ARGS: index --- レイヤーインデックス * r --- 赤強度(0 - 255) * g --- 緑強度(0 - 255) * b --- 青強度(0 - 255) * text, ... --- テキスト * NOTE: 書き込む座標、フォントはそれぞれ * mimi_sdl_locate * mimi_sdl_set_default_font * で指定する。 ************************************************/ void mimi_sdl_print_on_layer_with_rgb(int index, unsigned char r, unsigned char g, unsigned b, char* text, ...);
/************************************************ * NAME: mimi_sdl_print_on_layer_with_color * DESC: テキストレイヤーセット処理(改行処理付き) * ARGS: index --- レイヤーインデックス * color --- 色 * text, ... --- テキスト * NOTE: 書き込む座標、フォントはそれぞれ * mimi_sdl_locate * mimi_sdl_set_default_font * で指定する。 ************************************************/ void mimi_sdl_println_on_layer_with_color(int index, SDL_Color color, char* text, ...);
/************************************************ * NAME: mimi_sdl_println_on_layer_with_rgb * DESC: テキストレイヤーセット処理(改行処理付き) * ARGS: index --- レイヤーインデックス * r --- 赤強度(0 - 255) * g --- 緑強度(0 - 255) * b --- 青強度(0 - 255) * text, ... --- テキスト * NOTE: 書き込む座標、フォントはそれぞれ * mimi_sdl_locate * mimi_sdl_set_default_font * で指定する。 ************************************************/ void mimi_sdl_println_on_layer_with_rgb(int index, unsigned char r, unsigned char g, unsigned b, char* text, ...);
注意) mimi_sdl_print_on_layer()の書き始めの座標は、mimi_sdl_locate()で設定された座標となりますが、この場合の座標は、画面上の座標ではなく、レイヤー上の座標となります。また、mimi_sdl_print_on_layer_with_location()で指定するx,y座標もレイヤー上の座標です。ご注意ください。
レイヤー破棄
/************************************************ * NAME: mimi_sdl_drop_layer * DESC: レイヤーを破棄する * ARGS: index --- レイヤーインデックス ************************************************/ void mimi_sdl_drop_layer(int index);
指定されたインデックスのレイヤーを破棄します。
(レイヤー上の情報が消えるだけで、レイヤー数が減るわけではありません。
その他定義について
列挙体について
C言語の列挙体なので、正体はunsigned intですが、以下の値がセットされることが想定されています。
mimi_sdl_res
- MIMI_SDL_OK --- 成功/TRUE/OK
- MIMI_SDL_NG --- 失敗/TRUE/NG
mimi_sdl_flag
- MIMI_SDL_FLAG_ON --- はい/TRUE/ON
- MIMI_SDL_FLAG_OFF --- いいえ/FALSE/OFF
これら以外の関数について
これら以外にも関数を用意してありますが、機能不十分で使いにくいです。その辺は今後修正していきます。
