Libx GLFW ドキュメント

    このページの内容

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

    API入門

    このガイドでは GLFW の基本概念を紹介し、初期化、エラー処理、API の保証と制限について説明します。広範な内容を簡潔に学ぶチュートリアルについては、代わりに quick_guideを参照してください。この分類の特定の関数について詳しくは、initを参照してください。

    GLFW のほかの領域についてもガイドがあります。

    初期化と終了

    ほとんどの GLFW 関数を呼び出す前に、ライブラリを初期化しなければなりません。この初期化では、マシンで利用可能な機能の確認、モニターの列挙、タイマーの初期化、必要なプラットフォーム固有の初期化が行われます。

    ライブラリの初期化に成功する前に呼び出せるのは、次の関数だけです。また、いずれもメインスレッドからのみ呼び出せます。

    初期化に成功する前にこれら以外の関数を呼び出すと、GLFW_NOT_INITIALIZED エラーが発生します。

    GLFWを初期化する

    ライブラリは glfwInit で初期化します。エラーが発生した場合、この関数は GLFW_FALSE を返します。

    if (!glfwInit())
{
    // Handle initialization failure
}

    初期化の一部が失敗すると、成功した部分は glfwTerminate が呼ばれた場合と同様に終了処理されます。ライブラリの初期化は1回だけでよく、初期化済みのライブラリをさらに初期化しようとすると、直ちに GLFW_TRUE が返ります。

    ライブラリの初期化に成功したら、アプリケーションが終了する前にライブラリを終了するべきです。現代のシステムは終了したプログラムが割り当てたリソースを適切に解放しますが、GLFW はシステム全体の設定を変更することがあり、終了処理をしないと元に戻らない可能性があります。

    macOS: ライブラリを初期化すると、メインメニューと Dock アイコンが作成されます。コマンドライン専用プログラムには望ましくありません。GLFW_COCOA_MENUBAR 初期化ヒントを使うと、メインメニューと Dock アイコンの作成を無効にできます。

    初期化ヒント

    初期化ヒントは glfwInit より前に設定し、ライブラリが終了するまでの動作に影響します。ヒントは glfwInitHint で設定します。

    glfwInitHint(GLFW_JOYSTICK_HAT_BUTTONS, GLFW_FALSE);

    設定したヒントの値が GLFW によってリセットされることはありませんが、値が反映されるのは初期化中だけです。GLFW の初期化後に設定した値は、ライブラリを終了して再び初期化するまで無視されます。

    一部のヒントはプラットフォーム固有です。これらはどのプラットフォームでも設定できますが、対応するプラットフォームだけに影響し、ほかのプラットフォームでは無視されます。設定にプラットフォーム固有のヘッダーや関数は必要ありません。

    共通の初期化ヒント

    GLFW_PLATFORM は、ウィンドウ処理と入力に使うプラットフォームを指定します。指定できる値は GLFW_ANY_PLATFORM、GLFW_PLATFORM_WIN32、GLFW_PLATFORM_COCOA、GLFW_PLATFORM_WAYLAND、GLFW_PLATFORM_X11、GLFW_PLATFORM_NULL です。デフォルト値は GLFW_ANY_PLATFORM で、ライブラリがサポートするプラットフォームのうち Null バックエンド以外から選択します。

    GLFW_JOYSTICK_HAT_BUTTONS は、glfwGetJoystickHats がなかった以前の GLFW バージョンとの互換性のため、ジョイスティックのハットをボタンとしても公開するかどうかを指定します。指定できる値は GLFW_TRUE と GLFW_FALSE です。

    GLFW_ANGLE_PLATFORM_TYPE は、ANGLE を介して OpenGL ES と EGL を使うときに要求するプラットフォームの種類（描画バックエンド）を指定します。要求したプラットフォームの種類を利用できない場合、ANGLE はデフォルトを使います。指定できる値は GLFW_ANGLE_PLATFORM_TYPE_NONE、GLFW_ANGLE_PLATFORM_TYPE_OPENGL、GLFW_ANGLE_PLATFORM_TYPE_OPENGLES、GLFW_ANGLE_PLATFORM_TYPE_D3D9、GLFW_ANGLE_PLATFORM_TYPE_D3D11、GLFW_ANGLE_PLATFORM_TYPE_VULKAN、GLFW_ANGLE_PLATFORM_TYPE_METAL のいずれかです。

    ANGLE のプラットフォームの種類は、EGL_ANGLE_platform_angle 拡張を介して指定されます。このヒントがデフォルト値の GLFW_ANGLE_PLATFORM_TYPE_NONE の場合、この拡張は使われません。

    macOS固有の初期化ヒント

    GLFW_COCOA_CHDIR_RESOURCES は、アプリケーションのバンドルに Contents/Resources サブディレクトリがある場合、アプリケーションのカレントディレクトリをそこへ設定するかどうかを指定します。指定できる値は GLFW_TRUE と GLFW_FALSE です。ほかのプラットフォームでは無視されます。

    GLFW_COCOA_MENUBAR は、GLFW の初期化時にメニューバーと Dock アイコンを作成するかどうかを指定します。メニューバーを nib から作成する場合と GLFW が手動で作成する場合の両方に適用されます。指定できる値は GLFW_TRUE と GLFW_FALSE です。ほかのプラットフォームでは無視されます。

    Wayland固有の初期化ヒント

    GLFW_WAYLAND_LIBDECOR は、利用可能な場合にウィンドウ装飾へ libdecor を使うかどうかを指定します。指定できる値は GLFW_WAYLAND_PREFER_LIBDECOR と GLFW_WAYLAND_DISABLE_LIBDECOR です。ほかのプラットフォームでは無視されます。

    X11固有の初期化ヒント

    GLFW_X11_XCB_VULKAN_SURFACE は、Vulkan サーフェスの作成に VK_KHR_xcb_surface 拡張を優先するか、VK_KHR_xlib_surface 拡張を使うかを指定します。指定できる値は GLFW_TRUE と GLFW_FALSE です。ほかのプラットフォームでは無視されます。

    サポートされる値とデフォルト値

    初期化ヒントデフォルト値サポートされる値
    GLFW_PLATFORMGLFW_ANY_PLATFORMGLFW_ANY_PLATFORM、GLFW_PLATFORM_WIN32、GLFW_PLATFORM_COCOA、GLFW_PLATFORM_WAYLAND、GLFW_PLATFORM_X11、GLFW_PLATFORM_NULL のいずれか
    GLFW_JOYSTICK_HAT_BUTTONSGLFW_TRUEGLFW_TRUE または GLFW_FALSE
    GLFW_ANGLE_PLATFORM_TYPEGLFW_ANGLE_PLATFORM_TYPE_NONEGLFW_ANGLE_PLATFORM_TYPE_NONE、GLFW_ANGLE_PLATFORM_TYPE_OPENGL、GLFW_ANGLE_PLATFORM_TYPE_OPENGLES、GLFW_ANGLE_PLATFORM_TYPE_D3D9、GLFW_ANGLE_PLATFORM_TYPE_D3D11、GLFW_ANGLE_PLATFORM_TYPE_VULKAN、GLFW_ANGLE_PLATFORM_TYPE_METAL のいずれか
    GLFW_COCOA_CHDIR_RESOURCESGLFW_TRUEGLFW_TRUE または GLFW_FALSE
    GLFW_COCOA_MENUBARGLFW_TRUEGLFW_TRUE または GLFW_FALSE
    GLFW_WAYLAND_LIBDECORGLFW_WAYLAND_PREFER_LIBDECORGLFW_WAYLAND_PREFER_LIBDECOR または GLFW_WAYLAND_DISABLE_LIBDECOR
    GLFW_X11_XCB_VULKAN_SURFACEGLFW_TRUEGLFW_TRUE または GLFW_FALSE

    実行時のプラットフォーム選択

    GLFW は、複数のプラットフォーム（ウィンドウシステム）向けに同時にコンパイルできます。これにより、単一のライブラリバイナリで、Linux やその他の Unix 系システム上の Wayland と X11 の両方をサポートできます。

    GLFW_PLATFORM 初期化ヒントを介して、プラットフォーム選択を制御できます。デフォルトでは GLFW_ANY_PLATFORM に設定されます。これは、サポートされるウィンドウシステムを優先順位に従って探し、最初に見つかったものを選択します。特定のプラットフォームを設定し、それだけを GLFW に検索させることもできます。

    glfwInitHint(GLFW_PLATFORM, GLFW_PLATFORM_X11);

    この仕組みは Null プラットフォームも提供します。Null プラットフォームは常にサポートされますが、明示的に要求する必要があります。このプラットフォームは実質的にはスタブであり、単一の 1080p モニター上でウィンドウシステムを模倣しますが、実際のウィンドウシステムとは一切やり取りしません。

    glfwInitHint(GLFW_PLATFORM, GLFW_PLATFORM_NULL);

    glfwPlatformSupported を使うと、ライブラリバイナリが特定のプラットフォームのサポートを組み込んでコンパイルされたかどうかを検査できます。

    if (glfwPlatformSupported(GLFW_PLATFORM_WAYLAND))
    glfwInitHint(GLFW_PLATFORM, GLFW_PLATFORM_WAYLAND);

    GLFW の初期化後は、glfwGetPlatform で選択されたプラットフォームを取得できます。

    int platform = glfwGetPlatform();

    特に Linux やその他の Unix 系システムでネイティブアクセス関数を使う場合は、選択されたプラットフォームに対応する関数を呼んでいることを確認する必要があるかもしれません。

    ヒープメモリアロケーターを独自に指定する

    初期化前に glfwInitAllocator を使うと、ヒープメモリアロケーターを独自に指定できます。

    GLFWallocator allocator;
allocator.allocate = my_malloc;
allocator.reallocate = my_realloc;
allocator.deallocate = my_free;
allocator.user = NULL;

glfwInitAllocator(&allocator);

    アロケーターは初期化の開始時に有効になり、ライブラリが完全に終了するまで GLFW によって使われます。初期化後に設定したアロケーターは、次回の初期化時に初めて反映されます。

    このアロケーターが使われるのは、C 標準ライブラリで行われるはずだったメモリ割り当てだけです。プラットフォーム固有 API で行わなければならないメモリ割り当てには、引き続きその API が使われます。

    割り当て関数は GLFWallocatefun と一致するシグネチャでなければなりません。希望するバイト単位のサイズと、glfwInitAllocator に渡したユーザーポインターを受け取り、割り当てたメモリブロックのアドレスを返します。

    void* my_malloc(size_t size, void* user)
{
    ...
}

    GLFWallocatefun のドキュメントには、割り当て関数の要件と制限も記載されています。有効な関数がそのすべてを満たさない場合、GLFW が失敗する可能性があります。

    再割り当て関数は GLFWreallocatefun と一致する関数シグネチャでなければなりません。再割り当てするメモリブロック、新しく希望するバイト単位のサイズ、glfwInitAllocator に渡したユーザーポインターを受け取り、サイズ変更後のメモリブロックのアドレスを返します。

    void* my_realloc(void* block, size_t size, void* user)
{
    ...
}

    GLFWreallocatefun のドキュメントには、再割り当て関数の要件と制限も記載されています。有効な関数がそのすべてを満たさない場合、GLFW が失敗する可能性があります。

    解放関数は GLFWdeallocatefun と一致する関数シグネチャでなければなりません。解放するメモリブロックと、glfwInitAllocator に渡したユーザーポインターを受け取ります。

    void my_free(void* block, void* user)
{
    ...
}

    GLFWdeallocatefun のドキュメントには、解放関数の要件と制限も記載されています。有効な関数がそのすべてを満たさない場合、GLFW が失敗する可能性があります。

    GLFWを終了する

    GLFW ライブラリを初期化した場合は、アプリケーションが終了する前にライブラリを終了するべきです。これは glfwTerminate で行います。

    glfwTerminate();

    これにより、残っているウィンドウ、モニター、カーソルの各オブジェクトが破棄され、変更されたガンマランプが元に戻り、無効化されていた場合はスクリーンセーバーが再び有効になり、GLFW が割り当てたその他のリソースが解放されます。

    ライブラリを終了すると、一度も初期化されていなかった状態に戻ります。そのため、GLFW を再び使うにはもう一度初期化する必要があります。ライブラリが初期化されていない場合や、すでに終了している場合は、直ちに処理を返します。

    エラー処理

    一部の GLFW 関数はエラーを示す戻り値を持ちますが、何が起きたのか、なぜ起きたのかを調べるには役立たないことがよくあります。ほかの関数ではエラー用の戻り値が予約されていないため、エラー通知に別の経路が必要です。さらに、すべての GLFW 関数が戻り値を持つわけでもありません。

    呼び出し元スレッドで最後に発生したエラーコードは、いつでも glfwGetError で取得できます。

    int code = glfwGetError(NULL);

if (code != GLFW_NO_ERROR)
    handle_error(code);

    前回の呼び出し以降にエラーが発生していない場合は、GLFW_NO_ERROR（0）が返ります。エラーは関数が処理を返す前にクリアされます。

    エラーコードはエラーの大まかな分類を示します。GLFW_NOT_INITIALIZED のように意味が1つしかないエラーコードもあれば、GLFW_PLATFORM_ERROR のように多くの異なるエラーに使われるものもあります。

    GLFW は、エラーの大まかな分類より詳しい情報を持っていることがよくあります。エラーコードとともに、UTF-8 でエンコードされた人間が読める説明を取得できます。前回の呼び出し以降にエラーが発生していない場合、説明には NULL が設定されます。

    const char* description;
int code = glfwGetError(&description);

if (description)
    display_error_message(code, description);

    取得した説明文字列が有効なのは、次のエラーが発生するまでです。保持する必要がある場合はコピーしなければなりません。

    エラーが発生するたびに呼ばれるエラーコールバックを設定することもできます。glfwSetErrorCallback で設定します。

    glfwSetErrorCallback(error_callback);

    エラーコールバックは、glfwGetError が返すものと同じエラーコードと人間が読める説明を受け取ります。

    void error_callback(int code, const char* description)
{
    display_error_message(code, description);
}

    エラーコールバックはエラーの保存後に呼び出されます。そのため、エラーコールバック内で glfwGetError を呼び出すと、コールバック引数と同じ値が返ります。

    コールバックへ渡された説明文字列が有効なのは、エラーコールバックが処理を返すまでです。保持する必要がある場合はコピーしなければなりません。

    通知されるエラーが致命的になることはありません。 GLFW の初期化に成功していれば、発生するエラーの数にかかわらず、終了するまで初期化済みかつ安全な状態を保ちます。初期化中にエラーが発生して glfwInit が失敗した場合は、初期化されたライブラリの部分がすべて安全に終了処理されます。

    現在は無効な呼び出しが特定のエラーを生成することに依存しないでください。将来、同じ呼び出しが別のエラーを生成したり、有効になったりする可能性があります。

    座標系

    GLFW には、仮想スクリーン_と、ウィンドウの_コンテンツ領域（単に_コンテンツ領域_とも呼びます）という2つの主要な座標系があります。どちらも同じ単位、すなわち_仮想スクリーン座標_（単に_スクリーン座標_とも呼びます）を使います。この単位がピクセルと一致するとは限りません。

    仮想スクリーンとコンテンツ領域のどちらの座標系でも、X 軸は右方向、Y 軸は下方向を指します。

    ウィンドウとモニターの位置は、それぞれのコンテンツ領域の左上隅を仮想スクリーンに対して指定します。一方、カーソル位置はウィンドウのコンテンツ領域を基準に指定します。

    ウィンドウのコンテンツ領域座標系の原点は、ウィンドウ位置の指定基準となる点でもあるため、コンテンツ領域座標にウィンドウ位置を加えると仮想スクリーン座標へ変換できます。ウィンドウフレームがある場合、フレームはコンテンツ領域から外側へ広がりますが、ウィンドウ位置には影響しません。

    GLFW のほぼすべての位置とサイズは、上記2つの原点のいずれかを基準とするスクリーン座標で測定されます。これには、カーソル位置、ウィンドウの位置とサイズ、ウィンドウフレームのサイズ、モニター位置、ビデオモードの解像度が含まれます。

    例外は、ミリメートルで測定するモニターの物理サイズと、ピクセルで測定するフレームバッファサイズの2つです。

    使用中のマシンではピクセルとスクリーン座標が 1:1 で対応するかもしれませんが、Retina ディスプレイ搭載 Mac など、ほかのすべてのマシンで対応するとは限りません。スクリーン座標とピクセルの比率は、ウィンドウがどのモニター上にあるとみなされるかに応じて、実行時に変化することもあります。

    保証と制限

    この節では、オペレーティングシステムやドライバーのバグを除き、GLFW の動作を期待できる条件について説明します。この制限を外れて GLFW を使った場合、一部のプラットフォーム、マシン、状況、GLFW バージョンでは動作するかもしれませんが、いつ動かなくなっても不思議ではなく、それはバグとはみなされません。

    ポインターの有効期間

    GLFW が、利用者から渡されたポインターを解放することはありません。また、GLFW から渡されたポインターを利用者が解放してはなりません。

    多くの GLFW 関数は、動的に割り当てられた構造体、文字列、配列へのポインターを返します。また、一部のコールバックには文字列や配列が渡されます。これらは常に GLFW が管理するため、アプリケーションが解放してはいけません。各ポインターの有効期間は、GLFW の各関数とコールバックのドキュメントに記載されています。このデータを保持する必要がある場合は、有効期間が終了する前にコピーしなければなりません。

    多くの GLFW 関数は、アプリケーションが割り当てた構造体や文字列へのポインターを受け取ります。これらを GLFW が解放することはなく、常にアプリケーション側の責任となります。GLFW がこれらの構造体や文字列内のデータを保持する必要がある場合は、関数が処理を返す前にコピーされます。

    将来のマイナーリリースまたはパッチリリースで、ポインターの有効期間が短縮されることはありません。

    再入可能性

    GLFW のイベント処理とオブジェクト破棄は再入可能ではありません。つまり、次の関数はどのコールバック関数からも呼び出してはなりません。

    これらの関数は将来のマイナーリリースまたはパッチリリースで再入可能になるかもしれませんが、この一覧にない関数が再入不能へ変更されることはありません。

    スレッドセーフ性

    ほとんどの GLFW 関数はメインスレッド（main を呼び出すスレッド）からのみ呼び出せますが、ライブラリの初期化後は任意のスレッドから呼び出せる関数もあります。初期化前はライブラリ全体がスレッドセーフではありません。

    GLFW の各関数のリファレンスドキュメントには、メインスレッドに制限されるかどうかが記載されています。

    1つまたは複数のプラットフォームの制限により、初期化、終了、イベント処理、およびウィンドウ、カーソル、OpenGL コンテキスト、OpenGL ES コンテキストの作成と破棄は、すべてメインスレッドに制限されます。

    イベント処理はメインスレッドで行わなければならないため、エラーコールバック以外のすべてのコールバックは、そのスレッド上でのみ呼び出されます。どの GLFW 関数もエラーを生成する可能性があるため、エラーコールバックは任意のスレッドで呼び出される可能性があります。

    エラーコードと説明は任意のスレッドから取得できます。

    空イベントは任意のスレッドから送信できます。

    ウィンドウのユーザーポインターとクローズフラグは任意のスレッドから読み書きできますが、GLFW はこれらを同期しません。

    OpenGL および OpenGL ES コンテキストを扱う次の関数は任意のスレッドから呼び出せますが、GLFW はウィンドウオブジェクトを同期しません。

    生のタイマー関数は任意のスレッドから呼び出せます。

    通常のタイマーは任意のスレッドから使えますが、GLFW はタイマーのオフセットの読み書きを同期しません。

    ライブラリのバージョン情報は任意のスレッドから取得できます。

    プラットフォーム情報は任意のスレッドから取得できます。

    Vulkan 関連の関数はすべて任意のスレッドから呼び出せます。

    GLFW が内部で同期オブジェクトを使うのは、スレッド単位のコンテキスト状態とエラー状態を管理するためだけです。追加の同期はアプリケーション側で行います。

    現在任意のスレッドから呼び出せる関数は、今後も常にその性質を保ちます。一方、現在メインスレッドに制限されている関数は、将来のリリースで任意のスレッドから呼び出せるよう更新される可能性があります。

    バージョン互換性

    GLFW はセマンティックバージョニングを使います。これにより、以前のマイナーバージョンの API に対するソースとバイナリの後方互換性が保証されます。つまり、より新しいバージョンのライブラリへ置き換えても、既存のプログラムは引き続きコンパイルでき、既存のバイナリも引き続き実行できます。

    関数または定数が一度追加されると、その関数のシグネチャまたは定数の値は、GLFW の次のメジャーバージョンまで変更されません。メジャーバージョン間では、いかなる互換性も保証されません。

    ドキュメントに記載されていない動作は、記載されるまでいつでも変更される可能性があります。

    リファレンスドキュメントと実装が異なる場合、ほぼ常にリファレンスドキュメントが優先され、実装が次のリリースで修正されます。また、ガイドの記述よりもリファレンスドキュメントが優先されます。

    イベントの順序

    関連するイベントが到着する順序は、プラットフォーム間で一貫することが保証されません。例外は合成されたキーとマウスボタンの解放イベントで、これらは常にウィンドウのフォーカス喪失イベントの後に配信されます。

    バージョン管理

    GLFW は、アプリケーションのコンパイル対象となった GLFW のバージョンと、現在実行に使っているバージョンを識別する仕組みを提供します。GLFW を動的に読み込む場合（単に動的リンクする場合ではありません）は、これを使ってライブラリバイナリがアプリケーションと互換性を持つか検証できます。

    コンパイル時のバージョン

    GLFW のコンパイル時バージョンは、GLFW ヘッダーの GLFW_VERSION_MAJOR、GLFW_VERSION_MINOR、GLFW_VERSION_REVISION マクロで提供されます。

    printf("Compiled against GLFW %i.%i.%i\n",
       GLFW_VERSION_MAJOR,
       GLFW_VERSION_MINOR,
       GLFW_VERSION_REVISION);

    実行時のバージョン

    実行時バージョンは glfwGetVersion で取得できます。この関数は GLFW が初期化済みかどうかにかかわらず呼び出せます。

    int major, minor, revision;
glfwGetVersion(&major, &minor, &revision);

printf("Running against GLFW %i.%i.%i\n", major, minor, revision);

    バージョン文字列

    GLFW 3 は、バージョン、プラットフォーム、コンパイラ、プラットフォーム固有のコンパイル時オプションを説明する、コンパイル時に生成されたバージョン文字列も提供します。これは主にバグ報告の提出を目的としており、バイナリでどのコードパスが有効かを開発者が確認できるようにします。

    バージョン文字列は glfwGetVersionString が返します。この関数は GLFW が初期化済みかどうかにかかわらず呼び出せます。

    GLFW ライブラリのバージョンを解析するために、バージョン文字列を使わないでください。 実行中のライブラリバイナリのバージョンは、glfwGetVersion 関数ですでに取得できます。

    サポートされるプラットフォームを解析するために、バージョン文字列を使わないでください。 glfwPlatformSupported 関数でプラットフォームのサポートを照会できます。

    GLFW 3.4: 実行時のプラットフォーム選択の追加に対応するため、この文字列の形式が変更されました。

    文字列の形式は次のとおりです。

    • GLFW のバージョン
    • サポートされる各プラットフォームについて:
      • ウィンドウシステム API の名前
      • 該当する場合、ウィンドウシステム固有のコンテキスト作成 API の名前
    • 常にサポートされるコンテキスト作成 API である EGL と OSMesa の名前
    • その他のコンパイル時オプション、API、および（Windows の場合）使用したコンパイラ

    たとえば GLFW 3.5 を MinGW-64 で Windows 用 DLL としてコンパイルすると、次のようなバージョン文字列になる場合があります。

    3.5.0 Win32 WGL Null EGL OSMesa MinGW-w64 DLL

    Wayland と X11 の両方を有効にして GLFW を Linux 用の静的ライブラリとしてコンパイルすると、次のようなバージョン文字列になる場合があります。

    3.5.0 Wayland X11 GLX Null EGL OSMesa monotonic