Manipulating handles

Creating a handle

using Vulkan

const instance = Instance([], [])
const pdevice = first(unwrap(enumerate_physical_devices(instance)))
const device = Device(pdevice, [DeviceQueueCreateInfo(0, [1.0])], [], [])

Device(Ptr{Nothing} @0x00000000306eb010)

The most convenient way to create a handle is through its constructor

buffer = Buffer(
    device,
    100,
    BUFFER_USAGE_TRANSFER_SRC_BIT,
    SHARING_MODE_EXCLUSIVE,
    [];
    flags = BUFFER_CREATE_SPARSE_ALIASED_BIT,
)

Buffer(Ptr{Nothing} @0x000000002f9e40d8)

This is equivalent to

unwrap(
    create_buffer(
        device,
        100,
        BUFFER_USAGE_TRANSFER_SRC_BIT,
        SHARING_MODE_EXCLUSIVE,
        [];
        flags = BUFFER_CREATE_SPARSE_ALIASED_BIT,
    ),
)

Buffer(Ptr{Nothing} @0x000000002d502f58)

Error handling can be performed before unwrapping, e.g.

res = create_buffer(
    device,
    100,
    BUFFER_USAGE_TRANSFER_SRC_BIT,
    SHARING_MODE_EXCLUSIVE,
    [];
    flags = BUFFER_CREATE_SPARSE_ALIASED_BIT,
)
if iserror(res)
    error("Could not create buffer!")
else
    unwrap(res)
end

Buffer(Ptr{Nothing} @0x000000002b1cf5f8)

Create info parameters can be built separately, such as

info = BufferCreateInfo(
    100,
    BUFFER_USAGE_TRANSFER_SRC_BIT,
    SHARING_MODE_EXCLUSIVE,
    [];
    flags = BUFFER_CREATE_SPARSE_ALIASED_BIT,
)

Buffer(device, info)

Buffer(Ptr{Nothing} @0x000000002b061138)

create_buffer(device, info)

Result(Buffer(Ptr{Nothing} @0x000000002da1c2c8))

Handles allocated in batches (such as command buffers) do not have a dedicated constructor; you will need to call the corresponding function yourself.

command_pool = CommandPool(device, 0)
info = CommandBufferAllocateInfo(command_pool, COMMAND_BUFFER_LEVEL_PRIMARY, 5)
res = allocate_command_buffers(device, info)
iserror(res) && error("Tried to create 5 command buffers, but failed miserably.")
cbuffers = unwrap(res)

5-element Vector{CommandBuffer}:
 CommandBuffer(Ptr{Nothing} @0x000000002c4c0d10)
 CommandBuffer(Ptr{Nothing} @0x000000002bf99f70)
 CommandBuffer(Ptr{Nothing} @0x000000002d1c1320)
 CommandBuffer(Ptr{Nothing} @0x000000002d92f370)
 CommandBuffer(Ptr{Nothing} @0x000000002dbb3ac0)

Note that they won't be freed automatically; forgetting to free them after use would result in a memory leak (see Destroying a handle).

Destroying a handle

The garbage collector will free most handles automatically with a finalizer (see Automatic finalization), but you can force the destruction yourself early with

finalize(buffer) # calls `destroy_buffer`

This is most useful when you need to release resources associated to a handle, e.g. a DeviceMemory. Handle types that can be freed in batches don't register finalizers, such as CommandBuffer and DescriptorSet. They must be freed with

free_command_buffers(device, command_pool, cbuffers)

or the corresponding free_descriptor_sets for DescriptorSets.

This page was generated using Literate.jl.