LLVK 1.2.182-rc3
See the version list below for details.
dotnet add package LLVK --version 1.2.182-rc3
NuGet\Install-Package LLVK -Version 1.2.182-rc3
<PackageReference Include="LLVK" Version="1.2.182-rc3" />
paket add LLVK --version 1.2.182-rc3
#r "nuget: LLVK, 1.2.182-rc3"
// Install LLVK as a Cake Addin #addin nuget:?package=LLVK&version=1.2.182-rc3&prerelease // Install LLVK as a Cake Tool #tool nuget:?package=LLVK&version=1.2.182-rc3&prerelease
LLVK
Low-Level Vulkan Bindings (LLVK) is a set of auto-generated .NET 6+ bindings for Vulkan.
LLVK aims to be a very thin wrapper over the Vulkan C API, designed to minimize the overhead around preparing and using Vulkan types and calls. It also aims to add as little cruft as possible, making translating Vulkan C code to LLVK code easy (within the limitations of C#).
The majority of the library is code generated from the official Vulkan XML spec.
Design
The following design features are central to the codebase:
- No Marshaling - Every API type is an unmanaged struct with a byte-perfect memory layout match to the corresponding C types.
- Unmanaged Function Pointers - All API functions are implemented as
delegate* unmanaged<...>
, noDllImport
in sight. - Device Functions - Device-level functions are loaded with
vkGetDeviceProcAddr
for the best performance. - Native Types - Use of
nint
andnuint
where applicable, and raw pointers instead ofIntPtr
. - Extensive unit testing
There is also a small set of hand-crafted types that provide additional utilities for working with the API and unmanaged code in general.
Using the Library
The two main library components are the LLVK
namespace, which contains all of the hand-crafted support types, and the LLVK.Vulkan
class which contains all of the generated Vulkan API code.
The intended use for the Vulkan
class is to statically import it and its child classes to make Vulkan types and methods available in the current scope. The instance and device functions must also be loaded once the objects are created:
// Include LLVK utilities
using LLVK;
// Imports core Vulkan API types/functions into the current scope
using static LLVK.Vulkan;
// Imports vendor specific types/functions into the current scope
using static LLVK.Vulkan.KHR; // + other vendors
... // Global functions only
vkCreateInstance(&createInfo, null, &instance)
VulkanLoader.LoadInstanceFunctions(instance);
... // Global + Instance level functions only
vkCreateDevice(physicalDevice, &createInfo, null, &device);
VulkanLoader.LoadDeviceFunctions(device);
... // All functions are available
A few usage notes:
- Naming:
- Bitmask enums have
FlagBits
replaced withFlags
(e.g.VkImageUsageFlagBits
→VkImageUsageFlags
). - Enum values are normalized to PascalCase, have their common prefix removed, and have
_BIT
removed if present (e.g.VK_IMAGE_USAGE_TRANSFER_SRC_BIT
→VkImageUsageFlags.TransferSrc
). - Structs, handles, and functions all have the same name as their spec types.
- Bitmask enums have
- Loading Instance and Device Functions:
- After creating an instance or device,
LLVK.VulkanLoader.Load{Instance/Device}Functions(VkInstance/VkDevice)
must be called to load the functions. LLVK.VulkanLoader.IsFunctionLoaded(string)
can be used to check if an API function was successfully loaded.
- After creating an instance or device,
- Utilities:
- Extensions and layers can easily be queried with
InstanceExtensionSet
,InstanceLayerSet
, andDeviceExtensionSet
. - UTF-8 strings and lists of strings can be created and manipulated with
NativeStringUtf8
andNativeStringListUtf8
. VulkanStructureChain<...>
can create and operate on linked chains of supported Vulkan structs.- All handle types have implicit boolean casts for nullity.
- Extensions and layers can easily be queried with
- All disabled/provisional/beta extensions and features are not generated.
There are also some important factors to keep in mind due to the pecularities of C#:
- It is important that the
SType
andPNext
fields be initialized correctly on types that have them. This is done when calling the no-args constructor for those types, or by setting them manually. - The library requires a 64-bit little-endian target.
Versions
The versioning of the LLVK library is identical to the version of the Vulkan specification that the code was generated against. A fourth version component indicates the code revision, making the final version <sdk_major>.<sdk_minor>.<sdk_revision>.<revision>
. <revision>
will only be bumped within a specific SDK version to fix critical issues or add features, and should always start at zero for each release.
Building
The solution has two build configurations:
Generator|Any CPU
- Builds only the generator application.Library|Any CPU
- Builds all projects. Still requires 64-bit at runtime, despite targeting "Any CPU".
Updating Bindings
The generator app is designed to panic if anything even slightly out of the ordinary is encountered which is not accounted for explicitly in the generator. This is to ensure that nothing that appears in new API versions is missed just because it is not explicitly handled. It is expected that each API update will require a few additions and changes to make the generator happy. It is documented in the code how to make these changes as needed.
If you are updating the library for a specific version of the headers, perform the following steps:
- Update the Vulkan-Docs and Vulkan-Headers submodules to the desired version tag.
- Update the versions in
LLVK.csproj
andGenerator.csproj
to match the SDK version. - Build the Generator project (with the
Generator|Any CPU
config), and run it with:-i <vk.xml>
, pointing to the XML spec file in Vulkan-Docs.-l <path/to/LLVK.csproj>
-t <path/to/LLVK.Tests.csproj>
-s <X.X.X>
, where<X.X.X>
is the SDK version of the downloaded headers.- Optionally
-v
as well to help diagnose build issues.
- Fix all of the errors that crop up during the header parsing stage, which may include (but are not limited to):
- Supporting new platforms or beta specifications as they appear.
- Adding new generated or manual types and tests.
- Changing
SpecParser.cs
to handle new use cases. - Changing
SpecGenerator.cs
or any of the generation templates.
- Run
build.{sh|bat}
inLLVK.Tests/Native
to build the native testing code, and correct any build/generation issues. - Build the library (with the
Library|Any CPU
config), and run the unit tests and make changes until all are passing.
Credits
Legal
Both the LLVK generator application and library are licensed under the MIT license. See the LICENSE file at the root of this repository for more information.
Any third party tools are used under their original licenses, which can be found in the acknowledgement links above.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
-
net6.0
- No dependencies.
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
1.2.182-rc4 | 84 | 2/17/2024 |
1.2.182-rc3 | 71 | 2/8/2024 |
1.2.182-rc2 | 129 | 12/28/2023 |
1.2.182-rc | 135 | 11/7/2023 |