SDL_pad

SDL_pad 0.1.5

SDL_pad はプリミティブすぎて少し使いにくい SDL の event の抽象層です。

ダウンロードはこちら

• 機能
• 予定機能
• 検討中
• 不具合
• リファレンス
  • 基本的な関数
  • ユーザ定義ボタン、十字キー
  • 設定ファイル制御
  • ジョイスティックの threshould
  • SDL_Event の補助
• 設定ファイル
• メモ
• 更新履歴

機能

以下のような機能を持っています。

• キーボード、マウス、ジョイスティック、SDL_QUIT をボタンとして提供
• ボタンの降下状態以外に、ボタンを押し離ししている時間を検出可
• ボタン状態を取得は init と pump さえすればいつでも使用可
• 複数ボタン入力を合成できるユーザボタン
• 4つのユーザボタンもしくはボタンによって実現されるユーザ十字ボタン
• ユーザボタン、ユーザ十字ボタン設定の保存・読込
• ジョイスティックの threshould 設定
• ボタン設定、threshould自動認識ができる設定ツール

予定機能

以下のような機能を実装する予定ですが、未実装です。

• 各ゲームで共有できる設定ファイル
• 厳しく設定ファイルを解析する機能
• SDLKey に無いキーの補完 (本家に取り込んでもらえるのがベストか)
• ジョイスティックの軸特性を吸収
• ジョイスティックのボタン特性を吸収
• 英語

検討中

以下のような機能を検討中です。

• マウスによる十字入力
• 同時入力

→さらに上のレイヤーを作ることを検討してはどうか。

不具合

以下のような不具合が存在しています。

• テストが不十分
• エラーハンドリングが不十分
• マウスのホイールが使えない

リファレンス

定数群は SDL_padconst.h に記述されています。

以下のような関数を提供します。

基本的な関数

• int Pad_Init();

初期化を行います。

SDL_Init の後に実行して下さい。 Joystick のサブシステムが Init されていなければ Init します。 存在すれば、 Joystick を二つまで Open します。

成功すれば 0 、失敗すれば -1 を返します。

• void Pad_Pump(Uint32 flags);

イベントを集めます。

イベントキューには影響を与えません。 降下時間判定を正確に行いたい場合は 1フレームに一度だけ呼出すようにして下さい。

flags は以下の定数の論理和で表現します。

PAD_PUMP_USER
PAD_PUMP_KEYBOARD
PAD_PUMP_JOYSTICK
PAD_PUMP_MOUSE
PAD_PUMP_EVENT
PAD_PUMP_EVERYTHING

• int Pad_GetButton(int id);

ボタンの降下状態を調べます。

押されているのであれば 1 以上の値を、 押されていなければ 0 以下の値を返します。 押されている時間は正の返り値の値で、 離されている時間は -(負の返り値)+1 で調べることができます。

id は SDL_padconst.h に定義されている PADK_*, PADM_*, PADJ*, PADE_* もしくはユーザボタン ID です。 これを以下ではボタン ID と総称します。

• int Pad_GetButtonPushed(int id);
• int Pad_GetButtonPressed(int id);
• int Pad_GetButtonPulled(int id);
• int Pad_GetButtonReleased(int id);

Pad_GetButton のヘルパ関数群です。

それぞれ押された瞬間、押されている、離された瞬間、離されている、 場合に 1 を、そうでない場合に 0 を返します。

ユーザ定義ボタン、十字キー

• int Pad_AddButton(int id, int addid);

ユーザボタンを登録します。

ユーザボタンには 8つまでのボタンを割当てることができます。

id はユーザボタンの ID として有効な、正または 0 の整数に限ります。 addid は PADK_*, PADM_*, PADJ*, PADE_* に限ります。

成功すれば 0 を、失敗すれば -1 を返します。

• int Pad_GetAxis(int id);

十字キーの状態を取得します。

id は十字キーの ID として有効な、正または 0 の整数を使用して下さい。

返り値は

PAD_AXIS_NONE = 0
PAD_AXIS_UP = 1
PAD_AXIS_DOWN = 2
PAD_AXIS_LEFT = 4
PAD_AXIS_RIGHT = 8
PAD_AXIS_UPLEFT =  PAD_AXIS_UP | PAD_AXIS_RIGHT
PAD_AXIS_UPRIGHT =  PAD_AXIS_UP | PAD_AXIS_LEFT
PAD_AXIS_DOWNLEFT =  PAD_AXIS_DOWN | PAD_AXIS_LEFT
PAD_AXIS_DOWNRIGHT =  PAD_AXIS_DOWN | PAD_AXIS_RIGHT

のどれかです。

• void Pad_AddAxis(int id, int upid, int rightid, int downid, int leftid);

十字キーを登録します。

id は有効な十字キーの ID です。 upid, rightid, downid, leftid は有効なボタン ID です。

• void Pad_AddAxisKeyboardArrow(int id);
• void Pad_AddAxisKeyboardRogue(int id);
• void Pad_AddAxisKeyboardWASD(int id);
• void Pad_AddAxisJoystick1(int id);
• void Pad_AddAxisJoystick2(int id);

Pad_AddAxis のヘルパ関数群です。

設定ファイル制御

• int Pad_Load(const char* file, char** bnames, char** anames);

ユーザボタンの設定ファイルを読み込みます。

設定ファイルの書式については別記します。

file は有効なファイルパス文字列です。 bnames は NULL 終端した文字列の NULL 終端した配列で、 配列のインデックスのユーザボタン ID に文字列で名前を対応させます。 anames は NULL 終端した文字列の NULL 終端した配列で、 配列のインデックスの十字ボタン ID に文字列で名前を対応させます。

成功すれば 0 を、失敗すれば -1 を返します。

• int Pad_LoadDefault(const char* file);

Pad_Load のヘルパ関数です。

bnames として

"A_BUTTON", "B_BUTTON", "C_BUTTON", "D_BUTTON", "E_BUTTON",
"UP_BUTTON", "RIGHT_BUTTON", "DOWN_BUTTON", "LEFT_BUTTON",
"END_BUTTON", NULL

が、anames として

"AXIS1", "AXIS2", NULL

が使われます。

• int Pad_LoadRW(SDL_RWops* op, char** bnames, char** anames);

Pad_Load の RWops 版です。

• int Pad_Save(const char* file, char** bnames, char** anames);
• int Pad_SoadDefault(const char* file);
• int Pad_LoadRW(SDL_RWops* op, char** bnames, char** anames);

ユーザボタンの設定ファイルを書き込みます。

引数や返り値の意味は Pad_Load* と同様です。

ジョイスティックの threshould

• void Pad_SetJoystickThreshold(int joy, int val, int axis);
• void Pad_SetJoystickThresholdUp(int joy, int val);
• void Pad_SetJoystickThresholdRight(int joy, int val);
• void Pad_SetJoystickThresholdDown(int joy, int val);
• void Pad_SetJoystickThresholdLeft(int joy, int val);

それぞれジョイスティックの threshould を設定することができます。 axis には PAD_AXIS_UP, PAD_AXIS_RIGHT, PAD_AXIS_DOWN, PAD_AXIS_LEFT の いずれかを使用して下さい。

SDL_Event の補助

基本的に SDL_Event は使わないプログラムで使うことが想定されていますが、 SDL_Event を使用する場合の補助として便利な関数なので追加しました。

• PadKey Pad_PadKeyFromEvent(SDL_Event* ev);

SDL_Event から PadKey に変換することができます。 この帰り値は switch 文内で、

case (PADK_UP):
case (PADJ1_UP):

などと記述できて便利です。

設定ファイル

設定ファイルの仕様は以下のようなものです。

各行はキーとそれに対応させる値で構成され、

<KEY_NAME> = <VAL1_NAME> <VAL2_NAME> ...
<KEY_NAME> <VAL1_NAME> <VAL2_NAME> ...
<KEY_NAME>: <VAL1_NAME>,<VAL2_NAME> ...

などと様々な方法で記述することができます。 SDL_pad としては最初の形式を推奨します。 KEY_NAME, VAL_NAME としては a-zA-Z0-9_ が有効で、 それ以外はセパレータとして認識されます。

KEY_NAME が bnames 引数に与えられている場合は、 VAL*_NAME のボタンをユーザボタンに割当てます。

KEY_NAME が anames 引数に与えられている場合は、 VAL1_NAME,VAL2_NAME,VAL3_NAME,VAL4_NAME のボタンを それぞれ 上,右,下,左 のボタンとして十字ボタンを割当てます。

KEY_NAME が PADCONFIG_ で始まっている場合は、 SDL_pad の動作を制御する特殊な指示語となります。 現状では以下のようなキーが使用可能です。

PADCONFIG_JOYSTICK_THRESHOULD_RIGHT
PADCONFIG_JOYSTICK_THRESHOULD_LEFT
PADCONFIG_JOYSTICK_THRESHOULD_UP
PADCONFIG_JOYSTICK_THRESHOULD_DOWN

以上の仕様に合致しない場合、その行は無視します。

全体としてかなり甘い認識を行っています。 これは既存の形式との整合性が取れる確率を上げる、 他の設定が混在したファイルを解析できる、 などを目的としています。 ですが、解析中に警告を生成して取得する機能や、 ファイル解析を厳しく行う機能を実装する予定です。

サンプルとして padrc というファイルが入っていますのでご参照下さい。

メモ

ここからマニュアルっぽくない雑記になります。

ご意見頂ければとても嬉しいです。

SDL_pad.c で全部 include するってやり方は 割と手軽で好きなんですけどどうなんでしょう。

LGPL ライセンスにて配布します。

misc ディレクトリの下は BSD ライセンスに従います。 今のところ D のインポートライブラリがあります。

Pad_Pump のオプションいらん気が…

Unix では $(HOME)/.sdlpadrc 、さて、 Windows では？ レジストリでファイル名指定、かな？

気がつけば Joystick number は 1 origin でボタンは 0 origin。 ひどい。

更新履歴

• 0.0.1. 試作
• 0.0.2. ジョイスティックのバグ修正。ジョイスティックの threshould 設定。autoconf, automake, libtoolize 。
• 0.1.0. threshould 保存。外部設定ツール。 D のインポートライブラリ添付。
• 0.1.1. UPLEFT と UPRIGHT が入れ替わっている問題を修正。
• 0.1.2. 20ボタンまでのジョイスティックボタンに対応。10以上のジョイスティックをさすとヘンなことになるのを修正。
• 0.1.3. padconf で軸がおかしくなる問題を修正。
• 0.1.4. マウスのボタンが使えなくなっていたので修正。
• 0.1.5. Makefile.am を修正。 C++ でも C linkage に。

home / index

全てリンクフリーです。 コード片は自由に使用していただいて構いません。 その他のものはGPL扱いであればあらゆる使用に関して文句は言いません。 なにかあれば下記メールアドレスへ。