Skip to content

Commit 12f45c4

Browse files
cppchedycppchedy
committed
[CUDA][L0][Bindless] update design of urBindlessImagesImageCopyExp
The new design, proposed through this patch, addresses the current problems/limitations for urBindlessImagesImageCopyExp: - unused or redundant arguments. - lack of support for new features such as subregion layered image copies. - host versus device instead of source versus destination. The API accepts two image descriptors and two image formats which accommodate for copying between two different image types and possible formats. The copy information is captured by a new struct, namely `ur_exp_image_copy_region_t`. It enables subregion copy for layered images and mipmaps.
1 parent 05f0c61 commit 12f45c4

26 files changed

+556
-438
lines changed

‎include/ur_api.h

Lines changed: 35 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -283,6 +283,7 @@ typedef enum ur_structure_type_t {
283283
UR_STRUCTURE_TYPE_EXP_WIN32_HANDLE = 0x2004, ///< ::ur_exp_win32_handle_t
284284
UR_STRUCTURE_TYPE_EXP_SAMPLER_ADDR_MODES = 0x2005, ///< ::ur_exp_sampler_addr_modes_t
285285
UR_STRUCTURE_TYPE_EXP_SAMPLER_CUBEMAP_PROPERTIES = 0x2006, ///< ::ur_exp_sampler_cubemap_properties_t
286+
UR_STRUCTURE_TYPE_EXP_IMAGE_COPY_REGION = 0x2007, ///< ::ur_exp_image_copy_region_t
286287
UR_STRUCTURE_TYPE_EXP_ENQUEUE_NATIVE_COMMAND_PROPERTIES = 0x3000, ///< ::ur_exp_enqueue_native_command_properties_t
287288
/// @cond
288289
UR_STRUCTURE_TYPE_FORCE_UINT32 = 0x7fffffff
@@ -7501,6 +7502,18 @@ typedef struct ur_exp_interop_semaphore_desc_t {
75017502

75027503
} ur_exp_interop_semaphore_desc_t;
75037504

7505+
///////////////////////////////////////////////////////////////////////////////
7506+
/// @brief Describes the (sub-)regions and the extent to be copied
7507+
typedef struct ur_exp_image_copy_region_t {
7508+
ur_structure_type_t stype; ///< [in] type of this structure, must be
7509+
///< ::UR_STRUCTURE_TYPE_EXP_IMAGE_COPY_REGION
7510+
const void *pNext; ///< [in][optional] pointer to extension-specific structure
7511+
ur_rect_offset_t srcOffset; ///< [in] the offset into the source image
7512+
ur_rect_offset_t dstOffset; ///< [in] the offset into the destination image
7513+
ur_rect_region_t copyExtent; ///< [in] the extent (region) of the image to copy
7514+
7515+
} ur_exp_image_copy_region_t;
7516+
75047517
///////////////////////////////////////////////////////////////////////////////
75057518
/// @brief USM allocate pitched memory
75067519
///
@@ -7740,7 +7753,7 @@ urBindlessImagesSampledImageCreateExp(
77407753
);
77417754

77427755
///////////////////////////////////////////////////////////////////////////////
7743-
/// @brief Copy image data Host to Device or Device to Host
7756+
/// @brief Copy image data Host to Device, Device to Host, or Device to Device
77447757
///
77457758
/// @remarks
77467759
/// _Analogues_
@@ -7757,34 +7770,34 @@ urBindlessImagesSampledImageCreateExp(
77577770
/// - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
77587771
/// + `NULL == hQueue`
77597772
/// - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
7760-
/// + `NULL == pDst`
77617773
/// + `NULL == pSrc`
7762-
/// + `NULL == pImageFormat`
7763-
/// + `NULL == pImageDesc`
7774+
/// + `NULL == pDst`
7775+
/// + `NULL == pSrcImageDesc`
7776+
/// + `NULL == pDstImageDesc`
7777+
/// + `NULL == pSrcImageFormat`
7778+
/// + `NULL == pDstImageFormat`
7779+
/// + `NULL == pCopyRegion`
77647780
/// - ::UR_RESULT_ERROR_INVALID_ENUMERATION
77657781
/// + `::UR_EXP_IMAGE_COPY_FLAGS_MASK & imageCopyFlags`
77667782
/// - ::UR_RESULT_ERROR_INVALID_QUEUE
77677783
/// - ::UR_RESULT_ERROR_INVALID_VALUE
77687784
/// - ::UR_RESULT_ERROR_INVALID_IMAGE_FORMAT_DESCRIPTOR
7769-
/// + `pImageDesc && UR_MEM_TYPE_IMAGE_CUBEMAP_EXP < pImageDesc->type`
7785+
/// + `pSrcImageDesc && UR_MEM_TYPE_IMAGE_CUBEMAP_EXP < pSrcImageDesc->type`
7786+
/// + `pDstImageDesc && UR_MEM_TYPE_IMAGE_CUBEMAP_EXP < pDstImageDesc->type`
77707787
/// - ::UR_RESULT_ERROR_INVALID_IMAGE_SIZE
77717788
/// - ::UR_RESULT_ERROR_INVALID_OPERATION
77727789
UR_APIEXPORT ur_result_t UR_APICALL
77737790
urBindlessImagesImageCopyExp(
77747791
ur_queue_handle_t hQueue, ///< [in] handle of the queue object
7775-
void *pDst, ///< [in] location the data will be copied to
77767792
const void *pSrc, ///< [in] location the data will be copied from
7777-
const ur_image_format_t *pImageFormat, ///< [in] pointer to image format specification
7778-
const ur_image_desc_t *pImageDesc, ///< [in] pointer to image description
7793+
void *pDst, ///< [in] location the data will be copied to
7794+
const ur_image_desc_t *pSrcImageDesc, ///< [in] pointer to image description
7795+
const ur_image_desc_t *pDstImageDesc, ///< [in] pointer to image description
7796+
const ur_image_format_t *pSrcImageFormat, ///< [in] pointer to image format specification
7797+
const ur_image_format_t *pDstImageFormat, ///< [in] pointer to image format specification
7798+
ur_exp_image_copy_region_t *pCopyRegion, ///< [in] Pointer to structure describing the (sub-)regions of source and
7799+
///< destination images
77797800
ur_exp_image_copy_flags_t imageCopyFlags, ///< [in] flags describing copy direction e.g. H2D or D2H
7780-
ur_rect_offset_t srcOffset, ///< [in] defines the (x,y,z) source offset in pixels in the 1D, 2D, or 3D
7781-
///< image
7782-
ur_rect_offset_t dstOffset, ///< [in] defines the (x,y,z) destination offset in pixels in the 1D, 2D,
7783-
///< or 3D image
7784-
ur_rect_region_t copyExtent, ///< [in] defines the (width, height, depth) in pixels of the 1D, 2D, or 3D
7785-
///< region to copy
7786-
ur_rect_region_t hostExtent, ///< [in] defines the (width, height, depth) in pixels of the 1D, 2D, or 3D
7787-
///< region on the host
77887801
uint32_t numEventsInWaitList, ///< [in] size of the event wait list
77897802
const ur_event_handle_t *phEventWaitList, ///< [in][optional][range(0, numEventsInWaitList)] pointer to a list of
77907803
///< events that must be complete before this command can be executed.
@@ -11138,15 +11151,14 @@ typedef struct ur_bindless_images_sampled_image_create_exp_params_t {
1113811151
/// allowing the callback the ability to modify the parameter's value
1113911152
typedef struct ur_bindless_images_image_copy_exp_params_t {
1114011153
ur_queue_handle_t *phQueue;
11141-
void **ppDst;
1114211154
const void **ppSrc;
11143-
const ur_image_format_t **ppImageFormat;
11144-
const ur_image_desc_t **ppImageDesc;
11155+
void **ppDst;
11156+
const ur_image_desc_t **ppSrcImageDesc;
11157+
const ur_image_desc_t **ppDstImageDesc;
11158+
const ur_image_format_t **ppSrcImageFormat;
11159+
const ur_image_format_t **ppDstImageFormat;
11160+
ur_exp_image_copy_region_t **ppCopyRegion;
1114511161
ur_exp_image_copy_flags_t *pimageCopyFlags;
11146-
ur_rect_offset_t *psrcOffset;
11147-
ur_rect_offset_t *pdstOffset;
11148-
ur_rect_region_t *pcopyExtent;
11149-
ur_rect_region_t *phostExtent;
1115011162
uint32_t *pnumEventsInWaitList;
1115111163
const ur_event_handle_t **pphEventWaitList;
1115211164
ur_event_handle_t **pphEvent;

‎include/ur_ddi.h

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1581,15 +1581,14 @@ typedef ur_result_t(UR_APICALL *ur_pfnBindlessImagesSampledImageCreateExp_t)(
15811581
/// @brief Function-pointer for urBindlessImagesImageCopyExp
15821582
typedef ur_result_t(UR_APICALL *ur_pfnBindlessImagesImageCopyExp_t)(
15831583
ur_queue_handle_t,
1584-
void *,
15851584
const void *,
1586-
const ur_image_format_t *,
1585+
void *,
15871586
const ur_image_desc_t *,
1587+
const ur_image_desc_t *,
1588+
const ur_image_format_t *,
1589+
const ur_image_format_t *,
1590+
ur_exp_image_copy_region_t *,
15881591
ur_exp_image_copy_flags_t,
1589-
ur_rect_offset_t,
1590-
ur_rect_offset_t,
1591-
ur_rect_region_t,
1592-
ur_rect_region_t,
15931592
uint32_t,
15941593
const ur_event_handle_t *,
15951594
ur_event_handle_t *);

‎include/ur_print.h

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -962,6 +962,14 @@ UR_APIEXPORT ur_result_t UR_APICALL urPrintExpInteropMemDesc(const struct ur_exp
962962
/// - `buff_size < out_size`
963963
UR_APIEXPORT ur_result_t UR_APICALL urPrintExpInteropSemaphoreDesc(const struct ur_exp_interop_semaphore_desc_t params, char *buffer, const size_t buff_size, size_t *out_size);
964964

965+
///////////////////////////////////////////////////////////////////////////////
966+
/// @brief Print ur_exp_image_copy_region_t struct
967+
/// @returns
968+
/// - ::UR_RESULT_SUCCESS
969+
/// - ::UR_RESULT_ERROR_INVALID_SIZE
970+
/// - `buff_size < out_size`
971+
UR_APIEXPORT ur_result_t UR_APICALL urPrintExpImageCopyRegion(const struct ur_exp_image_copy_region_t params, char *buffer, const size_t buff_size, size_t *out_size);
972+
965973
///////////////////////////////////////////////////////////////////////////////
966974
/// @brief Print ur_exp_command_buffer_info_t enum
967975
/// @returns

‎include/ur_print.hpp

Lines changed: 63 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -334,6 +334,7 @@ inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct
334334
inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct ur_exp_sampler_cubemap_properties_t params);
335335
inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct ur_exp_interop_mem_desc_t params);
336336
inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct ur_exp_interop_semaphore_desc_t params);
337+
inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct ur_exp_image_copy_region_t params);
337338
inline std::ostream &operator<<(std::ostream &os, enum ur_exp_command_buffer_info_t value);
338339
inline std::ostream &operator<<(std::ostream &os, enum ur_exp_command_buffer_command_info_t value);
339340
inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct ur_exp_command_buffer_desc_t params);
@@ -1094,6 +1095,9 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_structure_type_t value
10941095
case UR_STRUCTURE_TYPE_EXP_SAMPLER_CUBEMAP_PROPERTIES:
10951096
os << "UR_STRUCTURE_TYPE_EXP_SAMPLER_CUBEMAP_PROPERTIES";
10961097
break;
1098+
case UR_STRUCTURE_TYPE_EXP_IMAGE_COPY_REGION:
1099+
os << "UR_STRUCTURE_TYPE_EXP_IMAGE_COPY_REGION";
1100+
break;
10971101
case UR_STRUCTURE_TYPE_EXP_ENQUEUE_NATIVE_COMMAND_PROPERTIES:
10981102
os << "UR_STRUCTURE_TYPE_EXP_ENQUEUE_NATIVE_COMMAND_PROPERTIES";
10991103
break;
@@ -1349,6 +1353,11 @@ inline ur_result_t printStruct(std::ostream &os, const void *ptr) {
13491353
printPtr(os, pstruct);
13501354
} break;
13511355

1356+
case UR_STRUCTURE_TYPE_EXP_IMAGE_COPY_REGION: {
1357+
const ur_exp_image_copy_region_t *pstruct = (const ur_exp_image_copy_region_t *)ptr;
1358+
printPtr(os, pstruct);
1359+
} break;
1360+
13521361
case UR_STRUCTURE_TYPE_EXP_ENQUEUE_NATIVE_COMMAND_PROPERTIES: {
13531362
const ur_exp_enqueue_native_command_properties_t *pstruct = (const ur_exp_enqueue_native_command_properties_t *)ptr;
13541363
printPtr(os, pstruct);
@@ -9607,6 +9616,41 @@ inline std::ostream &operator<<(std::ostream &os, const struct ur_exp_interop_se
96079616
return os;
96089617
}
96099618
///////////////////////////////////////////////////////////////////////////////
9619+
/// @brief Print operator for the ur_exp_image_copy_region_t type
9620+
/// @returns
9621+
/// std::ostream &
9622+
inline std::ostream &operator<<(std::ostream &os, const struct ur_exp_image_copy_region_t params) {
9623+
os << "(struct ur_exp_image_copy_region_t){";
9624+
9625+
os << ".stype = ";
9626+
9627+
os << (params.stype);
9628+
9629+
os << ", ";
9630+
os << ".pNext = ";
9631+
9632+
ur::details::printStruct(os,
9633+
(params.pNext));
9634+
9635+
os << ", ";
9636+
os << ".srcOffset = ";
9637+
9638+
os << (params.srcOffset);
9639+
9640+
os << ", ";
9641+
os << ".dstOffset = ";
9642+
9643+
os << (params.dstOffset);
9644+
9645+
os << ", ";
9646+
os << ".copyExtent = ";
9647+
9648+
os << (params.copyExtent);
9649+
9650+
os << "}";
9651+
return os;
9652+
}
9653+
///////////////////////////////////////////////////////////////////////////////
96109654
/// @brief Print operator for the ur_exp_command_buffer_info_t type
96119655
/// @returns
96129656
/// std::ostream &
@@ -14865,55 +14909,53 @@ inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct
1486514909
ur::details::printPtr(os,
1486614910
*(params->phQueue));
1486714911

14868-
os << ", ";
14869-
os << ".pDst = ";
14870-
14871-
ur::details::printPtr(os,
14872-
*(params->ppDst));
14873-
1487414912
os << ", ";
1487514913
os << ".pSrc = ";
1487614914

1487714915
ur::details::printPtr(os,
1487814916
*(params->ppSrc));
1487914917

1488014918
os << ", ";
14881-
os << ".pImageFormat = ";
14919+
os << ".pDst = ";
1488214920

1488314921
ur::details::printPtr(os,
14884-
*(params->ppImageFormat));
14922+
*(params->ppDst));
1488514923

1488614924
os << ", ";
14887-
os << ".pImageDesc = ";
14925+
os << ".pSrcImageDesc = ";
1488814926

1488914927
ur::details::printPtr(os,
14890-
*(params->ppImageDesc));
14928+
*(params->ppSrcImageDesc));
1489114929

1489214930
os << ", ";
14893-
os << ".imageCopyFlags = ";
14931+
os << ".pDstImageDesc = ";
1489414932

14895-
ur::details::printFlag<ur_exp_image_copy_flag_t>(os,
14896-
*(params->pimageCopyFlags));
14933+
ur::details::printPtr(os,
14934+
*(params->ppDstImageDesc));
1489714935

1489814936
os << ", ";
14899-
os << ".srcOffset = ";
14937+
os << ".pSrcImageFormat = ";
1490014938

14901-
os << *(params->psrcOffset);
14939+
ur::details::printPtr(os,
14940+
*(params->ppSrcImageFormat));
1490214941

1490314942
os << ", ";
14904-
os << ".dstOffset = ";
14943+
os << ".pDstImageFormat = ";
1490514944

14906-
os << *(params->pdstOffset);
14945+
ur::details::printPtr(os,
14946+
*(params->ppDstImageFormat));
1490714947

1490814948
os << ", ";
14909-
os << ".copyExtent = ";
14949+
os << ".pCopyRegion = ";
1491014950

14911-
os << *(params->pcopyExtent);
14951+
ur::details::printPtr(os,
14952+
*(params->ppCopyRegion));
1491214953

1491314954
os << ", ";
14914-
os << ".hostExtent = ";
14955+
os << ".imageCopyFlags = ";
1491514956

14916-
os << *(params->phostExtent);
14957+
ur::details::printFlag<ur_exp_image_copy_flag_t>(os,
14958+
*(params->pimageCopyFlags));
1491714959

1491814960
os << ", ";
1491914961
os << ".numEventsInWaitList = ";

‎scripts/core/EXP-BINDLESS-IMAGES.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -158,6 +158,7 @@ Types
158158
* ${x}_exp_win32_handle_t
159159
* ${x}_exp_sampler_addr_modes_t
160160
* ${x}_exp_sampler_cubemap_properties_t
161+
* ${x}_exp_image_copy_region_t
161162

162163
Functions
163164
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -240,6 +241,8 @@ Changelog
240241
| 14.0 || Rename func BindlessImagesDestroyExternalSemaphoreExp to |
241242
| || BindlessImagesReleaseExternalSemaphoreExp |
242243
+------------------------------------------------------------------------+
244+
| 15.0 | Added structures for supporting copying. |
245+
+----------+-------------------------------------------------------------+
243246

244247
Contributors
245248
--------------------------------------------------------------------------------

0 commit comments

Comments
 (0)