The goal of the VK² is to provide a library for the Vulkan C API to improve the developers Vulkan experience without introducing any considerable CPU runtime cost. It adds features like type safety for enums and bitfields, collection support, exceptions and simple enumerations.
Strongly inspired by Vulkan hpp, it's shaped on the Sasha examples port. It's the Vulkan counterpart of the OpenGL gln.
See it in action here!
You can find all the instructions by mary
To avoid name collisions with the lwjgl Vulkan bindings, the VK² wrapper resides mostly under the object vk. The following rules apply to the new naming
- All functions, extension functions, and structs have the Vk prefix removed. In addition to this the first letter of functions is lower case.
VkCreateImagecan be accessed asvk.createImageVkImageTilingcan be accessed asvk.ImageTilingVkImageCreateInfocan be accessed asvk.ImageCreateInfo
- Enums are mapped to scoped enums to provide compile time type safety. The names have been changed to have the Enum Base in CamelCase with the VK_ prefix and the enum name in Capital letters (corresponding to the original counterpart). Enums starting with a number requires
to be surrounded by backticksthe underscore prefix_, this because Idea handles backticks this very poorly.
Some examples:
VK_COLOR_SPACE_SRGB_NONLINEAR_KHRis nowVkColorSpace.SRGB_NONLINEAR_KHRVK_IMAGETYPE_2Dis nowVkImageType._2D
- Flag bits are handled like scoped enums with the addition that the
_BITsuffix has also been removed.
This is one case where Kotlin really shines: VK² declares a class for all handles to ensure full type safety and to add support for member functions on handles. A member function has been added to a handle class for each function which accepts the corresponding handle as first parameter. Instead of vkBindBufferMemory(device, ...) one can write device.bindBufferMemory(...).
All flags masks have been typealiased accordingly. For example a field of type VkBufferUsageFlags means that it represents a mask from the VkBufferUsage. enum.
The postfix Flag has been eliminated from the enum name for conciseness matter. However, it has been kept for some special cases, such as VkQueueFlag, to avoid clashes with existing other structures, in this case the VkQueue class for example.
When constructing a handle in Vulkan one usually has to create some CreateInfo struct which describes the new handle. Moreover, allocation has to be handled manually and everywhere C code uses pointers, we have to use buffers on the JVM.
This can result in quite lengthy code as can be seen in the following Vulkan example:
val info = VkImageCreateInfo.calloc()
.sType(VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO)
.pNext(null)
.flags(...some flags...)
.imageType(VK_IMAGE_TYPE_2D)
.format(VK_FORMAT_R8G8B8A8_UNORM)
.extent().apply {
.width(size.x)
.height(size.y)
.depth(1)
}
.mipLevels(1)
.arrayLayers(1)
.samples(VK_SAMPLE_COUNT_1_BIT)
.tiling(VK_IMAGE_TILING_OPTIMAL)
.usage(VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT)
.sharingMode(VK_SHARING_MODE_EXCLUSIVE)
.pQueueFamilyIndices(null)
.initialLayout(VK_IMAGE_LAYOUT_UNDEFINED)
val pImage = MemoryUtil.memAllocLong(1)
vkCreateImage(device, info, allocator, pImage)
image = pImage.get(0)
info.free()
memFree(pImage)One typical issue Vulkan developers encounter when filling out a CreateInfo struct field by field is that sType is incorrect.
VK² provides constructors for all CreateInfo objects (and others) where sType is automatically filled with the correct value and pNext set to a nullptr by default. All other field are also initialized to zero. There are exceptions though.
Moreover, all the allocations takes place in the thread local memory, using the lwjgl MemoryStack class.
VK² provides also special method accepting glm classes, like extent accepting a (Vec3i) or (Vec2i, Int).
Here's how the same code looks with a constructor:
val info = vk.ImageCreateInfo {
flags = ...some flags...
imageType = VkImageType.`2D`
format = VkFormat.R8G8B8A8_UNORM
extent(size, 1)
mipLevels = 1
arrayLayers = 1
samples = VkSampleCount.`1_BIT`
tiling = VkImageTiling.OPTIMAL
usage = VkImageUsage.COLOR_ATTACHMENT_BIT.i
sharingMode = VkSharingMode.EXCLUSIVE
}
image = device createImage infoErrors will be checked automatically in debug mode, but you can set DEBUG explicitely as you wish.
In case VULKAN_NO_EXCEPTIONS is true, errors will be reported in the System.err stream, otherwise the exception to the corresponding error will be thrown.
TODO
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent