vulkan

by realitix

realitix / vulkan

The ultimate Python binding for Vulkan API

230 Stars 19 Forks Last release: Not found Apache License 2.0 125 Commits 8 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

vulkan, the ultimate Python binding for Vulkan API

Table of Contents

Presentation

vulkan is a Python extension which supports the Vulkan API. It leverages power of Vulkan with simplicity of Python. It's a complete Vulkan wrapper, it keeps the original Vulkan API and try to limit differences induced by Python.

vulkan is compatible with Python 2 and Python 3.

How to install

Pip

You can install directly vulkan with pip:

pip install vulkan

Manual install

You can install it manually if you want the latest version:

git clone https://github.com/realitix/vulkan
cd vulkan
python setup.py install

How to use

Getting started

To try this wrapper, execute the following commands (on linux):

git clone https://github.com/realitix/vulkan.git
cd vulkan
python setup.py install
pip install pysdl2
python example/example_sdl2.py

Known errors :

OSError: cannot load library 'libvulkan.so'
means you didn't install the Vulkan SDK.

vulkan.VkErrorExtensionNotPresent
means your have installed the Vulkan SDK but your driver doesn't support it.

API

The vulkan wrapper gives you complete access to the Vulkan API, including extension functions.

Code convention

Similar to Vulkan, structs are prefixed with Vk, enumeration values are prefixed with VK_ and functions are prefixed with vk.

Structs

Vulkan struct creation is achieved in vulkan wrapper using python functions. For example, if you want to create the Vulkan struct

VkInstanceCreateInfo
, you must initialize it with its keyword parameters. In vulkan wrapper, you will call the Python function
VkInstanceCreateInfo
with named parameters as shown below.

In C++ (Vulkan) we write:

VkInstanceCreateInfo instance_create_info = {
    VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO, // sType
    nullptr, // pNext
    0, // flags
    &application_info, // *pApplicationInfo
    3, // enabledLayerCount
    &layers, // *ppEnabledLayerNames
    3, // enabledExtensionCount
    &extensions // *ppEnabledExtensionNames
};

Our vulkan wrapper equivalent of the above C++ code is :

import vulkan as vk

instance_create_info = vk.VkInstanceCreateInfo( sType=vk.VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO, pNext=None, flags=0, pApplicationInfo=application_info, enabledLayerCount=len(layers), ppEnabledLayerNames=layers, enabledExtensionCount=len(extensions), ppEnabledExtensionNames=extensions, )

To create the struct, you must remember to pass all parameters at creation time. This includes the Vulkan layers and extensions denoted by

ppEnabledLayerNames
and
ppEnabledExtensionNames
, which vulkan wrapper is able to facilitate too.

This struct example demonstrates how vulkan wrapper conveniently converts your Python code into native C types.

Note:

  • The default value for all parameters is
    None
    so you could have omitted
    pNext
    (because its value is
    None
    ).
  • The default value for
    sType
    parameter is the good value so you could have omitted
    sType
    .
  • The default value for
    enabledLayerCount
    parameter is the length of
    ppEnabledLayerNames
    so you could have omitted
    enabledLayerCount
    and
    enabledExtensionCount
    .
  • Order of parameters doesn't matter since they are keyword parameters.
  • The C++ syntax is more risky because you must pass all parameters in specific order.

Functions

vulkan greatly simplifies the calling of functions. In Vulkan API, you have to explicitly write three kinds of function:

  • functions that create nothing
  • functions that create one object
  • functions that create several objects

In vulkan wrapper, all these troubles goes away. vulkan will takes care of you and knows when to return

None
, an object or a
list
. Here are three examples:
# Create one object
instance = vk.vkCreateInstance(createInfo, None)

Create a list of object

extensions = vk.vkEnumerateDeviceExtensionProperties(physical_device, None)

Return None

vk.vkQueuePresentKHR(presentation_queue, present_create)

Vulkan functions usually return a

VkResult
, which returns the success and error codes/states of the function. vulkan is pythonic and converts
VkResult
to exception: if the result is not
VK_SUCCESS
, an exception is raised. More elaboration is given in the next section.

Exceptions

  • vulkan has two types of Exceptions, namely

    VkError
    or
    VkException
    . The
    VkError
    exception handles all the error codes reported by Vulkan's
    VkResult
    . The
    VkException
    exception handles all the success code reported by Vulkan's
    VkResult
    , except the
    VK_SUCCESS
    success code.
  • Exception names are pythonized:

    VK_NOT_READY
    ->
    VkNotReady
    .

Constants

All Vulkan constants are available in vulkan and it even provides some fancy constants like

UINT64_MAX
.

Resources

To understand how to use this wrapper, you have to look for

example/exemple_*
files or refer to Vulk engine.

How to contribute

To contribute, you should first read the

Architecture
section. Any contribution is welcome and I answer quickly.

Architecture

vulkan is a CFFI module generated by a Python script.

When you install this module, you need two files:

  • vulkan/vulkan.cdef.h
    containing CFFI definitions
  • vulkan/_vulkan.py
    containing the actual executed Python script

Theses two files are generated by the

generator/generate.py
script.

vulkan/vulkan.cdef.h
is generated with a
cpp
command call, it applies pre-processing to the Vulkan C header. It can't work as is because of
pycparser
which cannot parse the output. That's the purpose of
fake_libc_include
folder.

vulkan/_vulkan.py
needs more work. To proceed, the generator computes a model of Vulkan API based on
vk.xml
(the file from Kronos describing the API) and then uses a
jinja2
template to write the file.

Here the basic steps:

  • Load vk.xml
  • Use
    xmltodict
    to parse the xml document
  • Generate a good data model from it
  • Pass the model to the
    vulkan.template.py
    file
  • The template engine generate the final Python file

Community

You can checkout my blog, I speak about vulkan: Blog

Stay in touch

You can contact me by opening issue (bug or interesting discussion about the project). If you want a fast and pleasant talk, join the irc channel:

##vulkan
(I'm realitix). I'm connected from 9AM to 6PM (France).

History

This module comes from a long journey. I have first created CVulkan. CVulkan is a wrapper created in plain C, plain C is hard to maintain... So I have decided to restart with CFFI which is from far the best way to do it. There was a module pyVulkan that did what I wanted to do. But it was not working and the code was hard to maintain. I asked to the maintainer to let me help him but I got no answer. I forked his project and I rewrote every single part to obtain a good module.

Supported By

vulkan is supported by helpful 3rd parties via code contributions, test devices and so forth. Make our supporters happy and visit their sites!

linagora

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.