Create an image

Images are GPU resources that can be used to manipulate textures and canvas (i.e. framebuffers, depthbuffers, etc.). These resources are provided by haiku via the hk_image_t handle and its associated utility functions in haiku/graphics.h.

Image creation is achieved using the hkgfx_image_create function which requires a hk_device_t and hk_gfx_image_desc data structure.

Example:

hk_image_t my_image = hkgfx_image_create(device, &(hk_gfx_image_desc){
    .type           = HK_IMAGE_TYPE_2D,
    .usage_flags    = HK_IMAGE_USAGE_TRANSFER_DST_BIT | HK_IMAGE_USAGE_STORAGE_BIT,
    .memory_type    = HK_MEMORY_TYPE_GPU_ONLY
    .extent         = {.width = image_width, .height = image_height},
    .levels         = 1,
});

In this example, we are asking for a 2D image that lives on the GPU and will later be used both as storage and transfer destination. Dimension/Extent are given in pixels and only one level of mipmap pyramid is requested.

This function has its corresponding deallocation function hkgfx_image_destroy.

Usage flags are given by the hk_image_usage_flag_bits_e enumeration:

  • HK_IMAGE_USAGE_DEFAULT: default flag (HK_IMAGE_USAGE_SAMPLED_BIT).

  • HK_IMAGE_USAGE_TRANSFER_SRC_BIT: hints that the image will be later used as a tranfer source.

  • HK_IMAGE_USAGE_TRANSFER_DST_BIT: hints that the image will be later used as a tranfer destination.

  • HK_IMAGE_USAGE_SAMPLED_BIT: hints that the image will be later used as a sampled texture.

  • HK_IMAGE_USAGE_STORAGE_BIT: hints that the image will be later used as storage.

  • HK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT: hints that the image will be later used as a color attachment.

  • HK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT: hints that the image will be later used as a depth/stencil attachment.

As with buffers, the type of memory must be set. Image will usually use the HK_MEMORY_TYPE_GPU_ONLY. These flags are listed by hk_memory_type_e enumeration:

  • HK_MEMORY_TYPE_CPU_ONLY

  • HK_MEMORY_TYPE_GPU_ONLY

  • HK_MEMORY_TYPE_CPU_TO_GPU

  • HK_MEMORY_TYPE_GPU_TO_CPU

Resizing

haiku allows you to update the extent of your previously created hk_image_t handle using the hkgfx_image_resize:

hkgfx_image_resize(device, my_image, (hk_image_extent_t){new_width, new_height, 1} );

In this code snippet, we are resizing the previous 2D image with a new dimensions in pixels, because our image was a 2D image, we set the depth to 1.