Skip to content

Commit

Permalink
[Bindless] Structs & enums for image types and cubemap enablement
Browse files Browse the repository at this point in the history 
Add structs/enums to distinguish between image types that can be represented
equivalently in memory:

 - ur_exp_image_type_desc_t struct to hold the type of an image
 - ur_exp_image_type_t enum to enable distinguishing between image types
   that have the same underlying memory ordering/type

Add structs/enums for cubemap sampling:

 - ur_exp_sampler_cubemap_properties_t struct to enable seamless filtering
   between cubemap faces
 - ur_exp_sampler_cubemap_filter_mode_t enum to enable distinguishing
   between cubemap seamless filtering options

Co-authored-by: Sean Stirling <sean.stirling@codeplay.com>
Co-authored-by: Isaac Ault <isaac.ault@codeplay.com>
Co-authored-by: Przemek Malon <przemek.malon@codeplay.com>
  • Loading branch information
@Seanst98 @isaacault @przemektmalon
3 people committed Oct 23, 2023
1 parent 3653e58 commit 4368c24
Show file tree
Hide file tree
Showing 5 changed files with 367 additions and 40 deletions.
59 changes: 59 additions & 0 deletions include/ur.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -245,6 +245,8 @@ class ur_structure_type_v(IntEnum):
EXP_INTEROP_SEMAPHORE_DESC = 0x2002 ## ::ur_exp_interop_semaphore_desc_t
EXP_FILE_DESCRIPTOR = 0x2003 ## ::ur_exp_file_descriptor_t
EXP_WIN32_HANDLE = 0x2004 ## ::ur_exp_win32_handle_t
EXP_IMAGE_TYPE_DESC = 0x2005 ## ::ur_exp_image_type_desc_t
EXP_SAMPLER_CUBEMAP_PROPERTIES = 0x2006 ## ::ur_exp_sampler_cubemap_properties_t

class ur_structure_type_t(c_int):
def __str__(self):
Expand Down Expand Up @@ -2170,6 +2172,34 @@ def __str__(self):
return hex(self.value)


###############################################################################
## @brief Dictates the image type to distinguish between image types that can be
## represented equivalently in memory.
class ur_exp_image_type_v(IntEnum):
_1D = 0 ## 1D image type
_2D = 1 ## 2D image type
_3D = 2 ## 3D image type
CUBEMAP = 3 ## Cubemap image type
_1D_ARRAY = 4 ## 1D image array type
_2D_ARRAY = 5 ## 2D image array type
CUBEMAP_ARRAY = 6 ## Cubemap array image type

class ur_exp_image_type_t(c_int):
def __str__(self):
return str(ur_exp_image_type_v(self.value))


###############################################################################
## @brief Sampler cubemap seamless filtering mode.
class ur_exp_sampler_cubemap_filter_mode_v(IntEnum):
SEAMLESS = 0 ## Seamless filtering
DISJOINTED = 1 ## Disable seamless filtering

class ur_exp_sampler_cubemap_filter_mode_t(c_int):
def __str__(self):
return str(ur_exp_sampler_cubemap_filter_mode_v(self.value))


###############################################################################
## @brief File descriptor
class ur_exp_file_descriptor_t(Structure):
Expand Down Expand Up @@ -2210,6 +2240,21 @@ class ur_exp_sampler_mip_properties_t(Structure):
("mipFilterMode", ur_sampler_filter_mode_t) ## [in] mipmap filter mode used for filtering between mipmap levels
]

###############################################################################
## @brief Describes cubemap sampler properties
##
## @details
## - Specify these properties in ::urSamplerCreate via ::ur_sampler_desc_t
## as part of a `pNext` chain.
class ur_exp_sampler_cubemap_properties_t(Structure):
_fields_ = [
("stype", ur_structure_type_t), ## [in] type of this structure, must be
## ::UR_STRUCTURE_TYPE_EXP_SAMPLER_CUBEMAP_PROPERTIES
("pNext", c_void_p), ## [in,out][optional] pointer to extension-specific structure
("cubemapFilterMode", ur_exp_sampler_cubemap_filter_mode_t) ## [in] enables or disables seamless cubemap filtering between cubemap
## faces
]

###############################################################################
## @brief Describes an interop memory resource descriptor
class ur_exp_interop_mem_desc_t(Structure):
Expand All @@ -2228,6 +2273,20 @@ class ur_exp_interop_semaphore_desc_t(Structure):
("pNext", c_void_p) ## [in][optional] pointer to extension-specific structure
]

###############################################################################
## @brief Describes image type properties
##
## @details
## - Specify these properties in ::urBindlessImagesImageAllocateExp via
## ::ur_image_desc_t as part of a `pNext` chain.
class ur_exp_image_type_desc_t(Structure):
_fields_ = [
("stype", ur_structure_type_t), ## [in] type of this structure, must be
## ::UR_STRUCTURE_TYPE_EXP_IMAGE_TYPE_DESC
("pNext", c_void_p), ## [in][optional] pointer to extension-specific structure
("type", ur_exp_image_type_t) ## [in] indicates image type
]

###############################################################################
## @brief The extension string which defines support for command-buffers which
## is returned when querying device extensions.
Expand Down
139 changes: 99 additions & 40 deletions include/ur_api.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -214,46 +214,48 @@ typedef enum ur_function_t {
///////////////////////////////////////////////////////////////////////////////
/// @brief Defines structure types
typedef enum ur_structure_type_t {
UR_STRUCTURE_TYPE_CONTEXT_PROPERTIES = 0, ///< ::ur_context_properties_t
UR_STRUCTURE_TYPE_IMAGE_DESC = 1, ///< ::ur_image_desc_t
UR_STRUCTURE_TYPE_BUFFER_PROPERTIES = 2, ///< ::ur_buffer_properties_t
UR_STRUCTURE_TYPE_BUFFER_REGION = 3, ///< ::ur_buffer_region_t
UR_STRUCTURE_TYPE_BUFFER_CHANNEL_PROPERTIES = 4, ///< ::ur_buffer_channel_properties_t
UR_STRUCTURE_TYPE_BUFFER_ALLOC_LOCATION_PROPERTIES = 5, ///< ::ur_buffer_alloc_location_properties_t
UR_STRUCTURE_TYPE_PROGRAM_PROPERTIES = 6, ///< ::ur_program_properties_t
UR_STRUCTURE_TYPE_USM_DESC = 7, ///< ::ur_usm_desc_t
UR_STRUCTURE_TYPE_USM_HOST_DESC = 8, ///< ::ur_usm_host_desc_t
UR_STRUCTURE_TYPE_USM_DEVICE_DESC = 9, ///< ::ur_usm_device_desc_t
UR_STRUCTURE_TYPE_USM_POOL_DESC = 10, ///< ::ur_usm_pool_desc_t
UR_STRUCTURE_TYPE_USM_POOL_LIMITS_DESC = 11, ///< ::ur_usm_pool_limits_desc_t
UR_STRUCTURE_TYPE_DEVICE_BINARY = 12, ///< ::ur_device_binary_t
UR_STRUCTURE_TYPE_SAMPLER_DESC = 13, ///< ::ur_sampler_desc_t
UR_STRUCTURE_TYPE_QUEUE_PROPERTIES = 14, ///< ::ur_queue_properties_t
UR_STRUCTURE_TYPE_QUEUE_INDEX_PROPERTIES = 15, ///< ::ur_queue_index_properties_t
UR_STRUCTURE_TYPE_CONTEXT_NATIVE_PROPERTIES = 16, ///< ::ur_context_native_properties_t
UR_STRUCTURE_TYPE_KERNEL_NATIVE_PROPERTIES = 17, ///< ::ur_kernel_native_properties_t
UR_STRUCTURE_TYPE_QUEUE_NATIVE_PROPERTIES = 18, ///< ::ur_queue_native_properties_t
UR_STRUCTURE_TYPE_MEM_NATIVE_PROPERTIES = 19, ///< ::ur_mem_native_properties_t
UR_STRUCTURE_TYPE_EVENT_NATIVE_PROPERTIES = 20, ///< ::ur_event_native_properties_t
UR_STRUCTURE_TYPE_PLATFORM_NATIVE_PROPERTIES = 21, ///< ::ur_platform_native_properties_t
UR_STRUCTURE_TYPE_DEVICE_NATIVE_PROPERTIES = 22, ///< ::ur_device_native_properties_t
UR_STRUCTURE_TYPE_PROGRAM_NATIVE_PROPERTIES = 23, ///< ::ur_program_native_properties_t
UR_STRUCTURE_TYPE_SAMPLER_NATIVE_PROPERTIES = 24, ///< ::ur_sampler_native_properties_t
UR_STRUCTURE_TYPE_QUEUE_NATIVE_DESC = 25, ///< ::ur_queue_native_desc_t
UR_STRUCTURE_TYPE_DEVICE_PARTITION_PROPERTIES = 26, ///< ::ur_device_partition_properties_t
UR_STRUCTURE_TYPE_KERNEL_ARG_MEM_OBJ_PROPERTIES = 27, ///< ::ur_kernel_arg_mem_obj_properties_t
UR_STRUCTURE_TYPE_PHYSICAL_MEM_PROPERTIES = 28, ///< ::ur_physical_mem_properties_t
UR_STRUCTURE_TYPE_KERNEL_ARG_POINTER_PROPERTIES = 29, ///< ::ur_kernel_arg_pointer_properties_t
UR_STRUCTURE_TYPE_KERNEL_ARG_SAMPLER_PROPERTIES = 30, ///< ::ur_kernel_arg_sampler_properties_t
UR_STRUCTURE_TYPE_KERNEL_EXEC_INFO_PROPERTIES = 31, ///< ::ur_kernel_exec_info_properties_t
UR_STRUCTURE_TYPE_KERNEL_ARG_VALUE_PROPERTIES = 32, ///< ::ur_kernel_arg_value_properties_t
UR_STRUCTURE_TYPE_KERNEL_ARG_LOCAL_PROPERTIES = 33, ///< ::ur_kernel_arg_local_properties_t
UR_STRUCTURE_TYPE_EXP_COMMAND_BUFFER_DESC = 0x1000, ///< ::ur_exp_command_buffer_desc_t
UR_STRUCTURE_TYPE_EXP_SAMPLER_MIP_PROPERTIES = 0x2000, ///< ::ur_exp_sampler_mip_properties_t
UR_STRUCTURE_TYPE_EXP_INTEROP_MEM_DESC = 0x2001, ///< ::ur_exp_interop_mem_desc_t
UR_STRUCTURE_TYPE_EXP_INTEROP_SEMAPHORE_DESC = 0x2002, ///< ::ur_exp_interop_semaphore_desc_t
UR_STRUCTURE_TYPE_EXP_FILE_DESCRIPTOR = 0x2003, ///< ::ur_exp_file_descriptor_t
UR_STRUCTURE_TYPE_EXP_WIN32_HANDLE = 0x2004, ///< ::ur_exp_win32_handle_t
UR_STRUCTURE_TYPE_CONTEXT_PROPERTIES = 0, ///< ::ur_context_properties_t
UR_STRUCTURE_TYPE_IMAGE_DESC = 1, ///< ::ur_image_desc_t
UR_STRUCTURE_TYPE_BUFFER_PROPERTIES = 2, ///< ::ur_buffer_properties_t
UR_STRUCTURE_TYPE_BUFFER_REGION = 3, ///< ::ur_buffer_region_t
UR_STRUCTURE_TYPE_BUFFER_CHANNEL_PROPERTIES = 4, ///< ::ur_buffer_channel_properties_t
UR_STRUCTURE_TYPE_BUFFER_ALLOC_LOCATION_PROPERTIES = 5, ///< ::ur_buffer_alloc_location_properties_t
UR_STRUCTURE_TYPE_PROGRAM_PROPERTIES = 6, ///< ::ur_program_properties_t
UR_STRUCTURE_TYPE_USM_DESC = 7, ///< ::ur_usm_desc_t
UR_STRUCTURE_TYPE_USM_HOST_DESC = 8, ///< ::ur_usm_host_desc_t
UR_STRUCTURE_TYPE_USM_DEVICE_DESC = 9, ///< ::ur_usm_device_desc_t
UR_STRUCTURE_TYPE_USM_POOL_DESC = 10, ///< ::ur_usm_pool_desc_t
UR_STRUCTURE_TYPE_USM_POOL_LIMITS_DESC = 11, ///< ::ur_usm_pool_limits_desc_t
UR_STRUCTURE_TYPE_DEVICE_BINARY = 12, ///< ::ur_device_binary_t
UR_STRUCTURE_TYPE_SAMPLER_DESC = 13, ///< ::ur_sampler_desc_t
UR_STRUCTURE_TYPE_QUEUE_PROPERTIES = 14, ///< ::ur_queue_properties_t
UR_STRUCTURE_TYPE_QUEUE_INDEX_PROPERTIES = 15, ///< ::ur_queue_index_properties_t
UR_STRUCTURE_TYPE_CONTEXT_NATIVE_PROPERTIES = 16, ///< ::ur_context_native_properties_t
UR_STRUCTURE_TYPE_KERNEL_NATIVE_PROPERTIES = 17, ///< ::ur_kernel_native_properties_t
UR_STRUCTURE_TYPE_QUEUE_NATIVE_PROPERTIES = 18, ///< ::ur_queue_native_properties_t
UR_STRUCTURE_TYPE_MEM_NATIVE_PROPERTIES = 19, ///< ::ur_mem_native_properties_t
UR_STRUCTURE_TYPE_EVENT_NATIVE_PROPERTIES = 20, ///< ::ur_event_native_properties_t
UR_STRUCTURE_TYPE_PLATFORM_NATIVE_PROPERTIES = 21, ///< ::ur_platform_native_properties_t
UR_STRUCTURE_TYPE_DEVICE_NATIVE_PROPERTIES = 22, ///< ::ur_device_native_properties_t
UR_STRUCTURE_TYPE_PROGRAM_NATIVE_PROPERTIES = 23, ///< ::ur_program_native_properties_t
UR_STRUCTURE_TYPE_SAMPLER_NATIVE_PROPERTIES = 24, ///< ::ur_sampler_native_properties_t
UR_STRUCTURE_TYPE_QUEUE_NATIVE_DESC = 25, ///< ::ur_queue_native_desc_t
UR_STRUCTURE_TYPE_DEVICE_PARTITION_PROPERTIES = 26, ///< ::ur_device_partition_properties_t
UR_STRUCTURE_TYPE_KERNEL_ARG_MEM_OBJ_PROPERTIES = 27, ///< ::ur_kernel_arg_mem_obj_properties_t
UR_STRUCTURE_TYPE_PHYSICAL_MEM_PROPERTIES = 28, ///< ::ur_physical_mem_properties_t
UR_STRUCTURE_TYPE_KERNEL_ARG_POINTER_PROPERTIES = 29, ///< ::ur_kernel_arg_pointer_properties_t
UR_STRUCTURE_TYPE_KERNEL_ARG_SAMPLER_PROPERTIES = 30, ///< ::ur_kernel_arg_sampler_properties_t
UR_STRUCTURE_TYPE_KERNEL_EXEC_INFO_PROPERTIES = 31, ///< ::ur_kernel_exec_info_properties_t
UR_STRUCTURE_TYPE_KERNEL_ARG_VALUE_PROPERTIES = 32, ///< ::ur_kernel_arg_value_properties_t
UR_STRUCTURE_TYPE_KERNEL_ARG_LOCAL_PROPERTIES = 33, ///< ::ur_kernel_arg_local_properties_t
UR_STRUCTURE_TYPE_EXP_COMMAND_BUFFER_DESC = 0x1000, ///< ::ur_exp_command_buffer_desc_t
UR_STRUCTURE_TYPE_EXP_SAMPLER_MIP_PROPERTIES = 0x2000, ///< ::ur_exp_sampler_mip_properties_t
UR_STRUCTURE_TYPE_EXP_INTEROP_MEM_DESC = 0x2001, ///< ::ur_exp_interop_mem_desc_t
UR_STRUCTURE_TYPE_EXP_INTEROP_SEMAPHORE_DESC = 0x2002, ///< ::ur_exp_interop_semaphore_desc_t
UR_STRUCTURE_TYPE_EXP_FILE_DESCRIPTOR = 0x2003, ///< ::ur_exp_file_descriptor_t
UR_STRUCTURE_TYPE_EXP_WIN32_HANDLE = 0x2004, ///< ::ur_exp_win32_handle_t
UR_STRUCTURE_TYPE_EXP_IMAGE_TYPE_DESC = 0x2005, ///< ::ur_exp_image_type_desc_t
UR_STRUCTURE_TYPE_EXP_SAMPLER_CUBEMAP_PROPERTIES = 0x2006, ///< ::ur_exp_sampler_cubemap_properties_t
/// @cond
UR_STRUCTURE_TYPE_FORCE_UINT32 = 0x7fffffff
/// @endcond
Expand Down Expand Up @@ -6946,6 +6948,34 @@ typedef enum ur_exp_image_copy_flag_t {
/// @brief Bit Mask for validating ur_exp_image_copy_flags_t
#define UR_EXP_IMAGE_COPY_FLAGS_MASK 0xfffffff8

///////////////////////////////////////////////////////////////////////////////
/// @brief Dictates the image type to distinguish between image types that can be
/// represented equivalently in memory.
typedef enum ur_exp_image_type_t {
UR_EXP_IMAGE_TYPE_1D = 0, ///< 1D image type
UR_EXP_IMAGE_TYPE_2D = 1, ///< 2D image type
UR_EXP_IMAGE_TYPE_3D = 2, ///< 3D image type
UR_EXP_IMAGE_TYPE_CUBEMAP = 3, ///< Cubemap image type
UR_EXP_IMAGE_TYPE_1D_ARRAY = 4, ///< 1D image array type
UR_EXP_IMAGE_TYPE_2D_ARRAY = 5, ///< 2D image array type
UR_EXP_IMAGE_TYPE_CUBEMAP_ARRAY = 6, ///< Cubemap array image type
/// @cond
UR_EXP_IMAGE_TYPE_FORCE_UINT32 = 0x7fffffff
/// @endcond

} ur_exp_image_type_t;

///////////////////////////////////////////////////////////////////////////////
/// @brief Sampler cubemap seamless filtering mode.
typedef enum ur_exp_sampler_cubemap_filter_mode_t {
UR_EXP_SAMPLER_CUBEMAP_FILTER_MODE_SEAMLESS = 0, ///< Seamless filtering
UR_EXP_SAMPLER_CUBEMAP_FILTER_MODE_DISJOINTED = 1, ///< Disable seamless filtering
/// @cond
UR_EXP_SAMPLER_CUBEMAP_FILTER_MODE_FORCE_UINT32 = 0x7fffffff
/// @endcond

} ur_exp_sampler_cubemap_filter_mode_t;

///////////////////////////////////////////////////////////////////////////////
/// @brief File descriptor
typedef struct ur_exp_file_descriptor_t {
Expand Down Expand Up @@ -6986,6 +7016,21 @@ typedef struct ur_exp_sampler_mip_properties_t {

} ur_exp_sampler_mip_properties_t;

///////////////////////////////////////////////////////////////////////////////
/// @brief Describes cubemap sampler properties
///
/// @details
/// - Specify these properties in ::urSamplerCreate via ::ur_sampler_desc_t
/// as part of a `pNext` chain.
typedef struct ur_exp_sampler_cubemap_properties_t {
ur_structure_type_t stype; ///< [in] type of this structure, must be
///< ::UR_STRUCTURE_TYPE_EXP_SAMPLER_CUBEMAP_PROPERTIES
void *pNext; ///< [in,out][optional] pointer to extension-specific structure
ur_exp_sampler_cubemap_filter_mode_t cubemapFilterMode; ///< [in] enables or disables seamless cubemap filtering between cubemap
///< faces

} ur_exp_sampler_cubemap_properties_t;

///////////////////////////////////////////////////////////////////////////////
/// @brief Describes an interop memory resource descriptor
typedef struct ur_exp_interop_mem_desc_t {
Expand All @@ -7004,6 +7049,20 @@ typedef struct ur_exp_interop_semaphore_desc_t {

} ur_exp_interop_semaphore_desc_t;

///////////////////////////////////////////////////////////////////////////////
/// @brief Describes image type properties
///
/// @details
/// - Specify these properties in ::urBindlessImagesImageAllocateExp via
/// ::ur_image_desc_t as part of a `pNext` chain.
typedef struct ur_exp_image_type_desc_t {
ur_structure_type_t stype; ///< [in] type of this structure, must be
///< ::UR_STRUCTURE_TYPE_EXP_IMAGE_TYPE_DESC
const void *pNext; ///< [in][optional] pointer to extension-specific structure
ur_exp_image_type_t type; ///< [in] indicates image type

} ur_exp_image_type_desc_t;

///////////////////////////////////////////////////////////////////////////////
/// @brief USM allocate pitched memory
///
Expand Down
21 changes: 21 additions & 0 deletions scripts/core/EXP-BINDLESS-IMAGES.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,7 @@ Runtime:
* Sampled images
* Unsampled images
* Mipmaps
* Cubemaps
* USM backed images

* Interoperability support
Expand All @@ -68,6 +69,8 @@ Enums
${X}_STRUCTURE_TYPE_EXP_INTEROP_SEMAPHORE_DESC
${X}_STRUCTURE_TYPE_EXP_FILE_DESCRIPTOR
${X}_STRUCTURE_TYPE_EXP_WIN32_HANDLE
${X}_STRUCTURE_TYPE_EXP_IMAGE_TYPE_DESC
${X}_STRUCTURE_TYPE_EXP_SAMPLER_CUBEMAP_PROPERTIES

* ${x}_device_info_t
* ${X}_DEVICE_INFO_BINDLESS_IMAGES_SUPPORT_EXP
Expand Down Expand Up @@ -96,6 +99,19 @@ Enums
* ${X}_EXP_IMAGE_COPY_FLAG_DEVICE_TO_HOST
* ${X}_EXP_IMAGE_COPY_FLAG_DEVICE_TO_DEVICE

* ${x}_exp_image_type_t
* ${X}_EXP_IMAGE_TYPE_1D
* ${X}_EXP_IMAGE_TYPE_2D
* ${X}_EXP_IMAGE_TYPE_3D
* ${X}_EXP_IMAGE_TYPE_CUBEMAP
* ${X}_EXP_IMAGE_TYPE_1D_ARRAY
* ${X}_EXP_IMAGE_TYPE_2D_ARRAY
* ${X}_EXP_IMAGE_TYPE_CUBEMAP_ARRAY

* ${x}_exp_sampler_cubemap_filter_mode_t
* ${X}_EXP_SAMPLER_CUBEMAP_FILTER_MODE_SEAMLESS
* ${X}_EXP_SAMPLER_CUBEMAP_FILTER_MODE_DISJOINTED

* ${x}_function_t
* ${X}_FUNCTION_USM_PITCHED_ALLOC_EXP
* ${X}_FUNCTION_BINDLESS_IMAGES_UNSAMPLED_IMAGE_HANDLE_DESTROY_EXP
Expand Down Expand Up @@ -127,6 +143,8 @@ Types
* ${x}_exp_interop_semaphore_desc_t
* ${x}_exp_file_descriptor_t
* ${x}_exp_win32_handle_t
* ${x}_exp_image_type_desc_t
* ${x}_exp_sampler_cubemap_properties_t

Functions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -176,6 +194,9 @@ Changelog
+----------+-------------------------------------------------------------+
| 6.0 | Fix semaphore import function parameter name. |
+----------+-------------------------------------------------------------+
| 7.0 | Add image type descriptor, image type enum, and cubemap |
| | sampling properties. |
+----------+-------------------------------------------------------------+

Contributors
--------------------------------------------------------------------------------
Expand Down
Loading

0 comments on commit 4368c24

Please sign in to comment.