Vulkan API bindings for Go programming language
Switch branches/tags
Nothing to show
Clone or download
Latest commit b4d51f2 Sep 4, 2018
Permalink
Failed to load latest commit information.
android Bring back android headers (so host can re-gen). Nov 5, 2016
moltenVK MoltenVK 0.17.0 support. May 6, 2017
vulkan May 20, 2017 Vulkan 1.0.50 spec update May 30, 2017
windows win32 wip. Nov 5, 2016
LICENSE.txt Readme upd May 30, 2017
Makefile c-for-go May 2, 2017
README.md fix typo in readme Aug 28, 2018
cgo_helpers.c Re-gen. Sep 5, 2017
cgo_helpers.go Re-gen. Sep 5, 2017
cgo_helpers.h Re-gen. Sep 5, 2017
const.go Re-gen. Sep 5, 2017
doc.go Re-gen. Sep 5, 2017
errors.go Re-gen. May 22, 2016
init.go remove GLFW dependency Aug 27, 2018
types.go Re-gen. Sep 5, 2017
util.go remove GLFW dependency Aug 27, 2018
vk_bridge.c Add VK_GOOGLE_display_timing extension methods. May 3, 2017
vk_bridge.h MoltenVK 0.17.0 support. May 6, 2017
vk_debug_android.go Add Android support in a standalone file (semi-generated). Nov 5, 2016
vk_default_loader.c remove GLFW dependency Aug 27, 2018
vk_default_loader.h remove GLFW dependency Aug 27, 2018
vk_null32.go Move NullHandlers. Nov 7, 2016
vk_null64.go fix nil cgo values Sep 3, 2018
vk_wrapper.h remove GLFW dependency Aug 27, 2018
vk_wrapper_android.c remove GLFW dependency Aug 27, 2018
vk_wrapper_compute.c remove GLFW dependency Aug 27, 2018
vk_wrapper_desktop.c remove GLFW dependency Aug 27, 2018
vk_wrapper_ios.m Add VK_GOOGLE_display_timing extension methods. May 3, 2017
vulkan.go Re-gen. Sep 5, 2017
vulkan.yml Fix surface_capabilities2 May 30, 2017
vulkan_android.go Move NullHandlers. Nov 7, 2016
vulkan_darwin.go remove GLFW dependency Aug 27, 2018
vulkan_ios.go MoltenVK 0.17.0 support. May 6, 2017
vulkan_linux.go remove GLFW dependency Aug 27, 2018
vulkan_windows.go remove GLFW dependency Aug 27, 2018

README.md

Golang Bindings for Vulkan API version-1.0.50 GoDoc

Package vulkan provides Go bindings for Vulkan — a low-overhead, cross-platform 3D graphics and compute API.

Introduction

Vulkan API is the result of 18 months in an intense collaboration between leading hardware, game engine and platform vendors, built on significant contributions from multiple Khronos members. Vulkan is designed for portability across multiple platforms with desktop and mobile GPU architectures.

Read the brief: https://developer.nvidia.com/engaging-voyage-vulkan

The binding allows one to use Vulkan API directly within Go code, avoiding adding lots of C/C++ in the projects, also can be used to study Vulkan without diving too deep into C/C++ language semantics. For me it's just a matter of taste, writing Go code is simply more pleasant experience.

Project history timeline

  • 2016-02-16 Vulkan API publicly released.

  • 2016-03-06 vulkan-go initial commit and first binding.

  • 2016-05-14 Finally received my NVIDIA Shield Tablet K1 (DHL lost the first parcel), I decided to use tablet because it was the first device supporting Vulkan out of the box. And that was a really good implementation, much wow very reference.

  • 2016-05-17 Created android-go project in order to run Vulkan on the android platform.

  • 2016-05-23 First android-go + vulkan program runs on Tablet K1 (screenshot).

  • 2016-05-24 Improved VulkanInfo example runs on Tablet K1 (screenshot).

  • 2016-05-28 android-go released into public (Reddit post) with plenty of examples including GLES/EGL.

  • 2016-08-13 Finished an app that should draw triangle (ported from tri.c from LunarG demos). Draws nothing instead.

  • 2016-08-13 First unsuccessful attempt to write a spinning cube example. More than 25 hours spent, 2.5k lines of C code rewritten into 900 lines of Go code. The reference code was found in some very old LunarG demo, it seems I should've used the latest one.. At least got the validation layers working and found some bugs in the triangle app code.

  • 2016-08-16 First Vulkan API program in Go that draws triangle runs on Tablet K1 (photo), validaton layers work perfectly too.

  • 2016-08-16 Public announce of this project (Reddit post). Reaction was "Meh".

  • 2016-11-01 MoltenVK driver merged into GLFW (see GLFW issue #870) and this made possible to use Vulkan API under Apple OS X or macOS.

  • 2016-11-06 VulkanInfo and VulkanDraw both ported to desktop OS X and use GLFW to initialize Vulkan (screen #1 and screen #2)

  • 2016-11-07 VulkanInfo and VulkanDraw run fine on NVIDIA GTX980 initialized through GLFW under Windows 10 (screen #1 and screen #2).

  • 2016-11-08 VulkanInfo runs in headless (a.k.a computing) mode in Amazon AWS cloud on P2 Instance equipped Tesla K80 (screenshot).

  • 2016-11-09 ios-go project started, it's very easy to run Golang apps on iOS that use custom surface, for my case it was Metal surface.

  • 2016-11-11 VulkanInfo runs fine on my iPhone under iOS (screenshot), and so does VulkanDraw (photo also GPU report from XCode)

  • 2016-11-13 Second unsuccessful attempt to write spinning cube. 25 hours spent. The approach was highly inspired by Mali Vulkan SDK for Android 1.0 and I created initial version of vulkan-go/asche — a higher level framework to simplify Vulkan initialization for new apps.

  • 2016-11-29 Generic Linux support added in using GLFW (Issue #2) thanks @jfreymuth.

  • 2017-05-06 Third, successful attempt to write spining cube example. 16 hours spent, 4K LOC of C code rewritten from cube.c of LunarG demos. The whole process has been screencasted, maybe I will release it one day.

  • 2017-05-06 vulkan-go/asche complete.

vulkan cube golang

See all demos in vulkan-go/demos.

How to use

Usage of this project is straightforward due to the stateless nature of Vulkan API. Just import the package like this:

import vk "github.com/vulkan-go/vulkan"

Set the GetProcAddress pointer (used to look up Vulkan functions) using SetGetInstanceProcAddr or SetDefaultGetInstanceProcAddr. After that you can call Init to initialise the library. For example:

// Using SDL2:
vk.SetGetInstanceProcAddr(sdl.VulkanGetVkGetInstanceProcAddr())
// OR using GLFW:
vk.SetGetInstanceProcAddr(glfw.GetVulkanGetInstanceProcAddress())
// OR without using a windowing library (Linux only, recommended for compute-only tasks)
if err := vk.SetDefaultGetInstanceProcAddr(); err != nil {
    panic(err)
}

if err := vk.Init(); err != nil {
    panic(err)
}

And you're set. I must warn you that using the API properly is not an easy task at all, so beware and follow the official documentation: https://www.khronos.org/registry/vulkan/specs/1.0/html/vkspec.html

In order to simplify development, I created a high-level framework that manages Vulkan platform state and initialization. It is called asche because when you throw a gopher into volcano you get a pile of ash. Currently it's used in VulkanCube demo app.

Validation Layers

A good brief of the current state of Vulkan validation layers: Explore the Vulkan Loader and Validation Layers (PDF).

There is a full support of validation layers with custom callbacks in Go. For my Android experiments I got the standard pack of layers from https://github.com/LunarG/VulkanTools and built them like this:

$ cd build-android
$ ./update_external_sources_android.sh
$ ./android-generate.sh
$ ndk-build

After that you'd copy the objects to android/jni/libs in your project and activate the ValidationLayers.mk in your Android.mk so when building APK they will be copied alongside with your shared library. It just works then:

[INFO] Instance extensions: [VK_KHR_surface VK_KHR_android_surface]
[INFO] Instance layers: [VK_LAYER_LUNARG_screenshot VK_LAYER_GOOGLE_unique_objects VK_LAYER_LUNARG_api_dump VK_LAYER_LUNARG_image VK_LAYER_LUNARG_core_validation VK_LAYER_LUNARG_object_tracker VK_LAYER_GOOGLE_threading VK_LAYER_LUNARG_parameter_validation VK_LAYER_LUNARG_swapchain]

[Layer Swapchain][ERROR 4] The surface in pCreateInfo->surface, that was given to vkCreateSwapchainKHR(), must be a surface that is supported by the device as determined by vkGetPhysicalDeviceSurfaceSupportKHR().  However, vkGetPhysicalDeviceSurfaceSupportKHR() was never called with this surface.

[Layer Swapchain][ERROR 10] vkCreateSwapchainKHR() called with a non-supported pCreateInfo->compositeAlpha (i.e. VK_COMPOSITE_ALPHA_OPAQUE_BIT_KHR).  Supported values are:
     VK_COMPOSITE_ALPHA_INHERIT_BIT_KHR

[Layer DS][ERROR 8] Attempt to set lineWidth to 0.000000 but physical device wideLines feature not supported/enabled so lineWidth must be 1.0f!

[Layer DS][ERROR 22] Unable to allocate 2 descriptors of type VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER from pool 0x1c. This pool only has 1 descriptors of this type remaining.

Useful links

License

MIT