このリファレンスページは、GLFW 3.5.1 公式ドキュメントを Markdown 向けに改変したものです。書式、ナビゲーション、リンクは libx 用に変更していますが、技術的内容は GLFW 3.5.1 ソース配布物に基づいています。
説明
これは Vulkan 関連の関数と型のリファレンスドキュメントです。作業目的に沿った情報については、Vulkan ガイドを参照してください。
型定義 |
|
| typedef void(* | GLFWvkproc) (void) |
| Vulkan API 関数ポインター型。 |
|
関数 |
|
| int | glfwVulkanSupported (void) |
| Vulkan ローダーと ICD が見つかったかどうかを返します。 |
|
| const char ** | glfwGetRequiredInstanceExtensions (uint32_t *count) |
| GLFW が必要とする Vulkan インスタンス拡張を返します。 |
|
| GLFWvkproc | glfwGetInstanceProcAddress (VkInstance instance, const char *procname) |
| 指定された Vulkan インスタンス関数のアドレスを返します。 |
|
| int | glfwGetPhysicalDevicePresentationSupport (VkInstance instance, VkPhysicalDevice device, uint32_t queuefamily) |
| 指定されたキューファミリーがイメージを表示できるかどうかを返します。 |
|
| VkResult | glfwCreateWindowSurface (VkInstance instance, GLFWwindow *window, const VkAllocationCallbacks *allocator, VkSurfaceKHR *surface) |
| 指定されたウィンドウ用の Vulkan サーフェスを作成します。 |
|
型定義の詳細
◆ GLFWvkproc
| typedef void(* GLFWvkproc) (void) |
通常のポインターからのキャストを強制せずに Vulkan API 関数ポインターを返すために使用する、汎用関数ポインターです。
関連項目
Vulkan 関数ポインターの照会
導入バージョン
バージョン 3.2 で追加されました。
関数の詳細
◆ glfwVulkanSupported()
| int glfwVulkanSupported | ( | void | ) |
この関数は、Vulkan ローダーと、最低限機能するいずれかの ICD が見つかったかどうかを返します。
Vulkan ローダーや ICD が利用可能であっても、それだけではサーフェス作成やインスタンス作成が可能であるとは保証されません。Vulkan サーフェス作成に必要な拡張が利用可能かを確認するには glfwGetRequiredInstanceExtensions を、物理デバイスのキューファミリーがイメージ表示をサポートするかを確認するには glfwGetPhysicalDevicePresentationSupport を呼び出してください。
戻り値
Vulkan が最低限利用可能な場合は GLFW_TRUE、それ以外の場合は GLFW_FALSE。
エラー
発生する可能性のあるエラーには、GLFW_NOT_INITIALIZED があります。
スレッドセーフ性
この関数は、どのスレッドからでも呼び出せます。
関連項目
Vulkan サポートの照会
導入バージョン
バージョン 3.2 で追加されました。
◆ glfwGetRequiredInstanceExtensions()
| const char ** glfwGetRequiredInstanceExtensions | ( | uint32_t * | count | ) |
この関数は、GLFW ウィンドウ用の Vulkan サーフェスを作成するために GLFW が必要とする Vulkan インスタンス拡張名の配列を返します。成功した場合、リストには必ず VK_KHR_surface が含まれます。そのため、追加の拡張が不要であれば、このリストを VkInstanceCreateInfo 構造体へ直接渡せます。
マシン上で Vulkan が利用できない場合、この関数は NULL を返し、GLFW_API_UNAVAILABLE エラーを生成します。Vulkan が最低限利用可能かを確認するには、glfwVulkanSupported を呼び出してください。
Vulkan は利用可能でも、ウィンドウサーフェス作成を可能にする拡張の組み合わせが見つからない場合、この関数は NULL を返します。その場合でも、オフスクリーンレンダリングや計算処理には Vulkan を使用できます。
引数
| [out] | count | 戻り値の配列に含まれる拡張数を格納する場所。エラーが発生した場合は 0 に設定されます。 |
戻り値
ASCII エンコードされた拡張名の配列。エラーが発生した場合は NULL。
エラー
発生する可能性のあるエラーには、GLFW_NOT_INITIALIZED、GLFW_API_UNAVAILABLE があります。
備考
将来の GLFW バージョンでは、追加の拡張が必要になる可能性があります。VkInstanceCreateInfo 構造体で同じ拡張を複数回指定するとエラーになるため、有効化したい拡張が戻り値の配列にすでに含まれていないか確認してください。
ポインターの有効期間
戻り値の配列は GLFW によって確保および解放されます。自分で解放してはいけません。ライブラリが終了するまでのみ有効であることが保証されます。
スレッドセーフ性
この関数は、どのスレッドからでも呼び出せます。
関連項目
必要な Vulkan 拡張の照会
導入バージョン
バージョン 3.2 で追加されました。
◆ glfwGetInstanceProcAddress()
| GLFWvkproc glfwGetInstanceProcAddress | ( | VkInstance | instance, |
| const char * | procname | ||
| ) |
この関数は、指定されたインスタンスについて、指定された Vulkan コア関数または拡張関数のアドレスを返します。instance が NULL の場合、少なくとも次の関数を含む、Vulkan ローダーがエクスポートする任意の関数を返せます。
vkEnumerateInstanceExtensionPropertiesvkEnumerateInstanceLayerPropertiesvkCreateInstancevkGetInstanceProcAddr
マシン上で Vulkan が利用できない場合、この関数は NULL を返し、GLFW_API_UNAVAILABLE エラーを生成します。Vulkan が最低限利用可能かを確認するには、glfwVulkanSupported を呼び出してください。
この関数は、プラットフォーム固有の Vulkan ローダー照会をフォールバックとして使用して vkGetInstanceProcAddr を呼び出すことと同等です。
引数
| [in] | instance | 問い合わせる Vulkan インスタンス。インスタンス作成関連の関数を取得する場合は NULL。 |
| [in] | procname | ASCII エンコードされた関数名。 |
戻り値
関数のアドレス。エラーが発生した場合は NULL。
エラー
発生する可能性のあるエラーには、GLFW_NOT_INITIALIZED、GLFW_API_UNAVAILABLE があります。
ポインターの有効期間
戻り値の関数ポインターは、ライブラリが終了するまで有効です。
スレッドセーフ性
この関数は、どのスレッドからでも呼び出せます。
関連項目
Vulkan 関数ポインターの照会
導入バージョン
バージョン 3.2 で追加されました。
◆ glfwGetPhysicalDevicePresentationSupport()
| int glfwGetPhysicalDevicePresentationSupport | ( | VkInstance | instance, |
| VkPhysicalDevice | device, | ||
| uint32_t | queuefamily | ||
| ) |
この関数は、指定された物理デバイスの指定されたキューファミリーが、GLFW のビルド対象プラットフォームへの表示をサポートするかどうかを返します。
マシン上で Vulkan または必要なウィンドウサーフェス作成用インスタンス拡張が利用できない場合、あるいは指定されたインスタンスが必要な拡張を有効にして作成されていない場合、この関数は GLFW_FALSE を返し、GLFW_API_UNAVAILABLE エラーを生成します。Vulkan が最低限利用可能かを確認するには glfwVulkanSupported を、必要なインスタンス拡張を確認するには glfwGetRequiredInstanceExtensions を呼び出してください。
引数
| [in] | instance | 物理デバイスが属するインスタンス。 |
| [in] | device | キューファミリーが属する物理デバイス。 |
| [in] | queuefamily | 問い合わせるキューファミリーのインデックス。 |
戻り値
キューファミリーが表示をサポートする場合は GLFW_TRUE、それ以外の場合は GLFW_FALSE。
エラー
発生する可能性のあるエラーには、GLFW_NOT_INITIALIZED、GLFW_API_UNAVAILABLE、GLFW_PLATFORM_ERROR があります。
備考
macOS: VK_MVK_macos_surface および VK_EXT_metal_surface 拡張は vkGetPhysicalDevice*PresentationSupport 型の関数を提供しないため、現在この関数は常に GLFW_TRUE を返します。
スレッドセーフ性
この関数は、どのスレッドからでも呼び出せます。Vulkan オブジェクトの同期の詳細については、Vulkan 仕様を参照してください。
関連項目
Vulkan 表示サポートの照会
導入バージョン
バージョン 3.2 で追加されました。
◆ glfwCreateWindowSurface()
| VkResult glfwCreateWindowSurface | ( | VkInstance | instance, |
| GLFWwindow * | window, | ||
| const VkAllocationCallbacks * | allocator, | ||
| VkSurfaceKHR * | surface | ||
| ) |
この関数は、指定されたウィンドウ用の Vulkan サーフェスを作成します。
Vulkan ローダー、または最低限機能する ICD が 1 つも見つからない場合、この関数は VK_ERROR_INITIALIZATION_FAILED を返し、GLFW_API_UNAVAILABLE エラーを生成します。Vulkan が最低限利用可能かを確認するには、glfwVulkanSupported を呼び出してください。
必要なウィンドウサーフェス作成用インスタンス拡張が利用できない場合、または指定されたインスタンスがそれらの拡張を有効にして作成されていない場合、この関数は VK_ERROR_EXTENSION_NOT_PRESENT を返し、GLFW_API_UNAVAILABLE エラーを生成します。必要なインスタンス拡張を確認するには、glfwGetRequiredInstanceExtensions を呼び出してください。
ウィンドウサーフェスは別の API と共有できないため、ウィンドウはクライアント API ヒントを GLFW_NO_API に設定して作成されていなければなりません。そうでない場合、GLFW_INVALID_VALUE エラーを生成し、VK_ERROR_NATIVE_WINDOW_IN_USE_KHR を返します。
ウィンドウサーフェスは、指定された Vulkan インスタンスより先に破棄しなければなりません。ウィンドウサーフェスを破棄する責任は呼び出し側にあります。GLFW は代わりに破棄しません。サーフェスを破棄するには vkDestroySurfaceKHR を呼び出してください。
引数
| [in] | instance | サーフェスを作成する Vulkan インスタンス。 |
| [in] | window | サーフェスを作成する対象のウィンドウ。 |
| [in] | allocator | 使用するアロケーター。デフォルトのアロケーターを使用する場合は NULL。 |
| [out] | surface | サーフェスのハンドルを格納する場所。エラーが発生した場合は VK_NULL_HANDLE に設定されます。 |
戻り値
成功した場合は VK_SUCCESS。エラーが発生した場合は Vulkan エラーコード。
エラー
発生する可能性のあるエラーには、GLFW_NOT_INITIALIZED、GLFW_API_UNAVAILABLE、GLFW_PLATFORM_ERROR、GLFW_INVALID_VALUE があります。
備考
作成呼び出しが行われる前にエラーが発生した場合、GLFW はそのエラーに最も適した Vulkan エラーコードを返します。glfwVulkanSupported と glfwGetRequiredInstanceExtensions を適切に使用すれば、これらのエラーのほぼすべてを回避できます。
macOS: GLFW は VK_EXT_metal_surface 拡張を優先し、VK_MVK_macos_surface 拡張をフォールバックとして使用します。拡張が選択された場合、その名前は glfwGetRequiredInstanceExtensions が返す配列に含まれます。
macOS: この関数は、MoltenVK の動作に必要な CAMetalLayer インスタンスを作成し、ウィンドウのコンテンツビューに設定します。
X11: デフォルトでは、GLFW は VK_KHR_xcb_surface 拡張を優先し、VK_KHR_xlib_surface 拡張をフォールバックとして使用します。GLFW_X11_XCB_VULKAN_SURFACE 初期化ヒントを設定すると、VK_KHR_xlib_surface を優先拡張にできます。拡張が選択された場合、その名前は glfwGetRequiredInstanceExtensions が返す配列に含まれます。
スレッドセーフ性
この関数は、どのスレッドからでも呼び出せます。Vulkan オブジェクトの同期の詳細については、Vulkan 仕様を参照してください。
関連項目
Vulkan ウィンドウサーフェスの作成
glfwGetRequiredInstanceExtensions
導入バージョン
バージョン 3.2 で追加されました。