hsa_ext_image.h revision 1.1
1 //////////////////////////////////////////////////////////////////////////////// 2 // 3 // Copyright (C) 2014-2020 Advanced Micro Devices Inc. All rights reserved. 4 // 5 // Permission is hereby granted, free of charge, to any person or organization 6 // obtaining a copy of the software and accompanying documentation covered by 7 // this license (the "Software") to use, reproduce, display, distribute, 8 // execute, and transmit the Software, and to prepare derivative works of the 9 // Software, and to permit third-parties to whom the Software is furnished to 10 // do so, all subject to the following: 11 // 12 // The copyright notices in the Software and this entire statement, including 13 // the above license grant, this restriction and the following disclaimer, 14 // must be included in all copies of the Software, in whole or in part, and 15 // all derivative works of the Software, unless such copies or derivative 16 // works are solely in the form of machine-executable object code generated by 17 // a source language processor. 18 // 19 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 20 // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 21 // FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT 22 // SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE 23 // FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE, 24 // ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 25 // DEALINGS IN THE SOFTWARE. 26 // 27 //////////////////////////////////////////////////////////////////////////////// 28 29 #ifndef HSA_EXT_IMAGE_H 30 #define HSA_EXT_IMAGE_H 31 32 #include "hsa.h" 33 34 #undef HSA_API 35 #ifdef HSA_EXPORT_IMAGES 36 #define HSA_API HSA_API_EXPORT 37 #else 38 #define HSA_API HSA_API_IMPORT 39 #endif 40 41 #ifdef __cplusplus 42 extern "C" { 43 #endif /*__cplusplus*/ 44 45 /** \defgroup ext-images Images and Samplers 46 * @{ 47 */ 48 49 /** 50 * @brief Enumeration constants added to ::hsa_status_t by this extension. 51 * 52 * @remark Additions to hsa_status_t 53 */ 54 enum { 55 /** 56 * Image format is not supported. 57 */ 58 HSA_EXT_STATUS_ERROR_IMAGE_FORMAT_UNSUPPORTED = 0x3000, 59 /** 60 * Image size is not supported. 61 */ 62 HSA_EXT_STATUS_ERROR_IMAGE_SIZE_UNSUPPORTED = 0x3001, 63 /** 64 * Image pitch is not supported or invalid. 65 */ 66 HSA_EXT_STATUS_ERROR_IMAGE_PITCH_UNSUPPORTED = 0x3002, 67 /** 68 * Sampler descriptor is not supported or invalid. 69 */ 70 HSA_EXT_STATUS_ERROR_SAMPLER_DESCRIPTOR_UNSUPPORTED = 0x3003 71 }; 72 73 /** 74 * @brief Enumeration constants added to ::hsa_agent_info_t by this 75 * extension. 76 * 77 * @remark Additions to hsa_agent_info_t 78 */ 79 enum { 80 /** 81 * Maximum number of elements in 1D images. Must be at least 16384. The type 82 * of this attribute is size_t. 83 */ 84 HSA_EXT_AGENT_INFO_IMAGE_1D_MAX_ELEMENTS = 0x3000, 85 /** 86 * Maximum number of elements in 1DA images. Must be at least 16384. The type 87 * of this attribute is size_t. 88 */ 89 HSA_EXT_AGENT_INFO_IMAGE_1DA_MAX_ELEMENTS = 0x3001, 90 /** 91 * Maximum number of elements in 1DB images. Must be at least 65536. The type 92 * of this attribute is size_t. 93 */ 94 HSA_EXT_AGENT_INFO_IMAGE_1DB_MAX_ELEMENTS = 0x3002, 95 /** 96 * Maximum dimensions (width, height) of 2D images, in image elements. The X 97 * and Y maximums must be at least 16384. The type of this attribute is 98 * size_t[2]. 99 */ 100 HSA_EXT_AGENT_INFO_IMAGE_2D_MAX_ELEMENTS = 0x3003, 101 /** 102 * Maximum dimensions (width, height) of 2DA images, in image elements. The X 103 * and Y maximums must be at least 16384. The type of this attribute is 104 * size_t[2]. 105 */ 106 HSA_EXT_AGENT_INFO_IMAGE_2DA_MAX_ELEMENTS = 0x3004, 107 /** 108 * Maximum dimensions (width, height) of 2DDEPTH images, in image 109 * elements. The X and Y maximums must be at least 16384. The type of this 110 * attribute is size_t[2]. 111 */ 112 HSA_EXT_AGENT_INFO_IMAGE_2DDEPTH_MAX_ELEMENTS = 0x3005, 113 /** 114 * Maximum dimensions (width, height) of 2DADEPTH images, in image 115 * elements. The X and Y maximums must be at least 16384. The type of this 116 * attribute is size_t[2]. 117 */ 118 HSA_EXT_AGENT_INFO_IMAGE_2DADEPTH_MAX_ELEMENTS = 0x3006, 119 /** 120 * Maximum dimensions (width, height, depth) of 3D images, in image 121 * elements. The maximum along any dimension must be at least 2048. The type 122 * of this attribute is size_t[3]. 123 */ 124 HSA_EXT_AGENT_INFO_IMAGE_3D_MAX_ELEMENTS = 0x3007, 125 /** 126 * Maximum number of image layers in a image array. Must be at least 2048. The 127 * type of this attribute is size_t. 128 */ 129 HSA_EXT_AGENT_INFO_IMAGE_ARRAY_MAX_LAYERS = 0x3008, 130 /** 131 * Maximum number of read-only image handles that can be created for an agent at any one 132 * time. Must be at least 128. The type of this attribute is size_t. 133 */ 134 HSA_EXT_AGENT_INFO_MAX_IMAGE_RD_HANDLES = 0x3009, 135 /** 136 * Maximum number of write-only and read-write image handles (combined) that 137 * can be created for an agent at any one time. Must be at least 64. The type of this 138 * attribute is size_t. 139 */ 140 HSA_EXT_AGENT_INFO_MAX_IMAGE_RORW_HANDLES = 0x300A, 141 /** 142 * Maximum number of sampler handlers that can be created for an agent at any one 143 * time. Must be at least 16. The type of this attribute is size_t. 144 */ 145 HSA_EXT_AGENT_INFO_MAX_SAMPLER_HANDLERS = 0x300B, 146 /** 147 * Image pitch alignment. The agent only supports linear image data 148 * layouts with a row pitch that is a multiple of this value. Must be 149 * a power of 2. The type of this attribute is size_t. 150 */ 151 HSA_EXT_AGENT_INFO_IMAGE_LINEAR_ROW_PITCH_ALIGNMENT = 0x300C 152 }; 153 154 /** 155 * @brief Image handle, populated by ::hsa_ext_image_create or 156 * ::hsa_ext_image_create_with_layout. Image 157 * handles are only unique within an agent, not across agents. 158 * 159 */ 160 typedef struct hsa_ext_image_s { 161 /** 162 * Opaque handle. For a given agent, two handles reference the same object of 163 * the enclosing type if and only if they are equal. 164 */ 165 uint64_t handle; 166 167 } hsa_ext_image_t; 168 169 /** 170 * @brief Geometry associated with the image. This specifies the 171 * number of image dimensions and whether the image is an image 172 * array. See the <em>Image Geometry</em> section in the <em>HSA 173 * Programming Reference Manual</em> for definitions on each 174 * geometry. The enumeration values match the BRIG type @p 175 * hsa_ext_brig_image_geometry_t. 176 */ 177 typedef enum { 178 /** 179 * One-dimensional image addressed by width coordinate. 180 */ 181 HSA_EXT_IMAGE_GEOMETRY_1D = 0, 182 183 /** 184 * Two-dimensional image addressed by width and height coordinates. 185 */ 186 HSA_EXT_IMAGE_GEOMETRY_2D = 1, 187 188 /** 189 * Three-dimensional image addressed by width, height, and depth coordinates. 190 */ 191 HSA_EXT_IMAGE_GEOMETRY_3D = 2, 192 193 /** 194 * Array of one-dimensional images with the same size and format. 1D arrays 195 * are addressed by width and index coordinate. 196 */ 197 HSA_EXT_IMAGE_GEOMETRY_1DA = 3, 198 199 /** 200 * Array of two-dimensional images with the same size and format. 2D arrays 201 * are addressed by width, height, and index coordinates. 202 */ 203 HSA_EXT_IMAGE_GEOMETRY_2DA = 4, 204 205 /** 206 * One-dimensional image addressed by width coordinate. It has 207 * specific restrictions compared to ::HSA_EXT_IMAGE_GEOMETRY_1D. An 208 * image with an opaque image data layout will always use a linear 209 * image data layout, and one with an explicit image data layout 210 * must specify ::HSA_EXT_IMAGE_DATA_LAYOUT_LINEAR. 211 */ 212 HSA_EXT_IMAGE_GEOMETRY_1DB = 5, 213 214 /** 215 * Two-dimensional depth image addressed by width and height coordinates. 216 */ 217 HSA_EXT_IMAGE_GEOMETRY_2DDEPTH = 6, 218 219 /** 220 * Array of two-dimensional depth images with the same size and format. 2D 221 * arrays are addressed by width, height, and index coordinates. 222 */ 223 HSA_EXT_IMAGE_GEOMETRY_2DADEPTH = 7 224 } hsa_ext_image_geometry_t; 225 226 /** 227 * @brief Channel type associated with the elements of an image. See 228 * the <em>Channel Type</em> section in the <em>HSA Programming Reference 229 * Manual</em> for definitions on each channel type. The 230 * enumeration values and definition match the BRIG type @p 231 * hsa_ext_brig_image_channel_type_t. 232 */ 233 typedef enum { 234 HSA_EXT_IMAGE_CHANNEL_TYPE_SNORM_INT8 = 0, 235 HSA_EXT_IMAGE_CHANNEL_TYPE_SNORM_INT16 = 1, 236 HSA_EXT_IMAGE_CHANNEL_TYPE_UNORM_INT8 = 2, 237 HSA_EXT_IMAGE_CHANNEL_TYPE_UNORM_INT16 = 3, 238 HSA_EXT_IMAGE_CHANNEL_TYPE_UNORM_INT24 = 4, 239 HSA_EXT_IMAGE_CHANNEL_TYPE_UNORM_SHORT_555 = 5, 240 HSA_EXT_IMAGE_CHANNEL_TYPE_UNORM_SHORT_565 = 6, 241 HSA_EXT_IMAGE_CHANNEL_TYPE_UNORM_SHORT_101010 = 7, 242 HSA_EXT_IMAGE_CHANNEL_TYPE_SIGNED_INT8 = 8, 243 HSA_EXT_IMAGE_CHANNEL_TYPE_SIGNED_INT16 = 9, 244 HSA_EXT_IMAGE_CHANNEL_TYPE_SIGNED_INT32 = 10, 245 HSA_EXT_IMAGE_CHANNEL_TYPE_UNSIGNED_INT8 = 11, 246 HSA_EXT_IMAGE_CHANNEL_TYPE_UNSIGNED_INT16 = 12, 247 HSA_EXT_IMAGE_CHANNEL_TYPE_UNSIGNED_INT32 = 13, 248 HSA_EXT_IMAGE_CHANNEL_TYPE_HALF_FLOAT = 14, 249 HSA_EXT_IMAGE_CHANNEL_TYPE_FLOAT = 15 250 } hsa_ext_image_channel_type_t; 251 252 /** 253 * @brief A fixed-size type used to represent ::hsa_ext_image_channel_type_t constants. 254 */ 255 typedef uint32_t hsa_ext_image_channel_type32_t; 256 257 /** 258 * 259 * @brief Channel order associated with the elements of an image. See 260 * the <em>Channel Order</em> section in the <em>HSA Programming Reference 261 * Manual</em> for definitions on each channel order. The 262 * enumeration values match the BRIG type @p 263 * hsa_ext_brig_image_channel_order_t. 264 */ 265 typedef enum { 266 HSA_EXT_IMAGE_CHANNEL_ORDER_A = 0, 267 HSA_EXT_IMAGE_CHANNEL_ORDER_R = 1, 268 HSA_EXT_IMAGE_CHANNEL_ORDER_RX = 2, 269 HSA_EXT_IMAGE_CHANNEL_ORDER_RG = 3, 270 HSA_EXT_IMAGE_CHANNEL_ORDER_RGX = 4, 271 HSA_EXT_IMAGE_CHANNEL_ORDER_RA = 5, 272 HSA_EXT_IMAGE_CHANNEL_ORDER_RGB = 6, 273 HSA_EXT_IMAGE_CHANNEL_ORDER_RGBX = 7, 274 HSA_EXT_IMAGE_CHANNEL_ORDER_RGBA = 8, 275 HSA_EXT_IMAGE_CHANNEL_ORDER_BGRA = 9, 276 HSA_EXT_IMAGE_CHANNEL_ORDER_ARGB = 10, 277 HSA_EXT_IMAGE_CHANNEL_ORDER_ABGR = 11, 278 HSA_EXT_IMAGE_CHANNEL_ORDER_SRGB = 12, 279 HSA_EXT_IMAGE_CHANNEL_ORDER_SRGBX = 13, 280 HSA_EXT_IMAGE_CHANNEL_ORDER_SRGBA = 14, 281 HSA_EXT_IMAGE_CHANNEL_ORDER_SBGRA = 15, 282 HSA_EXT_IMAGE_CHANNEL_ORDER_INTENSITY = 16, 283 HSA_EXT_IMAGE_CHANNEL_ORDER_LUMINANCE = 17, 284 HSA_EXT_IMAGE_CHANNEL_ORDER_DEPTH = 18, 285 HSA_EXT_IMAGE_CHANNEL_ORDER_DEPTH_STENCIL = 19 286 } hsa_ext_image_channel_order_t; 287 288 /** 289 * @brief A fixed-size type used to represent ::hsa_ext_image_channel_order_t constants. 290 */ 291 typedef uint32_t hsa_ext_image_channel_order32_t; 292 293 294 /** 295 * @brief Image format. 296 */ 297 typedef struct hsa_ext_image_format_s { 298 /** 299 * Channel type. 300 */ 301 hsa_ext_image_channel_type32_t channel_type; 302 303 /** 304 * Channel order. 305 */ 306 hsa_ext_image_channel_order32_t channel_order; 307 } hsa_ext_image_format_t; 308 309 /** 310 * @brief Implementation independent image descriptor. 311 */ 312 typedef struct hsa_ext_image_descriptor_s { 313 /** 314 * Image geometry. 315 */ 316 hsa_ext_image_geometry_t geometry; 317 /** 318 * Width of the image, in components. 319 */ 320 size_t width; 321 /** 322 * Height of the image, in components. Only used if the geometry is 323 * ::HSA_EXT_IMAGE_GEOMETRY_2D, ::HSA_EXT_IMAGE_GEOMETRY_3D, 324 * HSA_EXT_IMAGE_GEOMETRY_2DA, HSA_EXT_IMAGE_GEOMETRY_2DDEPTH, or 325 * HSA_EXT_IMAGE_GEOMETRY_2DADEPTH, otherwise must be 0. 326 */ 327 size_t height; 328 /** 329 * Depth of the image, in components. Only used if the geometry is 330 * ::HSA_EXT_IMAGE_GEOMETRY_3D, otherwise must be 0. 331 */ 332 size_t depth; 333 /** 334 * Number of image layers in the image array. Only used if the geometry is 335 * ::HSA_EXT_IMAGE_GEOMETRY_1DA, ::HSA_EXT_IMAGE_GEOMETRY_2DA, or 336 * HSA_EXT_IMAGE_GEOMETRY_2DADEPTH, otherwise must be 0. 337 */ 338 size_t array_size; 339 /** 340 * Image format. 341 */ 342 hsa_ext_image_format_t format; 343 } hsa_ext_image_descriptor_t; 344 345 /** 346 * @brief Image capability. 347 */ 348 typedef enum { 349 /** 350 * Images of this geometry, format, and layout are not supported by 351 * the agent. 352 */ 353 HSA_EXT_IMAGE_CAPABILITY_NOT_SUPPORTED = 0x0, 354 /** 355 * Read-only images of this geometry, format, and layout are 356 * supported by the agent. 357 */ 358 HSA_EXT_IMAGE_CAPABILITY_READ_ONLY = 0x1, 359 /** 360 * Write-only images of this geometry, format, and layout are 361 * supported by the agent. 362 */ 363 HSA_EXT_IMAGE_CAPABILITY_WRITE_ONLY = 0x2, 364 /** 365 * Read-write images of this geometry, format, and layout are 366 * supported by the agent. 367 */ 368 HSA_EXT_IMAGE_CAPABILITY_READ_WRITE = 0x4, 369 /** 370 * @deprecated Images of this geometry, format, and layout can be accessed from 371 * read-modify-write atomic operations in the agent. 372 */ 373 HSA_EXT_IMAGE_CAPABILITY_READ_MODIFY_WRITE = 0x8, 374 /** 375 * Images of this geometry, format, and layout are guaranteed to 376 * have a consistent data layout regardless of how they are 377 * accessed by the associated agent. 378 */ 379 HSA_EXT_IMAGE_CAPABILITY_ACCESS_INVARIANT_DATA_LAYOUT = 0x10 380 } hsa_ext_image_capability_t; 381 382 /** 383 * @brief Image data layout. 384 * 385 * @details An image data layout denotes such aspects of image data 386 * layout as tiling and organization of channels in memory. Some image 387 * data layouts may only apply to specific image geometries, formats, 388 * and access permissions. Different agents may support different 389 * image layout identifiers, including vendor specific layouts. Note 390 * that an agent may not support the same image data layout for 391 * different access permissions to images with the same image 392 * geometry, size, and format. If multiple agents support the same 393 * image data layout then it is possible to use separate image handles 394 * for each agent that references the same image data. 395 */ 396 397 typedef enum { 398 /** 399 * An implementation specific opaque image data layout which can 400 * vary depending on the agent, geometry, image format, image size, 401 * and access permissions. 402 */ 403 HSA_EXT_IMAGE_DATA_LAYOUT_OPAQUE = 0x0, 404 /** 405 * The image data layout is specified by the following rules in 406 * ascending byte address order. For a 3D image, 2DA image array, 407 * or 1DA image array, the image data is stored as a linear sequence 408 * of adjacent 2D image slices, 2D images, or 1D images 409 * respectively, spaced according to the slice pitch. Each 2D image 410 * is stored as a linear sequence of adjacent image rows, spaced 411 * according to the row pitch. Each 1D or 1DB image is stored as a 412 * single image row. Each image row is stored as a linear sequence 413 * of image elements. Each image element is stored as a linear 414 * sequence of image components specified by the left to right 415 * channel order definition. Each image component is stored using 416 * the memory type specified by the channel type. 417 * 418 * The 1DB image geometry always uses the linear image data layout. 419 */ 420 HSA_EXT_IMAGE_DATA_LAYOUT_LINEAR = 0x1 421 } hsa_ext_image_data_layout_t; 422 423 /** 424 * @brief Retrieve the supported image capabilities for a given combination of 425 * agent, geometry, and image format for an image created with an opaque image 426 * data layout. 427 * 428 * @param[in] agent Agent to be associated with the image handle. 429 * 430 * @param[in] geometry Geometry. 431 * 432 * @param[in] image_format Pointer to an image format. Must not be NULL. 433 * 434 * @param[out] capability_mask Pointer to a memory location where the HSA 435 * runtime stores a bit-mask of supported image capability 436 * (::hsa_ext_image_capability_t) values. Must not be NULL. 437 * 438 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully. 439 * 440 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been 441 * initialized. 442 * 443 * @retval ::HSA_STATUS_ERROR_INVALID_AGENT The agent is invalid. 444 * 445 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p image_format is 446 * NULL, or @p capability_mask is NULL. 447 */ 448 hsa_status_t HSA_API hsa_ext_image_get_capability( 449 hsa_agent_t agent, 450 hsa_ext_image_geometry_t geometry, 451 const hsa_ext_image_format_t *image_format, 452 uint32_t *capability_mask); 453 454 /** 455 * @brief Retrieve the supported image capabilities for a given combination of 456 * agent, geometry, image format, and image layout for an image created with 457 * an explicit image data layout. 458 * 459 * @param[in] agent Agent to be associated with the image handle. 460 * 461 * @param[in] geometry Geometry. 462 * 463 * @param[in] image_format Pointer to an image format. Must not be NULL. 464 * 465 * @param[in] image_data_layout The image data layout. 466 * It is invalid to use ::HSA_EXT_IMAGE_DATA_LAYOUT_OPAQUE; use 467 * ::hsa_ext_image_get_capability instead. 468 * 469 * @param[out] capability_mask Pointer to a memory location where the HSA 470 * runtime stores a bit-mask of supported image capability 471 * (::hsa_ext_image_capability_t) values. Must not be NULL. 472 * 473 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully. 474 * 475 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been 476 * initialized. 477 * 478 * @retval ::HSA_STATUS_ERROR_INVALID_AGENT The agent is invalid. 479 * 480 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p image_format is 481 * NULL, @p image_data_layout is ::HSA_EXT_IMAGE_DATA_LAYOUT_OPAQUE, 482 * or @p capability_mask is NULL. 483 */ 484 hsa_status_t HSA_API hsa_ext_image_get_capability_with_layout( 485 hsa_agent_t agent, 486 hsa_ext_image_geometry_t geometry, 487 const hsa_ext_image_format_t *image_format, 488 hsa_ext_image_data_layout_t image_data_layout, 489 uint32_t *capability_mask); 490 491 /** 492 * @brief Agent specific image size and alignment requirements, populated by 493 * ::hsa_ext_image_data_get_info and ::hsa_ext_image_data_get_info_with_layout. 494 */ 495 typedef struct hsa_ext_image_data_info_s { 496 /** 497 * Image data size, in bytes. 498 */ 499 size_t size; 500 501 /** 502 * Image data alignment, in bytes. Must always be a power of 2. 503 */ 504 size_t alignment; 505 506 } hsa_ext_image_data_info_t; 507 508 /** 509 * @brief Retrieve the image data requirements for a given combination of agent, image 510 * descriptor, and access permission for an image created with an opaque image 511 * data layout. 512 * 513 * @details The optimal image data size and alignment requirements may 514 * vary depending on the image attributes specified in @p 515 * image_descriptor, the @p access_permission, and the @p agent. Also, 516 * different implementations of the HSA runtime may return different 517 * requirements for the same input values. 518 * 519 * The implementation must return the same image data requirements for 520 * different access permissions with matching image descriptors as long 521 * as ::hsa_ext_image_get_capability reports 522 * ::HSA_EXT_IMAGE_CAPABILITY_ACCESS_INVARIANT_DATA_LAYOUT. Image 523 * descriptors match if they have the same values, with the exception 524 * that s-form channel orders match the corresponding non-s-form 525 * channel order and vice versa. 526 * 527 * @param[in] agent Agent to be associated with the image handle. 528 * 529 * @param[in] image_descriptor Pointer to an image descriptor. Must not be NULL. 530 * 531 * @param[in] access_permission Access permission of the image when 532 * accessed by @p agent. The access permission defines how the agent 533 * is allowed to access the image and must match the corresponding 534 * HSAIL image handle type. The @p agent must support the image format 535 * specified in @p image_descriptor for the given @p 536 * access_permission. 537 * 538 * @param[out] image_data_info Memory location where the runtime stores the 539 * size and alignment requirements. Must not be NULL. 540 * 541 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully. 542 * 543 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been 544 * initialized. 545 * 546 * @retval ::HSA_STATUS_ERROR_INVALID_AGENT The agent is invalid. 547 * 548 * @retval ::HSA_EXT_STATUS_ERROR_IMAGE_FORMAT_UNSUPPORTED The @p 549 * agent does not support the image format specified by @p 550 * image_descriptor with the specified @p access_permission. 551 * 552 * @retval ::HSA_EXT_STATUS_ERROR_IMAGE_SIZE_UNSUPPORTED The agent 553 * does not support the image dimensions specified by @p 554 * image_descriptor with the specified @p access_permission. 555 * 556 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p image_descriptor is NULL, @p 557 * access_permission is not a valid access permission value, or @p 558 * image_data_info is NULL. 559 */ 560 hsa_status_t HSA_API hsa_ext_image_data_get_info( 561 hsa_agent_t agent, 562 const hsa_ext_image_descriptor_t *image_descriptor, 563 hsa_access_permission_t access_permission, 564 hsa_ext_image_data_info_t *image_data_info); 565 566 /** 567 * @brief Retrieve the image data requirements for a given combination of 568 * image descriptor, access permission, image data layout, image data row pitch, 569 * and image data slice pitch for an image created with an explicit image 570 * data layout. 571 * 572 * @details The image data size and alignment requirements may vary 573 * depending on the image attributes specified in @p image_descriptor, 574 * the @p access_permission, and the image layout. However, different 575 * implementations of the HSA runtime will return the same 576 * requirements for the same input values. 577 * 578 * The implementation must return the same image data requirements for 579 * different access permissions with matching image descriptors and 580 * matching image layouts as long as ::hsa_ext_image_get_capability 581 * reports 582 * ::HSA_EXT_IMAGE_CAPABILITY_ACCESS_INVARIANT_DATA_LAYOUT. Image 583 * descriptors match if they have the same values, with the exception 584 * that s-form channel orders match the corresponding non-s-form 585 * channel order and vice versa. Image layouts match if they are the 586 * same image data layout and use the same image row and slice pitch 587 * values. 588 * 589 * @param[in] image_descriptor Pointer to an image descriptor. Must not be NULL. 590 * 591 * @param[in] access_permission Access permission of the image when 592 * accessed by an agent. The access permission defines how the agent 593 * is allowed to access the image and must match the corresponding 594 * HSAIL image handle type. 595 * 596 * @param[in] image_data_layout The image data layout to use. 597 * It is invalid to use ::HSA_EXT_IMAGE_DATA_LAYOUT_OPAQUE; use 598 * ::hsa_ext_image_data_get_info instead. 599 * 600 * @param[in] image_data_row_pitch The size in bytes for a single row 601 * of the image in the image data. If 0 is specified then the default 602 * row pitch value is used: image width * image element byte size. 603 * The value used must be greater than or equal to the default row 604 * pitch, and be a multiple of the image element byte size. For the 605 * linear image layout it must also be a multiple of the image linear 606 * row pitch alignment for the agents that will access the image data 607 * using image instructions. 608 * 609 * @param[in] image_data_slice_pitch The size in bytes of a single 610 * slice of a 3D image, or the size in bytes of each image layer in an 611 * image array in the image data. If 0 is specified then the default 612 * slice pitch value is used: row pitch * height if geometry is 613 * ::HSA_EXT_IMAGE_GEOMETRY_3D, ::HSA_EXT_IMAGE_GEOMETRY_2DA, or 614 * ::HSA_EXT_IMAGE_GEOMETRY_2DADEPTH; row pitch if geometry is 615 * ::HSA_EXT_IMAGE_GEOMETRY_1DA; and 0 otherwise. The value used must 616 * be 0 if the default slice pitch is 0, be greater than or equal to 617 * the default slice pitch, and be a multiple of the row pitch. 618 * 619 * @param[out] image_data_info Memory location where the runtime stores the 620 * size and alignment requirements. Must not be NULL. 621 * 622 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully. 623 * 624 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been 625 * initialized. 626 * 627 * @retval ::HSA_EXT_STATUS_ERROR_IMAGE_FORMAT_UNSUPPORTED The image 628 * format specified by @p image_descriptor is not supported for the 629 * @p access_permission and @p image_data_layout specified. 630 * 631 * @retval ::HSA_EXT_STATUS_ERROR_IMAGE_SIZE_UNSUPPORTED The image 632 * dimensions specified by @p image_descriptor are not supported for 633 * the @p access_permission and @p image_data_layout specified. 634 * 635 * @retval ::HSA_EXT_STATUS_ERROR_IMAGE_PITCH_UNSUPPORTED The row and 636 * slice pitch specified by @p image_data_row_pitch and @p 637 * image_data_slice_pitch are invalid or not supported. 638 * 639 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p image_descriptor is 640 * NULL, @p image_data_layout is ::HSA_EXT_IMAGE_DATA_LAYOUT_OPAQUE, 641 * or @p image_data_info is NULL. 642 */ 643 hsa_status_t HSA_API hsa_ext_image_data_get_info_with_layout( 644 hsa_agent_t agent, 645 const hsa_ext_image_descriptor_t *image_descriptor, 646 hsa_access_permission_t access_permission, 647 hsa_ext_image_data_layout_t image_data_layout, 648 size_t image_data_row_pitch, 649 size_t image_data_slice_pitch, 650 hsa_ext_image_data_info_t *image_data_info); 651 652 /** 653 * @brief Creates an agent specific image handle to an image with an 654 * opaque image data layout. 655 * 656 * @details Images with an opaque image data layout created with 657 * different access permissions but matching image descriptors and 658 * same agent can share the same image data if 659 * ::HSA_EXT_IMAGE_CAPABILITY_ACCESS_INVARIANT_DATA_LAYOUT is reported 660 * by ::hsa_ext_image_get_capability for the image format specified in 661 * the image descriptor. Image descriptors match if they have the same 662 * values, with the exception that s-form channel orders match the 663 * corresponding non-s-form channel order and vice versa. 664 * 665 * If necessary, an application can use image operations (import, 666 * export, copy, clear) to prepare the image for the intended use 667 * regardless of the access permissions. 668 * 669 * @param[in] agent agent to be associated with the image handle created. 670 * 671 * @param[in] image_descriptor Pointer to an image descriptor. Must not be NULL. 672 * 673 * @param[in] image_data Image data buffer that must have been allocated 674 * according to the size and alignment requirements dictated by 675 * ::hsa_ext_image_data_get_info. Must not be NULL. 676 * 677 * Any previous memory contents are preserved upon creation. The application is 678 * responsible for ensuring that the lifetime of the image data exceeds that of 679 * all the associated images. 680 * 681 * @param[in] access_permission Access permission of the image when 682 * accessed by agent. The access permission defines how the agent 683 * is allowed to access the image using the image handle created and 684 * must match the corresponding HSAIL image handle type. The agent 685 * must support the image format specified in @p image_descriptor for 686 * the given @p access_permission. 687 * 688 * @param[out] image Pointer to a memory location where the HSA runtime stores 689 * the newly created image handle. Must not be NULL. 690 * 691 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully. 692 * 693 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been 694 * initialized. 695 * 696 * @retval ::HSA_STATUS_ERROR_INVALID_AGENT The agent is invalid. 697 * 698 * @retval ::HSA_EXT_STATUS_ERROR_IMAGE_FORMAT_UNSUPPORTED The agent 699 * does not have the capability to support the image format contained 700 * in @p image_descriptor using the specified @p access_permission. 701 * 702 * @retval ::HSA_EXT_STATUS_ERROR_IMAGE_SIZE_UNSUPPORTED The agent 703 * does not support the image dimensions specified by @p 704 * image_descriptor using the specified @p access_permission. 705 * 706 * @retval ::HSA_STATUS_ERROR_OUT_OF_RESOURCES The HSA runtime failed to allocate 707 * the required resources. 708 * 709 * support the creation of more image handles with the given @p access_permission). 710 * 711 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p image_descriptor is NULL, @p 712 * image_data is NULL, @p image_data does not have a valid alignment, 713 * @p access_permission is not a valid access permission 714 * value, or @p image is NULL. 715 */ 716 hsa_status_t HSA_API hsa_ext_image_create( 717 hsa_agent_t agent, 718 const hsa_ext_image_descriptor_t *image_descriptor, 719 const void *image_data, 720 hsa_access_permission_t access_permission, 721 hsa_ext_image_t *image); 722 723 /** 724 * @brief Creates an agent specific image handle to an image with an explicit 725 * image data layout. 726 * 727 * @details Images with an explicit image data layout created with 728 * different access permissions but matching image descriptors and 729 * matching image layout can share the same image data if 730 * ::HSA_EXT_IMAGE_CAPABILITY_ACCESS_INVARIANT_DATA_LAYOUT is reported 731 * by ::hsa_ext_image_get_capability_with_layout for the image format 732 * specified in the image descriptor and specified image data 733 * layout. Image descriptors match if they have the same values, with 734 * the exception that s-form channel orders match the corresponding 735 * non-s-form channel order and vice versa. Image layouts match if 736 * they are the same image data layout and use the same image row and 737 * slice values. 738 * 739 * If necessary, an application can use image operations (import, export, copy, 740 * clear) to prepare the image for the intended use regardless of the access 741 * permissions. 742 * 743 * @param[in] agent agent to be associated with the image handle created. 744 * 745 * @param[in] image_descriptor Pointer to an image descriptor. Must not be NULL. 746 * 747 * @param[in] image_data Image data buffer that must have been allocated 748 * according to the size and alignment requirements dictated by 749 * ::hsa_ext_image_data_get_info_with_layout. Must not be NULL. 750 * 751 * Any previous memory contents are preserved upon creation. The application is 752 * responsible for ensuring that the lifetime of the image data exceeds that of 753 * all the associated images. 754 * 755 * @param[in] access_permission Access permission of the image when 756 * accessed by the agent. The access permission defines how the agent 757 * is allowed to access the image and must match the corresponding 758 * HSAIL image handle type. The agent must support the image format 759 * specified in @p image_descriptor for the given @p access_permission 760 * and @p image_data_layout. 761 * 762 * @param[in] image_data_layout The image data layout to use for the 763 * @p image_data. It is invalid to use 764 * ::HSA_EXT_IMAGE_DATA_LAYOUT_OPAQUE; use ::hsa_ext_image_create 765 * instead. 766 * 767 * @param[in] image_data_row_pitch The size in bytes for a single row 768 * of the image in the image data. If 0 is specified then the default 769 * row pitch value is used: image width * image element byte size. 770 * The value used must be greater than or equal to the default row 771 * pitch, and be a multiple of the image element byte size. For the 772 * linear image layout it must also be a multiple of the image linear 773 * row pitch alignment for the agents that will access the image data 774 * using image instructions. 775 * 776 * @param[in] image_data_slice_pitch The size in bytes of a single 777 * slice of a 3D image, or the size in bytes of each image layer in an 778 * image array in the image data. If 0 is specified then the default 779 * slice pitch value is used: row pitch * height if geometry is 780 * ::HSA_EXT_IMAGE_GEOMETRY_3D, ::HSA_EXT_IMAGE_GEOMETRY_2DA, or 781 * ::HSA_EXT_IMAGE_GEOMETRY_2DADEPTH; row pitch if geometry is 782 * ::HSA_EXT_IMAGE_GEOMETRY_1DA; and 0 otherwise. The value used must 783 * be 0 if the default slice pitch is 0, be greater than or equal to 784 * the default slice pitch, and be a multiple of the row pitch. 785 * 786 * @param[out] image Pointer to a memory location where the HSA runtime stores 787 * the newly created image handle. Must not be NULL. 788 * 789 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully. 790 * 791 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been 792 * initialized. 793 * 794 * @retval ::HSA_STATUS_ERROR_INVALID_AGENT The agent is invalid. 795 * 796 * @retval ::HSA_EXT_STATUS_ERROR_IMAGE_FORMAT_UNSUPPORTED The agent does 797 * not have the capability to support the image format contained in the image 798 * descriptor using the specified @p access_permission and @p image_data_layout. 799 * 800 * @retval ::HSA_EXT_STATUS_ERROR_IMAGE_SIZE_UNSUPPORTED The agent 801 * does not support the image dimensions specified by @p 802 * image_descriptor using the specified @p access_permission and @p 803 * image_data_layout. 804 * 805 * @retval ::HSA_EXT_STATUS_ERROR_IMAGE_PITCH_UNSUPPORTED The agent does 806 * not support the row and slice pitch specified by @p image_data_row_pitch 807 * and @p image_data_slice_pitch, or the values are invalid. 808 * 809 * @retval ::HSA_STATUS_ERROR_OUT_OF_RESOURCES The HSA runtime failed to allocate 810 * the required resources. 811 * 812 * support the creation of more image handles with the given @p access_permission). 813 * 814 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p image_descriptor is NULL, @p 815 * image_data is NULL, @p image_data does not have a valid alignment, 816 * @p image_data_layout is ::HSA_EXT_IMAGE_DATA_LAYOUT_OPAQUE, 817 * or @p image is NULL. 818 */ 819 hsa_status_t HSA_API hsa_ext_image_create_with_layout( 820 hsa_agent_t agent, 821 const hsa_ext_image_descriptor_t *image_descriptor, 822 const void *image_data, 823 hsa_access_permission_t access_permission, 824 hsa_ext_image_data_layout_t image_data_layout, 825 size_t image_data_row_pitch, 826 size_t image_data_slice_pitch, 827 hsa_ext_image_t *image); 828 829 /** 830 * @brief Destroy an image handle previously created using ::hsa_ext_image_create or 831 * ::hsa_ext_image_create_with_layout. 832 * 833 * @details Destroying the image handle does not free the associated image data, 834 * or modify its contents. The application should not destroy an image handle while 835 * there are references to it queued for execution or currently being used in a 836 * kernel dispatch. 837 * 838 * @param[in] agent Agent associated with the image handle. 839 * 840 * @param[in] image Image handle to destroy. 841 * 842 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully. 843 * 844 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been 845 * initialized. 846 * 847 * @retval ::HSA_STATUS_ERROR_INVALID_AGENT The agent is invalid. 848 */ 849 hsa_status_t HSA_API hsa_ext_image_destroy( 850 hsa_agent_t agent, 851 hsa_ext_image_t image); 852 853 /** 854 * @brief Copies a portion of one image (the source) to another image (the 855 * destination). 856 * 857 * @details The source and destination image formats should be the 858 * same, with the exception that s-form channel orders match the 859 * corresponding non-s-form channel order and vice versa. For example, 860 * it is allowed to copy a source image with a channel order of 861 * HSA_EXT_IMAGE_CHANNEL_ORDER_SRGB to a destination image with a 862 * channel order of HSA_EXT_IMAGE_CHANNEL_ORDER_RGB. 863 * 864 * The source and destination images do not have to be of the same geometry and 865 * appropriate scaling is performed by the HSA runtime. It is possible to copy 866 * subregions between any combinations of source and destination geometries, provided 867 * that the dimensions of the subregions are the same. For example, it is 868 * allowed to copy a rectangular region from a 2D image to a slice of a 3D 869 * image. 870 * 871 * If the source and destination image data overlap, or the combination of 872 * offset and range references an out-out-bounds element in any of the images, 873 * the behavior is undefined. 874 * 875 * @param[in] agent Agent associated with both the source and destination image handles. 876 * 877 * @param[in] src_image Image handle of source image. The agent associated with the source 878 * image handle must be identical to that of the destination image. 879 * 880 * @param[in] src_offset Pointer to the offset within the source image where to 881 * copy the data from. Must not be NULL. 882 * 883 * @param[in] dst_image Image handle of destination image. 884 * 885 * @param[in] dst_offset Pointer to the offset within the destination 886 * image where to copy the data. Must not be NULL. 887 * 888 * @param[in] range Dimensions of the image portion to be copied. The HSA 889 * runtime computes the size of the image data to be copied using this 890 * argument. Must not be NULL. 891 * 892 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully. 893 * 894 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been 895 * initialized. 896 * 897 * @retval ::HSA_STATUS_ERROR_INVALID_AGENT The agent is invalid. 898 * 899 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p src_offset is 900 * NULL, @p dst_offset is NULL, or @p range is NULL. 901 */ 902 hsa_status_t HSA_API hsa_ext_image_copy( 903 hsa_agent_t agent, 904 hsa_ext_image_t src_image, 905 const hsa_dim3_t* src_offset, 906 hsa_ext_image_t dst_image, 907 const hsa_dim3_t* dst_offset, 908 const hsa_dim3_t* range); 909 910 /** 911 * @brief Image region. 912 */ 913 typedef struct hsa_ext_image_region_s { 914 /** 915 * Offset within an image (in coordinates). 916 */ 917 hsa_dim3_t offset; 918 919 /** 920 * Dimension size of the image range (in coordinates). The x, y, and z dimensions 921 * correspond to width, height, and depth or index respectively. 922 */ 923 hsa_dim3_t range; 924 } hsa_ext_image_region_t; 925 926 /** 927 * @brief Import a linearly organized image data from memory directly to an 928 * image handle. 929 * 930 * @details This operation updates the image data referenced by the image handle 931 * from the source memory. The size of the data imported from memory is 932 * implicitly derived from the image region. 933 * 934 * It is the application's responsibility to avoid out of bounds memory access. 935 * 936 * None of the source memory or destination image data memory can 937 * overlap. Overlapping of any of the source and destination image 938 * data memory within the import operation produces undefined results. 939 * 940 * @param[in] agent Agent associated with the image handle. 941 * 942 * @param[in] src_memory Source memory. Must not be NULL. 943 * 944 * @param[in] src_row_pitch The size in bytes of a single row of the image in the 945 * source memory. If the value is smaller than the destination image region 946 * width * image element byte size, then region width * image element byte 947 * size is used. 948 * 949 * @param[in] src_slice_pitch The size in bytes of a single 2D slice of a 3D image, 950 * or the size in bytes of each image layer in an image array in the source memory. 951 * If the geometry is ::HSA_EXT_IMAGE_GEOMETRY_1DA and the value is smaller than the 952 * value used for @p src_row_pitch, then the value used for @p src_row_pitch is used. 953 * If the geometry is ::HSA_EXT_IMAGE_GEOMETRY_3D, ::HSA_EXT_IMAGE_GEOMETRY_2DA, or 954 * HSA_EXT_IMAGE_GEOMETRY_2DADEPTH and the value is smaller than the value used for 955 * @p src_row_pitch * destination image region height, then the value used for 956 * @p src_row_pitch * destination image region height is used. 957 * Otherwise, the value is not used. 958 * 959 * @param[in] dst_image Image handle of destination image. 960 * 961 * @param[in] image_region Pointer to the image region to be updated. Must not 962 * be NULL. 963 * 964 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully. 965 * 966 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been 967 * initialized. 968 * 969 * @retval ::HSA_STATUS_ERROR_INVALID_AGENT The agent is invalid. 970 * 971 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p src_memory is NULL, or @p 972 * image_region is NULL. 973 * 974 */ 975 hsa_status_t HSA_API hsa_ext_image_import( 976 hsa_agent_t agent, 977 const void *src_memory, 978 size_t src_row_pitch, 979 size_t src_slice_pitch, 980 hsa_ext_image_t dst_image, 981 const hsa_ext_image_region_t *image_region); 982 983 /** 984 * @brief Export the image data to linearly organized memory. 985 * 986 * @details The operation updates the destination memory with the image data of 987 * @p src_image. The size of the data exported to memory is implicitly derived 988 * from the image region. 989 * 990 * It is the application's responsibility to avoid out of bounds memory access. 991 * 992 * None of the destination memory or source image data memory can 993 * overlap. Overlapping of any of the source and destination image 994 * data memory within the export operation produces undefined results. 995 * 996 * @param[in] agent Agent associated with the image handle. 997 * 998 * @param[in] src_image Image handle of source image. 999 * 1000 * @param[in] dst_memory Destination memory. Must not be NULL. 1001 * 1002 * @param[in] dst_row_pitch The size in bytes of a single row of the image in the 1003 * destination memory. If the value is smaller than the source image region 1004 * width * image element byte size, then region width * image element byte 1005 * size is used. 1006 * 1007 * @param[in] dst_slice_pitch The size in bytes of a single 2D slice of a 3D image, 1008 * or the size in bytes of each image in an image array in the destination memory. 1009 * If the geometry is ::HSA_EXT_IMAGE_GEOMETRY_1DA and the value is smaller than the 1010 * value used for @p dst_row_pitch, then the value used for @p dst_row_pitch is used. 1011 * If the geometry is ::HSA_EXT_IMAGE_GEOMETRY_3D, ::HSA_EXT_IMAGE_GEOMETRY_2DA, or 1012 * HSA_EXT_IMAGE_GEOMETRY_2DADEPTH and the value is smaller than the value used for 1013 * @p dst_row_pitch * source image region height, then the value used for 1014 * @p dst_row_pitch * source image region height is used. 1015 * Otherwise, the value is not used. 1016 * 1017 * @param[in] image_region Pointer to the image region to be exported. Must not 1018 * be NULL. 1019 * 1020 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully. 1021 * 1022 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been 1023 * initialized. 1024 * 1025 * @retval ::HSA_STATUS_ERROR_INVALID_AGENT The agent is invalid. 1026 * 1027 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p dst_memory is NULL, or @p 1028 * image_region is NULL. 1029 */ 1030 hsa_status_t HSA_API hsa_ext_image_export( 1031 hsa_agent_t agent, 1032 hsa_ext_image_t src_image, 1033 void *dst_memory, 1034 size_t dst_row_pitch, 1035 size_t dst_slice_pitch, 1036 const hsa_ext_image_region_t *image_region); 1037 1038 /** 1039 * @brief Clear a region of an image so that every image element has 1040 * the specified value. 1041 * 1042 * @param[in] agent Agent associated with the image handle. 1043 * 1044 * @param[in] image Image handle for image to be cleared. 1045 * 1046 * @param[in] data The value to which to set each image element being 1047 * cleared. It is specified as an array of image component values. The 1048 * number of array elements must match the number of access components 1049 * for the image channel order. The type of each array element must 1050 * match the image access type of the image channel type. When the 1051 * value is used to set the value of an image element, the conversion 1052 * method corresponding to the image channel type is used. See the 1053 * <em>Channel Order</em> section and <em>Channel Type</em> section in 1054 * the <em>HSA Programming Reference Manual</em> for more 1055 * information. Must not be NULL. 1056 * 1057 * @param[in] image_region Pointer to the image region to clear. Must not be 1058 * NULL. If the region references an out-out-bounds element, the behavior is 1059 * undefined. 1060 * 1061 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully. 1062 * 1063 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been 1064 * initialized. 1065 * 1066 * @retval ::HSA_STATUS_ERROR_INVALID_AGENT The agent is invalid. 1067 * 1068 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p data is NULL, or @p 1069 * image_region is NULL. 1070 */ 1071 hsa_status_t HSA_API hsa_ext_image_clear( 1072 hsa_agent_t agent, 1073 hsa_ext_image_t image, 1074 const void* data, 1075 const hsa_ext_image_region_t *image_region); 1076 1077 /** 1078 * @brief Sampler handle. Samplers are populated by 1079 * ::hsa_ext_sampler_create. Sampler handles are only unique within an 1080 * agent, not across agents. 1081 */ 1082 typedef struct hsa_ext_sampler_s { 1083 /** 1084 * Opaque handle. For a given agent, two handles reference the same object of 1085 * the enclosing type if and only if they are equal. 1086 */ 1087 uint64_t handle; 1088 } hsa_ext_sampler_t; 1089 1090 /** 1091 * @brief Sampler address modes. The sampler address mode describes 1092 * the processing of out-of-range image coordinates. See the 1093 * <em>Addressing Mode</em> section in the <em>HSA Programming Reference 1094 * Manual</em> for definitions on each address mode. The values 1095 * match the BRIG type @p hsa_ext_brig_sampler_addressing_t. 1096 */ 1097 typedef enum { 1098 /** 1099 * Out-of-range coordinates are not handled. 1100 */ 1101 HSA_EXT_SAMPLER_ADDRESSING_MODE_UNDEFINED = 0, 1102 1103 /** 1104 * Clamp out-of-range coordinates to the image edge. 1105 */ 1106 HSA_EXT_SAMPLER_ADDRESSING_MODE_CLAMP_TO_EDGE = 1, 1107 1108 /** 1109 * Clamp out-of-range coordinates to the image border color. 1110 */ 1111 HSA_EXT_SAMPLER_ADDRESSING_MODE_CLAMP_TO_BORDER = 2, 1112 1113 /** 1114 * Wrap out-of-range coordinates back into the valid coordinate 1115 * range so the image appears as repeated tiles. 1116 */ 1117 HSA_EXT_SAMPLER_ADDRESSING_MODE_REPEAT = 3, 1118 1119 /** 1120 * Mirror out-of-range coordinates back into the valid coordinate 1121 * range so the image appears as repeated tiles with every other 1122 * tile a reflection. 1123 */ 1124 HSA_EXT_SAMPLER_ADDRESSING_MODE_MIRRORED_REPEAT = 4 1125 1126 } hsa_ext_sampler_addressing_mode_t; 1127 1128 /** 1129 * @brief A fixed-size type used to represent ::hsa_ext_sampler_addressing_mode_t constants. 1130 */ 1131 typedef uint32_t hsa_ext_sampler_addressing_mode32_t; 1132 1133 /** 1134 * @brief Sampler coordinate normalization modes. See the 1135 * <em>Coordinate Normalization Mode</em> section in the <em>HSA 1136 * Programming Reference Manual</em> for definitions on each 1137 * coordinate normalization mode. The values match the BRIG type @p 1138 * hsa_ext_brig_sampler_coord_normalization_t. 1139 */ 1140 typedef enum { 1141 1142 /** 1143 * Coordinates are used to directly address an image element. 1144 */ 1145 HSA_EXT_SAMPLER_COORDINATE_MODE_UNNORMALIZED = 0, 1146 1147 /** 1148 * Coordinates are scaled by the image dimension size before being 1149 * used to address an image element. 1150 */ 1151 HSA_EXT_SAMPLER_COORDINATE_MODE_NORMALIZED = 1 1152 1153 } hsa_ext_sampler_coordinate_mode_t; 1154 1155 /** 1156 * @brief A fixed-size type used to represent ::hsa_ext_sampler_coordinate_mode_t constants. 1157 */ 1158 typedef uint32_t hsa_ext_sampler_coordinate_mode32_t; 1159 1160 1161 /** 1162 * @brief Sampler filter modes. See the <em>Filter Mode</em> section 1163 * in the <em>HSA Programming Reference Manual</em> for definitions 1164 * on each address mode. The enumeration values match the BRIG type @p 1165 * hsa_ext_brig_sampler_filter_t. 1166 */ 1167 typedef enum { 1168 /** 1169 * Filter to the image element nearest (in Manhattan distance) to the 1170 * specified coordinate. 1171 */ 1172 HSA_EXT_SAMPLER_FILTER_MODE_NEAREST = 0, 1173 1174 /** 1175 * Filter to the image element calculated by combining the elements in a 2x2 1176 * square block or 2x2x2 cube block around the specified coordinate. The 1177 * elements are combined using linear interpolation. 1178 */ 1179 HSA_EXT_SAMPLER_FILTER_MODE_LINEAR = 1 1180 1181 } hsa_ext_sampler_filter_mode_t; 1182 1183 /** 1184 * @brief A fixed-size type used to represent ::hsa_ext_sampler_filter_mode_t constants. 1185 */ 1186 typedef uint32_t hsa_ext_sampler_filter_mode32_t; 1187 1188 /** 1189 * @brief Implementation independent sampler descriptor. 1190 */ 1191 typedef struct hsa_ext_sampler_descriptor_s { 1192 /** 1193 * Sampler coordinate mode describes the normalization of image coordinates. 1194 */ 1195 hsa_ext_sampler_coordinate_mode32_t coordinate_mode; 1196 1197 /** 1198 * Sampler filter type describes the type of sampling performed. 1199 */ 1200 hsa_ext_sampler_filter_mode32_t filter_mode; 1201 1202 /** 1203 * Sampler address mode describes the processing of out-of-range image 1204 * coordinates. 1205 */ 1206 hsa_ext_sampler_addressing_mode32_t address_mode; 1207 1208 } hsa_ext_sampler_descriptor_t; 1209 1210 /** 1211 * @brief Create an agent specific sampler handle for a given agent 1212 * independent sampler descriptor and agent. 1213 * 1214 * @param[in] agent Agent to be associated with the sampler handle created. 1215 * 1216 * @param[in] sampler_descriptor Pointer to a sampler descriptor. Must not be 1217 * NULL. 1218 * 1219 * @param[out] sampler Memory location where the HSA runtime stores the newly 1220 * created sampler handle. Must not be NULL. 1221 * 1222 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully. 1223 * 1224 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been 1225 * initialized. 1226 * 1227 * @retval ::HSA_STATUS_ERROR_INVALID_AGENT The agent is invalid. 1228 * 1229 * @retval ::HSA_EXT_STATUS_ERROR_SAMPLER_DESCRIPTOR_UNSUPPORTED The 1230 * @p agent does not have the capability to support the properties 1231 * specified by @p sampler_descriptor or it is invalid. 1232 * 1233 * @retval ::HSA_STATUS_ERROR_OUT_OF_RESOURCES The HSA runtime failed to allocate 1234 * the required resources. 1235 * 1236 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p sampler_descriptor is NULL, or 1237 * @p sampler is NULL. 1238 */ 1239 hsa_status_t HSA_API hsa_ext_sampler_create( 1240 hsa_agent_t agent, 1241 const hsa_ext_sampler_descriptor_t *sampler_descriptor, 1242 hsa_ext_sampler_t *sampler); 1243 1244 /** 1245 * @brief Destroy a sampler handle previously created using ::hsa_ext_sampler_create. 1246 * 1247 * @details The sampler handle should not be destroyed while there are 1248 * references to it queued for execution or currently being used in a 1249 * kernel dispatch. 1250 * 1251 * @param[in] agent Agent associated with the sampler handle. 1252 * 1253 * @param[in] sampler Sampler handle to destroy. 1254 * 1255 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully. 1256 * 1257 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been 1258 * initialized. 1259 * 1260 * @retval ::HSA_STATUS_ERROR_INVALID_AGENT The agent is invalid. 1261 */ 1262 hsa_status_t HSA_API hsa_ext_sampler_destroy( 1263 hsa_agent_t agent, 1264 hsa_ext_sampler_t sampler); 1265 1266 1267 #define hsa_ext_images_1_00 1268 1269 /** 1270 * @brief The function pointer table for the images v1.00 extension. Can be returned by ::hsa_system_get_extension_table or ::hsa_system_get_major_extension_table. 1271 */ 1272 typedef struct hsa_ext_images_1_00_pfn_s { 1273 1274 hsa_status_t (*hsa_ext_image_get_capability)( 1275 hsa_agent_t agent, 1276 hsa_ext_image_geometry_t geometry, 1277 const hsa_ext_image_format_t *image_format, 1278 uint32_t *capability_mask); 1279 1280 hsa_status_t (*hsa_ext_image_data_get_info)( 1281 hsa_agent_t agent, 1282 const hsa_ext_image_descriptor_t *image_descriptor, 1283 hsa_access_permission_t access_permission, 1284 hsa_ext_image_data_info_t *image_data_info); 1285 1286 hsa_status_t (*hsa_ext_image_create)( 1287 hsa_agent_t agent, 1288 const hsa_ext_image_descriptor_t *image_descriptor, 1289 const void *image_data, 1290 hsa_access_permission_t access_permission, 1291 hsa_ext_image_t *image); 1292 1293 hsa_status_t (*hsa_ext_image_destroy)( 1294 hsa_agent_t agent, 1295 hsa_ext_image_t image); 1296 1297 hsa_status_t (*hsa_ext_image_copy)( 1298 hsa_agent_t agent, 1299 hsa_ext_image_t src_image, 1300 const hsa_dim3_t* src_offset, 1301 hsa_ext_image_t dst_image, 1302 const hsa_dim3_t* dst_offset, 1303 const hsa_dim3_t* range); 1304 1305 hsa_status_t (*hsa_ext_image_import)( 1306 hsa_agent_t agent, 1307 const void *src_memory, 1308 size_t src_row_pitch, 1309 size_t src_slice_pitch, 1310 hsa_ext_image_t dst_image, 1311 const hsa_ext_image_region_t *image_region); 1312 1313 hsa_status_t (*hsa_ext_image_export)( 1314 hsa_agent_t agent, 1315 hsa_ext_image_t src_image, 1316 void *dst_memory, 1317 size_t dst_row_pitch, 1318 size_t dst_slice_pitch, 1319 const hsa_ext_image_region_t *image_region); 1320 1321 hsa_status_t (*hsa_ext_image_clear)( 1322 hsa_agent_t agent, 1323 hsa_ext_image_t image, 1324 const void* data, 1325 const hsa_ext_image_region_t *image_region); 1326 1327 hsa_status_t (*hsa_ext_sampler_create)( 1328 hsa_agent_t agent, 1329 const hsa_ext_sampler_descriptor_t *sampler_descriptor, 1330 hsa_ext_sampler_t *sampler); 1331 1332 hsa_status_t (*hsa_ext_sampler_destroy)( 1333 hsa_agent_t agent, 1334 hsa_ext_sampler_t sampler); 1335 1336 } hsa_ext_images_1_00_pfn_t; 1337 1338 #define hsa_ext_images_1 1339 1340 /** 1341 * @brief The function pointer table for the images v1 extension. Can be returned by ::hsa_system_get_extension_table or ::hsa_system_get_major_extension_table. 1342 */ 1343 typedef struct hsa_ext_images_1_pfn_s { 1344 1345 hsa_status_t (*hsa_ext_image_get_capability)( 1346 hsa_agent_t agent, 1347 hsa_ext_image_geometry_t geometry, 1348 const hsa_ext_image_format_t *image_format, 1349 uint32_t *capability_mask); 1350 1351 hsa_status_t (*hsa_ext_image_data_get_info)( 1352 hsa_agent_t agent, 1353 const hsa_ext_image_descriptor_t *image_descriptor, 1354 hsa_access_permission_t access_permission, 1355 hsa_ext_image_data_info_t *image_data_info); 1356 1357 hsa_status_t (*hsa_ext_image_create)( 1358 hsa_agent_t agent, 1359 const hsa_ext_image_descriptor_t *image_descriptor, 1360 const void *image_data, 1361 hsa_access_permission_t access_permission, 1362 hsa_ext_image_t *image); 1363 1364 hsa_status_t (*hsa_ext_image_destroy)( 1365 hsa_agent_t agent, 1366 hsa_ext_image_t image); 1367 1368 hsa_status_t (*hsa_ext_image_copy)( 1369 hsa_agent_t agent, 1370 hsa_ext_image_t src_image, 1371 const hsa_dim3_t* src_offset, 1372 hsa_ext_image_t dst_image, 1373 const hsa_dim3_t* dst_offset, 1374 const hsa_dim3_t* range); 1375 1376 hsa_status_t (*hsa_ext_image_import)( 1377 hsa_agent_t agent, 1378 const void *src_memory, 1379 size_t src_row_pitch, 1380 size_t src_slice_pitch, 1381 hsa_ext_image_t dst_image, 1382 const hsa_ext_image_region_t *image_region); 1383 1384 hsa_status_t (*hsa_ext_image_export)( 1385 hsa_agent_t agent, 1386 hsa_ext_image_t src_image, 1387 void *dst_memory, 1388 size_t dst_row_pitch, 1389 size_t dst_slice_pitch, 1390 const hsa_ext_image_region_t *image_region); 1391 1392 hsa_status_t (*hsa_ext_image_clear)( 1393 hsa_agent_t agent, 1394 hsa_ext_image_t image, 1395 const void* data, 1396 const hsa_ext_image_region_t *image_region); 1397 1398 hsa_status_t (*hsa_ext_sampler_create)( 1399 hsa_agent_t agent, 1400 const hsa_ext_sampler_descriptor_t *sampler_descriptor, 1401 hsa_ext_sampler_t *sampler); 1402 1403 hsa_status_t (*hsa_ext_sampler_destroy)( 1404 hsa_agent_t agent, 1405 hsa_ext_sampler_t sampler); 1406 1407 hsa_status_t (*hsa_ext_image_get_capability_with_layout)( 1408 hsa_agent_t agent, 1409 hsa_ext_image_geometry_t geometry, 1410 const hsa_ext_image_format_t *image_format, 1411 hsa_ext_image_data_layout_t image_data_layout, 1412 uint32_t *capability_mask); 1413 1414 hsa_status_t (*hsa_ext_image_data_get_info_with_layout)( 1415 hsa_agent_t agent, 1416 const hsa_ext_image_descriptor_t *image_descriptor, 1417 hsa_access_permission_t access_permission, 1418 hsa_ext_image_data_layout_t image_data_layout, 1419 size_t image_data_row_pitch, 1420 size_t image_data_slice_pitch, 1421 hsa_ext_image_data_info_t *image_data_info); 1422 1423 hsa_status_t (*hsa_ext_image_create_with_layout)( 1424 hsa_agent_t agent, 1425 const hsa_ext_image_descriptor_t *image_descriptor, 1426 const void *image_data, 1427 hsa_access_permission_t access_permission, 1428 hsa_ext_image_data_layout_t image_data_layout, 1429 size_t image_data_row_pitch, 1430 size_t image_data_slice_pitch, 1431 hsa_ext_image_t *image); 1432 1433 } hsa_ext_images_1_pfn_t; 1434 /** @} */ 1435 1436 #ifdef __cplusplus 1437 } // end extern "C" block 1438 #endif /*__cplusplus*/ 1439 1440 #endif 1441
Indexes created Fri Mar 27 00:22:57 UTC 2026