A simple vulkan wrapper generator for python

I've tried to make it easily customizable in order to generate wrapper for other languages/library without too much trouble.

Behaviour

By default, the script will fetch the last version of vk.xml in the vulkan repo on github and generate the wrapper in 'vk.py'. If this behaviour is not desired, it is possible to generate the wrapper from a file by editing "SHARED" data in the source code OR by passing the following arguments to the script

-s web|file - From where to fetch "vk.xml". "file" use the local filesystem, "web" use a url.
-p [path] - Where vk.xml is located. This can be a path or an url (depending on the -s parameter)
-o [name] - Write the output script to "name"

Furthermore, it is possible to edit the default templates to add stuff to the wrapper as long as all the formatted fields ("{STUFF}") stay present.

Usage

python create_vulkan_wrapper.py [-s] [-p] [-o]
python create_vulkan_wrapper.py -s file -p xml/vk.xml -o wrapper.py
python create_vulkan_wrapper.py -o foo.py

Example

Access ENUMS and Structures

All vulkan types and enums are accessible through the generated script (ex: vk.SubmitInfo or vk.SHADER_STAGE_VERTEX_BIT)
Exported values do not have prefixes
Exported structure member names use snake case instead of camelcase (my_arg instead of myArg)
Exported structure member names pointer prefixes (p_, pp_) are removed

Loading functions

By default, these functions are directly accessible from the wrapper:

GetInstanceProcAddr
CreateInstance
EnumerateInstanceLayerProperties
EnumerateInstanceExtensionProperties

Other functions must be loaded dynamically. The wrapper export the vulkan function definitions grouped in families.
Families are groups of functions that share the same first argument type.

LoaderFunctions (automatically loaded in the wrapper)
InstanceFunctions
PhysicalDeviceFunctions
DeviceFunctions
CommandBufferFunctions
QueueFunctions

In order to load a function family in the code, the load_functions function can be used.
It is a light wrapper around GetInstanceProcAddr and GetDeviceProcAddr.

def load_functions(vk_object, functions_list, loader):

vk_object : This is either the Instance or the Device used to load the functions (the first argument of loader)
functions_list : List of families to wrap (see List of families under)
loader : Function to call. This is either GetInstanceProcAddr or GetDeviceProcAddr

This function returns a list of (FunctionName, FunctionPtr).

FunctionName being the name of the function without the prefix and
FunctionPtr being a ctypes CFUNCTYPE wrapper around the function.

Here is some pseudocode that load all the vulkan commands in two different python objects:

import vk

class MyInstance(object):
    def __init__(self):
        instance = vk.CreateInstance(*my_args)

        # Load instance functions
        for function_name, function in vk.load_functions(instance, vk.InstanceFunctions, vk.GetInstanceProcAddr):
            setattr(self, function_name, function)

        # Load physical device functions
        for function_name, function in vk.load_functions(instance, vk.PhysicalDeviceFunctions, vk.GetInstanceProcAddr):
            setattr(self, function_name, function)

class MyDevice(object):
    def __init__(self, instance):
        self.instance = instance
        device = instance.CreateDevice(*my_args)

        # Load device functions
        for function_name, function in vk.load_functions(device, vk.DeviceFunctions, instance.GetDeviceProcAddr):
            setattr(self, function_name, function)

        # Load command buffers functions
        for function_name, function in vk.load_functions(device, vk.CommandBufferFunctions, instance.GetDeviceProcAddr):
            setattr(self, function_name, function)

        # Load queue functions
        for function_name, function in vk.load_functions(device, vk.QueueFunctions, instance.GetDeviceProcAddr):
            setattr(self, function_name, function)



instance = MyInstance()
device = MyDevice(instance)

Other values

Typedefs of vulkan types are also exported. Ex: (vk.Instance).
Extensions names and versions are also exported
MAKE_VERSION is exported in order to encode vulkan versions
Vulkan v1.0 is defined as such: API_VERSION_1_0 = MAKE_VERSION(1,0,0)
A macro to dynamically load vulkan functions load_functions

Concrete example

For a concrete example of how a wrapper generated by this script can be used, please see https://github.com/gabdube/python-vulkan-triangle

Dependencies

This script and the generated wrapper were tested with python3 and python2. There are no external python libraries required.

License

CC0

jiaolu / python-vulkan-wrapper