Vulkan: add docs for the framework generation scripts
Bug: 134185757
Test: ./scripts/code_generator.py && build
Change-Id: I108412fdc672c5513f570ddac9221074a0027cd0
diff --git a/vulkan/scripts/api_generator.py b/vulkan/scripts/api_generator.py
index d1fff42..7c39075 100644
--- a/vulkan/scripts/api_generator.py
+++ b/vulkan/scripts/api_generator.py
@@ -13,13 +13,14 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
-#
-# This script provides the functions required for generating the
-# vulkan api framework directly from the vulkan registry (vk.xml)
+
+"""Generates the api_gen.h and api_gen.cpp.
+"""
import os
import generator_common as gencom
+# Functions intercepted at vulkan::api level.
_INTERCEPTED_COMMANDS = [
'vkCreateDevice',
'vkDestroyDevice',
@@ -30,6 +31,8 @@
def gen_h():
+ """Generates the api_gen.h file.
+ """
genfile = os.path.join(os.path.dirname(__file__),
'..', 'libvulkan', 'api_gen.h')
@@ -100,6 +103,12 @@
def _define_extension_stub(cmd, f):
+ """Emits a stub for an exported extension function.
+
+ Args:
+ cmd: Vulkan function name.
+ f: Output file handle.
+ """
if (cmd in gencom.extension_dict and gencom.is_function_exported(cmd)):
ext_name = gencom.extension_dict[cmd]
ret = gencom.return_type_dict[cmd]
@@ -121,6 +130,11 @@
def _is_intercepted(cmd):
+ """Returns true if a function is intercepted by vulkan::api.
+
+ Args:
+ cmd: Vulkan function name.
+ """
if gencom.is_function_supported(cmd):
if gencom.is_globally_dispatched(cmd) or cmd in _INTERCEPTED_COMMANDS:
return True
@@ -128,6 +142,11 @@
def _intercept_instance_proc_addr(f):
+ """Emits code for vkGetInstanceProcAddr for function interception.
+
+ Args:
+ f: Output file handle.
+ """
f.write("""\
// global functions
if (instance == VK_NULL_HANDLE) {\n""")
@@ -180,6 +199,11 @@
def _intercept_device_proc_addr(f):
+ """Emits code for vkGetDeviceProcAddr for function interception.
+
+ Args:
+ f: Output file handle.
+ """
f.write("""\
if (device == VK_NULL_HANDLE) {
ALOGE("invalid vkGetDeviceProcAddr(VK_NULL_HANDLE, ...) call");
@@ -220,6 +244,12 @@
def _api_dispatch(cmd, f):
+ """Emits code to dispatch a function.
+
+ Args:
+ cmd: Vulkan function name.
+ f: Output file handle.
+ """
assert not _is_intercepted(cmd)
f.write(gencom.indent(1))
@@ -233,6 +263,8 @@
def gen_cpp():
+ """Generates the api_gen.cpp file.
+ """
genfile = os.path.join(os.path.dirname(__file__),
'..', 'libvulkan', 'api_gen.cpp')