Repository files navigation

The goal of the VK² is to provide a library for the Vulkan C API to improve the developers Vulkan experience without introducingany considerable CPU runtime cost. It adds features like type safety for enums and bitfields, collection support, exceptions and simple enumerations.

Strongly inspired byVulkan hpp, it's shaped on the Sasha examplesport. It's the Vulkan counterpart of the OpenGLgln.

See it in actionhere!

You can find all the instructions bymary

To avoid name collisions with the lwjgl Vulkan bindings, the VK² wrapper resides mostly under theobject 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.
  • VkCreateImage can be accessed asvk.createImage
  • VkImageTiling can be accessed asvk.ImageTiling
  • VkImageCreateInfo can 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 requiresto be surrounded by backticks the underscore prefix_, this because Idea handles backticks this very poorly.

Some examples:

• VK_COLOR_SPACE_SRGB_NONLINEAR_KHR is nowVkColorSpace.SRGB_NONLINEAR_KHR
• VK_IMAGETYPE_2D is nowVkImageType._2D

• Flag bits are handled like scoped enums with the addition that the_BIT suffix 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 ofvkBindBufferMemory(device, ...) one can writedevice.bindBufferMemory(...).

All flags masks have beentypealiased accordingly. For example a field of typeVkBufferUsageFlags means that it represents a mask from theVkBufferUsage. enum.The postfixFlag has been eliminated from the enum name for conciseness matter. However, it has been kept for some special cases, such asVkQueueFlag, to avoid clashes with existing other structures, in this case theVkQueue class for example.

When constructing a handle in Vulkan one usually has to create someCreateInfo 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 thatsType is incorrect.

VK² provides constructors for all CreateInfo objects (and others) wheresType is automatically filled with the correct value andpNext set to anullptr 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 lwjglMemoryStack class.

VK² provides also special method accepting glm classes, likeextent 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 info

Errors will be checked automatically in debug mode, but you can setDEBUG explicitely as you wish.In caseVULKAN_NO_EXCEPTIONS istrue, errors will be reported in theSystem.err stream, otherwise the exception to the corresponding error will be thrown.

TODO