oneAPI Level Zero Specification - Version 1.13.0
Common#Enumerations
Structures
Defines Return/Error codes.
Values:
[Core] success
[Core] synchronization primitive not signaled
[Core] device hung, reset, was removed, or driver update occurred
[Core] insufficient host memory to satisfy call
[Core] insufficient device memory to satisfy call
[Core] error occurred when building module, see build log for details
[Core] error occurred when linking modules, see build log for details
[Core] device requires a reset
[Core] device currently in low power state
[Core, Experimental] device is not represented by a fabric vertex
[Core, Experimental] fabric vertex does not represent a device
[Core, Experimental] fabric vertex represents a remote device or subdevice
[Core, Experimental] operands of comparison are not compatible
[Core, Experimental] ray tracing acceleration structure build operation failed due to insufficient resources, retry with a larger acceleration structure buffer allocation
[Core, Experimental] ray tracing acceleration structure build operation deferred to parallel operation join
[Sysman] access denied due to permission level
[Sysman] resource already in use and simultaneous access not allowed or resource was removed
[Common] external required dependency is unavailable or missing
[Tools] data may have been dropped
[Validation] driver is not initialized
[Validation] generic error code for unsupported versions
[Validation] generic error code for unsupported features
[Validation] generic error code for invalid arguments
[Validation] handle argument is not valid
[Validation] object pointed to by handle still in-use by device
[Validation] pointer argument may not be nullptr
[Validation] size argument is invalid (e.g., must not be zero)
[Validation] size argument is not supported by the device (e.g., too large)
[Validation] alignment argument is not supported by the device (e.g., too small)
[Validation] synchronization object in invalid state
[Validation] enumerator argument is not valid
[Validation] enumerator argument is not supported by the device
[Validation] image format is not supported by the device
[Validation] native binary is not supported by the device
[Validation] global variable is not found in the module
[Validation] kernel name is not found in the module
[Validation] function name is not found in the module
[Validation] group size dimension is not valid for the kernel or device
[Validation] global width dimension is not valid for the kernel or device
[Validation] kernel argument index is not valid for kernel
[Validation] kernel argument size does not match kernel
[Validation] value of kernel attribute is not valid for the kernel or device
[Validation] module with imports needs to be linked before kernels can be created from it.
[Validation] command list type does not match command queue type
[Validation] copy operations do not support overlapping regions of memory
[Sysman] an action is required to complete the desired operation
[Core, Validation] kernel handle is invalid for the operation
[Core, Extension] ray tracing acceleration structure build operation failed due to insufficient resources, retry with a larger acceleration structure buffer allocation
[Core, Extension] ray tracing acceleration structure build operation deferred to parallel operation join
[Core, Extension] operands of comparison are not compatible
[Sysman] device is in survivability mode, firmware update needed
[Core] unknown or internal error
Value marking end of ZE_RESULT_* ENUMs.
Defines structure types.
Values:
ze_kernel_max_group_size_ext_properties_t
Value marking end of ZE_STRUCTURE_TYPE_* ENUMs.
Values:
an opaque POSIX file descriptor handle
a file descriptor handle for a Linux dma_buf
an NT handle
a global share (KMT) handle
an NT handle referring to a Direct3D 10 or 11 texture resource
a global share (KMT) handle referring to a Direct3D 10 or 11 texture resource
an NT handle referring to a Direct3D 12 heap resource
an NT handle referring to a Direct3D 12 committed resource
Value marking end of ZE_EXTERNAL_MEMORY_TYPE_FLAG_* ENUMs.
Bandwidth unit.
Values:
The unit used for bandwidth is unknown.
Bandwidth is provided in bytes/nanosec.
Bandwidth is provided in bytes/clock.
Value marking end of ZE_BANDWIDTH_UNIT_* ENUMs.
Latency unit.
Values:
The unit used for latency is unknown.
Latency is provided in nanosecs.
Latency is provided in clocks.
Latency is provided in hops (normalized so that the lowest latency link has a latency of 1 hop)
Value marking end of ZE_LATENCY_UNIT_* ENUMs.
IPC handle to a memory allocation.
Public Members
[out] Opaque data representing an IPC handle
IPC handle to a event pool allocation.
Public Members
[out] Opaque data representing an IPC handle
Universal unique id (UUID)
Public Members
[out] opaque data representing a UUID
Base for all callback function parameter types.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
Base for all properties types.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
Base for all descriptor types.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
Functions
Enumerations
Structures
Initialize the ‘oneAPI’ driver(s)
since 1.10. Please use zeInitDrivers()
flags – [in] initialization flags. must be 0 (default) or a combination of ze_init_flag_t.
Retrieves driver instances.
since 1.10. Please use zeInitDrivers()
pCount – [in,out] pointer to the number of driver instances. if count is zero, then the loader shall update the value with the total number of drivers available. if count is greater than the number of drivers available, then the loader shall update the value with the correct number of drivers available.
phDrivers – [in,out][optional][range(0, *pCount)] array of driver instance handles. if count is less than the number of drivers available, then the loader shall only retrieve that number of drivers.
Initialize the ‘oneAPI’ driver(s) based on the driver types requested and retrieve the driver handles.
The application must call this function or zeInit before calling any other function. (zeInit is [Deprecated] and is replaced by zeInitDrivers)
Calls to zeInit[Deprecated] or InitDrivers will not alter the drivers retrieved through either api.
Drivers init through zeInit[Deprecated] or InitDrivers will not be reInitialized once init in an application. The Loader will determine if the already init driver needs to be delivered to the user through the init type flags.
Already init Drivers will not be uninitialized if the call to InitDrivers does not include that driver’s type. Those init drivers which don’t match the init flags will not have their driver handles returned to the user in that InitDrivers call.
If this function or zeInit[Deprecated] is not called, then all other functions will return ZE_RESULT_ERROR_UNINITIALIZED.
Only one instance of each driver will be initialized per process.
A driver represents a collection of physical devices.
Multiple calls to this function will return identical driver handles, in the same order.
The drivers returned to the caller will be based on the init types which state the drivers to be included.
The application may pass nullptr for pDrivers when only querying the number of drivers.
The application may call this function multiple times with different flags or environment variables enabled.
The application must call this function after forking new processes. Each forked process must call this function.
The application may call this function from simultaneous threads.
The implementation of this function must be thread-safe for scenarios where multiple libraries may initialize the driver(s) simultaneously.
pCount – [in,out] pointer to the number of driver instances. if count is zero, then the loader shall update the value with the total number of drivers available. if count is greater than the number of drivers available, then the loader shall update the value with the correct number of drivers available.
phDrivers – [in,out][optional][range(0, *pCount)] array of driver instance handles. if count is less than the number of drivers available, then the loader shall only retrieve that number of drivers.
desc – [in] descriptor containing the driver type initialization details including ze_init_driver_type_flag_t combinations.
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pCount
nullptr == desc
ZE_RESULT_ERROR_INVALID_ENUMERATION
0x0 == desc->flags
Returns the API version supported by the specified driver.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hDriver – [in] handle of the driver instance
version – [out] api version
Retrieves properties of the driver.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hDriver – [in] handle of the driver instance
pDriverProperties – [in,out] query result for driver properties
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hDriver
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pDriverProperties
Retrieves IPC attributes of the driver.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hDriver – [in] handle of the driver instance
pIpcProperties – [in,out] query result for IPC properties
Retrieves extension properties.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hDriver – [in] handle of the driver instance
pCount – [in,out] pointer to the number of extension properties. if count is zero, then the driver shall update the value with the total number of extension properties available. if count is greater than the number of extension properties available, then the driver shall update the value with the correct number of extension properties available.
pExtensionProperties – [in,out][optional][range(0, *pCount)] array of query results for extension properties. if count is less than the number of extension properties available, then driver shall only retrieve that number of extension properties.
Retrieves function pointer for vendor-specific or experimental extensions.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hDriver – [in] handle of the driver instance
name – [in] extension function name
ppFunctionAddress – [out] pointer to function pointer
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hDriver
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == name
nullptr == ppFunctionAddress
Retrieves a string describing the last error code returned by the driver in the current thread.
String returned is thread local.
String is only updated on calls returning an error, i.e., not on calls returning ZE_RESULT_SUCCESS.
String may be empty if driver considers error code is already explicit enough to describe cause.
Memory pointed to by ppString is owned by the driver.
String returned is null-terminated.
hDriver – [in] handle of the driver instance
ppString – [in,out] pointer to a null-terminated array of characters describing cause of error.
Values:
only initialize GPU drivers
only initialize VPU drivers
Value marking end of ZE_INIT_FLAG_* ENUMs.
Values:
initialize and retrieve GPU drivers
initialize and retrieve NPU drivers
Value marking end of ZE_INIT_DRIVER_TYPE_FLAG_* ENUMs.
Supported API versions.
API versions contain major and minor attributes, use ZE_MAJOR_VERSION and ZE_MINOR_VERSION
Values:
version 1.0
version 1.1
version 1.2
version 1.3
version 1.4
version 1.5
version 1.6
version 1.7
version 1.8
version 1.9
version 1.10
version 1.11
version 1.12
latest known version
Value marking end of ZE_API_VERSION_* ENUMs.
Values:
Supports passing memory allocations between processes. See zeMemGetIpcHandle.
Supports passing event pools between processes. See zeEventPoolGetIpcHandle.
Value marking end of ZE_IPC_PROPERTY_FLAG_* ENUMs.
Init Driver Type descriptor.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] driver type init flags. must be a valid combination of ze_init_driver_type_flag_t or UINT32_MAX; driver types are init and retrieved based on these init flags in zeInitDrivers().
Driver universal unique id (UUID)
Public Members
[out] opaque data representing a driver UUID
Driver properties queried using zeDriverGetProperties.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] universal unique identifier.
[out] driver version The driver version is a non-zero, monotonically increasing value where higher values always indicate a more recent version.
IPC properties queried using zeDriverGetIpcProperties.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] 0 (none) or a valid combination of ze_ipc_property_flag_t
Extension properties queried using zeDriverGetExtensionProperties.
Public Members
[out] extension name
[out] extension version using ZE_MAKE_VERSION
Functions
Enumerations
Structures
Retrieves devices within a driver.
Multiple calls to this function will return identical device handles, in the same order.
The number and order of handles returned from this function is affected by the ::ZE_AFFINITY_MASK and ::ZE_ENABLE_PCI_ID_DEVICE_ORDER environment variables.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hDriver – [in] handle of the driver instance
pCount – [in,out] pointer to the number of devices. if count is zero, then the driver shall update the value with the total number of devices available. if count is greater than the number of devices available, then the driver shall update the value with the correct number of devices available.
phDevices – [in,out][optional][range(0, *pCount)] array of handle of devices. if count is less than the number of devices available, then driver shall only retrieve that number of devices.
Retrieves the root-device of a device handle.
When the device handle passed does not belong to any root-device, nullptr is returned.
Multiple calls to this function will return the same device handle.
The root-device handle returned by this function does not have access automatically to the resources created with the associated sub-device, unless those resources have been created with a context explicitly containing both handles.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hDevice – [in] handle of the device object
phRootDevice – [in,out] parent root device.
Retrieves a sub-device from a device.
When the device handle passed does not contain any sub-device, a pCount of 0 is returned.
Multiple calls to this function will return identical device handles, in the same order.
The number of handles returned from this function is affected by the ::ZE_AFFINITY_MASK environment variable.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hDevice – [in] handle of the device object
pCount – [in,out] pointer to the number of sub-devices. if count is zero, then the driver shall update the value with the total number of sub-devices available. if count is greater than the number of sub-devices available, then the driver shall update the value with the correct number of sub-devices available.
phSubdevices – [in,out][optional][range(0, *pCount)] array of handle of sub-devices. if count is less than the number of sub-devices available, then driver shall only retrieve that number of sub-devices.
Retrieves properties of the device.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hDevice – [in] handle of the device
pDeviceProperties – [in,out] query result for device properties
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hDevice
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pDeviceProperties
Retrieves compute properties of the device.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hDevice – [in] handle of the device
pComputeProperties – [in,out] query result for compute properties
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hDevice
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pComputeProperties
Retrieves module properties of the device.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hDevice – [in] handle of the device
pModuleProperties – [in,out] query result for module properties
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hDevice
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pModuleProperties
Retrieves command queue group properties of the device.
Properties are reported for each physical command queue type supported by the device.
Multiple calls to this function will return properties in the same order.
The order in which the properties are returned defines the command queue group’s ordinal.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hDevice – [in] handle of the device
pCount – [in,out] pointer to the number of command queue group properties. if count is zero, then the driver shall update the value with the total number of command queue group properties available. if count is greater than the number of command queue group properties available, then the driver shall update the value with the correct number of command queue group properties available.
pCommandQueueGroupProperties – [in,out][optional][range(0, *pCount)] array of query results for command queue group properties. if count is less than the number of command queue group properties available, then driver shall only retrieve that number of command queue group properties.
Retrieves local memory properties of the device.
Properties are reported for each physical memory type supported by the device.
Multiple calls to this function will return properties in the same order.
The order in which the properties are returned defines the device’s local memory ordinal.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hDevice – [in] handle of the device
pCount – [in,out] pointer to the number of memory properties. if count is zero, then the driver shall update the value with the total number of memory properties available. if count is greater than the number of memory properties available, then the driver shall update the value with the correct number of memory properties available.
pMemProperties – [in,out][optional][range(0, *pCount)] array of query results for memory properties. if count is less than the number of memory properties available, then driver shall only retrieve that number of memory properties.
Retrieves memory access properties of the device.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hDevice – [in] handle of the device
pMemAccessProperties – [in,out] query result for memory access properties
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hDevice
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pMemAccessProperties
Retrieves cache properties of the device.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hDevice – [in] handle of the device
pCount – [in,out] pointer to the number of cache properties. if count is zero, then the driver shall update the value with the total number of cache properties available. if count is greater than the number of cache properties available, then the driver shall update the value with the correct number of cache properties available.
pCacheProperties – [in,out][optional][range(0, *pCount)] array of query results for cache properties. if count is less than the number of cache properties available, then driver shall only retrieve that number of cache properties.
Retrieves image properties of the device.
See zeImageGetProperties for format-specific capabilities.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hDevice – [in] handle of the device
pImageProperties – [in,out] query result for image properties
Retrieves external memory import and export of the device.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hDevice – [in] handle of the device
pExternalMemoryProperties – [in,out] query result for external memory properties
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hDevice
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pExternalMemoryProperties
Retrieves peer-to-peer properties between one device and a peer devices.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hDevice – [in] handle of the device performing the access
hPeerDevice – [in] handle of the peer device with the allocation
pP2PProperties – [in,out] Peer-to-Peer properties between source and peer device
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hDevice
nullptr == hPeerDevice
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pP2PProperties
Queries if one device can directly access peer device allocations.
Any device can access any other device within a node through a scale-up fabric.
The following are conditions for CanAccessPeer query.
If both device and peer device are the same then return true.
If both sub-device and peer sub-device are the same then return true.
If both are sub-devices and share the same parent device then return true.
If both device and remote device are connected by a direct or indirect scale-up fabric or over PCIe (same root complex or shared PCIe switch) then true.
If both sub-device and remote parent device (and vice-versa) are connected by a direct or indirect scale-up fabric or over PCIe (same root complex or shared PCIe switch) then true.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hDevice – [in] handle of the device performing the access
hPeerDevice – [in] handle of the peer device with the allocation
value – [out] returned access capability
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hDevice
nullptr == hPeerDevice
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == value
Returns current status of the device.
Once a device is reset, this call will update the OS handle attached to the device handle.
The application may call this function from simultaneous threads with the same device handle.
The implementation of this function must be thread-safe.
hDevice – [in] handle of the device
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hDevice
Device is available for use.
Device is lost; must be reset for use.
Returns synchronized Host and device global timestamps.
The application may call this function from simultaneous threads with the same device handle.
The implementation of this function must be thread-safe.
hDevice – [in] handle of the device
hostTimestamp – [out] value of the Host’s global timestamp that correlates with the Device’s global timestamp value.
deviceTimestamp – [out] value of the Device’s global timestamp that correlates with the Host’s global timestamp value.
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hDevice
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == hostTimestamp
nullptr == deviceTimestamp
ZE_RESULT_ERROR_UNSUPPORTED_FEATURE
The feature is not supported by the underlying platform.
Supported device types.
Values:
Graphics Processing Unit.
Central Processing Unit.
Field Programmable Gate Array.
Memory Copy Accelerator.
Vision Processing Unit.
Value marking end of ZE_DEVICE_TYPE_* ENUMs.
Values:
Device is integrated with the Host.
Device handle used for query represents a sub-device.
Device supports error correction memory access.
Device supports on-demand page-faulting.
Value marking end of ZE_DEVICE_PROPERTY_FLAG_* ENUMs.
Values:
Device supports 16-bit floating-point operations.
Device supports 64-bit floating-point operations.
Device supports 64-bit atomic operations.
Device supports four component dot product and accumulate operations.
Value marking end of ZE_DEVICE_MODULE_FLAG_* ENUMs.
Values:
Supports denorms.
Supports INF and quiet NaNs.
Supports rounding to nearest even rounding mode.
Supports rounding to zero.
Supports rounding to both positive and negative INF.
Supports IEEE754-2008 fused multiply-add.
Supports rounding as defined by IEEE754 for divide and sqrt operations.
Uses software implementation for basic floating-point operations.
Value marking end of ZE_DEVICE_FP_FLAG_* ENUMs.
Values:
Command queue group supports enqueing compute commands.
Command queue group supports enqueing copy commands.
Command queue group supports cooperative kernels. See zeCommandListAppendLaunchCooperativeKernel for more details.
Command queue groups supports metric queries.
Value marking end of ZE_COMMAND_QUEUE_GROUP_PROPERTY_FLAG_* ENUMs.
Values:
reserved for future use
Value marking end of ZE_DEVICE_MEMORY_PROPERTY_FLAG_* ENUMs.
Values:
Supports load/store access.
Supports atomic access.
Supports concurrent access.
Supports concurrent atomic access.
Value marking end of ZE_MEMORY_ACCESS_CAP_FLAG_* ENUMs.
Values:
Device support User Cache Control (i.e. SLM section vs Generic Cache)
Value marking end of ZE_DEVICE_CACHE_PROPERTY_FLAG_* ENUMs.
Values:
Device supports access between peer devices.
Device supports atomics between peer devices.
Value marking end of ZE_DEVICE_P2P_PROPERTY_FLAG_* ENUMs.
Device universal unique id (UUID)
Public Members
[out] opaque data representing a device UUID
Device properties queried using zeDeviceGetProperties.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] generic device type
[out] vendor id from PCI configuration
[out] device id from PCI configuration. Note, the device id uses little-endian format.
[out] 0 (none) or a valid combination of ze_device_property_flag_t
[out] sub-device id. Only valid if ZE_DEVICE_PROPERTY_FLAG_SUBDEVICE is set.
[out] Clock rate for device core.
[out] Maximum memory allocation size.
[out] Maximum number of logical hardware contexts.
[out] Maximum priority for command queues. Higher value is higher priority.
[out] Maximum number of threads per EU.
[out] The physical EU simd width.
[out] Maximum number of EUs per sub-slice.
[out] Maximum number of sub-slices per slice.
[out] Maximum number of slices.
[out] Returns the resolution of device timer used for profiling, timestamps, etc. When stype==ZE_STRUCTURE_TYPE_DEVICE_PROPERTIES the units are in nanoseconds. When stype==ZE_STRUCTURE_TYPE_DEVICE_PROPERTIES_1_2 units are in cycles/sec
[out] Returns the number of valid bits in the timestamp value.
[out] Returns the number of valid bits in the kernel timestamp values
[out] universal unique identifier. Note: Subdevices will have their own uuid.
[out] Device name
Device thread identifier.
Public Members
[in,out] the slice number. Must be UINT32_MAX (all) or less than the numSlices member of ze_device_properties_t.
[in,out] the sub-slice number within its slice. Must be UINT32_MAX (all) or less than the numSubslicesPerSlice member of ze_device_properties_t.
[in,out] the EU number within its sub-slice. Must be UINT32_MAX (all) or less than the numEUsPerSubslice member of ze_device_properties_t.
[in,out] the thread number within its EU. Must be UINT32_MAX (all) or less than the numThreadsPerEU member of ze_device_properties_t.
Device compute properties queried using zeDeviceGetComputeProperties.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] Maximum items per compute group. (groupSizeX * groupSizeY * groupSizeZ) <= maxTotalGroupSize
[out] Maximum items for X dimension in group
[out] Maximum items for Y dimension in group
[out] Maximum items for Z dimension in group
[out] Maximum groups that can be launched for x dimension
[out] Maximum groups that can be launched for y dimension
[out] Maximum groups that can be launched for z dimension
[out] Maximum shared local memory per group.
[out] Number of subgroup sizes supported. This indicates number of entries in subGroupSizes.
[out] Size group sizes supported.
Native kernel universal unique id (UUID)
Public Members
[out] opaque data representing a native kernel UUID
Device module properties queried using zeDeviceGetModuleProperties.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] Maximum supported SPIR-V version. Returns zero if SPIR-V is not supported. Contains major and minor attributes, use ZE_MAJOR_VERSION and ZE_MINOR_VERSION.
[out] 0 or a valid combination of ze_device_module_flag_t
[out] Capabilities for half-precision floating-point operations. returns 0 (if ZE_DEVICE_MODULE_FLAG_FP16 is not set) or a combination of ze_device_fp_flag_t.
[out] Capabilities for single-precision floating-point operations. returns a combination of ze_device_fp_flag_t.
[out] Capabilities for double-precision floating-point operations. returns 0 (if ZE_DEVICE_MODULE_FLAG_FP64 is not set) or a combination of ze_device_fp_flag_t.
[out] Maximum kernel argument size that is supported.
[out] Maximum size of internal buffer that holds output of printf calls from kernel.
[out] Compatibility UUID of supported native kernel. UUID may or may not be the same across driver release, devices, or operating systems. Application is responsible for ensuring UUID matches before creating module using previously created native kernel.
Command queue group properties queried using zeDeviceGetCommandQueueGroupProperties.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] 0 (none) or a valid combination of ze_command_queue_group_property_flag_t
[out] maximum pattern_size supported by command queue group. See zeCommandListAppendMemoryFill for more details.
[out] the number of physical engines within the group.
Device local memory properties queried using zeDeviceGetMemoryProperties.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] 0 (none) or a valid combination of ze_device_memory_property_flag_t
[out] Maximum clock rate for device memory.
[out] Maximum bus width between device and memory.
[out] Total memory size in bytes that is available to the device.
[out] Memory name
Device memory access properties queried using zeDeviceGetMemoryAccessProperties.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] host memory capabilities. returns 0 (unsupported) or a combination of ze_memory_access_cap_flag_t.
[out] device memory capabilities. returns 0 (unsupported) or a combination of ze_memory_access_cap_flag_t.
[out] shared, single-device memory capabilities. returns 0 (unsupported) or a combination of ze_memory_access_cap_flag_t.
[out] shared, cross-device memory capabilities. returns 0 (unsupported) or a combination of ze_memory_access_cap_flag_t.
[out] shared, system memory capabilities. returns 0 (unsupported) or a combination of ze_memory_access_cap_flag_t.
Device cache properties queried using zeDeviceGetCacheProperties.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] 0 (none) or a valid combination of ze_device_cache_property_flag_t
[out] Per-cache size, in bytes
Device image properties queried using zeDeviceGetImageProperties.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] Maximum image dimensions for 1D resources. if 0, then 1D images are unsupported.
[out] Maximum image dimensions for 2D resources. if 0, then 2D images are unsupported.
[out] Maximum image dimensions for 3D resources. if 0, then 3D images are unsupported.
[out] Maximum image buffer size in bytes. if 0, then buffer images are unsupported.
[out] Maximum image array slices. if 0, then image arrays are unsupported.
[out] Max samplers that can be used in kernel. if 0, then sampling is unsupported.
[out] Returns the maximum number of simultaneous image objects that can be read from by a kernel. if 0, then reading images is unsupported.
[out] Returns the maximum number of simultaneous image objects that can be written to by a kernel. if 0, then writing images is unsupported.
Device external memory import and export properties.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] Supported external memory import types for memory allocations.
[out] Supported external memory export types for memory allocations.
[out] Supported external memory import types for images.
[out] Supported external memory export types for images.
Device peer-to-peer properties queried using zeDeviceGetP2PProperties.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] 0 (none) or a valid combination of ze_device_p2p_property_flag_t
Functions
Enumerations
Structures
Creates a context for the driver.
The application must only use the context for the driver which was provided during creation.
The application may call this function from simultaneous threads.
The implementation of this function must be thread-safe.
hDriver – [in] handle of the driver object
desc – [in] pointer to context descriptor
phContext – [out] pointer to handle of context object created
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hDriver
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == desc
nullptr == phContext
ZE_RESULT_ERROR_INVALID_ENUMERATION
0x1 < desc->flags
Creates a context for the driver.
The application must only use the context for the driver which was provided during creation.
The application may call this function from simultaneous threads.
The implementation of this function must be thread-safe.
hDriver – [in] handle of the driver object
desc – [in] pointer to context descriptor
numDevices – [in][optional] number of device handles; must be 0 if `nullptr == phDevices`
phDevices – [in][optional][range(0, numDevices)] array of device handles which context has visibility. if nullptr, then all devices and any sub-devices supported by the driver instance are visible to the context. otherwise, the context only has visibility to the devices and any sub-devices of the devices in this array.
phContext – [out] pointer to handle of context object created
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hDriver
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == desc
nullptr == phContext
ZE_RESULT_ERROR_INVALID_ENUMERATION
0x1 < desc->flags
(nullptr == phDevices) && (0 < numDevices)
Destroys a context.
The application must ensure the device is not currently referencing the context before it is deleted.
The implementation of this function may immediately free all Host and Device allocations associated with this context.
The application must not call this function from simultaneous threads with the same context handle.
The implementation of this function must be thread-safe.
hContext – [in][release] handle of context object to destroy
Returns current status of the context.
The application may call this function from simultaneous threads with the same context handle.
The implementation of this function should be lock-free.
hContext – [in] handle of context object
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hContext
Context is available for use.
Context is invalid; due to device lost or reset.
Values:
reserved for future use
Value marking end of ZE_CONTEXT_FLAG_* ENUMs.
Context descriptor.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] creation flags. must be 0 (default) or a valid combination of ze_context_flag_t; default behavior may use implicit driver-based heuristics.
Functions
Enumerations
Structures
Creates a command queue on the context.
A command queue represents a logical input stream to the device, tied to a physical input stream.
The application must only use the command queue 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.
hContext – [in] handle of the context object
hDevice – [in] handle of the device object
desc – [in] pointer to command queue descriptor
phCommandQueue – [out] pointer to handle of command queue object created
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hContext
nullptr == hDevice
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == desc
nullptr == phCommandQueue
ZE_RESULT_ERROR_INVALID_ENUMERATION
0x3 < desc->flags
ZE_COMMAND_QUEUE_MODE_ASYNCHRONOUS < desc->mode
ZE_COMMAND_QUEUE_PRIORITY_PRIORITY_HIGH < desc->priority
Destroys a command queue.
The application must destroy all fence handles created from the command queue before destroying the command queue itself
The application must ensure the device is not currently referencing the command queue before it is deleted
The implementation of this function may immediately free all Host and Device allocations associated with this command queue
The application must not call this function from simultaneous threads with the same command queue handle.
The implementation of this function must be thread-safe.
hCommandQueue – [in][release] handle of command queue object to destroy
Executes a command list in a command queue.
The command lists are submitted to the device in the order they are received, whether from multiple calls (on the same or different threads) or a single call with multiple command lists.
The application must ensure the command lists are accessible by the device on which the command queue was created.
The application must ensure the device is not currently referencing the command list since the implementation is allowed to modify the contents of the command list for submission.
The application must only execute command lists created with an identical command queue group ordinal to the command queue.
The application must use a fence created using the same command queue.
The application must ensure the command queue, command list and fence were created on the same context.
The application must ensure the command lists being executed are not immediate command lists.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hCommandQueue – [in] handle of the command queue
numCommandLists – [in] number of command lists to execute
phCommandLists – [in][range(0, numCommandLists)] list of handles of the command lists to execute
hFence – [in][optional] handle of the fence to signal on completion
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hCommandQueue
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == phCommandLists
0 == numCommandLists
Synchronizes a command queue by waiting on the host.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hCommandQueue – [in] handle of the command queue
timeout – [in] if non-zero, then indicates the maximum time (in nanoseconds) to yield before returning ZE_RESULT_SUCCESS or ZE_RESULT_NOT_READY; if zero, then immediately returns the status of the command queue; if `UINT64_MAX`, then function will not return until complete or device is lost. Due to external dependencies, timeout may be rounded to the closest value allowed by the accuracy of those dependencies.
Gets the command queue group ordinal.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hCommandQueue – [in] handle of the command queue
pOrdinal – [out] command queue group ordinal
Gets the command queue index within the group.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hCommandQueue – [in] handle of the command queue
pIndex – [out] command queue index within the group
Values:
command queue should be optimized for submission to a single device engine. driver must disable any implicit optimizations for distributing work across multiple engines. this flag should be used when applications want full control over multi-engine submission and scheduling. This flag is DEPRECATED as flag ${X}_COMMAND_LIST_FLAG_EXPLICIT_ONLY is DEPRECATED.
To be used only when creating immediate command lists. Commands appended to the immediate command list are executed in-order, with driver implementation enforcing dependencies between them. Application is not required to have the signal event of a given command being the wait event of the next to define an in-order list, and application is allowed to pass signal and wait events to each appended command to implement more complex dependency graphs.
Value marking end of ZE_COMMAND_QUEUE_FLAG_* ENUMs.
Supported command queue modes.
Values:
implicit default behavior; uses driver-based heuristics
Device execution always completes immediately on execute; Host thread is blocked using wait on implicit synchronization object
Device execution is scheduled and will complete in future; explicit synchronization object must be used to determine completeness
Value marking end of ZE_COMMAND_QUEUE_MODE_* ENUMs.
Supported command queue priorities.
Values:
[default] normal priority
lower priority than normal
higher priority than normal
Value marking end of ZE_COMMAND_QUEUE_PRIORITY_* ENUMs.
Command Queue descriptor.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] command queue group ordinal
[in] command queue index within the group; must be zero.
[in] usage flags. must be 0 (default) or a valid combination of ze_command_queue_flag_t; default behavior may use implicit driver-based heuristics to balance latency and throughput.
[in] operation mode
[in] priority
Functions
Enumerations
Structures
Creates a command list on the context.
A command list represents a sequence of commands for execution on a command queue.
The command list is created in the ‘open’ state.
The application must only use the command list 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.
hContext – [in] handle of the context object
hDevice – [in] handle of the device object
desc – [in] pointer to command list descriptor
phCommandList – [out] pointer to handle of command list object created
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hContext
nullptr == hDevice
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == desc
nullptr == phCommandList
ZE_RESULT_ERROR_INVALID_ENUMERATION
0x1f < desc->flags
Creates an immediate command list on the context.
An immediate command list is used for low-latency submission of commands.
An immediate command list creates an implicit command queue.
Immediate command lists must not be passed to zeCommandQueueExecuteCommandLists.
Commands appended into an immediate command list may execute synchronously, by blocking until the command is complete.
The command list is created in the ‘open’ state and never needs to be closed.
The application must only use the command list 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.
hContext – [in] handle of the context object
hDevice – [in] handle of the device object
altdesc – [in] pointer to command queue descriptor
phCommandList – [out] pointer to handle of command list object created
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hContext
nullptr == hDevice
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == altdesc
nullptr == phCommandList
ZE_RESULT_ERROR_INVALID_ENUMERATION
0x3 < altdesc->flags
ZE_COMMAND_QUEUE_MODE_ASYNCHRONOUS < altdesc->mode
ZE_COMMAND_QUEUE_PRIORITY_PRIORITY_HIGH < altdesc->priority
Destroys a command list.
The application must ensure the device is not currently referencing the command list before it is deleted.
The implementation of this function may immediately free all Host and Device allocations associated with this command list.
The application must not call this function from simultaneous threads with the same command list handle.
The implementation of this function must be thread-safe.
hCommandList – [in][release] handle of command list object to destroy
Closes a command list; ready to be executed by a command queue.
The application must not call this function from simultaneous threads with the same command list handle.
The implementation of this function should be lock-free.
hCommandList – [in] handle of command list object to close
Reset a command list to initial (empty) state; ready for appending commands.
The application must ensure the device is not currently referencing the command list before it is reset
The application must not call this function from simultaneous threads with the same command list handle.
The implementation of this function should be lock-free.
hCommandList – [in] handle of command list object to reset
Appends a memory write of the device’s global timestamp value into a command list.
The application must ensure the events are accessible by the device on which the command list was created.
The timestamp frequency can be queried from the timerResolution member of ze_device_properties_t.
The number of valid bits in the timestamp value can be queried from the timestampValidBits member of ze_device_properties_t.
The application must ensure the memory pointed to by dstptr is accessible by the device on which the command list was created.
The application must ensure the command list and events were created, and the memory was allocated, on the same context.
The application must not call this function from simultaneous threads with the same command list handle.
The implementation of this function should be lock-free.
hCommandList – [in] handle of the command list
dstptr – [in,out] pointer to memory where timestamp value will be written; must be 8byte-aligned.
hSignalEvent – [in][optional] handle of the event to signal on completion
numWaitEvents – [in][optional] number of events to wait on before executing query; must be 0 if `nullptr == phWaitEvents`
phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before executing query
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hCommandList
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == dstptr
(nullptr == phWaitEvents) && (0 < numWaitEvents)
Synchronizes an immediate command list by waiting on the host for the completion of all commands previously submitted to it.
The application must call this function only with command lists created with zeCommandListCreateImmediate.
Waiting on one immediate command list shall not block the concurrent execution of commands appended to other immediate command lists created with either a different ordinal or different index.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hCommandList – [in] handle of the immediate command list
timeout – [in] if non-zero, then indicates the maximum time (in nanoseconds) to yield before returning ZE_RESULT_SUCCESS or ZE_RESULT_NOT_READY; if zero, then immediately returns the status of the immediate command list; if `UINT64_MAX`, then function will not return until complete or device is lost. Due to external dependencies, timeout may be rounded to the closest value allowed by the accuracy of those dependencies.
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hCommandList
timeout expired
ZE_RESULT_ERROR_INVALID_ARGUMENT
handle does not correspond to an immediate command list
Gets the handle of the device on which the command list was created.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hCommandList – [in] handle of the command list
phDevice – [out] handle of the device on which the command list was created
Gets the handle of the context on which the command list was created.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hCommandList – [in] handle of the command list
phContext – [out] handle of the context on which the command list was created
Gets the command queue group ordinal to which the command list is submitted.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hCommandList – [in] handle of the command list
pOrdinal – [out] command queue group ordinal to which command list is submitted
Gets the command queue index within the group to which the immediate command list is submitted.
The application must call this function only with command lists created with zeCommandListCreateImmediate.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hCommandListImmediate – [in] handle of the immediate command list
pIndex – [out] command queue index within the group to which the immediate command list is submitted
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hCommandListImmediate
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pIndex
ZE_RESULT_ERROR_INVALID_ARGUMENT
handle does not correspond to an immediate command list
Query whether a command list is an immediate command list.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hCommandList – [in] handle of the command list
pIsImmediate – [out] Boolean indicating whether the command list is an immediate command list (true) or not (false)
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hCommandList
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pIsImmediate
Values:
driver may reorder commands (e.g., kernels, copies) between barriers and synchronization primitives. using this flag may increase Host overhead of zeCommandListClose. therefore, this flag should not be set for low-latency usage-models.
driver may perform additional optimizations that increase execution throughput. using this flag may increase Host overhead of zeCommandListClose and zeCommandQueueExecuteCommandLists. therefore, this flag should not be set for low-latency usage-models.
command list should be optimized for submission to a single command queue and device engine. driver must disable any implicit optimizations for distributing work across multiple engines. this flag should be used when applications want full control over multi-engine submission and scheduling. This flag is DEPRECATED and implementations are not expected to support this feature.
commands appended to this command list are executed in-order, with driver implementation enforcing dependencies between them. Application is not required to have the signal event of a given command being the wait event of the next to define an in-order list, and application is allowed to pass signal and wait events to each appended command to implement more complex dependency graphs. Cannot be combined with ZE_COMMAND_LIST_FLAG_RELAXED_ORDERING.
this command list may be cloned using zeCommandListCreateCloneExp after zeCommandListClose.
Value marking end of ZE_COMMAND_LIST_FLAG_* ENUMs.
Command List descriptor.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] command queue group ordinal to which this command list will be submitted
[in] usage flags. must be 0 (default) or a valid combination of ze_command_list_flag_t; default behavior may use implicit driver-based heuristics to balance latency and throughput.
Functions
Appends an execution and global memory barrier into a command list.
The application must ensure the events are accessible by the device on which the command list was created.
If numWaitEvents is zero, then all previous commands, enqueued on same command queue, must complete prior to the execution of the barrier. This is not the case when numWaitEvents is non-zero.
If numWaitEvents is non-zero, then only all phWaitEvents must be signaled prior to the execution of the barrier.
This command blocks all following commands from beginning until the execution of the barrier completes.
The application must not call this function from simultaneous threads with the same command list handle.
The implementation of this function should be lock-free.
hCommandList – [in] handle of the command list
hSignalEvent – [in][optional] handle of the event to signal on completion
numWaitEvents – [in][optional] number of events to wait on before executing barrier; must be 0 if `nullptr == phWaitEvents`
phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before executing barrier
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hCommandList
(nullptr == phWaitEvents) && (0 < numWaitEvents)
Appends a global memory ranges barrier into a command list.
The application must ensure the events are accessible by the device on which the command list was created.
If numWaitEvents is zero, then all previous commands are completed prior to the execution of the barrier.
If numWaitEvents is non-zero, then then all phWaitEvents must be signaled prior to the execution of the barrier.
This command blocks all following commands from beginning until the execution of the barrier completes.
The application must not call this function from simultaneous threads with the same command list handle.
The implementation of this function should be lock-free.
hCommandList – [in] handle of the command list
numRanges – [in] number of memory ranges
pRangeSizes – [in][range(0, numRanges)] array of sizes of memory range
pRanges – [in][range(0, numRanges)] array of memory ranges
hSignalEvent – [in][optional] handle of the event to signal on completion
numWaitEvents – [in][optional] number of events to wait on before executing barrier; must be 0 if `nullptr == phWaitEvents`
phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before executing barrier
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hCommandList
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pRangeSizes
nullptr == pRanges
(nullptr == phWaitEvents) && (0 < numWaitEvents)
Ensures in-bound writes to the device are globally observable.
This is a special-case system level barrier that can be used to ensure global observability of writes; typically needed after a producer (e.g., NIC) performs direct writes to the device’s memory (e.g., Direct RDMA writes). This is typically required when the memory corresponding to the writes is subsequently accessed from a remote device.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hContext – [in] handle of context object
hDevice – [in] handle of the device
Functions
Enumerations
Structures
Copies host, device, or shared memory.
The application must ensure the memory pointed to by dstptr and srcptr is accessible by the device on which the command list was created.
The implementation must not access the memory pointed to by dstptr and srcptr as they are free to be modified by either the Host or device up until execution.
The application must ensure the events are accessible by the device on which the command list was created.
The application must ensure the command list and events were created, and the memory was allocated, on the same context.
The application must not call this function from simultaneous threads with the same command list handle.
The implementation of this function should be lock-free.
hCommandList – [in] handle of command list
dstptr – [in] pointer to destination memory to copy to
srcptr – [in] pointer to source memory to copy from
size – [in] size in bytes to copy
hSignalEvent – [in][optional] handle of the event to signal on completion
numWaitEvents – [in][optional] number of events to wait on before launching; must be 0 if `nullptr == phWaitEvents`
phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hCommandList
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == dstptr
nullptr == srcptr
(nullptr == phWaitEvents) && (0 < numWaitEvents)
Initializes host, device, or shared memory.
The application must ensure the memory pointed to by dstptr is accessible by the device on which the command list was created.
The implementation must not access the memory pointed to by dstptr as it is free to be modified by either the Host or device up until execution.
The value to initialize memory to is described by the pattern and the pattern size.
The pattern size must be a power-of-two and less than or equal to the maxMemoryFillPatternSize member of ze_command_queue_group_properties_t.
The application must ensure the events are accessible by the device on which the command list was created.
The application must ensure the command list and events were created, and the memory was allocated, on the same context.
The application must not call this function from simultaneous threads with the same command list handle.
The implementation of this function should be lock-free.
hCommandList – [in] handle of command list
ptr – [in] pointer to memory to initialize
pattern – [in] pointer to value to initialize memory to
pattern_size – [in] size in bytes of the value to initialize memory to
size – [in] size in bytes to initialize
hSignalEvent – [in][optional] handle of the event to signal on completion
numWaitEvents – [in][optional] number of events to wait on before launching; must be 0 if `nullptr == phWaitEvents`
phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hCommandList
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == ptr
nullptr == pattern
(nullptr == phWaitEvents) && (0 < numWaitEvents)
Copies a region from a 2D or 3D array of host, device, or shared memory.
The application must ensure the memory pointed to by dstptr and srcptr is accessible by the device on which the command list was created.
The implementation must not access the memory pointed to by dstptr and srcptr as they are free to be modified by either the Host or device up until execution.
The region width, height, and depth for both src and dst must be same. The origins can be different.
The src and dst regions cannot be overlapping.
The application must ensure the events are accessible by the device on which the command list was created.
The application must ensure the command list and events were created, and the memory was allocated, on the same context.
The application must not call this function from simultaneous threads with the same command list handle.
The implementation of this function should be lock-free.
hCommandList – [in] handle of command list
dstptr – [in] pointer to destination memory to copy to
dstRegion – [in] pointer to destination region to copy to
dstPitch – [in] destination pitch in bytes
dstSlicePitch – [in] destination slice pitch in bytes. This is required for 3D region copies where the `depth` member of ze_copy_region_t is not 0, otherwise it’s ignored.
srcptr – [in] pointer to source memory to copy from
srcRegion – [in] pointer to source region to copy from
srcPitch – [in] source pitch in bytes
srcSlicePitch – [in] source slice pitch in bytes. This is required for 3D region copies where the `depth` member of ze_copy_region_t is not 0, otherwise it’s ignored.
hSignalEvent – [in][optional] handle of the event to signal on completion
numWaitEvents – [in][optional] number of events to wait on before launching; must be 0 if `nullptr == phWaitEvents`
phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hCommandList
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == dstptr
nullptr == dstRegion
nullptr == srcptr
nullptr == srcRegion
(nullptr == phWaitEvents) && (0 < numWaitEvents)
Copies host, device, or shared memory from another context.
The current active and source context must be from the same driver.
The application must ensure the memory pointed to by dstptr and srcptr is accessible by the device on which the command list was created.
The implementation must not access the memory pointed to by dstptr and srcptr as they are free to be modified by either the Host or device up until execution.
The application must ensure the events are accessible by the device on which the command list was created.
The application must ensure the command list and events were created, and the memory was allocated, on the same context.
The application must not call this function from simultaneous threads with the same command list handle.
The implementation of this function should be lock-free.
hCommandList – [in] handle of command list
dstptr – [in] pointer to destination memory to copy to
hContextSrc – [in] handle of source context object
srcptr – [in] pointer to source memory to copy from
size – [in] size in bytes to copy
hSignalEvent – [in][optional] handle of the event to signal on completion
numWaitEvents – [in][optional] number of events to wait on before launching; must be 0 if `nullptr == phWaitEvents`
phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hCommandList
nullptr == hContextSrc
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == dstptr
nullptr == srcptr
(nullptr == phWaitEvents) && (0 < numWaitEvents)
Copies an image.
The application must ensure the image and events are accessible by the device on which the command list was created.
The application must ensure the image format descriptors for both source and destination images are the same.
The application must ensure the command list, images and events were created on the same context.
The application must not call this function from simultaneous threads with the same command list handle.
The implementation of this function should be lock-free.
hCommandList – [in] handle of command list
hDstImage – [in] handle of destination image to copy to
hSrcImage – [in] handle of source image to copy from
hSignalEvent – [in][optional] handle of the event to signal on completion
numWaitEvents – [in][optional] number of events to wait on before launching; must be 0 if `nullptr == phWaitEvents`
phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hCommandList
nullptr == hDstImage
nullptr == hSrcImage
(nullptr == phWaitEvents) && (0 < numWaitEvents)
Copies a region of an image to another image.
The application must ensure the image and events are accessible by the device on which the command list was created.
The region width and height for both src and dst must be same. The origins can be different.
The src and dst regions cannot be overlapping.
The application must ensure the image format descriptors for both source and destination images are the same.
The application must ensure the command list, images and events were created, and the memory was allocated, on the same context.
The application must not call this function from simultaneous threads with the same command list handle.
The implementation of this function should be lock-free.
hCommandList – [in] handle of command list
hDstImage – [in] handle of destination image to copy to
hSrcImage – [in] handle of source image to copy from
pDstRegion – [in][optional] destination region descriptor
pSrcRegion – [in][optional] source region descriptor
hSignalEvent – [in][optional] handle of the event to signal on completion
numWaitEvents – [in][optional] number of events to wait on before launching; must be 0 if `nullptr == phWaitEvents`
phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hCommandList
nullptr == hDstImage
nullptr == hSrcImage
(nullptr == phWaitEvents) && (0 < numWaitEvents)
Copies from an image to device or shared memory.
The application must ensure the memory pointed to by dstptr is accessible by the device on which the command list was created.
The implementation must not access the memory pointed to by dstptr as it is free to be modified by either the Host or device up until execution.
The application must ensure the image and events are accessible by the device on which the command list was created.
The application must ensure the image format descriptor for the source image is a single-planar format.
The application must ensure the command list, image and events were created, and the memory was allocated, on the same context.
The application must not call this function from simultaneous threads with the same command list handle.
The implementation of this function should be lock-free.
hCommandList – [in] handle of command list
dstptr – [in] pointer to destination memory to copy to
hSrcImage – [in] handle of source image to copy from
pSrcRegion – [in][optional] source region descriptor
hSignalEvent – [in][optional] handle of the event to signal on completion
numWaitEvents – [in][optional] number of events to wait on before launching; must be 0 if `nullptr == phWaitEvents`
phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hCommandList
nullptr == hSrcImage
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == dstptr
(nullptr == phWaitEvents) && (0 < numWaitEvents)
Copies to an image from device or shared memory.
The application must ensure the memory pointed to by srcptr is accessible by the device on which the command list was created.
The implementation must not access the memory pointed to by srcptr as it is free to be modified by either the Host or device up until execution.
The application must ensure the image and events are accessible by the device on which the command list was created.
The application must ensure the image format descriptor for the destination image is a single-planar format.
The application must ensure the command list, image and events were created, and the memory was allocated, on the same context.
The application must not call this function from simultaneous threads with the same command list handle.
The implementation of this function should be lock-free.
hCommandList – [in] handle of command list
hDstImage – [in] handle of destination image to copy to
srcptr – [in] pointer to source memory to copy from
pDstRegion – [in][optional] destination region descriptor
hSignalEvent – [in][optional] handle of the event to signal on completion
numWaitEvents – [in][optional] number of events to wait on before launching; must be 0 if `nullptr == phWaitEvents`
phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hCommandList
nullptr == hDstImage
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == srcptr
(nullptr == phWaitEvents) && (0 < numWaitEvents)
Asynchronously prefetches shared memory to the device associated with the specified command list.
This is a hint to improve performance only and is not required for correctness.
Only prefetching to the device associated with the specified command list is supported. Prefetching to the host or to a peer device is not supported.
Prefetching may not be supported for all allocation types for all devices. If memory prefetching is not supported for the specified memory range the prefetch hint may be ignored.
Prefetching may only be supported at a device-specific granularity, such as at a page boundary. In this case, the memory range may be expanded such that the start and end of the range satisfy granularity requirements.
The application must ensure the memory pointed to by ptr is accessible by the device on which the command list was created.
The application must ensure the command list was created, and the memory was allocated, on the same context.
The application must not call this function from simultaneous threads with the same command list handle.
The implementation of this function should be lock-free.
hCommandList – [in] handle of command list
ptr – [in] pointer to start of the memory range to prefetch
size – [in] size in bytes of the memory range to prefetch
Provides advice about the use of a shared memory range.
Memory advice is a performance hint only and is not required for functional correctness.
Memory advice can be used to override driver heuristics to explicitly control shared memory behavior.
Not all memory advice hints may be supported for all allocation types for all devices. If a memory advice hint is not supported by the device it will be ignored.
Memory advice may only be supported at a device-specific granularity, such as at a page boundary. In this case, the memory range may be expanded such that the start and end of the range satisfy granularity requirements.
The application must ensure the memory pointed to by ptr is accessible by the device on which the command list was created.
The application must ensure the command list was created, and memory was allocated, on the same context.
The application must not call this function from simultaneous threads with the same command list handle, and the memory was allocated.
The implementation of this function should be lock-free.
hCommandList – [in] handle of command list
hDevice – [in] device associated with the memory advice
ptr – [in] Pointer to the start of the memory range
size – [in] Size in bytes of the memory range
advice – [in] Memory advice for the memory range
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hCommandList
nullptr == hDevice
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == ptr
Supported memory advice hints.
Values:
hint that memory will be read from frequently and written to rarely
removes the effect of ZE_MEMORY_ADVICE_SET_READ_MOSTLY
hint that the preferred memory location is the specified device
removes the effect of ZE_MEMORY_ADVICE_SET_PREFERRED_LOCATION
hints that memory will mostly be accessed non-atomically
removes the effect of ZE_MEMORY_ADVICE_SET_NON_ATOMIC_MOSTLY
hints that memory should be cached
hints that memory should be not be cached
hint that the preferred memory location is host memory
removes the effect of ZE_MEMORY_ADVICE_SET_SYSTEM_MEMORY_PREFERRED_LOCATION
Value marking end of ZE_MEMORY_ADVICE_* ENUMs.
Copy region descriptor.
Public Members
[in] The origin x offset for region in bytes
[in] The origin y offset for region in rows
[in] The origin z offset for region in slices
[in] The region width relative to origin in bytes
[in] The region height relative to origin in rows
[in] The region depth relative to origin in slices. Set this to 0 for 2D copy.
Region descriptor.
Public Members
[in] The origin x offset for region in pixels
[in] The origin y offset for region in pixels
[in] The origin z offset for region in pixels
[in] The region width relative to origin in pixels
[in] The region height relative to origin in pixels
[in] The region depth relative to origin. For 1D or 2D images, set this to 1.
Functions
Enumerations
Structures
Creates a pool of events on the context.
The application must only use events within the pool for the device(s), or their sub-devices, which were provided during creation.
The application may call this function from simultaneous threads.
The implementation of this function must be thread-safe.
hContext – [in] handle of the context object
desc – [in] pointer to event pool descriptor
numDevices – [in][optional] number of device handles; must be 0 if `nullptr == phDevices`
phDevices – [in][optional][range(0, numDevices)] array of device handles which have visibility to the event pool. if nullptr, then event pool is visible to all devices supported by the driver instance.
phEventPool – [out] pointer handle of event pool object created
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hContext
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == desc
nullptr == phEventPool
ZE_RESULT_ERROR_INVALID_ENUMERATION
0xf < desc->flags
0 == desc->count
(nullptr == phDevices) && (0 < numDevices)
Deletes an event pool object.
The application must destroy all event handles created from the pool before destroying the pool itself.
The application must ensure the device is not currently referencing the any event within the pool before it is deleted.
The implementation of this function may immediately free all Host and Device allocations associated with this event pool.
The application must not call this function from simultaneous threads with the same event pool handle.
The implementation of this function must be thread-safe.
hEventPool – [in][release] handle of event pool object to destroy
Creates an event from the pool.
An event is used to communicate fine-grain host-to-device, device-to-host or device-to-device dependencies have completed.
The application must ensure the location in the pool is not being used by another event.
The application must not call this function from simultaneous threads with the same event pool handle.
The implementation of this function should be lock-free.
hEventPool – [in] handle of the event pool
desc – [in] pointer to event descriptor
phEvent – [out] pointer to handle of event object created
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hEventPool
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == desc
nullptr == phEvent
ZE_RESULT_ERROR_INVALID_ENUMERATION
0x7 < desc->signal
0x7 < desc->wait
Deletes an event object.
The application must ensure the device is not currently referencing the event before it is deleted.
The implementation of this function may immediately free all Host and Device allocations associated with this event.
The application must not call this function from simultaneous threads with the same event handle.
The implementation of this function should be lock-free.
hEvent – [in][release] handle of event object to destroy
Gets an IPC event pool handle for the specified event handle that can be shared with another process.
Event pool must have been created with ZE_EVENT_POOL_FLAG_IPC.
The application may call this function from simultaneous threads.
hEventPool – [in] handle of event pool object
phIpc – [out] Returned IPC event handle
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hEventPool
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == phIpc
Returns an IPC event pool handle to the driver.
This call must be used for IPC handles previously obtained with zeEventPoolGetIpcHandle.
Upon call, driver may release any underlying resources associated with the IPC handle. For instance, it may close the file descriptor contained in the IPC handle, if such type of handle is being used by the driver.
This call does not destroy the original event pool for which the IPC handle was created.
This function may not be called from simultaneous threads with the same IPC handle.
The implementation of this function should be lock-free.
hContext – [in] handle of the context object associated with the IPC event pool handle
hIpc – [in] IPC event pool handle
Opens an IPC event pool handle to retrieve an event pool handle from another process.
Multiple calls to this function with the same IPC handle will return unique event pool handles.
The event handle in this process should not be freed with zeEventPoolDestroy, but rather with zeEventPoolCloseIpcHandle.
If the original event pool has been created for a device containing a number of sub-devices, then the event pool returned by this call may be used on a device containing the same number of sub-devices, or on any of those sub-devices.
However, if the original event pool has been created for a sub-device, then the event pool returned by this call cannot be used on a device containing any number of sub-devices, and must be used only in a sub-device. This ensures functional correctness for any implementation or optimizations the underlying Level Zero driver may do on event pools and events.
The application may call this function from simultaneous threads.
hContext – [in] handle of the context object to associate with the IPC event pool handle
hIpc – [in] IPC event pool handle
phEventPool – [out] pointer handle of event pool object created
Closes an IPC event handle in the current process.
Closes an IPC event handle by destroying events that were opened in this process using zeEventPoolOpenIpcHandle.
The application must not call this function from simultaneous threads with the same event pool handle.
hEventPool – [in][release] handle of event pool object
Appends a signal of the event from the device into a command list.
The application must ensure the events are accessible by the device on which the command list was created.
The duration of an event created from an event pool that was created using ZE_EVENT_POOL_FLAG_KERNEL_TIMESTAMP or ZE_EVENT_POOL_FLAG_KERNEL_MAPPED_TIMESTAMP flags is undefined. However, for consistency and orthogonality the event will report correctly as signaled when used by other event API functionality.
The application must ensure the command list and events were created on the same context.
The application must not call this function from simultaneous threads with the same command list handle.
The implementation of this function should be lock-free.
hCommandList – [in] handle of the command list
hEvent – [in] handle of the event
Appends wait on event(s) on the device into a command list.
The application must ensure the events are accessible by the device on which the command list was created.
The application must ensure the command list and events were created on the same context.
The application must not call this function from simultaneous threads with the same command list handle.
The implementation of this function should be lock-free.
hCommandList – [in] handle of the command list
numEvents – [in] number of events to wait on before continuing
phEvents – [in][range(0, numEvents)] handles of the events to wait on before continuing
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hCommandList
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == phEvents
Signals a event from host.
The duration of an event created from an event pool that was created using ZE_EVENT_POOL_FLAG_KERNEL_TIMESTAMP or ZE_EVENT_POOL_FLAG_KERNEL_MAPPED_TIMESTAMP flags is undefined. However, for consistency and orthogonality the event will report correctly as signaled when used by other event API functionality.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hEvent – [in] handle of the event
The current host thread waits on an event to be signaled.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hEvent – [in] handle of the event
timeout – [in] if non-zero, then indicates the maximum time (in nanoseconds) to yield before returning ZE_RESULT_SUCCESS or ZE_RESULT_NOT_READY; if zero, then operates exactly like zeEventQueryStatus; if `UINT64_MAX`, then function will not return until complete or device is lost. Due to external dependencies, timeout may be rounded to the closest value allowed by the accuracy of those dependencies.
Queries an event object’s status on the host.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hEvent – [in] handle of the event
Appends a reset of an event back to not signaled state into a command list.
The application must ensure the events are accessible by the device on which the command list was created.
The application must ensure the command list and events were created on the same context.
The application must not call this function from simultaneous threads with the same command list handle.
The implementation of this function should be lock-free.
hCommandList – [in] handle of the command list
hEvent – [in] handle of the event
The current host thread resets an event back to not signaled state.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hEvent – [in] handle of the event
Queries an event’s timestamp value on the host.
The application must ensure the event was created from an event pool that was created using ZE_EVENT_POOL_FLAG_KERNEL_TIMESTAMP or ZE_EVENT_POOL_FLAG_KERNEL_MAPPED_TIMESTAMP flag.
The destination memory will be unmodified if the event has not been signaled.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hEvent – [in] handle of the event
dstptr – [in,out] pointer to memory for where timestamp result will be written.
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hEvent
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == dstptr
not signaled
Appends a query of an events’ timestamp value(s) into a command list.
The application must ensure the events are accessible by the device on which the command list was created.
The application must ensure the events were created from an event pool that was created using ZE_EVENT_POOL_FLAG_KERNEL_TIMESTAMP flag.
The application must ensure the memory pointed to by both dstptr and pOffsets is accessible by the device on which the command list was created.
The value(s) written to the destination buffer are undefined if any timestamp event has not been signaled.
If pOffsets is nullptr, then multiple results will be appended sequentially into memory in the same order as phEvents.
The application must ensure the command list and events were created, and the memory was allocated, on the same context.
The application must not call this function from simultaneous threads with the same command list handle.
The implementation of this function should be lock-free.
hCommandList – [in] handle of the command list
numEvents – [in] the number of timestamp events to query
phEvents – [in][range(0, numEvents)] handles of timestamp events to query
dstptr – [in,out] pointer to memory where ze_kernel_timestamp_result_t will be written; must be size-aligned.
pOffsets – [in][optional][range(0, numEvents)] offset, in bytes, to write results; address must be 4byte-aligned and offsets must be size-aligned.
hSignalEvent – [in][optional] handle of the event to signal on completion
numWaitEvents – [in][optional] number of events to wait on before executing query; must be 0 if `nullptr == phWaitEvents`
phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before executing query
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hCommandList
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == phEvents
nullptr == dstptr
(nullptr == phWaitEvents) && (0 < numWaitEvents)
Gets the handle of the event pool for the event.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hEvent – [in] handle of the event
phEventPool – [out] handle of the event pool for the event
Gets the signal event scope.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hEvent – [in] handle of the event
pSignalScope – [out] signal event scope. This is the scope of relevant cache hierarchies that are flushed on a signal action before the event is triggered. May be 0 or a valid combination of ze_event_scope_flag_t.
Gets the wait event scope.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hEvent – [in] handle of the event
pWaitScope – [out] wait event scope. This is the scope of relevant cache hierarchies invalidated on a wait action after the event is complete. May be 0 or a valid combination of ze_event_scope_flag_t.
Gets the handle of the context on which the event pool was created.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hEventPool – [in] handle of the event pool
phContext – [out] handle of the context on which the event pool was created
Gets the creation flags used to create the event pool.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hEventPool – [in] handle of the event pool
pFlags – [out] creation flags used to create the event pool; may be 0 or a valid combination of ze_event_pool_flag_t
Values:
signals and waits are also visible to host
signals and waits may be shared across processes
Indicates all events in pool will contain kernel timestamps.
Indicates all events in pool will contain kernel timestamps synchronized to host time domain; cannot be combined with ZE_EVENT_POOL_FLAG_KERNEL_TIMESTAMP
Value marking end of ZE_EVENT_POOL_FLAG_* ENUMs.
Values:
cache hierarchies are flushed or invalidated sufficient for local sub-device access
cache hierarchies are flushed or invalidated sufficient for global device access and peer device access
cache hierarchies are flushed or invalidated sufficient for device and host access
Value marking end of ZE_EVENT_SCOPE_FLAG_* ENUMs.
Event pool descriptor.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] creation flags. must be 0 (default) or a valid combination of ze_event_pool_flag_t; default behavior is signals and waits are visible to the entire device and peer devices.
[in] number of events within the pool; must be greater than 0
Event descriptor.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] index of the event within the pool; must be less than the count specified during pool creation
[in] defines the scope of relevant cache hierarchies to flush on a signal action before the event is triggered. must be 0 (default) or a valid combination of ze_event_scope_flag_t; default behavior is synchronization within the command list only, no additional cache hierarchies are flushed.
[in] defines the scope of relevant cache hierarchies to invalidate on a wait action after the event is complete. must be 0 (default) or a valid combination of ze_event_scope_flag_t; default behavior is synchronization within the command list only, no additional cache hierarchies are invalidated.
Kernel timestamp clock data.
The timestamp frequency can be queried from the timerResolution member of ze_device_properties_t.
The number of valid bits in the timestamp value can be queried from the kernelTimestampValidBits member of ze_device_properties_t.
Public Members
[out] device clock at start of kernel execution
[out] device clock at end of kernel execution
Kernel timestamp result.
Functions
Enumerations
Structures
Creates a fence for the command queue.
A fence is a heavyweight synchronization primitive used to communicate to the host that command list execution has completed.
The application must only use the fence for the command queue which was provided during creation.
The application may call this function from simultaneous threads.
The implementation of this function must be thread-safe.
hCommandQueue – [in] handle of command queue
desc – [in] pointer to fence descriptor
phFence – [out] pointer to handle of fence object created
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hCommandQueue
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == desc
nullptr == phFence
ZE_RESULT_ERROR_INVALID_ENUMERATION
0x1 < desc->flags
Deletes a fence object.
The application must ensure the device is not currently referencing the fence before it is deleted.
The implementation of this function may immediately free all Host and Device allocations associated with this fence.
The application must not call this function from simultaneous threads with the same fence handle.
The implementation of this function must be thread-safe.
hFence – [in][release] handle of fence object to destroy
The current host thread waits on a fence to be signaled.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hFence – [in] handle of the fence
timeout – [in] if non-zero, then indicates the maximum time (in nanoseconds) to yield before returning ZE_RESULT_SUCCESS or ZE_RESULT_NOT_READY; if zero, then operates exactly like zeFenceQueryStatus; if `UINT64_MAX`, then function will not return until complete or device is lost. Due to external dependencies, timeout may be rounded to the closest value allowed by the accuracy of those dependencies.
Queries a fence object’s status.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hFence – [in] handle of the fence
Reset a fence back to the not signaled state.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hFence – [in] handle of the fence
Values:
fence is created in the signaled state, otherwise not signaled.
Value marking end of ZE_FENCE_FLAG_* ENUMs.
Fence descriptor.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] creation flags. must be 0 (default) or a valid combination of ze_fence_flag_t.
Functions
Enumerations
Structures
Retrieves supported properties of an image.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hDevice – [in] handle of the device
desc – [in] pointer to image descriptor
pImageProperties – [out] pointer to image properties
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hDevice
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == desc
nullptr == pImageProperties
ZE_RESULT_ERROR_INVALID_ENUMERATION
0x3 < desc->flags
ZE_IMAGE_TYPE_BUFFER < desc->type
Creates an image on the context.
The application must only use the image 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.
hContext – [in] handle of the context object
hDevice – [in] handle of the device
desc – [in] pointer to image descriptor
phImage – [out] pointer to handle of image object created
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hContext
nullptr == hDevice
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == desc
nullptr == phImage
ZE_RESULT_ERROR_INVALID_ENUMERATION
0x3 < desc->flags
ZE_IMAGE_TYPE_BUFFER < desc->type
Deletes an image object.
The application must ensure the device is not currently referencing the image before it is deleted.
The implementation of this function may immediately free all Host and Device allocations associated with this image.
The application must not call this function from simultaneous threads with the same image handle.
The implementation of this function must be thread-safe.
hImage – [in][release] handle of image object to destroy
Values:
kernels will write contents
device should not cache contents
Value marking end of ZE_IMAGE_FLAG_* ENUMs.
Supported image types.
Values:
1D
1D array
2D
2D array
3D
Buffer.
Value marking end of ZE_IMAGE_TYPE_* ENUMs.
Supported image format layouts.
Values:
8-bit single component layout
16-bit single component layout
32-bit single component layout
2-component 8-bit layout
4-component 8-bit layout
2-component 16-bit layout
4-component 16-bit layout
2-component 32-bit layout
4-component 32-bit layout
4-component 10_10_10_2 layout
3-component 11_11_10 layout
3-component 5_6_5 layout
4-component 5_5_5_1 layout
4-component 4_4_4_4 layout
Media Format: Y8. Format type and swizzle is ignored for this.
Media Format: NV12. Format type and swizzle is ignored for this.
Media Format: YUYV. Format type and swizzle is ignored for this.
Media Format: VYUY. Format type and swizzle is ignored for this.
Media Format: YVYU. Format type and swizzle is ignored for this.
Media Format: UYVY. Format type and swizzle is ignored for this.
Media Format: AYUV. Format type and swizzle is ignored for this.
Media Format: P010. Format type and swizzle is ignored for this.
Media Format: Y410. Format type and swizzle is ignored for this.
Media Format: P012. Format type and swizzle is ignored for this.
Media Format: Y16. Format type and swizzle is ignored for this.
Media Format: P016. Format type and swizzle is ignored for this.
Media Format: Y216. Format type and swizzle is ignored for this.
Media Format: P216. Format type and swizzle is ignored for this.
Media Format: P8. Format type and swizzle is ignored for this.
Media Format: YUY2. Format type and swizzle is ignored for this.
Media Format: A8P8. Format type and swizzle is ignored for this.
Media Format: IA44. Format type and swizzle is ignored for this.
Media Format: AI44. Format type and swizzle is ignored for this.
Media Format: Y416. Format type and swizzle is ignored for this.
Media Format: Y210. Format type and swizzle is ignored for this.
Media Format: I420. Format type and swizzle is ignored for this.
Media Format: YV12. Format type and swizzle is ignored for this.
Media Format: 400P. Format type and swizzle is ignored for this.
Media Format: 422H. Format type and swizzle is ignored for this.
Media Format: 422V. Format type and swizzle is ignored for this.
Media Format: 444P. Format type and swizzle is ignored for this.
Media Format: RGBP. Format type and swizzle is ignored for this.
Media Format: BRGP. Format type and swizzle is ignored for this.
3-component 8-bit layout
3-component 16-bit layout
3-component 32-bit layout
Value marking end of ZE_IMAGE_FORMAT_LAYOUT_* ENUMs.
Supported image format types.
Values:
Unsigned integer.
Signed integer.
Unsigned normalized integer.
Signed normalized integer.
Float.
Value marking end of ZE_IMAGE_FORMAT_TYPE_* ENUMs.
Supported image format component swizzle into channel.
Values:
Red component.
Green component.
Blue component.
Alpha component.
Zero.
One.
Don’t care.
Value marking end of ZE_IMAGE_FORMAT_SWIZZLE_* ENUMs.
Values:
device supports point filtering
device supports linear filtering
Value marking end of ZE_IMAGE_SAMPLER_FILTER_FLAG_* ENUMs.
Image format.
Image descriptor.
Image properties.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] supported sampler filtering. returns 0 (unsupported) or a combination of ze_image_sampler_filter_flag_t.
Functions
Enumerations
Structures
Allocates device memory on the context.
Device allocations are owned by a specific device.
In general, a device allocation may only be accessed by the device that owns it.
The application must only use the memory allocation for the context and device, or its sub-devices, which was provided during allocation.
The application may call this function from simultaneous threads.
The implementation of this function must be thread-safe.
hContext – [in] handle of the context object
device_desc – [in] pointer to device memory allocation descriptor
size – [in] size in bytes to allocate; must be less than or equal to the `maxMemAllocSize` member of ze_device_properties_t
alignment – [in] minimum alignment in bytes for the allocation; must be a power of two
hDevice – [in] handle of the device
pptr – [out] pointer to device allocation
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hContext
nullptr == hDevice
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == device_desc
nullptr == pptr
ZE_RESULT_ERROR_INVALID_ENUMERATION
0x7 < device_desc->flags
ZE_RESULT_ERROR_UNSUPPORTED_SIZE
0 == size
ZE_RESULT_ERROR_UNSUPPORTED_ALIGNMENT
Must be zero or a power-of-two
0 != (alignment & (alignment - 1))
Allocates host memory on the context.
Host allocations are owned by the host process.
Host allocations are accessible by the host and all devices within the driver’s context.
Host allocations are frequently used as staging areas to transfer data to or from devices.
The application must only use the memory allocation for the context which was provided during allocation.
The application may call this function from simultaneous threads.
The implementation of this function must be thread-safe.
hContext – [in] handle of the context object
host_desc – [in] pointer to host memory allocation descriptor
size – [in] size in bytes to allocate; must be less than or equal to the `maxMemAllocSize` member of ze_device_properties_t
alignment – [in] minimum alignment in bytes for the allocation; must be a power of two
pptr – [out] pointer to host allocation
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hContext
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == host_desc
nullptr == pptr
ZE_RESULT_ERROR_INVALID_ENUMERATION
0xf < host_desc->flags
ZE_RESULT_ERROR_UNSUPPORTED_SIZE
0 == size
ZE_RESULT_ERROR_UNSUPPORTED_ALIGNMENT
Must be zero or a power-of-two
0 != (alignment & (alignment - 1))
Frees allocated host memory, device memory, or shared memory on the context.
The application must ensure the device is not currently referencing the memory before it is freed
The implementation will use the default and immediate policy to schedule all Host and Device allocations associated with this memory to be freed, without any safety checking. Actual freeing of memory is specific to user mode driver and kernel mode driver implementation and may be done asynchronously.
The application must not call this function from simultaneous threads with the same pointer.
The implementation of this function must be thread-safe.
hContext – [in] handle of the context object
ptr – [in][release] pointer to memory to free
Retrieves attributes of a memory allocation.
The application may call this function from simultaneous threads.
The application may query attributes of a memory allocation unrelated to the context. When this occurs, the returned allocation type will be ZE_MEMORY_TYPE_UNKNOWN, and the returned identifier and associated device is unspecified.
hContext – [in] handle of the context object
ptr – [in] memory pointer to query
pMemAllocProperties – [in,out] query result for memory allocation properties
phDevice – [out][optional] device associated with this allocation
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hContext
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == ptr
nullptr == pMemAllocProperties
Retrieves the base address and/or size of an allocation.
The application may call this function from simultaneous threads.
hContext – [in] handle of the context object
ptr – [in] memory pointer to query
pBase – [in,out][optional] base address of the allocation
pSize – [in,out][optional] size of the allocation
Creates an IPC memory handle for the specified allocation.
Takes a pointer to a device memory allocation and creates an IPC memory handle for exporting it for use in another process.
The pointer must be base pointer of a device or host memory allocation; i.e. the value returned from zeMemAllocDevice or from zeMemAllocHost, respectively.
The application may call this function from simultaneous threads.
The implementation of this function must be thread-safe.
hContext – [in] handle of the context object
ptr – [in] pointer to the device memory allocation
pIpcHandle – [out] Returned IPC memory handle
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hContext
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == ptr
nullptr == pIpcHandle
Creates an IPC memory handle out of a file descriptor.
Handle passed must be a valid file descriptor obtained with ze_external_memory_export_fd_t via zeMemGetAllocProperties.
Returned IPC handle may contain metadata in addition to the file descriptor.
The application may call this function from simultaneous threads.
The implementation of this function must be thread-safe.
hContext – [in] handle of the context object
handle – [in] file descriptor
pIpcHandle – [out] Returned IPC memory handle
Gets the file descriptor contained in an IPC memory handle.
IPC memory handle must be a valid handle obtained with zeMemGetIpcHandle.
The application may call this function from simultaneous threads.
The implementation of this function must be thread-safe.
hContext – [in] handle of the context object
ipcHandle – [in] IPC memory handle
pHandle – [out] Returned file descriptor
Returns an IPC memory handle to the driver.
This call may be used for IPC handles previously obtained with either zeMemGetIpcHandle or with ze_external_memory_export_fd_t via zeMemGetAllocProperties.
Upon call, driver may release any underlying resources associated with the IPC handle. For instance, it may close the file descriptor contained in the IPC handle, if such type of handle is being used by the driver.
This call does not free the original allocation for which the IPC handle was created.
This function may not be called from simultaneous threads with the same IPC handle.
The implementation of this function should be lock-free.
hContext – [in] handle of the context object
handle – [in] IPC memory handle
Opens an IPC memory handle to retrieve a device pointer on the context.
Takes an IPC memory handle from a remote process and associates it with a device pointer usable in this process.
The device pointer in this process should not be freed with zeMemFree, but rather with zeMemCloseIpcHandle.
Multiple calls to this function with the same IPC handle will return unique pointers.
The application may call this function from simultaneous threads.
The implementation of this function must be thread-safe.
hContext – [in] handle of the context object
hDevice – [in] handle of the device to associate with the IPC memory handle
handle – [in] IPC memory handle
flags – [in] flags controlling the operation. must be 0 (default) or a valid combination of ze_ipc_memory_flag_t.
pptr – [out] pointer to device allocation in this process
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hContext
nullptr == hDevice
ZE_RESULT_ERROR_INVALID_ENUMERATION
0x3 < flags
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pptr
Closes an IPC memory handle.
Closes an IPC memory handle by unmapping memory that was opened in this process using zeMemOpenIpcHandle.
The application must not call this function from simultaneous threads with the same pointer.
The implementation of this function must be thread-safe.
hContext – [in] handle of the context object
ptr – [in][release] pointer to device allocation in this process
Sets atomic access attributes for a shared allocation.
If the shared-allocation is owned by multiple devices (i.e. nullptr was passed to zeMemAllocShared when creating it), then hDevice may be passed to set the attributes in that specific device. If nullptr is passed in hDevice, then the atomic attributes are set in all devices associated with the allocation.
If the atomic access attribute select is not supported by the driver, ZE_RESULT_ERROR_INVALID_ARGUMENT is returned.
The atomic access attribute may be only supported at a device-specific granularity, such as at a page boundary. In this case, the memory range may be expanded such that the start and end of the range satisfy granularity requirements.
When calling this function multiple times with different flags, only the attributes from last call are honored.
The application must not call this function for shared-allocations currently being used by the device.
The application must not call this function from simultaneous threads with the same pointer.
The implementation of this function should be lock-free.
hContext – [in] handle of context
hDevice – [in] device associated with the memory advice
ptr – [in] Pointer to the start of the memory range
size – [in] Size in bytes of the memory range
attr – [in] Atomic access attributes to set for the specified range. Must be 0 (default) or a valid combination of ze_memory_atomic_attr_exp_flag_t.
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hContext
nullptr == hDevice
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == ptr
ZE_RESULT_ERROR_INVALID_ENUMERATION
0x7f < attr
Retrieves the atomic access attributes previously set for a shared allocation.
The application may call this function from simultaneous threads with the same pointer.
The implementation of this function should be lock-free.
hContext – [in] handle of context
hDevice – [in] device associated with the memory advice
ptr – [in] Pointer to the start of the memory range
size – [in] Size in bytes of the memory range
pAttr – [out] Atomic access attributes for the specified range
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hContext
nullptr == hDevice
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == ptr
nullptr == pAttr
Values:
device should cache allocation
device should not cache allocation (UC)
optimize shared allocation for first access on the device
Value marking end of ZE_DEVICE_MEM_ALLOC_FLAG_* ENUMs.
Values:
host should cache allocation
host should not cache allocation (UC)
host memory should be allocated write-combined (WC)
optimize shared allocation for first access on the host
Value marking end of ZE_HOST_MEM_ALLOC_FLAG_* ENUMs.
Memory allocation type.
Values:
the memory pointed to is of unknown type
the memory pointed to is a host allocation
the memory pointed to is a device allocation
the memory pointed to is a shared ownership allocation
Value marking end of ZE_MEMORY_TYPE_* ENUMs.
Values:
device should cache allocation
device should not cache allocation (UC)
Value marking end of ZE_IPC_MEMORY_FLAG_* ENUMs.
Values:
Atomics on the pointer are not allowed.
Host atomics on the pointer are not allowed.
Host atomics on the pointer are allowed. Requires ZE_MEMORY_ACCESS_CAP_FLAG_ATOMIC returned by zeDeviceGetMemoryAccessProperties.
Device atomics on the pointer are not allowed.
Device atomics on the pointer are allowed. Requires ZE_MEMORY_ACCESS_CAP_FLAG_ATOMIC returned by zeDeviceGetMemoryAccessProperties.
Concurrent atomics on the pointer from both host and device are not allowed
Concurrent atomics on the pointer from both host and device are allowed. Requires ZE_MEMORY_ACCESS_CAP_FLAG_CONCURRENT_ATOMIC returned by zeDeviceGetMemoryAccessProperties.
Value marking end of ZE_MEMORY_ATOMIC_ATTR_EXP_FLAG_* ENUMs.
Device memory allocation descriptor.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] flags specifying additional allocation controls. must be 0 (default) or a valid combination of ze_device_mem_alloc_flag_t; default behavior may use implicit driver-based heuristics.
[in] ordinal of the device’s local memory to allocate from. must be less than the count returned from zeDeviceGetMemoryProperties.
Host memory allocation descriptor.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] flags specifying additional allocation controls. must be 0 (default) or a valid combination of ze_host_mem_alloc_flag_t; default behavior may use implicit driver-based heuristics.
Memory allocation properties queried using zeMemGetAllocProperties.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] type of allocated memory
[out] identifier for this allocation
[out] page size used for allocation
Additional allocation descriptor for exporting external memory.
This structure may be passed to zeMemAllocDevice and zeMemAllocHost, via the pNext member of ze_device_mem_alloc_desc_t or ze_host_mem_alloc_desc_t, respectively, to indicate an exportable memory allocation.
This structure may be passed to zeImageCreate, via the pNext member of ze_image_desc_t, to indicate an exportable image.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] flags specifying memory export types for this allocation. must be 0 (default) or a valid combination of ze_external_memory_type_flags_t
Additional allocation descriptor for importing external memory as a file descriptor.
This structure may be passed to zeMemAllocDevice or zeMemAllocHost, via the pNext member of ze_device_mem_alloc_desc_t or of ze_host_mem_alloc_desc_t, respectively, to import memory from a file descriptor.
This structure may be passed to zeImageCreate, via the pNext member of ze_image_desc_t, to import memory from a file descriptor.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] flags specifying the memory import type for the file descriptor. must be 0 (default) or a valid combination of ze_external_memory_type_flags_t
[in] the file descriptor handle to import
Exports an allocation as a file descriptor.
This structure may be passed to zeMemGetAllocProperties, via the pNext member of ze_memory_allocation_properties_t, to export a memory allocation as a file descriptor.
This structure may be passed to zeImageGetAllocPropertiesExt, via the pNext member of ze_image_allocation_ext_properties_t, to export an image as a file descriptor.
The requested memory export type must have been specified when the allocation was made.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] flags specifying the memory export type for the file descriptor. must be 0 (default) or a valid combination of ze_external_memory_type_flags_t
[out] the exported file descriptor handle representing the allocation.
Additional allocation descriptor for importing external memory as a Win32 handle.
When handle is nullptr, name must not be nullptr.
When name is nullptr, handle must not be nullptr.
When flags is ZE_EXTERNAL_MEMORY_TYPE_FLAG_OPAQUE_WIN32_KMT, name must be nullptr.
This structure may be passed to zeMemAllocDevice or zeMemAllocHost, via the pNext member of ze_device_mem_alloc_desc_t or of ze_host_mem_alloc_desc_t, respectively, to import memory from a Win32 handle.
This structure may be passed to zeImageCreate, via the pNext member of ze_image_desc_t, to import memory from a Win32 handle.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] flags specifying the memory import type for the Win32 handle. must be 0 (default) or a valid combination of ze_external_memory_type_flags_t
[in][optional] the Win32 handle to import
[in][optional] name of a memory object to import
Exports an allocation as a Win32 handle.
This structure may be passed to zeMemGetAllocProperties, via the pNext member of ze_memory_allocation_properties_t, to export a memory allocation as a Win32 handle.
This structure may be passed to zeImageGetAllocPropertiesExt, via the pNext member of ze_image_allocation_ext_properties_t, to export an image as a Win32 handle.
The requested memory export type must have been specified when the allocation was made.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] flags specifying the memory export type for the Win32 handle. must be 0 (default) or a valid combination of ze_external_memory_type_flags_t
[out] the exported Win32 handle representing the allocation.
Functions
Enumerations
Structures
Creates a module on the context.
Compiles the module for execution on the device.
The application must only use the module for the device, or its sub-devices, which was provided during creation.
The module can be copied to other devices and contexts within the same driver instance by using zeModuleGetNativeBinary.
A build log can optionally be returned to the caller. The caller is responsible for destroying build log using zeModuleBuildLogDestroy.
The module descriptor constants are only supported for SPIR-V specialization constants.
The application may call this function from simultaneous threads.
The implementation of this function must be thread-safe.
hContext – [in] handle of the context object
hDevice – [in] handle of the device
desc – [in] pointer to module descriptor
phModule – [out] pointer to handle of module object created
phBuildLog – [out][optional] pointer to handle of module’s build log.
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hContext
nullptr == hDevice
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == desc
nullptr == desc->pInputModule
nullptr == phModule
ZE_RESULT_ERROR_INVALID_ENUMERATION
ZE_MODULE_FORMAT_NATIVE < desc->format
0 == desc->inputSize
Destroys module.
The application must destroy all kernel handles created from the module before destroying the module itself.
The application must ensure the device is not currently referencing the module before it is deleted.
The implementation of this function may immediately free all Host and Device allocations associated with this module.
The application must not call this function from simultaneous threads with the same module handle.
The implementation of this function must be thread-safe.
hModule – [in][release] handle of the module
Dynamically link modules together that share import/export linkage dependencies.
Modules support SPIR-V import and export linkage types for functions and global variables. See the SPIR-V specification for linkage details.
Modules can have both import and export linkage.
Modules that do not have any imports or exports do not need to be linked.
All module import requirements must be satisfied via linking before kernel objects can be created from them.
Modules cannot be partially linked. Unsatisfiable import dependencies in the set of modules passed to zeModuleDynamicLink will result in ZE_RESULT_ERROR_MODULE_LINK_FAILURE being returned.
Modules will only be linked once. A module can be used in multiple link calls if it has exports but its imports will not be re-linked.
Ambiguous dependencies, where multiple modules satisfy the same import dependencies for a module, are not allowed.
The application must ensure the modules being linked were created on the same context.
The application may call this function from simultaneous threads as long as the import modules being linked are not the same.
ModuleGetNativeBinary can be called on any module regardless of whether it is linked or not.
A link log can optionally be returned to the caller. The caller is responsible for destroying the link log using zeModuleBuildLogDestroy.
The link log may contain a list of the unresolved import dependencies if present.
The implementation of this function should be lock-free.
numModules – [in] number of modules to be linked pointed to by phModules.
phModules – [in][range(0, numModules)] pointer to an array of modules to dynamically link together.
phLinkLog – [out][optional] pointer to handle of dynamic link log.
Destroys module build log object.
The implementation of this function may immediately free all Host allocations associated with this object.
The application must not call this function from simultaneous threads with the same build log handle.
The implementation of this function should be lock-free.
This function can be called before or after zeModuleDestroy for the associated module.
hModuleBuildLog – [in][release] handle of the module build log object.
Retrieves text string for build log.
The caller can pass nullptr for pBuildLog when querying only for size.
The caller must provide memory for build log.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hModuleBuildLog – [in] handle of the module build log object.
pSize – [in,out] size of build log string.
pBuildLog – [in,out][optional] pointer to null-terminated string of the log.
Retrieve native binary from Module.
The native binary output can be cached to disk and new modules can be later constructed from the cached copy.
The native binary will retain debugging information that is associated with a module.
The caller can pass nullptr for pModuleNativeBinary when querying only for size.
The implementation will copy the native binary into a buffer supplied by the caller.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hModule – [in] handle of the module
pSize – [in,out] size of native binary in bytes.
pModuleNativeBinary – [in,out][optional] byte pointer to native binary
Retrieve global variable pointer from Module.
The application may query global pointer from any module that either exports or imports it.
The application must dynamically link a module that imports a global before the global pointer can be queried from it.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hModule – [in] handle of the module
pGlobalName – [in] name of global variable in module
pSize – [in,out][optional] size of global variable
pptr – [in,out][optional] device visible pointer
Retrieve all kernel names in the module.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hModule – [in] handle of the module
pCount – [in,out] pointer to the number of names. if count is zero, then the driver shall update the value with the total number of names available. if count is greater than the number of names available, then the driver shall update the value with the correct number of names available.
pNames – [in,out][optional][range(0, *pCount)] array of names of functions. if count is less than the number of names available, then driver shall only retrieve that number of names.
Retrieve module properties.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hModule – [in] handle of the module
pModuleProperties – [in,out] query result for module properties.
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hModule
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pModuleProperties
Create a kernel from the module.
Modules that have unresolved imports need to be dynamically linked before a kernel can be created from them. (See zeModuleDynamicLink)
The application may call this function from simultaneous threads.
The implementation of this function must be thread-safe.
hModule – [in] handle of the module
desc – [in] pointer to kernel descriptor
phKernel – [out] handle of the Function object
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hModule
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == desc
nullptr == desc->pKernelName
nullptr == phKernel
ZE_RESULT_ERROR_INVALID_ENUMERATION
0x3 < desc->flags
Destroys a kernel object.
The application must ensure the device is not currently referencing the kernel before it is deleted.
The implementation of this function may immediately free all Host and Device allocations associated with this kernel.
The application must not call this function from simultaneous threads with the same kernel handle.
The implementation of this function must be thread-safe.
hKernel – [in][release] handle of the kernel object
Retrieve a function pointer from a module by name.
The function pointer is unique for the device on which the module was created.
The function pointer is no longer valid if module is destroyed.
The function name should only refer to callable functions within the module.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hModule – [in] handle of the module
pFunctionName – [in] Name of function to retrieve function pointer for.
pfnFunction – [out] pointer to function.
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hModule
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pFunctionName
nullptr == pfnFunction
Set group size for a kernel.
The group size will be used when a zeCommandListAppendLaunchKernel variant is called.
The application must not call this function from simultaneous threads with the same kernel handle.
The implementation of this function should be lock-free.
hKernel – [in] handle of the kernel object
groupSizeX – [in] group size for X dimension to use for this kernel
groupSizeY – [in] group size for Y dimension to use for this kernel
groupSizeZ – [in] group size for Z dimension to use for this kernel
Query a suggested group size for a kernel given a global size for each dimension.
This function ignores the group size that is set using zeKernelSetGroupSize.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hKernel – [in] handle of the kernel object
globalSizeX – [in] global width for X dimension
globalSizeY – [in] global width for Y dimension
globalSizeZ – [in] global width for Z dimension
groupSizeX – [out] recommended size of group for X dimension
groupSizeY – [out] recommended size of group for Y dimension
groupSizeZ – [out] recommended size of group for Z dimension
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hKernel
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == groupSizeX
nullptr == groupSizeY
nullptr == groupSizeZ
Query a suggested max group count for a cooperative kernel.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hKernel – [in] handle of the kernel object
totalGroupCount – [out] recommended total group count.
Set kernel argument for a kernel.
The argument values will be used when a zeCommandListAppendLaunchKernel variant is called.
The application must not call this function from simultaneous threads with the same kernel handle.
The implementation of this function should be lock-free.
hKernel – [in] handle of the kernel object
argIndex – [in] argument index in range [0, num args - 1]
argSize – [in] size of argument type
pArgValue – [in][optional] argument value represented as matching arg type. If null then argument value is considered null.
Sets kernel indirect access flags.
The application should specify which allocations will be indirectly accessed by the kernel to allow driver to optimize which allocations are made resident
This function may not be called from simultaneous threads with the same Kernel handle.
The implementation of this function should be lock-free.
hKernel – [in] handle of the kernel object
flags – [in] kernel indirect access flags
Retrieve kernel indirect access flags.
This function may be called from simultaneous threads with the same Kernel handle.
The implementation of this function should be lock-free.
hKernel – [in] handle of the kernel object
pFlags – [out] query result for kernel indirect access flags.
Retrieve all declared kernel attributes (i.e. can be specified with attribute in runtime language).
This function may be called from simultaneous threads with the same Kernel handle.
The implementation of this function should be lock-free.
hKernel – [in] handle of the kernel object
pSize – [in,out] pointer to size of string in bytes, including null-terminating character.
pString – [in,out][optional] pointer to application-managed character array (string data). If NULL, the string length of the kernel source attributes, including a null-terminating character, is returned in pSize. Otherwise, pString must point to valid application memory that is greater than or equal to *pSize bytes in length, and on return the pointed-to string will contain a space-separated list of kernel source attributes. Note: This API was originally intended to ship with a char *pString, however this typo was introduced. Thus the API has to stay this way for backwards compatible reasons. It can be corrected in v2.0. Suggestion is to create your own char *pString and then pass to this API with &pString.
Sets the preferred cache configuration.
The cache configuration will be used when a zeCommandListAppendLaunchKernel variant is called.
The application must not call this function from simultaneous threads with the same kernel handle.
The implementation of this function should be lock-free.
hKernel – [in] handle of the kernel object
flags – [in] cache configuration. must be 0 (default configuration) or a valid combination of ze_cache_config_flag_t.
Retrieve kernel properties.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hKernel – [in] handle of the kernel object
pKernelProperties – [in,out] query result for kernel properties.
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hKernel
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pKernelProperties
Retrieve kernel name from Kernel.
The caller can pass nullptr for pName when querying only for size.
The implementation will copy the kernel name into a buffer supplied by the caller.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hKernel – [in] handle of the kernel object
pSize – [in,out] size of kernel name string, including null terminator, in bytes.
pName – [in,out][optional] char pointer to kernel name.
Launch kernel over one or more work groups.
The application must ensure the kernel and events are accessible by the device on which the command list was created.
This may only be called for a command list created with command queue group ordinal that supports compute.
The application must ensure the command list, kernel and events were created on the same context.
This function may not be called from simultaneous threads with the same command list handle.
The implementation of this function should be lock-free.
hCommandList – [in] handle of the command list
hKernel – [in] handle of the kernel object
pLaunchFuncArgs – [in] thread group launch arguments
hSignalEvent – [in][optional] handle of the event to signal on completion
numWaitEvents – [in][optional] number of events to wait on before launching; must be 0 if `nullptr == phWaitEvents`
phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hCommandList
nullptr == hKernel
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pLaunchFuncArgs
(nullptr == phWaitEvents) && (0 < numWaitEvents)
Launch kernel cooperatively over one or more work groups.
The application must ensure the kernel and events are accessible by the device on which the command list was created.
This may only be called for a command list created with command queue group ordinal that supports compute.
This may only be used for a command list that are submitted to command queue with cooperative flag set.
The application must ensure the command list, kernel and events were created on the same context.
This function may not be called from simultaneous threads with the same command list handle.
The implementation of this function should be lock-free.
Use zeKernelSuggestMaxCooperativeGroupCount to recommend max group count for device for cooperative functions that device supports.
hCommandList – [in] handle of the command list
hKernel – [in] handle of the kernel object
pLaunchFuncArgs – [in] thread group launch arguments
hSignalEvent – [in][optional] handle of the event to signal on completion
numWaitEvents – [in][optional] number of events to wait on before launching; must be 0 if `nullptr == phWaitEvents`
phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hCommandList
nullptr == hKernel
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pLaunchFuncArgs
(nullptr == phWaitEvents) && (0 < numWaitEvents)
Launch kernel over one or more work groups using indirect arguments.
The application must ensure the kernel and events are accessible by the device on which the command list was created.
The application must ensure the launch arguments are visible to the device on which the command list was created.
The implementation must not access the contents of the launch arguments as they are free to be modified by either the Host or device up until execution.
This may only be called for a command list created with command queue group ordinal that supports compute.
The application must ensure the command list, kernel and events were created, and the memory was allocated, on the same context.
This function may not be called from simultaneous threads with the same command list handle.
The implementation of this function should be lock-free.
hCommandList – [in] handle of the command list
hKernel – [in] handle of the kernel object
pLaunchArgumentsBuffer – [in] pointer to device buffer that will contain thread group launch arguments
hSignalEvent – [in][optional] handle of the event to signal on completion
numWaitEvents – [in][optional] number of events to wait on before launching; must be 0 if `nullptr == phWaitEvents`
phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hCommandList
nullptr == hKernel
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pLaunchArgumentsBuffer
(nullptr == phWaitEvents) && (0 < numWaitEvents)
Launch multiple kernels over one or more work groups using an array of indirect arguments.
The application must ensure the kernel and events are accessible by the device on which the command list was created.
The application must ensure the array of launch arguments and count buffer are visible to the device on which the command list was created.
The implementation must not access the contents of the array of launch arguments or count buffer as they are free to be modified by either the Host or device up until execution.
This may only be called for a command list created with command queue group ordinal that supports compute.
The application must enusre the command list, kernel and events were created, and the memory was allocated, on the same context.
This function may not be called from simultaneous threads with the same command list handle.
The implementation of this function should be lock-free.
hCommandList – [in] handle of the command list
numKernels – [in] maximum number of kernels to launch
phKernels – [in][range(0, numKernels)] handles of the kernel objects
pCountBuffer – [in] pointer to device memory location that will contain the actual number of kernels to launch; value must be less than or equal to numKernels
pLaunchArgumentsBuffer – [in][range(0, numKernels)] pointer to device buffer that will contain a contiguous array of thread group launch arguments
hSignalEvent – [in][optional] handle of the event to signal on completion
numWaitEvents – [in][optional] number of events to wait on before launching; must be 0 if `nullptr == phWaitEvents`
phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hCommandList
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == phKernels
nullptr == pCountBuffer
nullptr == pLaunchArgumentsBuffer
(nullptr == phWaitEvents) && (0 < numWaitEvents)
Supported module creation input formats.
Values:
Format is SPIRV IL format.
Format is device native format.
Value marking end of ZE_MODULE_FORMAT_* ENUMs.
Values:
Module has imports (i.e. imported global variables and/or kernels). See zeModuleDynamicLink.
Value marking end of ZE_MODULE_PROPERTY_FLAG_* ENUMs.
Values:
force all device allocations to be resident during execution
application is responsible for all residency of device allocations. driver may disable implicit residency management.
Value marking end of ZE_KERNEL_FLAG_* ENUMs.
Values:
Indicates that the kernel accesses host allocations indirectly.
Indicates that the kernel accesses device allocations indirectly.
Indicates that the kernel accesses shared allocations indirectly.
Value marking end of ZE_KERNEL_INDIRECT_ACCESS_FLAG_* ENUMs.
Values:
Large SLM size.
Large General Data size.
Value marking end of ZE_CACHE_CONFIG_FLAG_* ENUMs.
Specialization constants - User defined constants.
Public Members
[in] Number of specialization constants.
[in][range(0, numConstants)] Array of IDs that is sized to numConstants.
[in][range(0, numConstants)] Array of pointers to values that is sized to numConstants.
Module descriptor.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] Module format passed in with pInputModule
[in] size of input IL or ISA from pInputModule.
[in] pointer to IL or ISA
[in][optional] string containing one or more (comma-separated) compiler flags. If unsupported, flag is ignored with a warning.
”-ze-opt-disable”
Disable optimizations
”-ze-opt-level”
Specifies optimization level for compiler. Levels are implementation specific.
0 is no optimizations (equivalent to -ze-opt-disable)
1 is optimize minimally (may be the same as 2)
2 is optimize more (default)
”-ze-opt-greater-than-4GB-buffer-required”
Use 64-bit offset calculations for buffers.
”-ze-opt-large-register-file”
Increase number of registers available to threads.
”-ze-opt-has-buffer-offset-arg”
Extend stateless to stateful optimization to more cases with the use of additional offset (e.g. 64-bit pointer to binding table with 32-bit offset).
”-g”
Include debugging information.
[in][optional] pointer to specialization constants. Valid only for SPIR-V input. This must be set to nullptr if no specialization constants are provided.
Module properties.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] 0 (none) or a valid combination of ze_module_property_flag_t
Kernel descriptor.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] creation flags. must be 0 (default) or a valid combination of ze_kernel_flag_t; default behavior may use driver-based residency.
[in] null-terminated name of kernel in module
Kernel universal unique id (UUID)
Public Members
[out] opaque data representing a kernel UUID
[out] opaque data representing the kernel’s module UUID
Kernel properties.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] number of kernel arguments.
[out] required group size in the X dimension, or zero if there is no required group size
[out] required group size in the Y dimension, or zero if there is no required group size
[out] required group size in the Z dimension, or zero if there is no required group size
[out] required number of subgroups per thread group, or zero if there is no required number of subgroups
[out] required subgroup size, or zero if there is no required subgroup size
[out] maximum subgroup size
[out] maximum number of subgroups per thread group
[out] local memory size used by each thread group
[out] private memory size allocated by compiler used by each thread
[out] spill memory size allocated by compiler
[out] universal unique identifier.
Additional kernel preferred group size properties.
This structure may be passed to zeKernelGetProperties, via the pNext member of ze_kernel_properties_t, to query additional kernel preferred group size properties.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] preferred group size multiple
Kernel dispatch group count.
Public Members
[in] number of thread groups in X dimension
[in] number of thread groups in Y dimension
[in] number of thread groups in Z dimension
Enumerations
Structures
Module Program Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_MODULE_PROGRAM_EXP_VERSION_* ENUMs.
Module extended descriptor to support multiple input modules.
Implementation must support ::ZE_experimental_module_program extension
Modules support import and export linkage for functions and global variables.
SPIR-V import and export linkage types are used. See SPIR-V specification for linkage details.
pInputModules, pBuildFlags, and pConstants from ze_module_desc_t is ignored.
Format in ze_module_desc_t needs to be set to ZE_MODULE_FORMAT_IL_SPIRV.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] Count of input modules
[in][range(0, count)] sizes of each input IL module in pInputModules.
[in][range(0, count)] pointer to an array of IL (e.g. SPIR-V modules). Valid only for SPIR-V input.
[in][optional][range(0, count)] array of strings containing build flags. See pBuildFlags in ze_module_desc_t.
[in][optional][range(0, count)] pointer to array of specialization constant strings. Valid only for SPIR-V input. This must be set to nullptr if no specialization constants are provided.
Enumerations
Structures
Raytracing Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_RAYTRACING_EXT_VERSION_* ENUMs.
Values:
Supports rayquery.
Value marking end of ZE_DEVICE_RAYTRACING_EXT_FLAG_* ENUMs.
Values:
reserved for future use
Value marking end of ZE_RAYTRACING_MEM_ALLOC_EXT_FLAG_* ENUMs.
Raytracing properties queried using zeDeviceGetModuleProperties.
This structure may be returned from zeDeviceGetModuleProperties, via the pNext member of ze_device_module_properties_t.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] 0 or a valid combination of ze_device_raytracing_ext_flags_t
[out] Maximum number of BVH levels supported
Raytracing memory allocation descriptor.
This structure must be passed to zeMemAllocShared or zeMemAllocDevice, via the pNext member of ze_device_mem_alloc_desc_t, for any memory allocation that is to be accessed by raytracing fixed-function of the device.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] flags specifying additional allocation controls. must be 0 (default) or a valid combination of ze_raytracing_mem_alloc_ext_flag_t; default behavior may use implicit driver-based heuristics.
Functions
Makes memory resident for the device.
The application must ensure the memory is resident before being referenced by the device
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hContext – [in] handle of context object
hDevice – [in] handle of the device
ptr – [in] pointer to memory to make resident
size – [in] size in bytes to make resident
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hContext
nullptr == hDevice
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == ptr
ZE_RESULT_ERROR_INVALID_ARGUMENT
ptr is not recognized by the implementation
Allows memory to be evicted from the device.
The application must ensure the device is not currently referencing the memory before it is evicted
The application may free the memory without evicting; the memory is implicitly evicted when freed.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hContext – [in] handle of context object
hDevice – [in] handle of the device
ptr – [in] pointer to memory to evict
size – [in] size in bytes to evict
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hContext
nullptr == hDevice
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == ptr
Makes image resident for the device.
The application must ensure the image is resident before being referenced by the device
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hContext – [in] handle of context object
hDevice – [in] handle of the device
hImage – [in] handle of image to make resident
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hContext
nullptr == hDevice
nullptr == hImage
Allows image to be evicted from the device.
The application must ensure the device is not currently referencing the image before it is evicted
The application may destroy the image without evicting; the image is implicitly evicted when destroyed.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hContext – [in] handle of context object
hDevice – [in] handle of the device
hImage – [in] handle of image to make evict
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hContext
nullptr == hDevice
nullptr == hImage
Functions
Enumerations
Structures
Creates sampler on the context.
The application must only use the sampler 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.
hContext – [in] handle of the context object
hDevice – [in] handle of the device
desc – [in] pointer to sampler descriptor
phSampler – [out] handle of the sampler
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hContext
nullptr == hDevice
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == desc
nullptr == phSampler
ZE_RESULT_ERROR_INVALID_ENUMERATION
ZE_SAMPLER_ADDRESS_MODE_MIRROR < desc->addressMode
ZE_SAMPLER_FILTER_MODE_LINEAR < desc->filterMode
Destroys sampler object.
The application must ensure the device is not currently referencing the sampler before it is deleted.
The implementation of this function may immediately free all Host and Device allocations associated with this sampler.
The application must not call this function from simultaneous threads with the same sampler handle.
The implementation of this function must be thread-safe.
hSampler – [in][release] handle of the sampler
Sampler addressing modes.
Values:
No coordinate modifications for out-of-bounds image access.
Out-of-bounds coordinates are wrapped back around.
Out-of-bounds coordinates are clamped to edge.
Out-of-bounds coordinates are clamped to border color which is (0.0f, 0.0f, 0.0f, 0.0f) if image format swizzle contains alpha, otherwise (0.0f, 0.0f, 0.0f, 1.0f).
Out-of-bounds coordinates are mirrored starting from edge.
Value marking end of ZE_SAMPLER_ADDRESS_MODE_* ENUMs.
Sampler filtering modes.
Values:
No coordinate modifications for out of bounds image access.
Out-of-bounds coordinates are wrapped back around.
Value marking end of ZE_SAMPLER_FILTER_MODE_* ENUMs.
Sampler descriptor.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] Sampler addressing mode to determine how out-of-bounds coordinates are handled.
[in] Sampler filter mode to determine how samples are filtered.
[in] Are coordinates normalized [0, 1] or not.
Functions
Enumerations
Structures
Reserves pages in virtual address space.
The application must only use the memory allocation on the context for which it was created.
The starting address and size must be page aligned. See zeVirtualMemQueryPageSize.
If pStart is not null then implementation will attempt to reserve starting from that address. If not available then will find another suitable starting address.
The application may call this function from simultaneous threads.
The access attributes will default to none to indicate reservation is inaccessible.
The implementation of this function must be thread-safe.
hContext – [in] handle of the context object
pStart – [in][optional] pointer to start of region to reserve. If nullptr then implementation will choose a start address.
size – [in] size in bytes to reserve; must be page aligned.
pptr – [out] pointer to virtual reservation.
Free pages in a reserved virtual address range.
Any existing virtual mappings for the range will be unmapped.
Physical allocations objects that were mapped to this range will not be destroyed. These need to be destroyed explicitly.
The application may call this function from simultaneous threads.
The implementation of this function must be thread-safe.
hContext – [in] handle of the context object
ptr – [in] pointer to start of region to free.
size – [in] size in bytes to free; must be page aligned.
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hContext
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == ptr
ZE_RESULT_ERROR_UNSUPPORTED_SIZE
0 == size
Queries page size to use for aligning virtual memory reservations and physical memory allocations.
The application may call this function from simultaneous threads.
The implementation of this function must be thread-safe.
hContext – [in] handle of the context object
hDevice – [in] handle of the device object
size – [in] unaligned allocation size in bytes
pagesize – [out] pointer to page size to use for start address and size alignments.
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hContext
nullptr == hDevice
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pagesize
ZE_RESULT_ERROR_UNSUPPORTED_SIZE
0 == size
Creates a physical memory object for the context.
The application must only use the physical memory object on the context for which it was created.
The size must be page aligned. For host memory, the operating system page size should be used. For device memory, see zeVirtualMemQueryPageSize.
The application may call this function from simultaneous threads.
The implementation of this function must be thread-safe.
hContext – [in] handle of the context object
hDevice – [in] handle of the device object, can be `nullptr` if creating physical host memory.
desc – [in] pointer to physical memory descriptor.
phPhysicalMemory – [out] pointer to handle of physical memory object created
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hContext
nullptr == hDevice
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == desc
nullptr == phPhysicalMemory
ZE_RESULT_ERROR_INVALID_ENUMERATION
0x3 < desc->flags
ZE_RESULT_ERROR_UNSUPPORTED_SIZE
0 == desc->size
Destroys a physical memory object.
The application must ensure the device is not currently referencing the physical memory object before it is deleted
The application must not call this function from simultaneous threads with the same physical memory handle.
The implementation of this function must be thread-safe.
hContext – [in] handle of the context object
hPhysicalMemory – [in][release] handle of physical memory object to destroy
Maps pages in virtual address space to pages from physical memory object.
The virtual address range must have been reserved using zeVirtualMemReserve.
The application must only use the mapped memory allocation on the context for which it was created.
The virtual start address and size must be page aligned. See zeVirtualMemQueryPageSize.
The application should use, for the starting address and size, the same size alignment used for the physical allocation.
The application may call this function from simultaneous threads.
The implementation of this function must be thread-safe.
hContext – [in] handle of the context object
ptr – [in] pointer to start of virtual address range to map.
size – [in] size in bytes of virtual address range to map; must be page aligned.
hPhysicalMemory – [in] handle to physical memory object.
offset – [in] offset into physical memory allocation object; must be page aligned.
access – [in] specifies page access attributes to apply to the virtual address range.
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hContext
nullptr == hPhysicalMemory
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == ptr
ZE_RESULT_ERROR_INVALID_ENUMERATION
ZE_MEMORY_ACCESS_ATTRIBUTE_READONLY < access
ZE_RESULT_ERROR_UNSUPPORTED_SIZE
0 == size
Unmaps pages in virtual address space from pages from a physical memory object.
The page access attributes for virtual address range will revert back to none.
The application may call this function from simultaneous threads.
The implementation of this function must be thread-safe.
hContext – [in] handle of the context object
ptr – [in] pointer to start of region to unmap.
size – [in] size in bytes to unmap; must be page aligned.
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hContext
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == ptr
ZE_RESULT_ERROR_UNSUPPORTED_ALIGNMENT
Address must be page aligned
ZE_RESULT_ERROR_UNSUPPORTED_SIZE
0 == size
Size must be page aligned
Set memory access attributes for a virtual address range.
This function may be called from simultaneous threads with the same function handle.
The implementation of this function should be lock-free.
hContext – [in] handle of the context object
ptr – [in] pointer to start of reserved virtual address region.
size – [in] size in bytes; must be page aligned.
access – [in] specifies page access attributes to apply to the virtual address range.
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hContext
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == ptr
ZE_RESULT_ERROR_INVALID_ENUMERATION
ZE_MEMORY_ACCESS_ATTRIBUTE_READONLY < access
ZE_RESULT_ERROR_UNSUPPORTED_ALIGNMENT
Address must be page aligned
ZE_RESULT_ERROR_UNSUPPORTED_SIZE
0 == size
Size must be page aligned
Get memory access attribute for a virtual address range.
If size and outSize are equal then the pages in the specified virtual address range have the same access attributes.
This function may be called from simultaneous threads with the same function handle.
The implementation of this function should be lock-free.
hContext – [in] handle of the context object
ptr – [in] pointer to start of virtual address region for query.
size – [in] size in bytes; must be page aligned.
access – [out] query result for page access attribute.
outSize – [out] query result for size of virtual address range, starting at ptr, that shares same access attribute.
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hContext
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == ptr
nullptr == access
nullptr == outSize
ZE_RESULT_ERROR_UNSUPPORTED_ALIGNMENT
Address must be page aligned
ZE_RESULT_ERROR_UNSUPPORTED_SIZE
0 == size
Size must be page aligned
Virtual memory page access attributes.
Values:
Indicates the memory page is inaccessible.
Indicates the memory page supports read write access.
Indicates the memory page supports read-only access.
Value marking end of ZE_MEMORY_ACCESS_ATTRIBUTE_* ENUMs.
Values:
[default] allocate physical device memory.
Allocate physical host memory instead.
Value marking end of ZE_PHYSICAL_MEM_FLAG_* ENUMs.
Physical memory descriptor.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] creation flags. must be 0 (default) or a valid combination of ze_physical_mem_flag_t; default is to create physical device memory.
[in] size in bytes to reserve; must be page aligned.
Enumerations
Structures
Floating-Point Atomics Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_FLOAT_ATOMICS_EXT_VERSION_* ENUMs.
Values:
Supports atomic load, store, and exchange.
Supports atomic add and subtract.
Supports atomic min and max.
Supports atomic load, store, and exchange.
Supports atomic add and subtract.
Supports atomic min and max.
Value marking end of ZE_DEVICE_FP_ATOMIC_EXT_FLAG_* ENUMs.
Device floating-point atomic properties queried using zeDeviceGetModuleProperties.
This structure may be returned from zeDeviceGetModuleProperties, via the pNext member of ze_device_module_properties_t.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] Capabilities for half-precision floating-point atomic operations
[out] Capabilities for single-precision floating-point atomic operations
[out] Capabilities for double-precision floating-point atomic operations
Functions
Enumerations
Set global work offset for a kernel.
The global work offset will be used when a zeCommandListAppendLaunchKernel() variant is called.
The application must not call this function from simultaneous threads with the same kernel handle.
The implementation of this function should be lock-free.
hKernel – [in] handle of the kernel object
offsetX – [in] global offset for X dimension to use for this kernel
offsetY – [in] global offset for Y dimension to use for this kernel
offsetZ – [in] global offset for Z dimension to use for this kernel
Global Offset Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_GLOBAL_OFFSET_EXP_VERSION_* ENUMs.
Enumerations
Structures
Relaxed Allocation Limits Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_RELAXED_ALLOCATION_LIMITS_EXP_VERSION_* ENUMs.
Values:
Allocation size may exceed the maxMemAllocSize member of ze_device_properties_t.
Value marking end of ZE_RELAXED_ALLOCATION_LIMITS_EXP_FLAG_* ENUMs.
Relaxed limits memory allocation descriptor.
This structure may be passed to zeMemAllocShared or zeMemAllocDevice, via the pNext member of ze_device_mem_alloc_desc_t.
This structure may also be passed to zeMemAllocHost, via the pNext member of ze_host_mem_alloc_desc_t.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] flags specifying allocation limits to relax. must be 0 (default) or a valid combination of ze_relaxed_allocation_limits_exp_flag_t;
Functions
Enumerations
Retrieves kernel binary program data (ISA GEN format).
A valid kernel handle must be created with zeKernelCreate.
Returns Intel Graphics Assembly (GEN ISA) format binary program data for kernel handle.
The application may call this function from simultaneous threads.
The implementation of this function must be thread-safe.
hKernel – [in] Kernel handle.
pSize – [in,out] pointer to variable with size of GEN ISA binary.
pKernelBinary – [in,out] pointer to storage area for GEN ISA binary function.
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hKernel
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pSize
nullptr == pKernelBinary
Get Kernel Binary Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_KERNEL_GET_BINARY_EXP_VERSION_* ENUMs.
Enumerations
Structures
Driver Direct Device Interface (DDI) Handles Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_DRIVER_DDI_HANDLES_EXT_VERSION_* ENUMs.
Values:
Driver Supports DDI Handles Extension.
Value marking end of ZE_DRIVER_DDI_HANDLE_EXT_FLAG_* ENUMs.
Driver DDI Handles properties queried using zeDriverGetProperties.
This structure may be returned from zeDriverGetProperties, via the pNext member of ze_driver_properties_t.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] 0 (none) or a valid combination of ze_driver_ddi_handle_ext_flags_t
Functions
Enumerations
Structures
Import an external semaphore.
Imports an external semaphore.
This function may be called from simultaneous threads with the same device handle.
The implementation of this function should be lock-free.
hDevice – [in] The device handle.
desc – [in] The pointer to external semaphore descriptor.
phSemaphore – [out] The handle of the external semaphore imported.
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hDevice
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == desc
nullptr == phSemaphore
ZE_RESULT_ERROR_INVALID_ENUMERATION
0x1ff < desc->flags
Release an external semaphore.
The application must ensure the device is not currently referencing the semaphore before it is released.
The application must not call this function from simultaneous threads with the same semaphore handle.
The implementation of this function must be thread-safe.
hSemaphore – [in] The handle of the external semaphore.
Signal an external semaphore.
Signals an external semaphore.
This function must only be used with an immediate command list.
This function may be called from simultaneous threads with the same command list handle.
The implementation of this function should be lock-free.
hCommandList – [in] The command list handle.
numSemaphores – [in] The number of external semaphores.
phSemaphores – [in][range(0, numSemaphores)] The vector of external semaphore handles to be appended into command list.
signalParams – [in] Signal parameters.
hSignalEvent – [in][optional] handle of the event to signal on completion
numWaitEvents – [in][optional] number of events to wait on before launching; must be 0 if `nullptr == phWaitEvents`
phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hCommandList
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == phSemaphores
nullptr == signalParams
(nullptr == phWaitEvents) && (0 < numWaitEvents)
(nullptr == phSemaphores) && (0 < numSemaphores)
(nullptr == signalParams) && (0 < numSemaphores)
ZE_RESULT_ERROR_INVALID_ARGUMENT
Commandlist handle does not correspond to an immediate command list
Wait on external semaphores.
Waits on external semaphores.
This function must only be used with an immediate command list.
This function may be called from simultaneous threads with the same command list handle.
The implementation of this function should be lock-free.
hCommandList – [in] The command list handle.
numSemaphores – [in] The number of external semaphores.
phSemaphores – [in] [range(0,numSemaphores)] The vector of external semaphore handles to append into command list.
waitParams – [in] Wait parameters.
hSignalEvent – [in][optional] handle of the event to signal on completion
numWaitEvents – [in][optional] number of events to wait on before launching; must be 0 if `nullptr == phWaitEvents`
phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hCommandList
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == phSemaphores
nullptr == waitParams
(nullptr == phWaitEvents) && (0 < numWaitEvents)
(nullptr == phSemaphores) && (0 < numSemaphores)
(nullptr == waitParams) && (0 < numSemaphores)
ZE_RESULT_ERROR_INVALID_ARGUMENT
Commandlist handle does not correspond to an immediate command list
External Semaphores Extension Version.
Values:
version 1.0
latest known version
Value marking end of ZE_EXTERNAL_SEMAPHORE_EXT_VERSION_* ENUMs.
Values:
Semaphore is an Linux opaque file descriptor.
Semaphore is an opaque Win32 handle for monitored fence.
Semaphore is an opaque Win32 KMT handle for monitored fence.
Semaphore is a D3D12 fence.
Semaphore is a D3D11 fence.
Semaphore is a keyed mutex for Win32.
Semaphore is a keyed mutex for Win32 KMT.
Semaphore is a Vulkan Timeline semaphore for Linux.
Semaphore is a Vulkan Timeline semaphore for Win32.
Value marking end of ZE_EXTERNAL_SEMAPHORE_EXT_FLAG_* ENUMs.
External Semaphore Descriptor.
External Semaphore Win32 Descriptor.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] Win32 handle of the semaphore. Must be a valid Win32 handle.
[in] Name of the semaphore. Must be a valid null-terminated string.
External Semaphore FD Descriptor.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] File descriptor of the semaphore. Must be a valid file descriptor.
External Semaphore Signal parameters.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] [optional] Value to signal. Specified by user as an expected value with some of semaphore types, such as ZE_EXTERNAL_SEMAPHORE_EXT_FLAG_D3D12_FENCE.
External Semaphore Wait parameters.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] [optional] Value to wait for. Specified by user as an expected value with some of semaphore types, such as ZE_EXTERNAL_SEMAPHORE_EXT_FLAG_D3D12_FENCE.
Enumerations
Structures
CacheLine Size Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_DEVICE_CACHE_LINE_SIZE_EXT_VERSION_* ENUMs.
CacheLine Size queried using zeDeviceGetCacheProperties.
This structure may be returned from zeDeviceGetCacheProperties via the pNext member of ze_device_cache_properties_t.
Used for determining the cache line size supported on a device.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] The cache line size in bytes.
Functions
Enumerations
Structures
Creates a ray tracing acceleration structure builder object.
The application may call this function from simultaneous threads.
The implementation of this function must be thread-safe.
The implementation must support ::ZE_extension_rtas extension.
hDriver – [in] handle of driver object
pDescriptor – [in] pointer to builder descriptor
phBuilder – [out] handle of builder object
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hDriver
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pDescriptor
nullptr == phBuilder
ZE_RESULT_ERROR_INVALID_ENUMERATION
ZE_RTAS_BUILDER_EXT_VERSION_CURRENT < pDescriptor->builderVersion
Retrieves ray tracing acceleration structure builder properties.
The application may call this function from simultaneous threads.
The implementation of this function must be thread-safe.
hBuilder – [in] handle of builder object
pBuildOpDescriptor – [in] pointer to build operation descriptor
pProperties – [in,out] query result for builder properties
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hBuilder
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pBuildOpDescriptor
nullptr == pProperties
ZE_RESULT_ERROR_INVALID_ENUMERATION
ZE_RTAS_FORMAT_EXT_MAX < pBuildOpDescriptor->rtasFormat
ZE_RTAS_BUILDER_BUILD_QUALITY_HINT_EXT_HIGH < pBuildOpDescriptor->buildQuality
0x3 < pBuildOpDescriptor->buildFlags
Checks ray tracing acceleration structure format compatibility.
The application may call this function from simultaneous threads.
The implementation of this function must be thread-safe.
hDriver – [in] handle of driver object
rtasFormatA – [in] operand A
rtasFormatB – [in] operand B
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hDriver
ZE_RESULT_ERROR_INVALID_ENUMERATION
ZE_RTAS_FORMAT_EXT_MAX < rtasFormatA
ZE_RTAS_FORMAT_EXT_MAX < rtasFormatB
An acceleration structure built with rtasFormatA is compatible with devices that report rtasFormatB.
ZE_RESULT_EXT_ERROR_OPERANDS_INCOMPATIBLE
An acceleration structure built with rtasFormatA is not compatible with devices that report rtasFormatB.
Build ray tracing acceleration structure.
This function builds an acceleration structure of the scene consisting of the specified geometry information and writes the acceleration structure to the provided destination buffer. All types of geometries can get freely mixed inside a scene.
Before an acceleration structure can be built, the user must allocate the memory for the acceleration structure buffer and scratch buffer using sizes queried with the zeRTASBuilderGetBuildPropertiesExt function.
When using the “worst-case” size for the acceleration structure buffer, the acceleration structure construction will never fail with ZE_RESULT_EXT_RTAS_BUILD_RETRY.
When using the “expected” size for the acceleration structure buffer, the acceleration structure construction may fail with ZE_RESULT_EXT_RTAS_BUILD_RETRY. If this happens, the user may resize their acceleration structure buffer using the returned *pRtasBufferSizeBytes value, which will be updated with an improved size estimate that will likely result in a successful build.
The acceleration structure construction is run on the host and is synchronous, thus after the function returns with a successful result, the acceleration structure may be used.
All provided data buffers must be host-accessible. The referenced scene data (index- and vertex- buffers) have to be accessible from the host, and will not be referenced by the build acceleration structure.
The acceleration structure buffer is typicall a host allocation that is later manually copied to a device allocation. Alternatively one can also use a shared USM allocation as acceration structure buffer and skip the copy.
A successfully constructed acceleration structure is entirely self-contained. There is no requirement for input data to persist beyond build completion.
A successfully constructed acceleration structure is non-copyable.
Acceleration structure construction may be parallelized by passing a valid handle to a parallel operation object and joining that parallel operation using zeRTASParallelOperationJoinExt with user-provided worker threads.
A successfully constructed acceleration structure is generally non-copyable. It can only get copied from host to device using the special zeRTASBuilderCommandListAppendCopyExt function.
Additional Notes
”The geometry infos array, geometry infos, and scratch buffer must
all be standard host memory allocations.”
”A pointer to a geometry info can be a null pointer, in which case
the geometry is treated as empty.”
”If no parallel operation handle is provided, the build is run
sequentially on the current thread.”
”A parallel operation object may only be associated with a single
acceleration structure build at a time.”
hBuilder – [in] handle of builder object
pBuildOpDescriptor – [in] pointer to build operation descriptor
pScratchBuffer – [in][range(0, `scratchBufferSizeBytes`)] scratch buffer to be used during acceleration structure construction
scratchBufferSizeBytes – [in] size of scratch buffer, in bytes
pRtasBuffer – [in] pointer to destination buffer
rtasBufferSizeBytes – [in] destination buffer size, in bytes
hParallelOperation – [in][optional] handle to parallel operation object
pBuildUserPtr – [in][optional] pointer passed to callbacks
pBounds – [in,out][optional] pointer to destination address for acceleration structure bounds
pRtasBufferSizeBytes – [out][optional] updated acceleration structure size requirement, in bytes
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hBuilder
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pBuildOpDescriptor
nullptr == pScratchBuffer
nullptr == pRtasBuffer
ZE_RESULT_ERROR_INVALID_ENUMERATION
ZE_RTAS_FORMAT_EXT_MAX < pBuildOpDescriptor->rtasFormat
ZE_RTAS_BUILDER_BUILD_QUALITY_HINT_EXT_HIGH < pBuildOpDescriptor->buildQuality
0x3 < pBuildOpDescriptor->buildFlags
ZE_RESULT_EXT_RTAS_BUILD_DEFERRED
Acceleration structure build completion is deferred to parallel operation join.
ZE_RESULT_EXT_RTAS_BUILD_RETRY
Acceleration structure build failed due to insufficient resources, retry the build operation with a larger acceleration structure buffer allocation.
ZE_RESULT_ERROR_HANDLE_OBJECT_IN_USE
Acceleration structure build failed due to parallel operation object participation in another build operation.
Copies a ray tracing acceleration structure (RTAS) from host to device memory.
The memory pointed to by srcptr must be host memory containing a valid ray tracing acceleration structure.
The number of bytes to copy must be larger or equal to the size of the ray tracing acceleration structure.
The application must ensure the memory pointed to by dstptr and srcptr is accessible by the device on which the command list was created.
The implementation must not access the memory pointed to by dstptr and srcptr as they are free to be modified by either the Host or device up until execution.
The application must ensure the events are accessible by the device on which the command list was created.
The application must ensure the command list and events were created, and the memory was allocated, on the same context.
The application must not call this function from simultaneous threads with the same command list handle.
The implementation of this function should be lock-free.
hCommandList – [in] handle of command list
dstptr – [in] pointer to destination in device memory to copy the ray tracing acceleration structure to
srcptr – [in] pointer to a valid source ray tracing acceleration structure in host memory to copy from
size – [in] size in bytes to copy
hSignalEvent – [in][optional] handle of the event to signal on completion
numWaitEvents – [in][optional] number of events to wait on before launching; must be 0 if `nullptr == phWaitEvents`
phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hCommandList
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == dstptr
nullptr == srcptr
(nullptr == phWaitEvents) && (0 < numWaitEvents)
Destroys a ray tracing acceleration structure builder object.
The implementation of this function may immediately release any internal Host and Device resources associated with this builder.
The application must not call this function from simultaneous threads with the same builder handle.
The implementation of this function must be thread-safe.
hBuilder – [in][release] handle of builder object to destroy
Creates a ray tracing acceleration structure builder parallel operation object.
The application may call this function from simultaneous threads.
The implementation of this function must be thread-safe.
The implementation must support ::ZE_extension_rtas extension.
hDriver – [in] handle of driver object
phParallelOperation – [out] handle of parallel operation object
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hDriver
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == phParallelOperation
Retrieves ray tracing acceleration structure builder parallel operation properties.
The application must first bind the parallel operation object to a build operation before it may query the parallel operation properties. In other words, the application must first call zeRTASBuilderBuildExt with hParallelOperation before calling this function.
The application may call this function from simultaneous threads.
The implementation of this function must be thread-safe.
hParallelOperation – [in] handle of parallel operation object
pProperties – [in,out] query result for parallel operation properties
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hParallelOperation
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pProperties
Joins a parallel build operation.
All worker threads return the same error code for the parallel build operation upon build completion
hParallelOperation – [in] handle of parallel operation object
Destroys a ray tracing acceleration structure builder parallel operation object.
The implementation of this function may immediately release any internal Host and Device resources associated with this parallel operation.
The application must not call this function from simultaneous threads with the same parallel operation handle.
The implementation of this function must be thread-safe.
hParallelOperation – [in][release] handle of parallel operation object to destroy
Ray Tracing Acceleration Structure Builder Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_RTAS_BUILDER_EXT_VERSION_* ENUMs.
Values:
reserved for future use
Value marking end of ZE_RTAS_DEVICE_EXT_FLAG_* ENUMs.
Ray tracing acceleration structure format.
This is an opaque ray tracing acceleration structure format identifier.
Values:
Invalid acceleration structure format code.
Maximum acceleration structure format code.
Value marking end of ZE_RTAS_FORMAT_EXT_* ENUMs.
Values:
Reserved for future use.
Value marking end of ZE_RTAS_BUILDER_EXT_FLAG_* ENUMs.
Values:
Reserved for future use.
Value marking end of ZE_RTAS_PARALLEL_OPERATION_EXT_FLAG_* ENUMs.
Values:
non-opaque geometries invoke an any-hit shader
Value marking end of ZE_RTAS_BUILDER_GEOMETRY_EXT_FLAG_* ENUMs.
Values:
disables culling of front-facing and back-facing triangles
reverses front and back face of triangles
forces instanced geometry to be opaque, unless ray flag forces it to be non-opaque
forces instanced geometry to be non-opaque, unless ray flag forces it to be opaque
Value marking end of ZE_RTAS_BUILDER_INSTANCE_EXT_FLAG_* ENUMs.
Values:
build more compact acceleration structure
guarantees single any-hit shader invocation per primitive
Value marking end of ZE_RTAS_BUILDER_BUILD_OP_EXT_FLAG_* ENUMs.
Ray tracing acceleration structure builder build quality hint.
Depending on use case different quality modes for acceleration structure build are supported.
A low-quality build builds an acceleration structure fast, but at the cost of some reduction in ray tracing performance. This mode is recommended for dynamic content, such as animated characters.
A medium-quality build uses a compromise between build quality and ray tracing performance. This mode should be used by default.
Higher ray tracing performance can be achieved by using a high-quality build, but acceleration structure build performance might be significantly reduced.
Values:
build low-quality acceleration structure (fast)
build medium-quality acceleration structure (slower)
build high-quality acceleration structure (slow)
Value marking end of ZE_RTAS_BUILDER_BUILD_QUALITY_HINT_EXT_* ENUMs.
Ray tracing acceleration structure builder geometry type.
Values:
triangle mesh geometry type
quad mesh geometry type
procedural geometry type
instance geometry type
Value marking end of ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXT_* ENUMs.
Ray tracing acceleration structure data buffer element format.
Specifies the format of data buffer elements.
Data buffers may contain instancing transform matrices, triangle/quad vertex indices, etc…
Values:
3-component float vector (see ze_rtas_float3_ext_t)
3x4 affine transformation in column-major format (see ze_rtas_transform_float3x4_column_major_ext_t)
3x4 affine transformation in column-major format (see ze_rtas_transform_float3x4_aligned_column_major_ext_t)
3x4 affine transformation in row-major format (see ze_rtas_transform_float3x4_row_major_ext_t)
3-dimensional axis-aligned bounding-box (see ze_rtas_aabb_ext_t)
Unsigned 32-bit triangle indices (see ze_rtas_triangle_indices_uint32_ext_t)
Unsigned 32-bit quad indices (see ze_rtas_quad_indices_uint32_ext_t)
Value marking end of ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXT_* ENUMs.
Ray tracing acceleration structure builder descriptor.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] ray tracing acceleration structure builder version
Ray tracing acceleration structure builder properties.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] ray tracing acceleration structure builder flags
[out] expected size (in bytes) required for acceleration structure buffer
When using an acceleration structure buffer of this size, the build is expected to succeed; however, it is possible that the build may fail with ZE_RESULT_EXT_RTAS_BUILD_RETRY
[out] worst-case size (in bytes) required for acceleration structure buffer
When using an acceleration structure buffer of this size, the build is guaranteed to not run out of memory.
[out] scratch buffer size (in bytes) required for acceleration structure build.
Ray tracing acceleration structure builder parallel operation properties.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] ray tracing acceleration structure builder parallel operation flags
[out] maximum number of threads that may join the parallel operation
Ray tracing acceleration structure device properties.
This structure may be passed to zeDeviceGetProperties, via pNext member of ze_device_properties_t.
The implementation shall populate format with a value other than ZE_RTAS_FORMAT_EXT_INVALID when the device supports ray tracing.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] ray tracing acceleration structure device flags
[out] ray tracing acceleration structure format
[out] required alignment of acceleration structure buffer
A 3-component vector type.
Public Members
[in] x-coordinate of float3 vector
[in] y-coordinate of float3 vector
[in] z-coordinate of float3 vector
3x4 affine transformation in column-major layout
A 3x4 affine transformation in column major layout, consisting of vectors
vx=(vx_x, vx_y, vx_z),
vy=(vy_x, vy_y, vy_z),
vz=(vz_x, vz_y, vz_z), and
p=(p_x, p_y, p_z)
The transformation transforms a point (x, y, z) to: x*vx + y*vy + z*vz + p.
Public Members
[in] element 0 of column 0 of 3x4 matrix
[in] element 1 of column 0 of 3x4 matrix
[in] element 2 of column 0 of 3x4 matrix
[in] element 0 of column 1 of 3x4 matrix
[in] element 1 of column 1 of 3x4 matrix
[in] element 2 of column 1 of 3x4 matrix
[in] element 0 of column 2 of 3x4 matrix
[in] element 1 of column 2 of 3x4 matrix
[in] element 2 of column 2 of 3x4 matrix
[in] element 0 of column 3 of 3x4 matrix
[in] element 1 of column 3 of 3x4 matrix
[in] element 2 of column 3 of 3x4 matrix
3x4 affine transformation in column-major layout with aligned column vectors
A 3x4 affine transformation in column major layout, consisting of vectors
vx=(vx_x, vx_y, vx_z),
vy=(vy_x, vy_y, vy_z),
vz=(vz_x, vz_y, vz_z), and
p=(p_x, p_y, p_z)
The transformation transforms a point (x, y, z) to: x*vx + y*vy + z*vz + p.
The column vectors are aligned to 16-bytes and pad members are ignored.
Public Members
[in] element 0 of column 0 of 3x4 matrix
[in] element 1 of column 0 of 3x4 matrix
[in] element 2 of column 0 of 3x4 matrix
[in] ignored padding
[in] element 0 of column 1 of 3x4 matrix
[in] element 1 of column 1 of 3x4 matrix
[in] element 2 of column 1 of 3x4 matrix
[in] ignored padding
[in] element 0 of column 2 of 3x4 matrix
[in] element 1 of column 2 of 3x4 matrix
[in] element 2 of column 2 of 3x4 matrix
[in] ignored padding
[in] element 0 of column 3 of 3x4 matrix
[in] element 1 of column 3 of 3x4 matrix
[in] element 2 of column 3 of 3x4 matrix
[in] ignored padding
3x4 affine transformation in row-major layout
A 3x4 affine transformation in row-major layout, consisting of vectors
vx=(vx_x, vx_y, vx_z),
vy=(vy_x, vy_y, vy_z),
vz=(vz_x, vz_y, vz_z), and
p=(p_x, p_y, p_z)
The transformation transforms a point (x, y, z) to: x*vx + y*vy + z*vz + p.
Public Members
[in] element 0 of row 0 of 3x4 matrix
[in] element 1 of row 0 of 3x4 matrix
[in] element 2 of row 0 of 3x4 matrix
[in] element 3 of row 0 of 3x4 matrix
[in] element 0 of row 1 of 3x4 matrix
[in] element 1 of row 1 of 3x4 matrix
[in] element 2 of row 1 of 3x4 matrix
[in] element 3 of row 1 of 3x4 matrix
[in] element 0 of row 2 of 3x4 matrix
[in] element 1 of row 2 of 3x4 matrix
[in] element 2 of row 2 of 3x4 matrix
[in] element 3 of row 2 of 3x4 matrix
A 3-dimensional axis-aligned bounding-box with lower and upper bounds in each dimension.
Triangle represented using 3 vertex indices.
Represents a triangle using 3 vertex indices that index into a vertex array that needs to be provided together with the index array.
The linear barycentric u/v parametrization of the triangle is defined as:
(u=0, v=0) at v0,
(u=1, v=0) at v1, and
(u=0, v=1) at v2
Public Members
[in] first index pointing to the first triangle vertex in vertex array
[in] second index pointing to the second triangle vertex in vertex array
[in] third index pointing to the third triangle vertex in vertex array
Quad represented using 4 vertex indices.
Represents a quad composed of 4 indices that index into a vertex array that needs to be provided together with the index array.
A quad is a triangle pair represented using 4 vertex indices v0, v1, v2, v3. The first triangle is made out of indices v0, v1, v3 and the second triangle from indices v2, v3, v1. The piecewise linear barycentric u/v parametrization of the quad is defined as:
(u=0, v=0) at v0,
(u=1, v=0) at v1,
(u=0, v=1) at v3, and
(u=1, v=1) at v2 This is achieved by correcting the u’/v’ coordinates of the second triangle by u = 1-u’ and v = 1-v’, yielding a piecewise linear parametrization.
Public Members
[in] first index pointing to the first quad vertex in vertex array
[in] second index pointing to the second quad vertex in vertex array
[in] third index pointing to the third quad vertex in vertex array
[in] fourth index pointing to the fourth quad vertex in vertex array
Ray tracing acceleration structure builder geometry info.
Public Members
[in] geometry type
Ray tracing acceleration structure builder triangle mesh geometry info.
The linear barycentric u/v parametrization of the triangle is defined as:
(u=0, v=0) at v0,
(u=1, v=0) at v1, and
(u=0, v=1) at v2
Public Members
[in] geometry type, must be ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXT_TRIANGLES
[in] 0 or some combination of ze_rtas_builder_geometry_ext_flag_t bits representing the geometry flags for all primitives of this geometry
[in] 8-bit geometry mask for ray masking
[in] format of triangle buffer data, must be ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXT_TRIANGLE_INDICES_UINT32
[in] format of vertex buffer data, must be ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXT_FLOAT3
[in] number of triangles in triangle buffer
[in] number of vertices in vertex buffer
[in] stride (in bytes) of triangles in triangle buffer
[in] stride (in bytes) of vertices in vertex buffer
[in] pointer to array of triangle indices in specified format
[in] pointer to array of triangle vertices in specified format
Ray tracing acceleration structure builder quad mesh geometry info.
A quad is a triangle pair represented using 4 vertex indices v0, v1, v2, v3. The first triangle is made out of indices v0, v1, v3 and the second triangle from indices v2, v3, v1. The piecewise linear barycentric u/v parametrization of the quad is defined as:
(u=0, v=0) at v0,
(u=1, v=0) at v1,
(u=0, v=1) at v3, and
(u=1, v=1) at v2 This is achieved by correcting the u’/v’ coordinates of the second triangle by u = 1-u’ and v = 1-v’, yielding a piecewise linear parametrization.
Public Members
[in] geometry type, must be ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXT_QUADS
[in] 0 or some combination of ze_rtas_builder_geometry_ext_flag_t bits representing the geometry flags for all primitives of this geometry
[in] 8-bit geometry mask for ray masking
[in] format of quad buffer data, must be ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXT_QUAD_INDICES_UINT32
[in] format of vertex buffer data, must be ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXT_FLOAT3
[in] number of quads in quad buffer
[in] number of vertices in vertex buffer
[in] stride (in bytes) of quads in quad buffer
[in] stride (in bytes) of vertices in vertex buffer
[in] pointer to array of quad indices in specified format
[in] pointer to array of quad vertices in specified format
AABB callback function parameters.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] first primitive to return bounds for
[in] number of primitives to return bounds for
[in] pointer provided through geometry descriptor
[in] pointer provided through zeRTASBuilderBuildExt function
[out] destination buffer to write AABB bounds to
Ray tracing acceleration structure builder procedural primitives geometry info.
A host-side bounds callback function is invoked by the acceleration structure builder to query the bounds of procedural primitives on demand. The callback is passed some pGeomUserPtr that can point to an application-side representation of the procedural primitives. Further, a second pBuildUserPtr, which is set by a parameter to zeRTASBuilderBuildExt, is passed to the callback. This allows the build to change the bounds of the procedural geometry, for example, to build a BVH only over a short time range to implement multi-segment motion blur.
Public Members
[in] geometry type, must be ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXT_PROCEDURAL
[in] 0 or some combination of ze_rtas_builder_geometry_ext_flag_t bits representing the geometry flags for all primitives of this geometry
[in] 8-bit geometry mask for ray masking
[in] reserved for future use
[in] number of primitives in geometry
[in] pointer to callback function to get the axis-aligned bounding-box for a range of primitives
[in] user data pointer passed to callback
Ray tracing acceleration structure builder instance geometry info.
Public Members
[in] geometry type, must be ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXT_INSTANCE
[in] 0 or some combination of ze_rtas_builder_geometry_ext_flag_t bits representing the geometry flags for all primitives of this geometry
[in] 8-bit geometry mask for ray masking
[in] format of the specified transformation
[in] user-specified identifier for the instance
[in] object-to-world instance transformation in specified format
[in] object-space axis-aligned bounding-box of the instanced acceleration structure
[in] device pointer to acceleration structure to instantiate
Functions
Enumerations
Structures
Retrieves the vector width properties of the device.
Properties are reported for each vector width supported by the device.
Multiple calls to this function will return properties in the same order.
The number of vector width properties is reported thru the pCount parameter which is updated by the driver given pCount == 0.
The application may provide a buffer that is larger than the number of properties, but the application must set pCount to the number of properties to retrieve.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hDevice – [in] handle of the device
pCount – [in,out] pointer to the number of vector width properties. if count is zero, then the driver shall update the value with the total number of vector width properties available. if count is greater than the number of vector width properties available, then the driver shall update the value with the correct number of vector width properties available.
pVectorWidthProperties – [in,out][optional][range(0, *pCount)] array of vector width properties. if count is less than the number of properties available, then the driver will return only the number requested.
Device Vector Sizes Query Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_DEVICE_VECTOR_SIZES_EXT_VERSION_* ENUMs.
Device Vector Width Properties queried using $DeviceGetVectorWidthPropertiesExt.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] The associated vector width size supported by the device.
[out] The preferred vector width size for char type supported by the device.
[out] The preferred vector width size for short type supported by the device.
[out] The preferred vector width size for int type supported by the device.
[out] The preferred vector width size for long type supported by the device.
[out] The preferred vector width size for float type supported by the device.
[out] The preferred vector width size for double type supported by the device.
[out] The preferred vector width size for half type supported by the device.
[out] The native vector width size for char type supported by the device.
[out] The native vector width size for short type supported by the device.
[out] The native vector width size for int type supported by the device.
[out] The native vector width size for long type supported by the device.
[out] The native vector width size for float type supported by the device.
[out] The native vector width size for double type supported by the device.
[out] The native vector width size for half type supported by the device.
Functions
Enumerations
Structures
Reserve Cache on Device.
The application may call this function but may not be successful as some other application may have reserve prior
hDevice – [in] handle of the device object
cacheLevel – [in] cache level where application want to reserve. If zero, then the driver shall default to last level of cache and attempt to reserve in that cache.
cacheReservationSize – [in] value for reserving size, in bytes. If zero, then the driver shall remove prior reservation
Assign VA section to use reserved section.
The application may call this function to assign VA to particular reservartion region
hDevice – [in] handle of the device object
ptr – [in] memory pointer to query
regionSize – [in] region size, in pages
cacheRegion – [in] reservation region
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hDevice
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == ptr
ZE_RESULT_ERROR_INVALID_ENUMERATION
ZE_CACHE_EXT_REGION_NON_RESERVED < cacheRegion
Cache_Reservation Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_CACHE_RESERVATION_EXT_VERSION_* ENUMs.
Cache Reservation Region.
Values:
[DEPRECATED] utilize driver default scheme. Use ZE_CACHE_EXT_REGION_DEFAULT.
[DEPRECATED] utilize reserved region. Use ZE_CACHE_EXT_REGION_RESERVED.
[DEPRECATED] utilize non-reserverd region. Use ZE_CACHE_EXT_REGION_NON_RESERVED.
utilize driver default scheme
utilize reserved region
utilize non-reserverd region
Value marking end of ZE_CACHE_EXT_REGION_* ENUMs.
CacheReservation structure.
This structure must be passed to zeDeviceGetCacheProperties via the pNext member of ze_device_cache_properties_t
Used for determining the max cache reservation allowed on device. Size of zero means no reservation available.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] max cache reservation size
Functions
Enumerations
Query event timestamps for a device or sub-device.
The application may call this function from simultaneous threads.
The implementation of this function must be thread-safe.
The implementation must support ::ZE_experimental_event_query_timestamps.
The implementation must return all timestamps for the specified event and device pair.
The implementation must return all timestamps for all sub-devices when device handle is parent device.
The implementation may return all timestamps for sub-devices when device handle is sub-device or may return 0 for count.
hEvent – [in] handle of the event
hDevice – [in] handle of the device to query
pCount – [in,out] pointer to the number of timestamp results. if count is zero, then the driver shall update the value with the total number of timestamps available. if count is greater than the number of timestamps available, then the driver shall update the value with the correct number of timestamps available.
pTimestamps – [in,out][optional][range(0, *pCount)] array of timestamp results. if count is less than the number of timestamps available, then driver shall only retrieve that number of timestamps.
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hEvent
nullptr == hDevice
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pCount
Event Query Timestamps Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_EVENT_QUERY_TIMESTAMPS_EXP_VERSION_* ENUMs.
Functions
Enumerations
Structures
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_experimental_image_memory_properties extension.
hImage – [in] handle of image object
pMemoryProperties – [in,out] query result for image memory properties.
Image Memory Properties Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_IMAGE_MEMORY_PROPERTIES_EXP_VERSION_* ENUMs.
Image memory properties.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] size of image allocation in bytes.
[out] size of image row in bytes.
[out] size of image slice in bytes.
Functions
Enumerations
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_extension_image_view 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.
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
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
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_experimental_image_view 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.
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
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
Image View Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_IMAGE_VIEW_EXT_VERSION_* ENUMs.
Image View Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_IMAGE_VIEW_EXP_VERSION_* ENUMs.
Enumerations
Structures
Image View Planar Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_IMAGE_VIEW_PLANAR_EXT_VERSION_* ENUMs.
Image View Planar Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_IMAGE_VIEW_PLANAR_EXP_VERSION_* ENUMs.
Image view planar descriptor.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] the 0-based plane index (e.g. NV12 is 0 = Y plane, 1 UV plane)
Image view planar descriptor.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[DEPRECATED] no longer supported, use ze_image_view_planar_ext_desc_t instead
Functions
Enumerations
Structures
Provide kernel scheduling hints that may improve performance.
The scheduling hints may improve performance only and are not required for correctness.
If a specified scheduling hint is unsupported it will be silently ignored.
If two conflicting scheduling hints are specified there is no defined behavior; the hints may be ignored or one hint may be chosen arbitrarily.
The application must not call this function from simultaneous threads with the same kernel handle.
The implementation of this function should be lock-free.
hKernel – [in] handle of the kernel object
pHint – [in] pointer to kernel scheduling hint descriptor
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hKernel
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pHint
ZE_RESULT_ERROR_INVALID_ENUMERATION
0x7 < pHint->flags
Kernel Scheduling Hints Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_SCHEDULING_HINTS_EXP_VERSION_* ENUMs.
Values:
Hint that the kernel prefers oldest-first scheduling.
Hint that the kernel prefers round-robin scheduling.
Hint that the kernel prefers stall-based round-robin scheduling.
Value marking end of ZE_SCHEDULING_HINT_EXP_FLAG_* ENUMs.
Device kernel scheduling hint properties queried using zeDeviceGetModuleProperties.
This structure may be returned from zeDeviceGetModuleProperties, via the pNext member of ze_device_module_properties_t.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] Supported kernel scheduling hints. May be 0 (none) or a valid combination of ze_scheduling_hint_exp_flag_t.
Kernel scheduling hint descriptor.
This structure may be passed to zeKernelSchedulingHintExp.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] flags specifying kernel scheduling hints. must be 0 (default) or a valid combination of ze_scheduling_hint_exp_flag_t.
Enumerations
Linkonce ODR Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_LINKONCE_ODR_EXT_VERSION_* ENUMs.
Enumerations
Structures
Power Saving Hint Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_POWER_SAVING_HINT_EXP_VERSION_* ENUMs.
Supported device types.
Values:
Minumum power savings. The device will make no attempt to save power while executing work submitted to this context.
Maximum power savings. The device will do everything to bring power to a minimum while executing work submitted to this context.
Value marking end of ZE_POWER_SAVING_HINT_TYPE_* ENUMs.
Extended context descriptor containing power saving hint.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] power saving hint (default value = 0). This is value from [0,100] and can use pre-defined settings from ze_power_saving_hint_type_t.
Enumerations
Subgroups Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_SUBGROUP_EXT_VERSION_* ENUMs.
Enumerations
Structures
EU Count Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_EU_COUNT_EXT_VERSION_* ENUMs.
EU count queried using zeDeviceGetProperties.
This structure may be returned from zeDeviceGetProperties via the pNext member of ze_device_properties_t.
Used for determining the total number of EUs available on device.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] Total number of EUs available
Functions
Enumerations
Structures
Get PCI properties - address, max speed.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hDevice – [in] handle of the device object.
pPciProperties – [in,out] returns the PCI properties of the device.
PCI Properties Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_PCI_PROPERTIES_EXT_VERSION_* ENUMs.
Device PCI address.
This structure may be passed to zeDevicePciGetPropertiesExt as an attribute of ze_pci_ext_properties_t.
A PCI BDF address is the bus:device:function address of the device and is useful for locating the device in the PCI switch fabric.
Public Members
[out] PCI domain number
[out] PCI BDF bus number
[out] PCI BDF device number
[out] PCI BDF function number
Device PCI speed.
Public Members
[out] The link generation. A value of -1 means that this property is unknown.
[out] The number of lanes. A value of -1 means that this property is unknown.
[out] The theoretical maximum bandwidth in bytes/sec (sum of all lanes). A value of -1 means that this property is unknown.
Static PCI properties.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] The BDF address
[out] Fastest port configuration supported by the device (sum of all lanes)
Enumerations
Structures
sRGB Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_SRGB_EXT_VERSION_* ENUMs.
sRGB image descriptor
This structure may be passed to zeImageCreate via the pNext member of ze_image_desc_t
Used for specifying that the image is in sRGB format.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] Is sRGB.
Functions
Enumerations
Copies from an image to device or shared memory.
The application must ensure the memory pointed to by dstptr is accessible by the device on which the command list was created.
The implementation must not access the memory pointed to by dstptr as it is free to be modified by either the Host or device up until execution.
The application must ensure the image and events are accessible by the device on which the command list was created.
The application must ensure the image format descriptor for the source image is a single-planar format.
The application must ensure that the rowPitch is set to 0 if image is a 1D image. Otherwise the rowPitch must be greater than or equal to the element size in bytes x width.
If rowPitch is set to 0, the appropriate row pitch is calculated based on the size of each element in bytes multiplied by width
The application must ensure that the slicePitch is set to 0 if image is a 1D or 2D image. Otherwise this value must be greater than or equal to rowPitch x height.
If slicePitch is set to 0, the appropriate slice pitch is calculated based on the rowPitch x height.
The application must ensure the command list, image and events were created, and the memory was allocated, on the same context.
The application must not call this function from simultaneous threads with the same command list handle.
The implementation of this function should be lock-free.
hCommandList – [in] handle of command list
dstptr – [in] pointer to destination memory to copy to
hSrcImage – [in] handle of source image to copy from
pSrcRegion – [in][optional] source region descriptor
destRowPitch – [in] size in bytes of the 1D slice of the 2D region of a 2D or 3D image or each image of a 1D or 2D image array being written
destSlicePitch – [in] size in bytes of the 2D slice of the 3D region of a 3D image or each image of a 1D or 2D image array being written
hSignalEvent – [in][optional] handle of the event to signal on completion
numWaitEvents – [in][optional] number of events to wait on before launching; must be 0 if `nullptr == phWaitEvents`
phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hCommandList
nullptr == hSrcImage
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == dstptr
(nullptr == phWaitEvents) && (0 < numWaitEvents)
Copies to an image from device or shared memory.
The application must ensure the memory pointed to by srcptr is accessible by the device on which the command list was created.
The implementation must not access the memory pointed to by srcptr as it is free to be modified by either the Host or device up until execution.
The application must ensure the image and events are accessible by the device on which the command list was created.
The application must ensure the image format descriptor for the destination image is a single-planar format.
The application must ensure that the rowPitch is set to 0 if image is a 1D image. Otherwise the rowPitch must be greater than or equal to the element size in bytes x width.
If rowPitch is set to 0, the appropriate row pitch is calculated based on the size of each element in bytes multiplied by width
The application must ensure that the slicePitch is set to 0 if image is a 1D or 2D image. Otherwise this value must be greater than or equal to rowPitch x height.
If slicePitch is set to 0, the appropriate slice pitch is calculated based on the rowPitch x height.
The application must ensure the command list, image and events were created, and the memory was allocated, on the same context.
The application must not call this function from simultaneous threads with the same command list handle.
The implementation of this function should be lock-free.
hCommandList – [in] handle of command list
hDstImage – [in] handle of destination image to copy to
srcptr – [in] pointer to source memory to copy from
pDstRegion – [in][optional] destination region descriptor
srcRowPitch – [in] size in bytes of the 1D slice of the 2D region of a 2D or 3D image or each image of a 1D or 2D image array being read
srcSlicePitch – [in] size in bytes of the 2D slice of the 3D region of a 3D image or each image of a 1D or 2D image array being read
hSignalEvent – [in][optional] handle of the event to signal on completion
numWaitEvents – [in][optional] number of events to wait on before launching; must be 0 if `nullptr == phWaitEvents`
phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hCommandList
nullptr == hDstImage
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == srcptr
(nullptr == phWaitEvents) && (0 < numWaitEvents)
Image Copy Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_IMAGE_COPY_EXT_VERSION_* ENUMs.
Functions
Enumerations
Structures
Retrieves attributes of an image allocation.
The application may call this function from simultaneous threads.
hContext – [in] handle of the context object
hImage – [in] handle of image object to query
pImageAllocProperties – [in,out] query result for image allocation properties
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hContext
nullptr == hImage
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pImageAllocProperties
Image Query Allocation Properties Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_IMAGE_QUERY_ALLOC_PROPERTIES_EXT_VERSION_* ENUMs.
Image allocation properties queried using zeImageGetAllocPropertiesExt.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] identifier for this allocation
Functions
Enumerations
Structures
List Imports & Exports.
List all the import & unresolveable import dependencies & exports of a set of modules
pInspectDesc – [in] pointer to linkage inspection descriptor structure.
numModules – [in] number of modules to be inspected pointed to by phModules.
phModules – [in][range(0, numModules)] pointer to an array of modules to be inspected for import dependencies.
phLog – [out] pointer to handle of linkage inspection log. Log object will contain separate lists of imports, un-resolvable imports, and exports.
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pInspectDesc
nullptr == phModules
nullptr == phLog
ZE_RESULT_ERROR_INVALID_ENUMERATION
0x7 < pInspectDesc->flags
Linkage Inspection Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_LINKAGE_INSPECTION_EXT_VERSION_* ENUMs.
Values:
List all imports of modules.
List all imports of modules that do not have a corresponding export.
List all exports of modules.
Value marking end of ZE_LINKAGE_INSPECTION_EXT_FLAG_* ENUMs.
Module linkage inspection descriptor.
This structure may be passed to zeModuleInspectLinkageExt.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] flags specifying module linkage inspection. must be 0 (default) or a valid combination of ze_linkage_inspection_ext_flag_t.
Enumerations
Structures
Memory Compression Hints Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_MEMORY_COMPRESSION_HINTS_EXT_VERSION_* ENUMs.
Values:
Hint Driver implementation to make allocation compressible.
Hint Driver implementation to make allocation not compressible.
Value marking end of ZE_MEMORY_COMPRESSION_HINTS_EXT_FLAG_* ENUMs.
Compression hints memory allocation descriptor.
This structure may be passed to zeMemAllocShared or zeMemAllocDevice, via the pNext member of ze_device_mem_alloc_desc_t.
This structure may be passed to zeMemAllocHost, via the pNext member of ze_host_mem_alloc_desc_t.
This structure may be passed to zeImageCreate, via the pNext member of ze_image_desc_t.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] flags specifying if allocation should be compressible or not. Must be set to one of the ze_memory_compression_hints_ext_flag_t;
Functions
Enumerations
Structures
Frees allocated host memory, device memory, or shared memory on the context using the specified free policy.
Similar to zeMemFree, with added parameter to choose the free policy.
Does not gaurantee memory is freed upon return. See free policy descriptions for details.
The application must not call this function from simultaneous threads with the same pointer.
The implementation of this function must be thread-safe.
hContext – [in] handle of the context object
pMemFreeDesc – [in] pointer to memory free descriptor
ptr – [in][release] pointer to memory to free
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hContext
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pMemFreeDesc
nullptr == ptr
ZE_RESULT_ERROR_INVALID_ENUMERATION
0x3 < pMemFreeDesc->freePolicy
Memory Free Policies Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_MEMORY_FREE_POLICIES_EXT_VERSION_* ENUMs.
Values:
Blocks until all commands using the memory are complete before scheduling memory to be freed. Does not guarantee memory is freed upon return, only that it is safe and is scheduled to be freed. Actual freeing of memory is specific to user mode driver and kernel mode driver implementation and may be done asynchronously.
Immediately schedules the memory to be freed and returns without blocking. Memory may be freed after all commands using the memory are complete. Actual freeing of memory is specific to user mode driver and kernel mode driver implementation and may be done asynchronously.
Value marking end of ZE_DRIVER_MEMORY_FREE_POLICY_EXT_FLAG_* ENUMs.
Driver memory free properties queried using zeDriverGetProperties.
All drivers must support an immediate free policy, which is the default free policy.
This structure may be returned from zeDriverGetProperties, via the pNext member of ze_driver_properties_t.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] Supported memory free policies. must be 0 or a combination of ze_driver_memory_free_policy_ext_flag_t.
Memory free descriptor with free policy.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] flags specifying the memory free policy. must be 0 (default) or a supported ze_driver_memory_free_policy_ext_flag_t; default behavior is to free immediately.
Structures
P2P Bandwidth Properties.
This structure may be passed to zeDeviceGetP2PProperties by having the pNext member of ze_device_p2p_properties_t point at this struct.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] total logical design bandwidth for all links connecting the two devices
[out] total physical design bandwidth for all links connecting the two devices
[out] bandwidth unit
[out] average logical design latency for all links connecting the two devices
[out] average physical design latency for all links connecting the two devices
[out] latency unit
Copy Bandwidth Properties.
This structure may be passed to zeDeviceGetCommandQueueGroupProperties by having the pNext member of ze_command_queue_group_properties_t point at this struct.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] design bandwidth supported by this engine type for copy operations
[out] copy bandwidth unit
Enumerations
Structures
Device Local Identifier (LUID) Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_DEVICE_LUID_EXT_VERSION_* ENUMs.
Device local identifier (LUID)
Public Members
[out] opaque data representing a device LUID
Device LUID properties queried using zeDeviceGetProperties.
This structure may be returned from zeDeviceGetProperties, via the pNext member of ze_device_properties_t.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] locally unique identifier (LUID). The returned LUID can be cast to a LUID object and must be equal to the locally unique identifier of an IDXGIAdapter1 object that corresponds to the device.
[out] node mask. The returned node mask must contain exactly one bit. If the device is running on an operating system that supports the Direct3D 12 API and the device corresponds to an individual device in a linked device adapter, the returned node mask identifies the Direct3D 12 node corresponding to the device. Otherwise, the returned node mask must be 1.
Functions
Enumerations
Structures
Retrieves fabric vertices within a driver.
A fabric vertex represents either a device or a switch connected to other fabric vertices.
The application may call this function from simultaneous threads.
The implementation of this function must be thread-safe.
hDriver – [in] handle of the driver instance
pCount – [in,out] pointer to the number of fabric vertices. if count is zero, then the driver shall update the value with the total number of fabric vertices available. if count is greater than the number of fabric vertices available, then the driver shall update the value with the correct number of fabric vertices available.
phVertices – [in,out][optional][range(0, *pCount)] array of handle of fabric vertices. if count is less than the number of fabric vertices available, then driver shall only retrieve that number of fabric vertices.
Retrieves a fabric sub-vertex from a fabric vertex.
Multiple calls to this function will return identical fabric vertex handles, in the same order.
The number of handles returned from this function is affected by the ::ZE_AFFINITY_MASK environment variable.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hVertex – [in] handle of the fabric vertex object
pCount – [in,out] pointer to the number of sub-vertices. if count is zero, then the driver shall update the value with the total number of sub-vertices available. if count is greater than the number of sub-vertices available, then the driver shall update the value with the correct number of sub-vertices available.
phSubvertices – [in,out][optional][range(0, *pCount)] array of handle of sub-vertices. if count is less than the number of sub-vertices available, then driver shall only retrieve that number of sub-vertices.
Retrieves properties of the fabric vertex.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hVertex – [in] handle of the fabric vertex
pVertexProperties – [in,out] query result for fabric vertex properties
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hVertex
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pVertexProperties
Returns device handle from fabric vertex handle.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hVertex – [in] handle of the fabric vertex
phDevice – [out] device handle corresponding to fabric vertex
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hVertex
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == phDevice
ZE_RESULT_EXP_ERROR_VERTEX_IS_NOT_DEVICE
Provided fabric vertex handle does not correspond to a device or subdevice.
ZE_RESULT_EXP_ERROR_REMOTE_DEVICE
Provided fabric vertex handle corresponds to remote device or subdevice.
Returns fabric vertex handle from device handle.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hDevice – [in] handle of the device
phVertex – [out] fabric vertex handle corresponding to device
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hDevice
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == phVertex
ZE_RESULT_EXP_ERROR_DEVICE_IS_NOT_VERTEX
Provided device handle does not correspond to a fabric vertex.
Retrieves all fabric edges between provided pair of fabric vertices.
A fabric edge represents one or more physical links between two fabric vertices.
The application may call this function from simultaneous threads.
The implementation of this function must be thread-safe.
hVertexA – [in] handle of first fabric vertex instance
hVertexB – [in] handle of second fabric vertex instance
pCount – [in,out] pointer to the number of fabric edges. if count is zero, then the driver shall update the value with the total number of fabric edges available. if count is greater than the number of fabric edges available, then the driver shall update the value with the correct number of fabric edges available.
phEdges – [in,out][optional][range(0, *pCount)] array of handle of fabric edges. if count is less than the number of fabric edges available, then driver shall only retrieve that number of fabric edges.
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hVertexA
nullptr == hVertexB
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pCount
Retrieves fabric vertices connected by a fabric edge.
A fabric vertex represents either a device or a switch connected to other fabric vertices via a fabric edge.
The application may call this function from simultaneous threads.
The implementation of this function must be thread-safe.
hEdge – [in] handle of the fabric edge instance
phVertexA – [out] fabric vertex connected to one end of the given fabric edge.
phVertexB – [out] fabric vertex connected to other end of the given fabric edge.
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hEdge
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == phVertexA
nullptr == phVertexB
Retrieves properties of the fabric edge.
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hEdge – [in] handle of the fabric edge
pEdgeProperties – [in,out] query result for fabric edge properties
Fabric Vertex types.
Values:
Fabric vertex type is unknown.
Fabric vertex represents a device.
Fabric vertex represents a subdevice.
Fabric vertex represents a switch.
Value marking end of ZE_FABRIC_VERTEX_EXP_TYPE_* ENUMs.
Fabric edge duplexity.
Values:
Fabric edge duplexity is unknown.
Fabric edge is half duplex, i.e. stated bandwidth is obtained in only one direction at time
Fabric edge is full duplex, i.e. stated bandwidth is supported in both directions simultaneously
Value marking end of ZE_FABRIC_EDGE_EXP_DUPLEXITY_* ENUMs.
PCI address.
A PCI BDF address is the bus:device:function address of the device and is useful for locating the device in the PCI switch fabric.
Public Members
[out] PCI domain number
[out] PCI BDF bus number
[out] PCI BDF device number
[out] PCI BDF function number
Fabric Vertex properties.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] universal unique identifier. If the vertex is co-located with a device/subdevice, then this uuid will match that of the corresponding device/subdevice
[out] does the fabric vertex represent a device, subdevice, or switch?
[out] does the fabric vertex live on the local node or on a remote node?
[out] B/D/F address of fabric vertex & associated device/subdevice if available
Fabric Edge properties.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] universal unique identifier.
[out] Description of fabric edge technology. Will be set to the string “unkown” if this cannot be determined for this edge
[out] design bandwidth
[out] bandwidth unit
[out] design latency
[out] latency unit
[out] Duplexity of the fabric edge
Enumerations
Structures
Device Memory Properties Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_DEVICE_MEMORY_PROPERTIES_EXT_VERSION_* ENUMs.
Memory module types.
Values:
HBM memory.
HBM2 memory.
DDR memory.
DDR2 memory.
DDR3 memory.
DDR4 memory.
DDR5 memory.
LPDDR memory.
LPDDR3 memory.
LPDDR4 memory.
LPDDR5 memory.
SRAM memory.
L1 cache.
L3 cache.
Execution unit register file.
Execution unit shared local memory.
GDDR4 memory.
GDDR5 memory.
GDDR5X memory.
GDDR6 memory.
GDDR6X memory.
GDDR7 memory.
Value marking end of ZE_DEVICE_MEMORY_EXT_TYPE_* ENUMs.
Memory properties.
This structure may be returned from zeDeviceGetMemoryProperties via the pNext member of ze_device_memory_properties_t
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] The memory type
[out] Physical memory size in bytes. A value of 0 indicates that this property is not known. However, a call to zesMemoryGetState() will correctly return the total size of usable memory.
[out] Design bandwidth for reads
[out] Design bandwidth for writes
[out] bandwidth unit
Enumerations
Bfloat16 Conversions Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_BFLOAT16_CONVERSIONS_EXT_VERSION_* ENUMs.
Enumerations
Structures
Device IP Version Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_DEVICE_IP_VERSION_VERSION_* ENUMs.
Device IP version queried using zeDeviceGetProperties.
This structure may be returned from zeDeviceGetProperties via the pNext member of ze_device_properties_t
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] Device IP version. The meaning of the device IP version is implementation-defined, but newer devices should have a higher version than older devices.
Enumerations
Structures
Kernel Max Group Size Properties Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_KERNEL_MAX_GROUP_SIZE_PROPERTIES_EXT_VERSION_* ENUMs.
Additional kernel max group size properties.
This structure may be passed to zeKernelGetProperties, via the pNext member of ze_kernel_properties_t, to query additional kernel max group size properties.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] maximum group size that can be used to execute the kernel. This value may be less than or equal to the maxTotalGroupSize member of ze_device_compute_properties_t.
Enumerations
Structures
Sub-Allocations Properties Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_SUB_ALLOCATIONS_EXP_VERSION_* ENUMs.
Properties returned for a sub-allocation.
Public Members
[in,out][optional] base address of the sub-allocation
[in,out][optional] size of the allocation
Sub-Allocations Properties.
This structure may be passed to zeMemGetAllocProperties, via the pNext member of ze_memory_allocation_properties_t.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in,out] pointer to the number of sub-allocations. if count is zero, then the driver shall update the value with the total number of sub-allocations on which the allocation has been divided. if count is greater than the number of sub-allocations, then the driver shall update the value with the correct number of sub-allocations.
[in,out][optional][range(0, *pCount)] array of properties for sub-allocations. if count is less than the number of sub-allocations available, then driver shall only retrieve properties for that number of sub-allocations.
Functions
Enumerations
Structures
Query an event’s timestamp value on the host, with domain preference.
For collecting only kernel timestamps, the application must ensure the event was created from an event pool that was created using ZE_EVENT_POOL_FLAG_KERNEL_TIMESTAMP flag.
For collecting synchronized timestamps, the application must ensure the event was created from an event pool that was created using ZE_EVENT_POOL_FLAG_KERNEL_MAPPED_TIMESTAMP flag. Kernel timestamps are also available from this type of event pool, but there is a performance cost.
The destination memory will be unmodified if the event has not been signaled.
The application may call this function from simultaneous threads.
The implementation of this function must be thread-safe.
The implementation must support ::ZE_extension_event_query_kernel_timestamps.
The implementation must return all timestamps for the specified event and device pair.
The implementation must return all timestamps for all sub-devices when device handle is parent device.
The implementation may return all timestamps for sub-devices when device handle is sub-device or may return 0 for count.
hEvent – [in] handle of the event
hDevice – [in] handle of the device to query
pCount – [in,out] pointer to the number of event packets available.
This value is implementation specific.
if `*pCount` is zero, then the driver shall update the value with the total number of event packets available.
if `*pCount` is greater than the number of event packets available, the driver shall update the value with the correct value.
Buffer(s) for query results must be sized by the application to accommodate a minimum of `*pCount` elements.
pResults – [in,out][optional][range(0, *pCount)] pointer to event query properties structure(s).
This parameter may be null when `*pCount` is zero.
if `*pCount` is less than the number of event packets available, the driver may only update `*pCount` elements, starting at element zero.
if `*pCount` is greater than the number of event packets available, the driver may only update the valid elements.
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hEvent
nullptr == hDevice
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pCount
Event Query Kernel Timestamps Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_EVENT_QUERY_KERNEL_TIMESTAMPS_EXT_VERSION_* ENUMs.
Values:
Kernel timestamp results.
Device event timestamps synchronized to the host time domain.
Value marking end of ZE_EVENT_QUERY_KERNEL_TIMESTAMPS_EXT_FLAG_* ENUMs.
Event query kernel timestamps properties.
This structure may be returned from zeDeviceGetProperties, via the pNext member of ze_device_properties_t.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] 0 or some combination of ze_event_query_kernel_timestamps_ext_flag_t flags
Kernel timestamp clock data synchronized to the host time domain.
Public Members
[out] synchronized clock at start of kernel execution
[out] synchronized clock at end of kernel execution
Synchronized kernel timestamp result.
Event query kernel timestamps results properties.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in,out][optional][range(0, *pCount)] pointer to destination buffer of kernel timestamp results
[in,out][optional][range(0, *pCount)] pointer to destination buffer of synchronized timestamp results
Functions
Enumerations
Structures
Creates a ray tracing acceleration structure builder object.
The application may call this function from simultaneous threads.
The implementation of this function must be thread-safe.
The implementation must support ::ZE_experimental_rtas_builder extension.
hDriver – [in] handle of driver object
pDescriptor – [in] pointer to builder descriptor
phBuilder – [out] handle of builder object
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hDriver
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pDescriptor
nullptr == phBuilder
ZE_RESULT_ERROR_INVALID_ENUMERATION
ZE_RTAS_BUILDER_EXP_VERSION_CURRENT < pDescriptor->builderVersion
Retrieves ray tracing acceleration structure builder properties.
The application may call this function from simultaneous threads.
The implementation of this function must be thread-safe.
hBuilder – [in] handle of builder object
pBuildOpDescriptor – [in] pointer to build operation descriptor
pProperties – [in,out] query result for builder properties
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hBuilder
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pBuildOpDescriptor
nullptr == pProperties
ZE_RESULT_ERROR_INVALID_ENUMERATION
ZE_RTAS_FORMAT_EXP_MAX < pBuildOpDescriptor->rtasFormat
ZE_RTAS_BUILDER_BUILD_QUALITY_HINT_EXP_HIGH < pBuildOpDescriptor->buildQuality
0x3 < pBuildOpDescriptor->buildFlags
Checks ray tracing acceleration structure format compatibility.
The application may call this function from simultaneous threads.
The implementation of this function must be thread-safe.
hDriver – [in] handle of driver object
rtasFormatA – [in] operand A
rtasFormatB – [in] operand B
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hDriver
ZE_RESULT_ERROR_INVALID_ENUMERATION
ZE_RTAS_FORMAT_EXP_MAX < rtasFormatA
ZE_RTAS_FORMAT_EXP_MAX < rtasFormatB
An acceleration structure built with rtasFormatA is compatible with devices that report rtasFormatB.
ZE_RESULT_EXP_ERROR_OPERANDS_INCOMPATIBLE
An acceleration structure built with rtasFormatA is not compatible with devices that report rtasFormatB.
Build ray tracing acceleration structure.
This function builds an acceleration structure of the scene consisting of the specified geometry information and writes the acceleration structure to the provided destination buffer. All types of geometries can get freely mixed inside a scene.
It is the user’s responsibility to manage the acceleration structure buffer allocation, de-allocation, and potential prefetching to the device memory. The required size of the acceleration structure buffer can be queried with the zeRTASBuilderGetBuildPropertiesExp function. The acceleration structure buffer must be a shared USM allocation and should be present on the host at build time. The referenced scene data (index- and vertex- buffers) can be standard host allocations, and will not be referenced into by the build acceleration structure.
Before an acceleration structure can be built, the user must allocate the memory for the acceleration structure buffer and scratch buffer using sizes based on a query for the estimated size properties.
When using the “worst-case” size for the acceleration structure buffer, the acceleration structure construction will never fail with ZE_RESULT_EXP_RTAS_BUILD_RETRY.
When using the “expected” size for the acceleration structure buffer, the acceleration structure construction may fail with ZE_RESULT_EXP_RTAS_BUILD_RETRY. If this happens, the user may resize their acceleration structure buffer using the returned *pRtasBufferSizeBytes value, which will be updated with an improved size estimate that will likely result in a successful build.
The acceleration structure construction is run on the host and is synchronous, thus after the function returns with a successful result, the acceleration structure may be used.
All provided data buffers must be host-accessible.
The acceleration structure buffer must be a USM allocation.
A successfully constructed acceleration structure is entirely self-contained. There is no requirement for input data to persist beyond build completion.
A successfully constructed acceleration structure is non-copyable.
Acceleration structure construction may be parallelized by passing a valid handle to a parallel operation object and joining that parallel operation using zeRTASParallelOperationJoinExp with user-provided worker threads.
Additional Notes
”The geometry infos array, geometry infos, and scratch buffer must
all be standard host memory allocations.”
”A pointer to a geometry info can be a null pointer, in which case
the geometry is treated as empty.”
”If no parallel operation handle is provided, the build is run
sequentially on the current thread.”
”A parallel operation object may only be associated with a single
acceleration structure build at a time.”
hBuilder – [in] handle of builder object
pBuildOpDescriptor – [in] pointer to build operation descriptor
pScratchBuffer – [in][range(0, `scratchBufferSizeBytes`)] scratch buffer to be used during acceleration structure construction
scratchBufferSizeBytes – [in] size of scratch buffer, in bytes
pRtasBuffer – [in] pointer to destination buffer
rtasBufferSizeBytes – [in] destination buffer size, in bytes
hParallelOperation – [in][optional] handle to parallel operation object
pBuildUserPtr – [in][optional] pointer passed to callbacks
pBounds – [in,out][optional] pointer to destination address for acceleration structure bounds
pRtasBufferSizeBytes – [out][optional] updated acceleration structure size requirement, in bytes
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hBuilder
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pBuildOpDescriptor
nullptr == pScratchBuffer
nullptr == pRtasBuffer
ZE_RESULT_ERROR_INVALID_ENUMERATION
ZE_RTAS_FORMAT_EXP_MAX < pBuildOpDescriptor->rtasFormat
ZE_RTAS_BUILDER_BUILD_QUALITY_HINT_EXP_HIGH < pBuildOpDescriptor->buildQuality
0x3 < pBuildOpDescriptor->buildFlags
ZE_RESULT_EXP_RTAS_BUILD_DEFERRED
Acceleration structure build completion is deferred to parallel operation join.
ZE_RESULT_EXP_RTAS_BUILD_RETRY
Acceleration structure build failed due to insufficient resources, retry the build operation with a larger acceleration structure buffer allocation.
ZE_RESULT_ERROR_HANDLE_OBJECT_IN_USE
Acceleration structure build failed due to parallel operation object participation in another build operation.
Destroys a ray tracing acceleration structure builder object.
The implementation of this function may immediately release any internal Host and Device resources associated with this builder.
The application must not call this function from simultaneous threads with the same builder handle.
The implementation of this function must be thread-safe.
hBuilder – [in][release] handle of builder object to destroy
Creates a ray tracing acceleration structure builder parallel operation object.
The application may call this function from simultaneous threads.
The implementation of this function must be thread-safe.
The implementation must support ::ZE_experimental_rtas_builder extension.
hDriver – [in] handle of driver object
phParallelOperation – [out] handle of parallel operation object
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hDriver
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == phParallelOperation
Retrieves ray tracing acceleration structure builder parallel operation properties.
The application must first bind the parallel operation object to a build operation before it may query the parallel operation properties. In other words, the application must first call zeRTASBuilderBuildExp with hParallelOperation before calling this function.
The application may call this function from simultaneous threads.
The implementation of this function must be thread-safe.
hParallelOperation – [in] handle of parallel operation object
pProperties – [in,out] query result for parallel operation properties
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hParallelOperation
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pProperties
Joins a parallel build operation.
All worker threads return the same error code for the parallel build operation upon build completion
hParallelOperation – [in] handle of parallel operation object
Destroys a ray tracing acceleration structure builder parallel operation object.
The implementation of this function may immediately release any internal Host and Device resources associated with this parallel operation.
The application must not call this function from simultaneous threads with the same parallel operation handle.
The implementation of this function must be thread-safe.
hParallelOperation – [in][release] handle of parallel operation object to destroy
Ray Tracing Acceleration Structure Builder Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_RTAS_BUILDER_EXP_VERSION_* ENUMs.
Values:
reserved for future use
Value marking end of ZE_RTAS_DEVICE_EXP_FLAG_* ENUMs.
Ray tracing acceleration structure format.
This is an opaque ray tracing acceleration structure format identifier.
Values:
Invalid acceleration structure format.
Maximum acceleration structure format code.
Value marking end of ZE_RTAS_FORMAT_EXP_* ENUMs.
Values:
Reserved for future use.
Value marking end of ZE_RTAS_BUILDER_EXP_FLAG_* ENUMs.
Values:
Reserved for future use.
Value marking end of ZE_RTAS_PARALLEL_OPERATION_EXP_FLAG_* ENUMs.
Values:
non-opaque geometries invoke an any-hit shader
Value marking end of ZE_RTAS_BUILDER_GEOMETRY_EXP_FLAG_* ENUMs.
Values:
disables culling of front-facing and back-facing triangles
reverses front and back face of triangles
forces instanced geometry to be opaque, unless ray flag forces it to be non-opaque
forces instanced geometry to be non-opaque, unless ray flag forces it to be opaque
Value marking end of ZE_RTAS_BUILDER_INSTANCE_EXP_FLAG_* ENUMs.
Values:
build more compact acceleration structure
guarantees single any-hit shader invocation per primitive
Value marking end of ZE_RTAS_BUILDER_BUILD_OP_EXP_FLAG_* ENUMs.
Ray tracing acceleration structure builder build quality hint.
Depending on use case different quality modes for acceleration structure build are supported.
A low-quality build builds an acceleration structure fast, but at the cost of some reduction in ray tracing performance. This mode is recommended for dynamic content, such as animated characters.
A medium-quality build uses a compromise between build quality and ray tracing performance. This mode should be used by default.
Higher ray tracing performance can be achieved by using a high-quality build, but acceleration structure build performance might be significantly reduced.
Values:
build low-quality acceleration structure (fast)
build medium-quality acceleration structure (slower)
build high-quality acceleration structure (slow)
Value marking end of ZE_RTAS_BUILDER_BUILD_QUALITY_HINT_EXP_* ENUMs.
Ray tracing acceleration structure builder geometry type.
Values:
triangle mesh geometry type
quad mesh geometry type
procedural geometry type
instance geometry type
Value marking end of ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXP_* ENUMs.
Ray tracing acceleration structure data buffer element format.
Specifies the format of data buffer elements.
Data buffers may contain instancing transform matrices, triangle/quad vertex indices, etc…
Values:
3-component float vector (see ze_rtas_float3_exp_t)
3x4 affine transformation in column-major format (see ze_rtas_transform_float3x4_column_major_exp_t)
3x4 affine transformation in column-major format (see ze_rtas_transform_float3x4_aligned_column_major_exp_t)
3x4 affine transformation in row-major format (see ze_rtas_transform_float3x4_row_major_exp_t)
3-dimensional axis-aligned bounding-box (see ze_rtas_aabb_exp_t)
Unsigned 32-bit triangle indices (see ze_rtas_triangle_indices_uint32_exp_t)
Unsigned 32-bit quad indices (see ze_rtas_quad_indices_uint32_exp_t)
Value marking end of ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXP_* ENUMs.
Ray tracing acceleration structure builder descriptor.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] ray tracing acceleration structure builder version
Ray tracing acceleration structure builder properties.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] ray tracing acceleration structure builder flags
[out] expected size (in bytes) required for acceleration structure buffer
When using an acceleration structure buffer of this size, the build is expected to succeed; however, it is possible that the build may fail with ZE_RESULT_EXP_RTAS_BUILD_RETRY
[out] worst-case size (in bytes) required for acceleration structure buffer
When using an acceleration structure buffer of this size, the build is guaranteed to not run out of memory.
[out] scratch buffer size (in bytes) required for acceleration structure build.
Ray tracing acceleration structure builder parallel operation properties.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] ray tracing acceleration structure builder parallel operation flags
[out] maximum number of threads that may join the parallel operation
Ray tracing acceleration structure device properties.
This structure may be passed to zeDeviceGetProperties, via pNext member of ze_device_properties_t.
The implementation shall populate format with a value other than ZE_RTAS_FORMAT_EXP_INVALID when the device supports ray tracing.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] ray tracing acceleration structure device flags
[out] ray tracing acceleration structure format
[out] required alignment of acceleration structure buffer
A 3-component vector type.
Public Members
[in] x-coordinate of float3 vector
[in] y-coordinate of float3 vector
[in] z-coordinate of float3 vector
3x4 affine transformation in column-major layout
A 3x4 affine transformation in column major layout, consisting of vectors
vx=(vx_x, vx_y, vx_z),
vy=(vy_x, vy_y, vy_z),
vz=(vz_x, vz_y, vz_z), and
p=(p_x, p_y, p_z)
The transformation transforms a point (x, y, z) to: x*vx + y*vy + z*vz + p.
Public Members
[in] element 0 of column 0 of 3x4 matrix
[in] element 1 of column 0 of 3x4 matrix
[in] element 2 of column 0 of 3x4 matrix
[in] element 0 of column 1 of 3x4 matrix
[in] element 1 of column 1 of 3x4 matrix
[in] element 2 of column 1 of 3x4 matrix
[in] element 0 of column 2 of 3x4 matrix
[in] element 1 of column 2 of 3x4 matrix
[in] element 2 of column 2 of 3x4 matrix
[in] element 0 of column 3 of 3x4 matrix
[in] element 1 of column 3 of 3x4 matrix
[in] element 2 of column 3 of 3x4 matrix
3x4 affine transformation in column-major layout with aligned column vectors
A 3x4 affine transformation in column major layout, consisting of vectors
vx=(vx_x, vx_y, vx_z),
vy=(vy_x, vy_y, vy_z),
vz=(vz_x, vz_y, vz_z), and
p=(p_x, p_y, p_z)
The transformation transforms a point (x, y, z) to: x*vx + y*vy + z*vz + p.
The column vectors are aligned to 16-bytes and pad members are ignored.
Public Members
[in] element 0 of column 0 of 3x4 matrix
[in] element 1 of column 0 of 3x4 matrix
[in] element 2 of column 0 of 3x4 matrix
[in] ignored padding
[in] element 0 of column 1 of 3x4 matrix
[in] element 1 of column 1 of 3x4 matrix
[in] element 2 of column 1 of 3x4 matrix
[in] ignored padding
[in] element 0 of column 2 of 3x4 matrix
[in] element 1 of column 2 of 3x4 matrix
[in] element 2 of column 2 of 3x4 matrix
[in] ignored padding
[in] element 0 of column 3 of 3x4 matrix
[in] element 1 of column 3 of 3x4 matrix
[in] element 2 of column 3 of 3x4 matrix
[in] ignored padding
3x4 affine transformation in row-major layout
A 3x4 affine transformation in row-major layout, consisting of vectors
vx=(vx_x, vx_y, vx_z),
vy=(vy_x, vy_y, vy_z),
vz=(vz_x, vz_y, vz_z), and
p=(p_x, p_y, p_z)
The transformation transforms a point (x, y, z) to: x*vx + y*vy + z*vz + p.
Public Members
[in] element 0 of row 0 of 3x4 matrix
[in] element 1 of row 0 of 3x4 matrix
[in] element 2 of row 0 of 3x4 matrix
[in] element 3 of row 0 of 3x4 matrix
[in] element 0 of row 1 of 3x4 matrix
[in] element 1 of row 1 of 3x4 matrix
[in] element 2 of row 1 of 3x4 matrix
[in] element 3 of row 1 of 3x4 matrix
[in] element 0 of row 2 of 3x4 matrix
[in] element 1 of row 2 of 3x4 matrix
[in] element 2 of row 2 of 3x4 matrix
[in] element 3 of row 2 of 3x4 matrix
A 3-dimensional axis-aligned bounding-box with lower and upper bounds in each dimension.
Triangle represented using 3 vertex indices.
Represents a triangle using 3 vertex indices that index into a vertex array that needs to be provided together with the index array.
The linear barycentric u/v parametrization of the triangle is defined as:
(u=0, v=0) at v0,
(u=1, v=0) at v1, and
(u=0, v=1) at v2
Public Members
[in] first index pointing to the first triangle vertex in vertex array
[in] second index pointing to the second triangle vertex in vertex array
[in] third index pointing to the third triangle vertex in vertex array
Quad represented using 4 vertex indices.
Represents a quad composed of 4 indices that index into a vertex array that needs to be provided together with the index array.
A quad is a triangle pair represented using 4 vertex indices v0, v1, v2, v3. The first triangle is made out of indices v0, v1, v3 and the second triangle from indices v2, v3, v1. The piecewise linear barycentric u/v parametrization of the quad is defined as:
(u=0, v=0) at v0,
(u=1, v=0) at v1,
(u=0, v=1) at v3, and
(u=1, v=1) at v2 This is achieved by correcting the u’/v’ coordinates of the second triangle by u = 1-u’ and v = 1-v’, yielding a piecewise linear parametrization.
Public Members
[in] first index pointing to the first quad vertex in vertex array
[in] second index pointing to the second quad vertex in vertex array
[in] third index pointing to the third quad vertex in vertex array
[in] fourth index pointing to the fourth quad vertex in vertex array
Ray tracing acceleration structure builder geometry info.
Public Members
[in] geometry type
Ray tracing acceleration structure builder triangle mesh geometry info.
The linear barycentric u/v parametrization of the triangle is defined as:
(u=0, v=0) at v0,
(u=1, v=0) at v1, and
(u=0, v=1) at v2
Public Members
[in] geometry type, must be ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXP_TRIANGLES
[in] 0 or some combination of ze_rtas_builder_geometry_exp_flag_t bits representing the geometry flags for all primitives of this geometry
[in] 8-bit geometry mask for ray masking
[in] format of triangle buffer data, must be ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXP_TRIANGLE_INDICES_UINT32
[in] format of vertex buffer data, must be ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXP_FLOAT3
[in] number of triangles in triangle buffer
[in] number of vertices in vertex buffer
[in] stride (in bytes) of triangles in triangle buffer
[in] stride (in bytes) of vertices in vertex buffer
[in] pointer to array of triangle indices in specified format
[in] pointer to array of triangle vertices in specified format
Ray tracing acceleration structure builder quad mesh geometry info.
A quad is a triangle pair represented using 4 vertex indices v0, v1, v2, v3. The first triangle is made out of indices v0, v1, v3 and the second triangle from indices v2, v3, v1. The piecewise linear barycentric u/v parametrization of the quad is defined as:
(u=0, v=0) at v0,
(u=1, v=0) at v1,
(u=0, v=1) at v3, and
(u=1, v=1) at v2 This is achieved by correcting the u’/v’ coordinates of the second triangle by u = 1-u’ and v = 1-v’, yielding a piecewise linear parametrization.
Public Members
[in] geometry type, must be ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXP_QUADS
[in] 0 or some combination of ze_rtas_builder_geometry_exp_flag_t bits representing the geometry flags for all primitives of this geometry
[in] 8-bit geometry mask for ray masking
[in] format of quad buffer data, must be ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXP_QUAD_INDICES_UINT32
[in] format of vertex buffer data, must be ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXP_FLOAT3
[in] number of quads in quad buffer
[in] number of vertices in vertex buffer
[in] stride (in bytes) of quads in quad buffer
[in] stride (in bytes) of vertices in vertex buffer
[in] pointer to array of quad indices in specified format
[in] pointer to array of quad vertices in specified format
AABB callback function parameters.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] first primitive to return bounds for
[in] number of primitives to return bounds for
[in] pointer provided through geometry descriptor
[in] pointer provided through zeRTASBuilderBuildExp function
[out] destination buffer to write AABB bounds to
Ray tracing acceleration structure builder procedural primitives geometry info.
A host-side bounds callback function is invoked by the acceleration structure builder to query the bounds of procedural primitives on demand. The callback is passed some pGeomUserPtr that can point to an application-side representation of the procedural primitives. Further, a second pBuildUserPtr, which is set by a parameter to zeRTASBuilderBuildExp, is passed to the callback. This allows the build to change the bounds of the procedural geometry, for example, to build a BVH only over a short time range to implement multi-segment motion blur.
Public Members
[in] geometry type, must be ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXP_PROCEDURAL
[in] 0 or some combination of ze_rtas_builder_geometry_exp_flag_t bits representing the geometry flags for all primitives of this geometry
[in] 8-bit geometry mask for ray masking
[in] reserved for future use
[in] number of primitives in geometry
[in] pointer to callback function to get the axis-aligned bounding-box for a range of primitives
[in] user data pointer passed to callback
Ray tracing acceleration structure builder instance geometry info.
Public Members
[in] geometry type, must be ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXP_INSTANCE
[in] 0 or some combination of ze_rtas_builder_geometry_exp_flag_t bits representing the geometry flags for all primitives of this geometry
[in] 8-bit geometry mask for ray masking
[in] format of the specified transformation
[in] user-specified identifier for the instance
[in] object-to-world instance transformation in specified format
[in] object-space axis-aligned bounding-box of the instanced acceleration structure
[in] pointer to acceleration structure to instantiate
Enumerations
Structures
Counter-based Event Pools Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_EVENT_POOL_COUNTER_BASED_EXP_VERSION_* ENUMs.
Values:
Counter-based event pool is used for immediate command lists (default)
Counter-based event pool is for non-immediate command lists.
Value marking end of ZE_EVENT_POOL_COUNTER_BASED_EXP_FLAG_* ENUMs.
Event pool descriptor for counter-based events. This structure may be passed to zeEventPoolCreate as pNext member of ze_event_pool_desc_t.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] mode flags. must be 0 (default) or a valid value of ze_event_pool_counter_based_exp_flag_t default behavior is counter-based event pool is only used for immediate command lists.
Functions
Enumerations
Structures
Allocate pitched USM memory for images.
Retrieves pitch for 2D image given the width, height and size in bytes
The memory is then allocated using zeMemAllocDevice by providing input size calculated as the returned pitch value multiplied by image height
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_experimental_bindless_image extension.
hContext – [in] handle of the context object
hDevice – [in] handle of the device
imageWidth – [in] imageWidth
imageHeight – [in] imageHeight
elementSizeInBytes – [in] Element size in bytes
rowPitch – [out] rowPitch
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_experimental_bindless_image extension.
hImage – [in] handle of the image
pDeviceOffset – [out] bindless device offset for image
Bindless Image Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_BINDLESS_IMAGE_EXP_VERSION_* ENUMs.
Values:
Bindless images are created with zeImageCreate. The image handle created with this flag is valid on both host and device.
Bindless sampled images are created with zeImageCreate by combining BINDLESS and SAMPLED_IMAGE. Create sampled image view from bindless unsampled image using SAMPLED_IMAGE.
Value marking end of ZE_IMAGE_BINDLESS_EXP_FLAG_* ENUMs.
Image descriptor for bindless images. This structure may be passed to zeImageCreate via pNext member of ze_image_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
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] pointer to pitched device allocation allocated using zeMemAllocDevice
Device specific properties for pitched allocations.
This structure may be passed to zeDeviceGetImageProperties via the pNext member of ze_device_image_properties_t.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] Maximum image linear width.
[out] Maximum image linear height.
Functions
Enumerations
Creates a command list as the clone of another command list.
The source command list must be created with the ZE_COMMAND_LIST_FLAG_EXP_CLONEABLE flag.
The source command list must be closed prior to cloning.
The source command list may be cloned while it is running on the device.
The cloned command list inherits all properties of the source command list.
The cloned command list must be destroyed prior to the source command list.
The application must only use the command list 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.
hCommandList – [in] handle to source command list (the command list to clone)
phClonedCommandList – [out] pointer to handle of the cloned command list
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hCommandList
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == phClonedCommandList
Command List Clone Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_COMMAND_LIST_CLONE_EXP_VERSION_* ENUMs.
Functions
Enumerations
Appends command lists to dispatch from an immediate command list.
The application must call this function only with command lists created with zeCommandListCreateImmediate.
The command lists passed to this function in the phCommandLists argument must be regular command lists (i.e. not immediate command lists).
The application may call this function from simultaneous threads.
The implementation of this function should be lock-free.
hCommandListImmediate – [in] handle of the immediate command list
numCommandLists – [in] number of command lists
phCommandLists – [in][range(0, numCommandLists)] handles of command lists
hSignalEvent – [in][optional] handle of the event to signal on completion
if not null, this event is signaled after the completion of all appended command lists
numWaitEvents – [in][optional] number of events to wait on before executing appended command lists; must be 0 if nullptr == phWaitEvents
phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before executing appended command lists.
if not null, all wait events must be satisfied prior to the start of any appended command list(s)
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hCommandListImmediate
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == phCommandLists
Immediate Command List Append Extension Version(s)
Values:
version 1.0
latest known version
Value marking end of ZE_IMMEDIATE_COMMAND_LIST_APPEND_EXP_VERSION_* ENUMs.
Functions
Enumerations
Structures
Returns a unique command identifier for the next command to be appended to a command list.
This function may only be called for a mutable command list.
This function may not be called on a closed command list.
This function may be called from simultaneous threads with the same command list handle.
The implementation of this function should be lock-free.
hCommandList – [in] handle of the command list
desc – [in] pointer to mutable command identifier descriptor
pCommandId – [out] pointer to mutable command identifier to be written
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hCommandList
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == desc
nullptr == pCommandId
ZE_RESULT_ERROR_INVALID_ENUMERATION
0xff < desc->flags
Returns a unique command identifier for the next command to be appended to a command list. Provides possible kernel handles for kernel mutation when ZE_MUTABLE_COMMAND_EXP_FLAG_KERNEL_INSTRUCTION flag is present.
This function may only be called for a mutable command list.
This function may not be called on a closed command list.
This function may be called from simultaneous threads with the same command list handle.
The implementation of this function should be lock-free.
hCommandList – [in] handle of the command list
desc – [in][out] pointer to mutable command identifier descriptor
numKernels – [in][optional] number of entries on phKernels list
phKernels – [in][optional][range(0, numKernels)] list of kernels that user can switch between using zeCommandListUpdateMutableCommandKernelsExp call
pCommandId – [out] pointer to mutable command identifier to be written
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hCommandList
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == desc
nullptr == pCommandId
ZE_RESULT_ERROR_INVALID_ENUMERATION
0xff < desc->flags
Updates mutable commands.
This function may only be called for a mutable command list.
The application must synchronize mutable command list execution before calling this function.
The application must close a mutable command list after completing all updates.
This function must not be called from simultaneous threads with the same command list handle.
The implementation of this function should be lock-free.
hCommandList – [in] handle of the command list
desc – [in] pointer to mutable commands descriptor; multiple descriptors may be chained via `pNext` member
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hCommandList
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == desc
ZE_RESULT_ERROR_INVALID_ARGUMENT
Invalid kernel argument or not matching update descriptor provided
Updates the signal event for a mutable command in a mutable command list.
This function may only be called for a mutable command list.
The type, scope and flags of the signal event must match those of the source command.
The application must synchronize mutable command list execution before calling this function.
The application must close a mutable command list after completing all updates.
This function must not be called from simultaneous threads with the same command list handle.
The implementation of this function should be lock-free.
hCommandList – [in] handle of the command list
commandId – [in] command identifier
hSignalEvent – [in][optional] handle of the event to signal on completion
Updates the wait events for a mutable command in a mutable command list.
This function may only be called for a mutable command list.
The number of wait events must match that of the source command.
The type, scope and flags of the wait events must match those of the source command.
Passing nullptr as the wait events will update the command to not wait on any events prior to dispatch.
Passing nullptr as an event on event wait list will remove event dependency from this wait list slot.
The application must synchronize mutable command list execution before calling this function.
The application must close a mutable command list after completing all updates.
This function must not be called from simultaneous threads with the same command list handle.
The implementation of this function should be lock-free.
hCommandList – [in] handle of the command list
commandId – [in] command identifier
numWaitEvents – [in][optional] the number of wait events
phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hCommandList
The numWaitEvents parameter does not match that of the original command.
Updates the kernel for a mutable command in a mutable command list.
This function may only be called for a mutable command list.
The kernel handle must be from the provided list for given command id.
The application must synchronize mutable command list execution before calling this function.
The application must close a mutable command list after completing all updates.
This function must not be called from simultaneous threads with the same command list handle.
This function must be called before updating kernel arguments and dispatch parameters, when kernel is mutated.
The implementation of this function should be lock-free.
hCommandList – [in] handle of the command list
numKernels – [in] the number of kernels to update
pCommandId – [in][range(0, numKernels)] command identifier
phKernels – [in][range(0, numKernels)] handle of the kernel for a command identifier to switch to
ZE_RESULT_ERROR_INVALID_NULL_HANDLE
nullptr == hCommandList
ZE_RESULT_ERROR_INVALID_NULL_POINTER
nullptr == pCommandId
nullptr == phKernels
ZE_RESULT_ERROR_INVALID_KERNEL_HANDLE
Invalid kernel handle provided for the mutation kernel instruction operation.
Mutable Command List Extension Version(s)
Values:
version 1.0
version 1.1
latest known version
Value marking end of ZE_MUTABLE_COMMAND_LIST_EXP_VERSION_* ENUMs.
Values:
kernel arguments
kernel group count
kernel group size
kernel global offset
command signal event
command wait events
command kernel
graph arguments
Value marking end of ZE_MUTABLE_COMMAND_EXP_FLAG_* ENUMs.
Values:
reserved
Value marking end of ZE_MUTABLE_COMMAND_LIST_EXP_FLAG_* ENUMs.
Mutable command identifier descriptor.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] mutable command flags.
must be 0 (default, equivalent to setting all flags bar kernel instruction), or a valid combination of ze_mutable_command_exp_flag_t
in order to include kernel instruction mutation, ZE_MUTABLE_COMMAND_EXP_FLAG_KERNEL_INSTRUCTION must be explictly included
Mutable command list properties.
Public Members
[in] type of this structure
[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[out] mutable command list flags
[out] mutable command flags
Mutable command list descriptor.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] mutable command list flags.
must be 0 (default) or a valid combination of ze_mutable_command_list_exp_flag_t
Mutable commands descriptor.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] must be 0, this field is reserved for future use
Mutable kernel argument descriptor.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] command identifier
[in] kernel argument index
[in] kernel argument size
[in] pointer to kernel argument value
Mutable kernel group count descriptor.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] command identifier
[in] pointer to group count
Mutable kernel group size descriptor.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] command identifier
[in] group size for X dimension to use for the kernel
[in] group size for Y dimension to use for the kernel
[in] group size for Z dimension to use for the kernel
Mutable kernel global offset descriptor.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] command identifier
[in] global offset for X dimension to use for this kernel
[in] global offset for Y dimension to use for this kernel
[in] global offset for Z dimension to use for this kernel
Mutable graph argument descriptor.
Public Members
[in] type of this structure
[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).
[in] command identifier
[in] graph argument index
[in] pointer to graph argument value
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4