include/hsa_ext_image.h

   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