From: Charles Giessen <charles@lunarg.com>
Date: Tue, 3 Sep 2024 20:55:31 +0000 (-0500)
Subject: Document layer requirements for querying vkCreateInstance from GIPA
X-Git-Tag: upstream/1.3.296~10
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=c758bac8bf1580b5018adafd3a2ec709237b0134;p=platform%2Fupstream%2FVulkan-Loader.git

Document layer requirements for querying vkCreateInstance from GIPA

The vkGetInstanceProcAddr function was ammended in header version 1.2.193
to require global functions be queried with NULL instance parameters,
including vkCreateInstance. Layers written before that time may not expect
the instance parameter to be NULL, so in order to maintain compatibility,
the loader code (which itself dates to before Vulkan's public release) is
left unmodified.

Instead, code comments were left to indicate the non-spec compliant
implementation as well as documentation in the LoaderLayerInterface mentioning
how layers should handle the now invalid API usage.

In the future, the loader could be modified to correctly follow the spec, but
a survey of existing and previous layer implementations would need to be done
to determine the impact of the change.
---

diff --git a/docs/LoaderLayerInterface.md b/docs/LoaderLayerInterface.md
index 6ca9bc57..08a41755 100644
--- a/docs/LoaderLayerInterface.md
+++ b/docs/LoaderLayerInterface.md
@@ -986,7 +986,15 @@ ignore `instance` when `pName` is `vkCreateDevice`.
   - The specification **requires** `NULL` to be returned from
 `vkGetInstanceProcAddr` and `vkGetDeviceProcAddr` for disabled functions.
     - A layer may return `NULL` itself or rely on the following layers to do so.
-
+  - A layer's implementation `vkGetInstanceProcAddr` **should**, when querying for
+`vkCreateInstance`, return a valid function pointer regardless of the value of the
+`instance` parameter.
+    - The specification **requires** that the `instance` parameter **must** be NULL.
+However, older versions of the specification did not have this requirement, allowing
+for non-NULL `instance` handles to be passed in and return a valid `vkCreateInstance`
+function pointer. The Vulkan-Loader itself does this and will continue to do so to
+maintain compatibility with layers which were released before this specification
+change was made.
 
 ## Layer Dispatch Initialization
 
diff --git a/loader/loader.c b/loader/loader.c
index 531146a9..525334c7 100644
--- a/loader/loader.c
+++ b/loader/loader.c
@@ -4751,6 +4751,11 @@ VkResult loader_create_instance_chain(const VkInstanceCreateInfo *pCreateInfo, c
     feature_flags = windows_initialize_dxgi();
 #endif
 
+    // The following line of code is actually invalid at least according to the Vulkan spec with header update 1.2.193 and onwards.
+    // The update required calls to vkGetInstanceProcAddr querying "global" functions (which includes vkCreateInstance) to pass NULL
+    // for the instance parameter. Because it wasn't required to be NULL before, there may be layers which expect the loader's
+    // behavior of passing a non-NULL value into vkGetInstanceProcAddr.
+    // In an abundance of caution, the incorrect code remains as is, with a big comment to indicate that its wrong
     PFN_vkCreateInstance fpCreateInstance = (PFN_vkCreateInstance)next_gipa(*created_instance, "vkCreateInstance");
     if (fpCreateInstance) {
         VkLayerInstanceCreateInfo instance_dispatch;