Libx GLFW ドキュメント

    このページの内容

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

    モニターガイド

    このガイドでは、モニターに関連する GLFW の関数を紹介します。この分類の特定の関数について詳しくは、monitorを参照してください。GLFW のほかの領域についてもガイドがあります。

    モニターオブジェクト

    モニターオブジェクトは、現在接続されているモニターを表し、不透明型 GLFWmonitor へのポインターとして表現されます。アプリケーションはモニターオブジェクトを作成・破棄できません。そのアドレスは、表しているモニターが切断されるか、ライブラリが終了するまで維持されます。

    各モニターには、現在のビデオモード、サポートするビデオモードの一覧、仮想位置、人間が読める名前、推定物理サイズ、ガンマランプがあります。モニターのうち1つがプライマリモニターです。

    モニターの仮想位置はスクリーン座標で表され、現在のビデオモードとともに、接続された各モニターがそれらにまたがる仮想デスクトップに対して提供するビューポートを表します。

    GLFW がモニター構成と利用可能なビデオモードをどのように認識しているか確認するには、monitors テストプログラムを実行してください。

    モニターを取得する

    プライマリモニターは glfwGetPrimaryMonitor が返します。これはユーザーが優先するモニターであり、通常はタスクバーやメニューバーなど、システム全体の UI 要素があるモニターです。

    GLFWmonitor* primary = glfwGetPrimaryMonitor();

    glfwGetMonitors を使うと、現在接続されているすべてのモニターを取得できます。返される配列の有効期間については、リファレンスドキュメントを参照してください。

    int count;
GLFWmonitor** monitors = glfwGetMonitors(&count);

    返される配列では、プライマリモニターが常に最初のモニターです。ただし、モニターの接続・切断時に、ほかのモニターが別のインデックスへ移動することがあります。

    モニター構成の変更

    モニターが接続または切断されたときに通知を受け取りたい場合は、モニターコールバックを設定します。

    glfwSetMonitorCallback(monitor_callback);

    コールバック関数は、接続または切断されたモニターのハンドルと、発生したイベントを受け取ります。

    void monitor_callback(GLFWmonitor* monitor, int event)
{
    if (event == GLFW_CONNECTED)
    {
        // The monitor was connected
    }
    else if (event == GLFW_DISCONNECTED)
    {
        // The monitor was disconnected
    }
}

    モニターが切断されると、そのモニター上でフルスクリーンになっているすべてのウィンドウは、コールバックが呼び出される前にウィンドウモードへ切り替わります。切断されたモニターについて有用な値を返すのは glfwGetMonitorName と glfwGetMonitorUserPointer だけであり、それもモニターコールバックが処理を返すまでに限られます。

    モニターのプロパティ

    各モニターには、現在のビデオモード、サポートするビデオモードの一覧、仮想位置、コンテンツスケール、人間が読める名前、ユーザーポインター、推定物理サイズ、ガンマランプがあります。

    ビデオモード

    フルスクリーンウィンドウの作成、ビデオモードの変更、ウィンドウモードからフルスクリーンへの切り替えを行うとき、GLFW は通常、適切なビデオモードをうまく選択します。ただし、どのビデオモードがサポートされているかを正確に把握すると便利な場合があります。

    ビデオモードは GLFWvidmode 構造体で表現されます。glfwGetVideoModes を使うと、モニターがサポートするビデオモードの配列を取得できます。返される配列の有効期間については、リファレンスドキュメントを参照してください。

    int count;
GLFWvidmode* modes = glfwGetVideoModes(monitor, &count);

    モニターの現在のビデオモードを取得するには、glfwGetVideoMode を呼び出します。返されるポインターの有効期間については、リファレンスドキュメントを参照してください。

    const GLFWvidmode* mode = glfwGetVideoMode(monitor);

    ビデオモードの解像度は、ピクセルではなくスクリーン座標で指定されます。

    物理サイズ

    モニターの物理サイズまたはその推定値は、glfwGetMonitorPhysicalSize を使ってミリメートル単位で取得できます。これは現在の_解像度_、つまり現在のビデオモードの幅と高さとは関係ありません。

    int width_mm, height_mm;
glfwGetMonitorPhysicalSize(monitor, &width_mm, &height_mm);

    この値からモニターの生の DPI を計算できますが、多くの場合は有用ではありません。代わりに、モニターのコンテンツスケールとウィンドウのコンテンツスケールを使ってコンテンツを拡大・縮小してください。

    コンテンツスケール

    モニターのコンテンツスケールは glfwGetMonitorContentScale で取得できます。

    float xscale, yscale;
glfwGetMonitorContentScale(monitor, &xscale, &yscale);

    コンテンツスケールの意味と使い方について詳しくは、ウィンドウのコンテンツスケールを参照してください。

    仮想位置

    仮想デスクトップ上のモニター位置はスクリーン座標で表され、glfwGetMonitorPos で取得できます。

    int xpos, ypos;
glfwGetMonitorPos(monitor, &xpos, &ypos);

    ワークエリア

    モニターのうち、システム全体のタスクバーやメニューバーが占有していない領域をワークエリアと呼びます。これはスクリーン座標で指定され、glfwGetMonitorWorkarea で取得できます。

    int xpos, ypos, width, height;
glfwGetMonitorWorkarea(monitor, &xpos, &ypos, &width, &height);

    人間が読める名前

    モニターの UTF-8 でエンコードされた人間が読める名前は、glfwGetMonitorName が返します。返される文字列の有効期間については、リファレンスドキュメントを参照してください。

    const char* name = glfwGetMonitorName(monitor);

    モニター名が一意であることは保証されません。同じメーカーの同じモデルのモニターは、同じ名前を持つ可能性があります。一意性が保証されるのはモニターハンドルだけであり、それもそのモニターが切断されるまでに限られます。

    ユーザーポインター

    各モニターには、glfwSetMonitorUserPointer で設定し、glfwGetMonitorUserPointer で取得できるユーザーポインターがあります。任意の用途に使用でき、GLFW が変更することはありません。この値は、モニターが切断されるかライブラリが終了するまで保持されます。

    ポインターの初期値は NULL です。

    ガンマランプ

    モニターのガンマランプは glfwSetGammaRamp で設定できます。この関数はモニターハンドルと GLFWgammaramp 構造体へのポインターを受け取ります。

    GLFWgammaramp ramp;
unsigned short red[256], green[256], blue[256];

ramp.size = 256;
ramp.red = red;
ramp.green = green;
ramp.blue = blue;

for (i = 0;  i < ramp.size;  i++)
{
    // Fill out gamma ramp arrays as desired
}

glfwSetGammaRamp(monitor, &ramp);

    ガンマランプのデータは関数が処理を返す前にコピーされるため、ランプの設定後に保持する必要はありません。

    ガンマランプのサイズは、そのモニターの現在のガンマランプと同じにすることを推奨します。

    モニターの現在のガンマランプは glfwGetGammaRamp が返します。返される構造体の有効期間については、リファレンスドキュメントを参照してください。

    const GLFWgammaramp* ramp = glfwGetGammaRamp(monitor);

    通常のガンマランプを設定したい場合は、glfwSetGamma に希望する指数を渡すと GLFW が計算します。この関数は、生成したランプを使って glfwSetGammaRamp を呼び出します。

    glfwSetGamma(monitor, 1.0);

    glfwSetGamma 関数を使ったガンマ補正を試すには、gamma テストプログラムを実行してください。

    注: ソフトウェア制御のガンマランプは、ハードウェアのガンマ補正に_加えて_適用されます。現在のハードウェア補正は通常、sRGB ガンマの近似です。したがって、完全に線形なランプ、すなわちガンマ 1.0 を設定すると、デフォルトの（通常は sRGB に似た）動作になります。

    注: Wayland: アプリケーションはモニターのガンマランプを読み取りまたは変更できません。glfwGetGammaRamp、glfwSetGammaRamp、glfwSetGamma の各関数は GLFW_FEATURE_UNAVAILABLE を通知します。