Package club.doki7.vulkan.handle

package club.doki7.vulkan.handle

Opaque handle types of Vulkan API.

Quick start

An opaque handle is usually defined in native languages like such:

typedef struct OpaqueStruct *OpaqueHandle;

In vulkan4j ecosystem, opaque handles are represented with a Java record type containing a single MemorySegment field. That segment is basically the opaque handle itself You may think that it is pointing to a hypothetical OpaqueStruct structure.

Handles themselves cannot be allocated, because the layout of the memory block it points to is completely unknown: C APIs use opaque handles intentionally to hide these details. There are two common C API designs:

OpaqueHandle obtainOpaqueHandle(void);

and

void obtainOpaqueHandles(OpaqueHandle *pHandle, int capacity);

In order to handle the second case, and to handle the cases you need to pass an array of handles to C APIs:

void useOpaqueHandles(OpaqueHandle const* pHandles, int count);

All the handle types defined have a Ptr subclass, which is a pointer to the handle type.

NULL handles

vulkan4j ecosystem represents a NULL handle with a null Java reference of that handle type, instead of a handle instance containing a null or MemorySegment.NULL. We made this choice because it is always easier to analyse whether a Java reference is null or not: there have been many tools (JSR305 for example) to help you with that. See the documentation of IPointer#segment() for more details.