Images¶

In order to use textures and render targets, haiku provides hk_image_t and associated utility functions in haiku/graphics.h.

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

hkgfx_image_resize(device, img, (hk_image_extent_t){app_frame_width, app_frame_height, 1} );

hkgfx_image_destroy(device,img);

How to create images¶

enum hk_image_format_e¶

Image format enum tags.

Values:

enumerator HK_IMAGE_FORMAT_DEFAULT¶

enumerator HK_IMAGE_FORMAT_RGBA8¶

enumerator HK_IMAGE_FORMAT_RGBA8_SRGB¶

enumerator HK_IMAGE_FORMAT_R32U¶

enumerator HK_IMAGE_FORMAT_R32F¶

enumerator HK_IMAGE_FORMAT_RGB16F¶

enumerator HK_IMAGE_FORMAT_RGB32F¶

enumerator HK_IMAGE_FORMAT_RGBA16F¶

enumerator HK_IMAGE_FORMAT_RGBA32F¶

enumerator HK_IMAGE_FORMAT_BGRBA8¶

enumerator HK_IMAGE_FORMAT_BGRBA8_SRGB¶

enumerator HK_IMAGE_FORMAT_DEPTH16_STENCIL8¶

enumerator HK_IMAGE_FORMAT_DEPTH24_STENCIL8¶

enumerator HK_IMAGE_FORMAT_DEPTH32F_STENCIL8¶

enumerator HK_IMAGE_FORMAT_DEPTH32F¶

enumerator HK_IMAGE_FORMAT_COUNT¶

enum hk_image_usage_flag_bits_e¶

Image usage flag bits.

Values:

enumerator HK_IMAGE_USAGE_DEFAULT¶: Default flag.

enumerator HK_IMAGE_USAGE_TRANSFER_SRC_BIT¶: Hint that image will be later used as a tranfer source.

enumerator HK_IMAGE_USAGE_TRANSFER_DST_BIT¶: Hint that image will be later used as a tranfer destination.

enumerator HK_IMAGE_USAGE_SAMPLED_BIT¶: Hint that image will be later used as a sampled texture.

enumerator HK_IMAGE_USAGE_STORAGE_BIT¶: Hint that image will be later used as storage.

enumerator HK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT¶: Hint that image will be later used as a color attachment.

enumerator HK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT¶: Hint that image will be later used as a depth/stencil attachment.

enum hk_image_type_e¶

Image type enum tags.

Values:

enumerator HK_IMAGE_TYPE_DEFAULT¶: Default image type (2D).

enumerator HK_IMAGE_TYPE_1D¶: 1D image.

enumerator HK_IMAGE_TYPE_2D¶: 2D image.

enumerator HK_IMAGE_TYPE_3D¶: 3D image.

enumerator HK_IMAGE_TYPE_CUBEMAP¶: Cubemap image.

enumerator HK_IMAGE_TYPE_1D_ARRAY¶: 1D images array.

enumerator HK_IMAGE_TYPE_2D_ARRAY¶: 2D images array.

enumerator HK_IMAGE_TYPE_CUBEMAP_ARRAY¶: Cubemap images array.

enumerator HK_IMAGE_TYPE_COUNT¶: Do not use. Internal usage only.

enum hk_image_aspect_flag_bits_e¶

Image aspect flag bits.

Values:

enumerator HK_IMAGE_ASPECT_DEFAULT¶: Default image aspect (color).

enumerator HK_IMAGE_ASPECT_COLOR_BIT¶: Suggests that the image stores color data.

enumerator HK_IMAGE_ASPECT_DEPTH_BIT¶: Suggests that the image stores depth data.

enumerator HK_IMAGE_ASPECT_STENCIL_BIT¶: Suggests that the image stores stencil data.

struct hk_gfx_image_desc¶

Graphics image configuration data structure

Public Members

char label[HK_MAX_LABEL_SIZE]¶: Optional label/name. Useful when debugging.

hk_image_type_e type¶

Texture type enum flag. Tells how data will be stored.

HK_IMAGE_TYPE_1D
HK_IMAGE_TYPE_2D
HK_IMAGE_TYPE_3D
HK_IMAGE_TYPE_CUBEMAP
HK_IMAGE_TYPE_1D_ARRAY
HK_IMAGE_TYPE_2D_ARRAY
HK_IMAGE_TYPE_CUBEMAP_ARRAY It could be omitted, the default will fallback to the 2D type.

hk_image_format_e format¶

Texture pixel format flag. Tells how pixel is formatted. Some usual formats:

HK_IMAGE_FORMAT_RGBA8
HK_IMAGE_FORMAT_R32U
HK_IMAGE_FORMAT_R32F
HK_IMAGE_FORMAT_DEPTH32F
etc. It could be omitted, the default will fallback to the RGBA8 format.

hk_image_state_e state¶

Texture pixel state flag. Tells the initial state of the image. Should be one of

HK_IMAGE_STATE_UNDEFINED
HK_IMAGE_STATE_PREINITIALIZED It could be omitted, the default will fallback to the undefined state.

uint32_t usage_flags¶: Image usage flags

uint32_t aspect_flags¶: Image aspect flags (color/depth/stencil)

hk_memory_type_e memory_type¶: Image memory type

uint32_t levels¶: Image levels (mipmap pyramid size)

uint32_t layers¶: Image layers (must be 6 for cubemaps)

hk_image_sample_count_e sample_count¶: Image sample count (multisampling)

hk_image_extent_t extent¶

hk_image_t hkgfx_image_create(hk_device_t *device, const hk_gfx_image_desc *desc)¶: Creates a gpu image/texture object.

void hkgfx_image_destroy(hk_device_t *device, hk_image_t image)¶: Destroys a gpu image/texture object.

How to resize images¶

Warning

doxygenstruct: Cannot find class “hk_image_extent_s” in doxygen xml output for project “haiku” from directory: /builds/haiku/haiku/build/docs//xml

void hkgfx_image_resize(hk_device_t *device, hk_image_t img, hk_image_extent_t new_extent)¶: Resizes a gpu image/texture object referred by handle.

How to transition between image states¶

enum hk_image_state_e¶

Image state transition enum tags.

Values:

enumerator HK_IMAGE_STATE_DEFAULT¶: Default image state.

enumerator HK_IMAGE_STATE_UNDEFINED¶: Undefined state. Used as an initial state for an image.

enumerator HK_IMAGE_STATE_PREINITIALIZED¶: Preinitialized state. Used as an initial state for an image if data is uploaded at beginning.

enumerator HK_IMAGE_STATE_RENDER_TARGET¶: Render target state. Image will be used as a target (color/depth/stencil attachment).

enumerator HK_IMAGE_STATE_SHADER_ACCESS¶: Shader unordered access state. Image will be read or written by a shader.

enumerator HK_IMAGE_STATE_SHADER_READ¶: Shader read-only state. Image will be read by a shader.

enumerator HK_IMAGE_STATE_SHADER_WRITE¶: Shader write-only state. Image will be modified by a shader.

enumerator HK_IMAGE_STATE_TRANSFER_SRC¶: Transfer source state. Image will be the source of a transfer command.

enumerator HK_IMAGE_STATE_TRANSFER_DST¶: Transfer destinatation state. Image will be the destination of a transfer command.

enumerator HK_IMAGE_STATE_DEPTH_READ¶: Depth read state. Image will be read as a depth in shaders.

enumerator HK_IMAGE_STATE_DEPTH_WRITE¶: Depth write state. Image will be modified as a depth in shaders.

enumerator HK_IMAGE_STATE_PRESENT¶: Presentation state.

enumerator HK_IMAGE_STATE_COUNT¶: Do not use. Internal usage only.

struct hk_gfx_barrier_image_params¶

Image barrier command arguments description.

Public Members

hk_image_t image¶: Image resource to transition to another state.

hk_image_state_e prev_state¶: Previous/Current image state before transition.

hk_image_state_e next_state¶: Next image state to transition.

uint32_t aspect_flags¶: Image aspect flag (how the stored data will be interpreted (color/depth/stencil)).

bool update_subresource¶: If true, user need to specify mip levels and array layers. Otherwise the whole image is transitioned.

struct hk_gfx_barrier_image_params::image_barrier_subresource_s subresource¶: Subresource description. Allows user to transition part of an image.

struct image_barrier_subresource_s¶

Public Members

uint32_t base_miplevel¶: First mipmap level to transition.

uint32_t level_count¶: Number of mipmap levels to transition.

uint32_t base_layer¶: First array layer to transition.

uint32_t layer_count¶: Number of array layers to transition.

void hkgfx_context_image_barrier(hk_context_t ctx, const hk_gfx_barrier_image_params *params)¶: Apply an image barrier command.