このページは、GLFW 3.5.1 公式ドキュメントを Markdown 向けに改変したものです。書式、ナビゲーション、リンクは libx 用に変更していますが、技術的内容は GLFW 3.5.1 ソース配布物に基づいています。

GLFW 2 から 3 への移行

これは GLFW 2 から 3 へ移行するためのガイドです。変更または削除された内容を説明しますが、既存のコードベースを新しい API へ移行する際に必要なものを除き、新機能は扱いません。たとえば、GLFW 3 でフルスクリーンウィンドウを作成するには、新しいマルチモニター関数が必要です。

変更・削除された機能

名前が変更されたライブラリとヘッダーファイル

GLFW 3 のヘッダーは glfw3.h という名前で GLFW ディレクトリへ移動され、ほかのメジャーバージョンのヘッダーとの衝突を避けています。同様に、GLFW 3 ライブラリの名前は glfw3, です。ただし、Unix 系システムで共有ライブラリとしてインストールされる場合は、soname libglfw.so.3 を使用します。

旧構文

#include <GL/glfw.h>

新構文

#include <GLFW/glfw3.h>

スレッド関数の削除

スレッド単位のスリープ関数を含むスレッド関数は削除されました。これらはかなり原始的で、あまり使われず、統合も不十分であり、GLFW の中心領域（コンテキスト、入力、ウィンドウ）に充てる時間を奪っていました。より優れたスレッドライブラリが存在し、普及しつつある C++11 と C11 の両方でネイティブのスレッド機能を利用できます。

C++11 または C11 の機能を使用したくてもコンパイラーがまだ対応していない場合は、GLFW の原作者が作成した TinyThread++ および TinyCThread プロジェクトを参照してください。これらのライブラリは C++11 と C11 のスレッド API の実用的なサブセットを実装しており、実際に GLFW 3 の一部のテストプログラムでも TinyCThread を使用しています。

一方、GLFW 3 は GLFW 2 よりも_複数スレッドからの使用_を適切にサポートしています。一度に 1 スレッドだけという制約はありますが、どのスレッドでもコンテキストをカレントにできます。また、どの関数を任意のスレッドから使用でき、どの関数をメインスレッドからのみ使用すべきかがドキュメントに明記されています。

削除された関数

glfwSleep, glfwCreateThread, glfwDestroyThread, glfwWaitThread, glfwGetThreadID, glfwCreateMutex, glfwDestroyMutex, glfwLockMutex, glfwUnlockMutex, glfwCreateCond, glfwDestroyCond, glfwWaitCond, glfwSignalCond, glfwBroadcastCond and glfwGetNumberOfProcessors.

削除された型

GLFWthreadfun

画像・テクスチャ読み込みの削除

画像およびテクスチャ読み込み関数は削除されました。Targa 画像形式しかサポートしておらず、主に初心者向けの例でしか役立たなかったためです。GLFW 3 に残すに値する品質にするには、ほかの形式だけでなく、OpenGL テクスチャリングの現代的な拡張もサポートする必要がありました。その場合、多数の外部依存関係（libjpeg、libpng など）を追加するか、それらのライブラリの組み込み版を GLFW に同梱することになります。

すでに同じ処理を行うライブラリがあるため、作業を重複させ、その複製を GLFW に結び付ける必要はありません。OpenGL と stdio は GLFW が利用できる場所ならどこでも利用できるため、そのようなライブラリはプラットフォーム非依存にもできます。

削除された関数

glfwReadImage, glfwReadMemoryImage, glfwFreeImage, glfwLoadTexture2D, glfwLoadMemoryTexture2D and glfwLoadTextureImage2D.

GLFWCALL マクロの削除

Windows 上でコールバック関数に __stdcall を使用させる GLFWCALL マクロは削除されました。GLFW は Pascal ではなく C で記述されています。このマクロの削除により、すべてのコールバック関数へ GLFWCALL を付ける要件をアプリケーション開発者が覚える必要がなくなります。また、@n エントリーポイント接尾辞を明示的に無効化する必要がなくなり、DLL と DLL リンクライブラリの作成も簡単になります。

旧構文

void GLFWCALL callback_function(...);

新構文

void callback_function(...);

ウィンドウハンドル引数

GLFW 3 は複数のウィンドウをサポートするため、ウィンドウ関連のすべての GLFW 関数とコールバックにウィンドウハンドル引数が追加されました。新しく作成されたウィンドウのハンドルは、以前の glfwOpenWindow に相当する glfwCreateWindow が返します。ウィンドウハンドルは、不透明型 GLFWwindow へのポインターです。

旧構文

glfwSetWindowTitle("New Window Title");

新構文

glfwSetWindowTitle(window, "New Window Title");

明示的なモニター選択

GLFW 3 は複数のモニターをサポートします。フルスクリーンモードのウィンドウを要求するには、GLFW_FULLSCREEN を渡す代わりに、ウィンドウで使用するモニターを指定します。glfwGetPrimaryMonitor 関数は GLFW 2 が選択していたモニターを返しますが、ほかにも多数のモニター関数があります。モニターハンドルは、不透明型 GLFWmonitor へのポインターです。

旧式の基本的なフルスクリーン

glfwOpenWindow(640, 480, 8, 8, 8, 0, 24, 0, GLFW_FULLSCREEN);

新式の基本的なフルスクリーン

window = glfwCreateWindow(640, 480, "My Window", glfwGetPrimaryMonitor(), NULL);

注記: glfwOpenWindow のフレームバッファビット深度引数はウィンドウヒントになりましたが、妥当なデフォルト値が指定されているため、これらのヒントを設定する必要はほとんどありません。

自動イベントポーリングの削除

GLFW 3 の glfwSwapBuffers はイベントを自動的にポーリングしないため、glfwPollEvents または glfwWaitEvents を自分で呼び出す必要があります。単一のウィンドウへ作用するバッファ交換とは異なり、イベント処理関数はすべてのウィンドウへ同時に作用します。

旧式の基本的なメインループ

while (...)
{
    // Process input
    // Render output
    glfwSwapBuffers();
}

新式の基本的なメインループ

while (...)
{
    // Process input
    // Render output
    glfwSwapBuffers(window);
    glfwPollEvents();
}

明示的なコンテキスト管理

各 GLFW 3 ウィンドウは独自の OpenGL コンテキストを持ち、どの時点でどのスレッド上のどのコンテキストをカレントにすべきかは、アプリケーション開発者だけが判断できます。そのため、GLFW 3 はこの判断を利用者に委ねます。

つまり、ウィンドウ作成後、OpenGL 関数を呼び出す前に glfwMakeContextCurrent を呼び出す必要があります。

ウィンドウサイズとフレームバッファサイズの分離

ウィンドウの位置とサイズはスクリーン座標を使用するようになりました。高 DPI モニターを備えたマシンでは、スクリーン座標とピクセルが一致しない場合があります。OpenGL はスクリーン座標ではなくピクセルを使用するため、これは重要です。たとえば、glViewport で指定する矩形にはピクセルを使用する必要があります。そのため、フレームバッファサイズ関数が追加されました。glfwGetFramebufferSize 関数でウィンドウのフレームバッファサイズを取得できます。また、glfwSetFramebufferSizeCallback で設定できるフレームバッファサイズコールバックも追加されました。

旧式の基本的なビューポート設定

glfwGetWindowSize(&width, &height);
glViewport(0, 0, width, height);

新式の基本的なビューポート設定

glfwGetFramebufferSize(window, &width, &height);
glViewport(0, 0, width, height);

ウィンドウを閉じる処理の変更

GLFW_OPENED ウィンドウ引数は削除されました。glfwDestroyWindow または glfwTerminate によって破棄されていない限り、ウィンドウは「開いて」います。

ユーザーがウィンドウを閉じようとする操作は、ほかと同様の単なるイベントになりました。GLFW 2 とは異なり、GLFW 3 で作成されたウィンドウとコンテキストは、利用者が選択しない限り破棄されません。各ウィンドウには閉じるフラグがあり、ユーザーがそのウィンドウを閉じようとすると GLFW_TRUE に設定されます。デフォルトではそれ以外の処理は行われず、ウィンドウは表示されたままです。ウィンドウを破棄するか、別の処理を行うか、要求を無視するかは利用者が決めます。

閉じるフラグは glfwWindowShouldClose でいつでも照会でき、glfwSetWindowShouldClose でいつでも設定できます。

旧式の基本的なメインループ

while (glfwGetWindowParam(GLFW_OPENED))
{
    ...
}

新式の基本的なメインループ

while (!glfwWindowShouldClose(window))
{
    ...
}

閉じるコールバックは値を返さなくなりました。代わりに、閉じるフラグが設定された後、イベント処理が完了する前に呼び出されるため、必要に応じてその値を上書きできます。ただし、閉じるコールバック（およびその他のウィンドウ関連コールバック）から glfwDestroyWindow を呼び出すことはできません。

旧構文

int GLFWCALL window_close_callback(void);

新構文

void window_close_callback(GLFWwindow* window);

注記: GLFW が閉じるフラグを GLFW_FALSE にクリアすることはありません。そのため、ゲーム内メニューでユーザーが終了を選んだ場合など、ほかの理由でウィンドウを閉じるためにも使用できます。

永続的なウィンドウヒント

glfwOpenWindowHint 関数は glfwWindowHint に改名されました。

ウィンドウヒントは、ウィンドウ作成時にデフォルト値へリセットされなくなりました。glfwWindowHint または glfwDefaultWindowHints で変更されるか、ライブラリが終了して再初期化されるまで値を保持します。

ビデオモードの列挙

ビデオモードの列挙はモニター単位になりました。glfwGetVideoModes 関数は、必要な配列サイズを推測させる代わりに、指定されたモニターで利用可能なすべてのモードを返すようになりました。動作の定義が不十分だった glfwGetDesktopMode 関数は、モニターの現在のモードを返す glfwGetVideoMode に置き換えられました。

文字アクションの削除

文字コールバックの action 引数は削除されました。これは、スウェーデン人が英語環境で開発したという GLFW の起源による名残でした。しかし、多くのキーボード配列では、発音区別符号付き文字を生成するために複数のキーが必要です。スウェーデン語キーボード配列でも、ü のような一般的でない文字には複数のキーが必要です。

旧構文

void GLFWCALL character_callback(int character, int action);

新構文

void character_callback(GLFWwindow* window, int character);

カーソル位置の変更

glfwGetMousePos 関数は glfwGetCursorPos に、glfwSetMousePos は glfwSetCursorPos に、glfwSetMousePosCallback は glfwSetCursorPosCallback に改名されました。

直接呼び出す関数とコールバックの両方で、カーソル位置は int ではなく double になりました。一部のプラットフォームはサブピクセル単位のカーソル移動を提供でき、そのデータが利用可能な場合はアプリケーションへ渡されます。提供されないプラットフォームでは、小数部は 0 になります。

GLFW 3 では、以前の glfwSetMousePos に相当する glfwSetCursorPos を使ってウィンドウ内のカーソル位置を設定できるのは、そのウィンドウがアクティブな場合だけです。ウィンドウがアクティブでなければ、この関数は何も通知せず失敗します。

ホイール位置からスクロールオフセットへの置き換え

glfwGetMouseWheel 関数は削除されました。スクロールはオフセット入力であり、絶対位置を持ちません。マウスホイールコールバックは、2 次元の浮動小数点スクロールオフセットを受け取るスクロールコールバックに置き換えられました。これにより、現代的なタッチパッドなどから精密なスクロールデータを受け取れます。

旧構文

void GLFWCALL mouse_wheel_callback(int position);

新構文

void scroll_callback(GLFWwindow* window, double xoffset, double yoffset);

削除された関数

glfwGetMouseWheel

キーリピートアクション

GLFW_KEY_REPEAT による有効化は削除され、キーと文字の両方でキーリピートが常に有効になりました。新しいキーアクション GLFW_REPEAT が追加され、キーコールバックで最初のキー押下とリピートを区別できます。glfwGetKey は引き続き GLFW_PRESS または GLFW_RELEASE だけを返すことに注意してください。

物理キー入力

GLFW 3 のキートークンは物理キーへ対応します。現在のキーボード配列が生成する値へ対応していた GLFW 2 とは異なります。トークンは標準的な米国配列での値に従って命名されていますが、これは大半の開発者がその配列を知っていると想定した便宜上のものにすぎません。つまり、たとえば GLFW_KEY_LEFT_BRACKET は常に 1 つのキーであり、プログラム利用者のキーボード配列にかかわらず、同じ位置にある同じキーです。

キー入力機能は元来テキスト入力用ではありませんが、GLFW 2 ではその用途でも多少は機能しました。テキスト入力に使用していた場合、GLFW 2 と 3 のどちらでも、代わりに文字コールバックを使用すべきです。これにより、押されたキーではなく、入力された文字を取得できます。

GLFW 3 は標準的な 105 キーキーボードのすべてのキーに対応するキートークンを持つため、a と A のどちらを検査するか覚える代わりに、GLFW_KEY_A を検査します。

ジョイスティック関数の変更

glfwGetJoystickPos 関数は glfwGetJoystickAxes に改名されました。

glfwGetJoystickParam 関数と GLFW_PRESENT、GLFW_AXES、GLFW_BUTTONS トークンは、glfwJoystickPresent 関数、および glfwGetJoystickAxes と glfwGetJoystickButtons 関数が返す軸数とボタン数に置き換えられました。

Win32 MBCS サポート

GLFW 3 の Win32 ポートは MBCS モードではコンパイルできません。ただし、Unicode 版 Win32 API の使用が影響するのは、それを使って作成されたウィンドウだけで、プロセス全体には影響しないため、同じアプリケーションの別の部分から MBCS 関数を呼び出すことは完全に可能です。したがって、GLFW を使用するアプリケーションに MBCS モードのコードがあっても、GLFW 自体がそれをサポートする必要はありません。

Windows XP より古いバージョンのサポート

Windows XP より古いバージョンに対する明示的なサポートはすべて削除されました。GLFW 3 が古いバージョン上で動作することを積極的に阻止するコードはありませんが、それらのバージョンに存在しない Win32 関数を使用します。

Windows XP は 2001 年にリリースされ、2015 年 1 月時点では、それ以前のほぼすべての Windows を置き換えただけでなく、XP 自体も Windows 7 と 8 に急速に置き換えられていました。MSDN ライブラリは Windows 2000 より古いバージョンのドキュメントさえ提供していないため、労力をかける価値があると判断しても、それらのバージョンとの互換性を維持することは困難です。

Win32 API も進化を続けており、GLFW 3 は Windows XP 以降にしか存在しない多数の関数を使用します。Windows 95 をまだサポートする GLFW 2 の視点では新しい OS である XP でさえ、現代の Windows にしか存在しない多数の関数を実行時に検査する必要があります。

システム全体のホットキーの捕捉

Alt+Tab のようなシステム全体のホットキーを無効化・捕捉する機能は削除されました。現代のアプリケーションは、ゲーム、科学的可視化、その他の用途を問わず、デスクトップの良き一員として、フルスクリーンモードで動作中でもこれらのホットキーを機能させることが期待されています。

自動終了処理

GLFW 3 は初期化時に glfwTerminate を atexit へ登録しません。exit は呼び出し元スレッドから登録済み関数を呼び出し、exit 自体は任意のスレッドから呼び出せる一方、glfwTerminate はメインスレッドからのみ呼び出さなければならないためです。

GLFW が確保したすべてのリソースを解放するには、プログラム終了前にメインスレッドから glfwTerminate を自分で呼び出してください。これにより、glfwDestroyWindow でまだ破棄されていないすべてのウィンドウが破棄され、残っているウィンドウハンドルが無効になることに注意してください。

GLU ヘッダーのインクルード

GLFW 3 はデフォルトでは GLU ヘッダーをインクルードせず、GLU 自体も Khronos によって非推奨とされています。新しいプロジェクトでは GLU を使用すべきではありません。ただし、GLFW 3 へ移行したレガシーコードで必要な場合は、GLFW ヘッダーをインクルードする前に GLFW_INCLUDE_GLU を定義し、GLFW ヘッダーに GLU をインクルードさせることができます。

旧構文

#include <GL/glfw.h>

新構文

#define GLFW_INCLUDE_GLU
#include <GLFW/glfw3.h>

GLU が提供する機能の代替となるライブラリは多数あります。行列ヘルパー関数については、GLM（C++ 向け）、linmath.h（C 向け）などの数学ライブラリを参照してください。テッセレーション関数については、たとえば libtess2 を参照してください。

名前変更表

改名された関数

改名された型

| GLFW 2 | GLFW 3 | 備考 | | ------------------- | --------------------- | | | GLFWmousewheelfun | GLFWscrollfun | | | GLFWmouseposfun | GLFWcursorposfun | |

改名されたトークン