GLFW2から3への移行ガイド 日本語訳
目次
- 削除された機能
- スレッド関数
- 画像とテクスチャのロード
- 文字アクション
- マウスホイール位置
- GLFWCALLマクロ
- Win32 MBCSのサポート
- XP以前のWindowsバージョンのサポート
- システム管理ホットキーのキャプチャ
- ウィンドウオープンのパラメータ
- イベントの自動ポーリング
- 自動終了
- GLUヘッダの読込み
- 既存機能の変更
- ウィンドウハンドル
- マルチモニタのサポート
- ウィンドウの終了
- 明示的なコンテキスト管理
- キーリビート
- 物理キー入力
- ジョイスティック入力
- ビデオモードenum
- カーソル位置
- 永続的なウィンドウヒント
- 名前の変更
これはGLFW2から3への移行ガイドです。
どんな変更や削除があったかを説明していますが、既存コードから新しいAPIへの移行時に必要な場合を除いて、新機能の説明しません。
例えば、GLFW3でフルスクリーンウィンドウを作成するために、新しいマルチモニタ関数の使用が必要です。
削除された機能
スレッド関数
スリープ関数を含め、スレッド関数は削除されました。
それらは、極めて原始的で、利用に際して統合化されておらず、GLFWの趣旨（すなわち、コンテキストや入力やウィンドウ）から外れ、時間を浪費します。
もっと良いスレッドライブラリがありますし、C++11やC11の両方にネイティブなスレッドサポートが利用可能で、それらは牽引を獲得しています。
もしC++11やC11の機能を使いたいけれどコンパイラがサポートしていない場合は、GLFWの原作者が作成しているTinyThread++やTinyCThreadプロジェクトを参照してください。
これらのライブラリは、C++11やC11のスレッドAPIの使いやすいサブセットを実装していて、実際にいくつかのGLFW3のテストプログラムではTinyCThreadを使っています。
とは言え、GLFW3は、GLFW2よりも良い、複数スレッドからの利用をサポートしています。
セカンダリスレッドから、コンテキストをカレントにしてレンダリングすることができ、ドキュメントには明示的に関数がセカンダリスレッドから利用できるか、メインスレッドつまりmainを呼び出すスレッドからの利用のみを想定しているかを記述しています。
画像とテクスチャのロード
画像とテクスチャのロード関数は削除されました。
Targa画像フォーマットのみがサポートされており、それらのほとんどが初級者レベルのサンプルに利用されています。
GLFW3でそれらを十分高い品質を保証するためには、他のフォーマットをサポートするだけでなく、OpenGLのテクスチャ機能への現代的な拡張も必要です。
それには、外部依存関係（libjpegやlibpngなど）を数多く追加したり、これらのライブラリのバージョンを固定してGLFWを出荷しなければなりません。
それを実現するためのライブラリが既にあり、この作業を重複することやGLFWへこの複製を紐付けることは不必要であると思います。
freeglutのようなGLFWに似たプロジェクトは、それらのライブラリから得ることもできます、そして、GLFWはOpenGLや標準入出力のようにどこでも利用可能であるためには、それらのライブラリのプラットフォーム依存の部分があってはいけません。
文字アクション
文字列コールバックのアクションパラメータは削除されました。これは、元々のGLFW、つまりスウェーデン人によって英国で開発していた時からありました。
けれど、多くのキーボードレイアウトでは、ダイアクリティカルマーク（発音記号）を入力するのに1つ以上のキーが必要です。
スウェーデン語キーボードでさえ、üのような稀なケースで同時押しが必要です。
文字列コールバックのアクション引数だけの削除であり、文字列コールバック自体の削除ではないことに注意してください。
マウスホイール位置
glfwGetMousWheel関数は削除されました。
スクロールイベントは絶対的な状態を表現しませんが、代わりに文字列入力のような相対的な状態変化を解釈します。
よって、文字列入力と同様に、返すための正常な“現在の状態”はありません。
マウスホイールコールバックは、スクロールコールバックに置き換えられ、2軸のスクロール量を受け取れます。
GLFWCALLマクロ
Windowsで__stdcallを使うコールバック関数を作成するGLFWCALLマクロは削除されました。
GLFWはCで書かれていて、Pascalではありません。
このマクロの削除は、GLFWユーザが覚えておくべき事項、つまり、すべてのコールバック関数をGLFWCALLでマークする必要があること、が1つ減ることを意味します。
DLLとDLLリンクライブラリの作成も単純化し、明示的に@nエントリポイント接尾語を無効にする必要がなくなります。
Win32 MBCSのサポート
GLFW3のWin32版は、MBCSモードでコンパインできなくなります。
しかし、Win32 APIのUnicode版を使えば処理全体にはまったく影響しませんし、それを用いてウィンドウ作成するだけで、同じアプリケーションの他の箇所からMBCS関数を呼び出すことも完璧にできます。
したがって、MBCSモードのコードを持つGLFWを用いたアプリショーションがあっても、GLFW自体がそれをサポートする必要はありません。
XP以前のWindowsバージョンのサポート
XP以前のWindowsバージョンの明示的なサポートは削除されました。
これらの以前のバージョンでGLFW3を動かすことを妨げるようなコードはありませんが、それらのバージョンにないWin32関数を使っています。
WindowsXPは2001年にリリースされ、現在（2013年）までにそれ以前のすべてのバージョンのWindowsを置き換えましたが、今は急速にWindows7や8に切り替えられつつあります。
MSDNライブラリはWindows2000以前のバージョンのドキュメントを既に提供していませんので、たとえ努力する価値があったとしても、これらのバージョンとの互換性を維持するのが困難になっています。
Win32 APIはまだ残っていますし、GLFW3はWindowsXP以降で利用可能な関数のみを使っています。
（Windows95をまだサポートしているGLFW2から見て新しい）XP以前のOSをサポートするとしても、最近のWindowsバージョンだけで用意されている多くの関数のためにランタイムチェックが必要となってしまいます。
システム管理ホットキーのキャプチャ
ALT+TABのようなシステム管理ホットキーを無効化して取得する機能は削除されました。
ゲームや科学的な可視化やそれ以外であっても、モダンなアプリケーションは行儀の良いデスクトップ市民であることが望まれていて、フルスクリーンモードで動作している時でさえ、これらのホットキーが機能することを期待されています。
ウィンドウオープンのパラメータ
GLFW_OPENEDウィンドウパラメータは削除されました。
ウィンドウオブジェクトが存在している限り、ウィンドウは“open”です。
ユーザがウィンドウを閉じようとしたことを検知するためには、glfwWindowShouldCloseと閉じるコールバックを参照してください。
イベントの自動ポーリング
GLFW3は、glfwSwapBuffers上でイベントの自動ポーリングを行いません。これはglfwPollEventsまたはglfwWaitEventを自分で呼び出す必要があることを意味します。
バッファスワップと異なり、イベント処理関数はすべてのウィンドウで1度だけ実行されます。
自動終了
GLFW3は、初期化時に、atexitにglfwTerminateを登録しません。
したがって、GLFWが確保したすべてのリソースを適切に解放するには、glfwTerminateを終了前に自分で呼び出さなければなりません。
GLUヘッダの読込み
GLFW3は、GLUヘッダをデフォルトでインクルードしなくなり、GLU自体が非推奨になっています。ですが、GLFW3ヘッダのインクルード前にGLFW_INCLUDE_GLUを定義しておくことで、GLFW3ヘッダがGLUをインクルードするようにできます。
既存機能の変更
Window handlesウィンドウハンドル
GLFW3はマルチウィンドウをサポートしているので、ウィンドウハンドル引数がすべてのウィンドウ関連GLFW関数とコールバックに追加されました。
新しく作成したウィンドウのハンドルは、glfwCreateWindow（以前はglfwOpenWindow）によって返されます。
ウィンドウハンドルはGLFWWindow*型で、つまり、不透明な（訳注：opaque = 実装が隠蔽された）構造体へのポインタです。
マルチモニタのサポート
GLFW3はマルチモニタサポートを提供し、GLFWmonitor*ハンドル型と関連する関数群が追加されています。
フルスクリーンモードのウィンドウを要求するには、GLFW_FULLSCREENを渡す代わりに、そのウィンドウでどのモニタを使うかを指定します。
GLFW2と同様の振る舞いを提供するために、glfwGetPrimaryMonitorがあります。
ウィンドウの終了
ウィンドウの終了は、他と同様にユーザがイベントイベントを引き起こすことで始まります。
GLFW2と異なり、GLFW3で作成されたウィンドウとコンテキストは、足元から消えたりしません。
各ウィンドウは閉じるフラグを持つようになり、それはユーザがそのウィンドウを閉じようとした時にセットされます。
デフォルトでは、何もせず、ウィンドウは開いたままで見えた状態を維持します。
そこで、そのウィンドウを破棄する、他のアクションをする、あるいはその要求を単に無視するといった処理を自分で行います。
閉じるフラグの状態をglfwWindowShouldCloseで取得することや、いつでもglfwSetWindowShouldCloseを使ってフラグをセットすることが可能です。
閉じるコールバックは、値を返さなくなりました。
代わりに、閉じるフラグがセットされた直後に呼び出されます。そして、その値を上書きすることもできます。そうする場合は、イベント処理が完了する前にそれを行います。
しかしながら、閉じるコールバックの中で（あるいは、他のウィンドウ関連コールバックで）、glfwDestoryWindowを呼び出せないかも知れません。
GLFW自体は閉じるフラグをクリアすることはありませんが、実装者はウィンドウを閉じるためにいくつかの理由でそれをセットすることが許可されています。例えば、ユーザがメインメニューから終了を選択した場合などです。
明示的なコンテキスト管理
各GLFW3ウィンドウはOpenGLコンテキストを所有しており、実装者とユーザだけが、どんなときでもスレッド上でどのコンテキストがカレントになっているべきかを知っています。
したがって、GLFW3は、そのコンテキストがいつカレントになって、いつカレントじゃなくなるか、を仮定しません。それを決定するのはあなたです。
これは、他のことと合わせて、ウィンドウを作成した後で、OpenGL関数を呼出す前に、glfwMakeContextCurrentを呼出す必要があることを意味しています。
キーリピート
GLFW_KEY_REPEATの有効化は削除され、キーリピートはキーと文字列の両方で常に有効にになっています。
キーコールバックでリピートの中から最初のキー押下を区別するために、新しいキーアクションGLFW_REPEATが追加されました。
glfwGetKeyはGLFW_PRESSまたはGLFW_RELEASEのどちらかだけを返すままであることに注意してください。
物理キー入力
GLFW2では現在のキーボード配列によって生成された値になっていましたが、それと異なり、GLFW3のキートークンは物理キーにマッピングされています。
そのトークンは、標準US配列のキーボードを用いた値と対応する名前が付けられていますが、これは便利なだけでなく、ほとんどのプログラマがキー配列を知っていると仮定されています。
（例として） GLFW_KEY_LEFT_BRACKETは常に単一のキーであり、ユーザが使うキーボード配列がどんなものでも、同じ位置にある同じキーだということを意味しています。
キー入力機器は必ずしもテキストを入力することを意味しません、GLFW2ではとりあえず動いていたのでその方法を使っていましたけれど。
テキスト入力のためにそれを使っているなら、GLFW2でも3でも、文字列入力コールバックを使わなければなりません。
押下されたキーではなく、入力された文字列が取得できます。
GLFW3では、標準的な105キーのキーボードにおけるすべてのキーのトークンが用意されていますので、文字の ’a’や’A’をチェックする代わりに、GLFW_KEY_Aをチェックしてください。
ジョイスティック入力
glfwGetJoystickPos関数はglfwGetJoystickAxesへ名前が変更されました。
glfwGetJoystickParam関数とGLFW_PRESENT、GLFW_AXES、GLFW_BUTTONSトークンは、glfwJoystickPresent関数、軸とボタンカウントを返すglfwGetJoystickAxes関数とglfwGetJoystickButtons関数に置き換えられました。
ビデオモードenum
ビデオモードenumはモニタごとの値になっています。
glfwGetVideoModes関数は、必要な配列の大きさがどれくらいかを推定する必要はなく、指定したモニタのすべての利用可能なモードを返します。
貧弱な定義された挙動をしていたglfwGetDesktopMode関数は、glfwGetVideoMode関数に変更されています。
それは、現在のモニタのモードを返します。
カーソル位置
GLFW3は、ウィンドウがアクティブな場合だけglfwSetCursorPos (以前は glfwSetMousePos)を用いて、ウィンドウ上のカーソルの位置を設定することだけが可能です。
ウィンドウがアクティブになっていない場合は、この関数は暗黙的に失敗します。
永続的なウィンドウヒント
ウィンドウヒントはウィンドウ作成時のデフォルト値へリセットされなくなりましたが、代わりに、glfwWindowHint（以前はglfwOpenWindowHint）やglfwDefaultWindowHintsによって変更されるまで、あるいはライブラリが終了して再度初期化されるまで、それらの値が維持されます。
名前の変更
ライブラリとヘッダファイル
メジャーバージョンのヘッダとの衝突を避けるため、GLFW3ヘッダはglfw3。hという名前になってGLFWディレクトリへ移動されました。
同様に、GLFW3ライブラリはglfw3という名前になっています。ただし、Unix-likeなシステムの共有ライブラリとしてインストールされた場合を除きます。その場合はlibglfw。so。3というso名が利用されます。
関数
| GLFW 2 | GLFW 3 | Notes |
glfwOpenWindow | glfwCreateWindow | すべてのチャンネルビット深度はヒントになりました |
glfwCloseWindow | glfwDestroyWindow | |
glfwOpenWindowHint | glfwWindowHint | すべてのGLFW_*_BITSトークンを受け付けるようになりました |
glfwEnable | glfwSetInputMode | |
glfwDisable | glfwSetInputMode | |
glfwGetMousePos | glfwGetCursorPos | |
glfwSetMousePos | glfwSetCursorPos | |
glfwSetMousePosCallback | glfwSetCursorPosCallback | |
glfwSetMouseWheelCallback | glfwSetScrollCallback | 2軸のスクロールオフセットをdouble型で受け取ります |
glfwGetJoystickPos | glfwGetJoystickAxes | |
glfwGetWindowParam | glfwGetWindowAttrib | |
glfwGetGLVersion | glfwGetWindowAttrib | GLFW_CONTEXT_VERSION_MAJOR， GLFW_CONTEXT_VERSION_MINOR，GLFW_CONTEXT_REVISION を使います |
glfwGetDesktopMode | glfwGetVideoMode | 現在のモニタモードを返します |
glfwGetJoystickParam | glfwJoystickPresent | 軸とボタン数は glfwGetJoystickAxes とglfwGetJoystickButtons によって提供される |
トークン
| GLFW 2 | GLFW 3 | Notes |
GLFW_OPENGL_VERSION_MAJOR | GLFW_CONTEXT_VERSION_MAJOR | OpenGL ES にも適用するために名前を変更 |
GLFW_OPENGL_VERSION_MINOR | GLFW_CONTEXT_VERSION_MINOR | OpenGL ES にも適用するために名前を変更 |
GLFW_FSAA_SAMPLES | GLFW_SAMPLES | OpenGL API に沿って名前を変更 |
GLFW_ACTIVE | GLFW_FOCUSED | ウィンドウフォーカスコールバックに合わせて名前を変更 |
GLFW_WINDOW_NO_RESIZE | GLFW_RESIZABLE | デフォルトを逆にした |
GLFW_MOUSE_CURSOR | GLFW_CURSOR | glfwSetInputModeで利用される |
GLFW_KEY_ESC | GLFW_KEY_ESCAPE | |
GLFW_KEY_DEL | GLFW_KEY_DELETE | |
GLFW_KEY_PAGEUP | GLFW_KEY_PAGE_UP | |
GLFW_KEY_PAGEDOWN | GLFW_KEY_PAGE_DOWN | |
GLFW_KEY_KP_NUM_LOCK | GLFW_KEY_NUM_LOCK | |
GLFW_KEY_LCTRL | GLFW_KEY_LEFT_CONTROL | |
GLFW_KEY_LSHIFT | GLFW_KEY_LEFT_SHIFT | |
GLFW_KEY_LALT | GLFW_KEY_LEFT_ALT | |
GLFW_KEY_LSUPER | GLFW_KEY_LEFT_SUPER | |
GLFW_KEY_RCTRL | GLFW_KEY_RIGHT_CONTROL | |
GLFW_KEY_RSHIFT | GLFW_KEY_RIGHT_SHIFT | |
GLFW_KEY_RALT | GLFW_KEY_RIGHT_ALT | |
GLFW_KEY_RSUPER | GLFW_KEY_RIGHT_SUPER | |
Last update on Wed Nov 20 2013 for GLFW 3.0.4
