How to create a device

In this section we will learn how to create device using haiku graphics API. A “device” encapsulates the GPU used in your program and manages all resources.

A device ?

A device is one of the most important data structure of an haiku application. It manages all graphics resources used inside your application. It is used to select a physical GPU, to allocate/deallocate resources and to submit your GPU commands.

It is one of the few “owning pointers” given to you by haiku : hk_device_t*.

To initialize it, you’ll need to call the hkgfx_device_create function:

hk_device_t* my_device = hkgfx_device_create( &(hk_gfx_device_desc){
    .requested_queues = HK_QUEUE_COMPUTE_BIT | HK_QUEUE_TRANSFER_BIT,
    .selector         = {.type = HK_DEVICE_TYPE_INTEGRATED}
});

In this example, we are asking for a device that supports compute and transfer operations and, if possible, for an integrated GPU.

The user should set fields from hk_gfx_device_desc to properly configure the application device.

  • If you want a windowed application, you’ll probably need to set the .enable_swapchain field

  • If you want to use mesh shaders, you’ll require to set the .enable_mesh_shading

To deallocate the hk_device_t* at the end of your application, use the respective hkgfx_device_destroy function.

Can I list all my devices ?

It is possible to list all avalaible devices on your computer on the standard output using hkgfx_module_list_all_devices. This function must be called after the module initialization and before any device creation (as it loads vulkan symbol to enable fetching device informations and unloads it afterwards).

For secific features like mesh shading, you can call features checks like hkgfx_module_any_device_supporting_mesh_shading which returns any device supporting the requested feature.

Can I select a specific one ?

To select a specific GPU, you can use the selector field from hk_gfx_device_desc. You can set the .id field with a specific GPU (non-zero) ID from the list of available GPUs. Or you can set the .type field if you want an integrated GPU or a discrete one for instance.

You can also hint for specific needs with other fields (ex: set with_max_2D_image_resolution if you want the device which provides the highest supported image resolution.)

It is not yet possible to explicitly select a llvmpipe device. It is currently being developed.