jcoronado
The jcoronado package provides a very thin layer over the Vulkan
API that intends to provide some degree of memory and type safety. The intention
of the package is to make Vulkan feel like a Java API, without sacrificing
performance. Internally, the package uses the excellent LWJGL3
Vulkan bindings, and adds a thin layer of immutable types and interfaces.
Features
- Type-safe Vulkan frontend
- Strong separation of API and implementation to allow for switching to different bindings at compile-time
- Extensive use of
try-with-resourcesto prevent resource leaks - Strongly-typed interfaces with a heavy emphasis on immutable value types
- Type-safe extension mechanism
- Fully documented (JavaDoc)
- Example code included
- OSGi ready.
- JPMS ready.
- ISC license
Requirements
The jcoronado package currently targets Vulkan 1.3 and up. Some optional
device features are required by the package.
synchronization2
The package requires the synchronization2 feature to be available and enabled.
This is necessary to avoid having a lot of branching code paths around queue
submission and render passes.
At the time of writing, according to the
Vulkan hardware database,
this feature is available on 99.82% of hardware.
timelineSemaphore
The package requires the timelineSemaphore feature to be available and
enabled. This is necessary because timeline semaphores are a mandatory part
of the API exposed by the package.
At the time of writing, according to the
Vulkan hardware database,
this feature is available on 99.88% of hardware.
Building
Install a Vulkan SDK. On Linux, there will be almost certainly be distribution
packages available with names such as vulkan-validationlayers, vulkan-tools,
etc. On Windows, install the LunarG SDK. On
Windows, ensure that you have the right vendor drivers installed for your
graphics card; if you don't do this, the library (and the test suite) will
raise exceptions with messages such as "Missing vulkan-1.dll".
Then run:
$ mvn clean package
If this step fails, it's a bug. Please report it!
Utilities
Allocation Tracker
The com.io7m.jcoronado.utility.allocation_tracker module provides a simple
implementation of the VulkanHostAllocatorType interface that simply delegates
an existing allocator (such as jemalloc) but also tracks the current amount
of memory allocated for every allocation type.
Simply instantiate a VulkanHostAllocatorTracker instance and use it anywhere
the API accepts a VulkanHostAllocatorType.
Swap Chain
The com.io7m.jcoronado.utility.swapchain module provides a utility for
managing the swapchain
correctly.
Swapchain management is notoriously difficult, with many pitfalls and sharp
edges. The JCSwapchainManager class provides a class for correctly creating
swapchains, automatically recreating them if they become suboptimal or
out-of-date, and acquiring and presenting images.
The class requires the use of the
VK_EXT_swapchain_maintenance1
extension to fix serious design flaws in the original VK_KHR_swapchain API.
Briefly, create a swapchain:
final var swapChainManager =
resources.add(
JCSwapchainManager.create(
JCSwapchainConfiguration.builder()
.setDevice(device)
.setGraphicsQueue(graphicsQueue)
.setPresentationQueue(presentationQueue)
.setSurface(surface)
.setSurfaceExtension(khrSurfaceExt)
.setSwapChainExtension(khrSwapchainExt)
.addSurfaceAlphaFlags(VK_COMPOSITE_ALPHA_OPAQUE_BIT_KHR)
.addImageUsageFlags(VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT)
.addImageUsageFlags(VK_IMAGE_USAGE_TRANSFER_DST_BIT)
.addPreferredModes(VK_PRESENT_MODE_MAILBOX_KHR)
.addPreferredModes(VK_PRESENT_MODE_FIFO_KHR)
.addPreferredModes(VK_PRESENT_MODE_IMMEDIATE_KHR)
.build()
)
);
Acquire images in the rendering loop:
while (rendering) {
try (var image = swapChainManager.acquire()) {
render(image);
image.present();
}
}
When an image is acquired or presented, the current swapchain may be detected as being suboptimal or out-of-date. When this happens, a new swapchain is created internally and the old one is (eventually) deleted.
On many operating systems, dragging a window's resize box can result in a flurry of updates that will result in hundreds of swapchain instances being created and deleted. For best results, disable rendering during window resize events. As an example, when using GLFW:
AtomicBoolean windowIsResizing;
GLFW.glfwSetWindowSizeCallback(
window,
GLFWWindowSizeCallback.create((_, _, _) -> {
windowIsResizing.set(true);
})
);
while (rendering) {
this.windowIsResizing.set(false);
GLFW.glfwPollEvents();
if (!windowIsResizing.get()) {
try (var image = swapChainManager.acquire()) {
render(image);
image.present();
}
} else {
pauseOneFrame();
}
}
By avoiding rendering during window resizes, we effectively avoid creating and destroying swapchains for the intermediate window sizes. When the window eventually stops resizing, we'll automatically create a suitable swapchain for the final size.
See the HelloSwapChain example.
Releases & Development Snapshots
Releases
You can subscribe to the atom feed to be notified of project releases.
The most recently released version of the package is 0.0.1.
0.0.1 Release (2024-12-03Z)
The compiled artifacts for the release (and all previous releases) are available on Maven Central.
Maven Modules
<dependency> <group>com.io7m.jcoronado</group> <artifactId>com.io7m.jcoronado.api</artifactId> <version>0.0.1</version> </dependency><dependency> <group>com.io7m.jcoronado</group> <artifactId>com.io7m.jcoronado.documentation</artifactId> <version>0.0.1</version> </dependency><dependency> <group>com.io7m.jcoronado</group> <artifactId>com.io7m.jcoronado.examples</artifactId> <version>0.0.1</version> </dependency><dependency> <group>com.io7m.jcoronado</group> <artifactId>com.io7m.jcoronado.extensions.ext_debug_utils.api</artifactId> <version>0.0.1</version> </dependency><dependency> <group>com.io7m.jcoronado</group> <artifactId>com.io7m.jcoronado.extensions.ext_layer_settings.api</artifactId> <version>0.0.1</version> </dependency><dependency> <group>com.io7m.jcoronado</group> <artifactId>com.io7m.jcoronado.extensions.khr_surface.api</artifactId> <version>0.0.1</version> </dependency><dependency> <group>com.io7m.jcoronado</group> <artifactId>com.io7m.jcoronado.fake</artifactId> <version>0.0.1</version> </dependency><dependency> <group>com.io7m.jcoronado</group> <artifactId>com.io7m.jcoronado.layers.khronos_validation.api</artifactId> <version>0.0.1</version> </dependency><dependency> <group>com.io7m.jcoronado</group> <artifactId>com.io7m.jcoronado.layers.lunarg_api_dump.api</artifactId> <version>0.0.1</version> </dependency><dependency> <group>com.io7m.jcoronado</group> <artifactId>com.io7m.jcoronado.lwjgl</artifactId> <version>0.0.1</version> </dependency><dependency> <group>com.io7m.jcoronado</group> <artifactId>com.io7m.jcoronado.tests</artifactId> <version>0.0.1</version> </dependency><dependency> <group>com.io7m.jcoronado</group> <artifactId>com.io7m.jcoronado.utility.allocation_tracker</artifactId> <version>0.0.1</version> </dependency><dependency> <group>com.io7m.jcoronado</group> <artifactId>com.io7m.jcoronado.utility.swapchain</artifactId> <version>0.0.1</version> </dependency><dependency> <group>com.io7m.jcoronado</group> <artifactId>com.io7m.jcoronado.vma</artifactId> <version>0.0.1</version> </dependency>
Development Snapshots
At the time of writing, the current unstable development version of the package is 0.0.2-SNAPSHOT.
Development snapshots may be available in the Central Portal Snapshots repository. Snapshots are published to this repository every time the project is built by the project's continuous integration system, but snapshots do expire after around ninety days and so may or may not be available depending on when a build of the package was last triggered.
Manual
User Manual
Sources
This project uses Git to manage source code.
Repository: https://www.github.com/io7m-com/jcoronado
$ git clone --recursive https://www.github.com/io7m-com/jcoronado
Issues
This project uses GitHub Issues to track issues.
License
Copyright © 2023 Mark Raynsford <code@io7m.com> https://www.io7m.com Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies. THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.