Image - Experimental

oneAPI Level Zero Specification - Version 1.18.31

Image - Experimental Functions

zeImageGetMemoryPropertiesExp

Added in version 1.2

ZE_APIEXPORT ze_result_t ZE_APICALL zeImageGetMemoryPropertiesExp(ze_image_handle_t hImage, ze_image_memory_properties_exp_t *pMemoryProperties)

Query image memory properties.

• The application may call this function from simultaneous threads.

• The implementation of this function must be thread-safe.

• The implementation must support ZE_IMAGE_MEMORY_PROPERTIES_EXP_NAME extension.

Remark

Analogues

• None

Parameters:

• hImage – [in] handle of image object

• pMemoryProperties – [in,out] query result for image memory properties.

Returns:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hImage

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pMemoryProperties

zeImageViewCreateExp

Added in version 1.2

ZE_APIEXPORT ze_result_t ZE_APICALL zeImageViewCreateExp(ze_context_handle_t hContext, ze_device_handle_t hDevice, const ze_image_desc_t *desc, ze_image_handle_t hImage, ze_image_handle_t *phImageView)

Create image view on the context.

• The application must only use the image view for the device, or its sub-devices, which was provided during creation.

• The application may call this function from simultaneous threads.

• The implementation of this function must be thread-safe.

• The implementation must support ZE_IMAGE_VIEW_EXP_NAME extension.

• Image views are treated as images from the API.

• Image views provide a mechanism to redescribe how an image is interpreted (e.g. different format).

• Image views become disabled when their corresponding image resource is destroyed.

• Use zeImageDestroy to destroy image view objects.

• Note: This function is deprecated and replaced by zeImageViewCreateExt.

Remark

Analogues

• None

Parameters:

• hContext – [in] handle of the context object

• hDevice – [in] handle of the device

• desc – [in] pointer to image descriptor

• hImage – [in] handle of image object to create view from

• phImageView – [out] pointer to handle of image object created for view

Returns:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hContext

  • nullptr == hDevice

  • nullptr == hImage

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == desc

  • nullptr == phImageView

• ZE_RESULT_ERROR_INVALID_ENUMERATION

  • 0x3 < desc->flags

  • ZE_IMAGE_TYPE_BUFFER < desc->type

• ZE_RESULT_ERROR_UNSUPPORTED_ENUMERATION

• ZE_RESULT_ERROR_UNSUPPORTED_IMAGE_FORMAT

zeImageGetDeviceOffsetExp

Added in version 1.9

ZE_APIEXPORT ze_result_t ZE_APICALL zeImageGetDeviceOffsetExp(ze_image_handle_t hImage, uint64_t *pDeviceOffset)

Get bindless device offset for image.

• The application may call this function from simultaneous threads

• The implementation of this function must be thread-safe.

• The implementation of this function should be lock-free.

• The implementation must support ZE_BINDLESS_IMAGE_EXP_NAME extension.

Parameters:

• hImage – [in] handle of the image

• pDeviceOffset – [out] bindless device offset for image

Returns:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hImage

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pDeviceOffset

Image - Experimental Enums

ze_image_bindless_exp_flags_t

Added in version 1.9

enum ze_image_bindless_exp_flag_t

Values:

enumerator ZE_IMAGE_BINDLESS_EXP_FLAG_BINDLESS

Bindless images are created with zeImageCreate. The image handle created with this flag is valid on both host and device.

enumerator ZE_IMAGE_BINDLESS_EXP_FLAG_SAMPLED_IMAGE

Bindless sampled images are created with zeImageCreate by combining BINDLESS and SAMPLED_IMAGE. Create sampled image view from bindless unsampled image using SAMPLED_IMAGE.

enumerator ZE_IMAGE_BINDLESS_EXP_FLAG_FORCE_UINT32

Value marking end of ZE_IMAGE_BINDLESS_EXP_FLAG_* ENUMs.

Image - Experimental Structures

ze_image_memory_properties_exp_t

Added in version 1.2

struct ze_image_memory_properties_exp_t

Image memory properties.

Public Members

ze_structure_type_t stype

[in] type of this structure

const void *pNext

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

uint64_t size

[out] size of image allocation in bytes.

uint64_t rowPitch

[out] size of image row in bytes.

uint64_t slicePitch

[out] size of image slice in bytes.

ze_image_view_planar_exp_desc_t

Added in version 1.2

struct ze_image_view_planar_exp_desc_t

Image view planar descriptor.

Public Members

ze_structure_type_t stype

[in] type of this structure

const void *pNext

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

uint32_t planeIndex

[DEPRECATED] no longer supported, use ze_image_view_planar_ext_desc_t instead

ze_image_bindless_exp_desc_t

Added in version 1.9

struct ze_image_bindless_exp_desc_t

Image descriptor for bindless images. This structure may be passed to zeImageCreate via pNext member of ze_image_desc_t.

Public Members

ze_structure_type_t stype

[in] type of this structure

const void *pNext

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_image_bindless_exp_flags_t flags

[in] image flags. must be 0 (default) or a valid value of ze_image_bindless_exp_flag_t default behavior is bindless images are not used when creating handles via zeImageCreate. When the flag is passed to zeImageCreate, then only the memory for the image is allocated. Additional image handles can be created with zeImageViewCreateExt. When ZE_IMAGE_BINDLESS_EXP_FLAG_SAMPLED_IMAGE flag is passed, ze_sampler_desc_t must be attached via pNext member of ze_image_bindless_exp_desc_t.

ze_image_pitched_exp_desc_t

Added in version 1.9

struct ze_image_pitched_exp_desc_t

Image descriptor for bindless images created from pitched allocations. This structure may be passed to zeImageCreate via pNext member of ze_image_desc_t.

Public Members

ze_structure_type_t stype

[in] type of this structure

const void *pNext

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

void *ptr

[in] pointer to pitched device allocation allocated using zeMemAllocDevice