SWDEV-368553 - Update mipmap apis' comments (#3286)

Remove DEPRECATED(DEPRECATED_MSG) from mipmap Apis' comments. Add "This API is implemented on Windows, under development on Linux." in mipmap Apis' notes. Add DEPRECATED(DEPRECATED_MSG) to texture reference Apis. Change-Id: Ief4ea81941e25d21bcafd213b3a84a65eb23cf93
ROCm · Jul 9, 2023 · 22e9263 · 22e9263
1 parent 8b065da
commit 22e9263
Show file tree

Hide file tree

Showing 2 changed files with 113 additions and 103 deletions.
diff --git a/docs/.doxygen/mainpage.md b/docs/.doxygen/mainpage.md
@@ -24,7 +24,6 @@ This is the full HIP Runtime API reference. The API is organized into
 - @ref Clang
 - @ref Texture
   - @ref TextureD
-  - @ref TextureU
 - @ref Runtime
 - @ref Callback
 - @ref Graph

diff --git a/include/hip/hip_runtime_api.h b/include/hip/hip_runtime_api.h
@@ -4107,14 +4107,6 @@ hipError_t hipMalloc3D(hipPitchedPtr* pitchedDevPtr, hipExtent extent);
  *  @see hipMalloc, hipMallocPitch, hipFree, hipMallocArray, hipHostMalloc, hipHostFree
  */
 hipError_t hipFreeArray(hipArray* array);
-/**
- * @brief Frees a mipmapped array on the device
- *
- * @param[in] mipmappedArray - Pointer to mipmapped array to free
- *
- * @return #hipSuccess, #hipErrorInvalidValue
- */
-hipError_t hipFreeMipmappedArray(hipMipmappedArray_t mipmappedArray);
 /**
  *  @brief Allocate an array on the device.
  *
@@ -4128,36 +4120,6 @@ hipError_t hipFreeMipmappedArray(hipMipmappedArray_t mipmappedArray);
  */
 hipError_t hipMalloc3DArray(hipArray** array, const struct hipChannelFormatDesc* desc,
                             struct hipExtent extent, unsigned int flags);
-/**
- * @brief Allocate a mipmapped array on the device
- *
- * @param[out] mipmappedArray  - Pointer to allocated mipmapped array in device memory
- * @param[in]  desc            - Requested channel format
- * @param[in]  extent          - Requested allocation size (width field in elements)
- * @param[in]  numLevels       - Number of mipmap levels to allocate
- * @param[in]  flags           - Flags for extensions
- *
- * @return #hipSuccess, #hipErrorInvalidValue, #hipErrorMemoryAllocation
- */
-hipError_t hipMallocMipmappedArray(
-    hipMipmappedArray_t *mipmappedArray,
-    const struct hipChannelFormatDesc* desc,
-    struct hipExtent extent,
-    unsigned int numLevels,
-    unsigned int flags __dparm(0));
-/**
- * @brief Gets a mipmap level of a HIP mipmapped array
- *
- * @param[out] levelArray     - Returned mipmap level HIP array
- * @param[in]  mipmappedArray - HIP mipmapped array
- * @param[in]  level          - Mipmap level
- *
- * @return #hipSuccess, #hipErrorInvalidValue
- */
-hipError_t hipGetMipmappedArrayLevel(
-    hipArray_t *levelArray,
-    hipMipmappedArray_const_t mipmappedArray,
-    unsigned int level);
 /**
  * @brief Gets info about the specified array
  *
@@ -5437,22 +5399,6 @@ hipError_t hipExtLaunchKernel(const void* function_address, dim3 numBlocks, dim3
  *  This section describes the texture management functions of HIP runtime API.
  */
 
-/**
- * @brief  Binds a mipmapped array to a texture.
- *
- * @param [in] tex  pointer to the texture reference to bind
- * @param [in] mipmappedArray  memory mipmapped array on the device
- * @param [in] desc  opointer to the channel format
- *
- * @returns #hipSuccess, #hipErrorInvalidValue
- *
- */
-DEPRECATED(DEPRECATED_MSG)
-hipError_t hipBindTextureToMipmappedArray(
-    const textureReference* tex,
-    hipMipmappedArray_const_t mipmappedArray,
-    const hipChannelFormatDesc* desc);
-
 /**
  * @brief Creates a texture object.
  *
@@ -5602,13 +5548,125 @@ hipError_t hipTexObjectGetTextureDesc(
     HIP_TEXTURE_DESC* pTexDesc,
     hipTextureObject_t texObject);
 
+/**
+ * @brief Allocate a mipmapped array on the device.
+ *
+ * @param[out] mipmappedArray  - Pointer to allocated mipmapped array in device memory
+ * @param[in]  desc            - Requested channel format
+ * @param[in]  extent          - Requested allocation size (width field in elements)
+ * @param[in]  numLevels       - Number of mipmap levels to allocate
+ * @param[in]  flags           - Flags for extensions
+ *
+ * @return #hipSuccess, #hipErrorInvalidValue, #hipErrorMemoryAllocation
+ *
+ * @note  This API is implemented on Windows, under development on Linux.
+ *
+ */
+hipError_t hipMallocMipmappedArray(
+    hipMipmappedArray_t *mipmappedArray,
+    const struct hipChannelFormatDesc* desc,
+    struct hipExtent extent,
+    unsigned int numLevels,
+    unsigned int flags __dparm(0));
+
+/**
+ * @brief Frees a mipmapped array on the device.
+ *
+ * @param[in] mipmappedArray - Pointer to mipmapped array to free
+ *
+ * @return #hipSuccess, #hipErrorInvalidValue
+ *
+ * @note  This API is implemented on Windows, under development on Linux.
+ *
+ */
+hipError_t hipFreeMipmappedArray(hipMipmappedArray_t mipmappedArray);
+
+/**
+ * @brief Gets a mipmap level of a HIP mipmapped array.
+ *
+ * @param[out] levelArray     - Returned mipmap level HIP array
+ * @param[in]  mipmappedArray - HIP mipmapped array
+ * @param[in]  level          - Mipmap level
+ *
+ * @return #hipSuccess, #hipErrorInvalidValue
+ *
+ * @note  This API is implemented on Windows, under development on Linux.
+ *
+ */
+hipError_t hipGetMipmappedArrayLevel(
+    hipArray_t *levelArray,
+    hipMipmappedArray_const_t mipmappedArray,
+    unsigned int level);
+
+/**
+ * @brief Create a mipmapped array.
+ *
+ * @param [out] pHandle  pointer to mipmapped array
+ * @param [in] pMipmappedArrayDesc  mipmapped array descriptor
+ * @param [in] numMipmapLevels  mipmap level
+ *
+ * @returns #hipSuccess, #hipErrorNotSupported, #hipErrorInvalidValue
+ *
+ * @note  This API is implemented on Windows, under development on Linux.
+ */
+hipError_t hipMipmappedArrayCreate(
+    hipMipmappedArray_t* pHandle,
+    HIP_ARRAY3D_DESCRIPTOR* pMipmappedArrayDesc,
+    unsigned int numMipmapLevels);
+
+/**
+ * @brief Destroy a mipmapped array.
+ *
+ * @param [out] hMipmappedArray  pointer to mipmapped array to destroy
+ *
+ * @returns #hipSuccess, #hipErrorInvalidValue
+ *
+ * @note  This API is implemented on Windows, under development on Linux.
+ *
+ */
+hipError_t hipMipmappedArrayDestroy(hipMipmappedArray_t hMipmappedArray);
+
+/**
+ * @brief Get a mipmapped array on a mipmapped level.
+ *
+ * @param [in] pLevelArray Pointer of array
+ * @param [out] hMipMappedArray Pointer of mipmapped array on the requested mipmap level
+ * @param [out] level  Mipmap level
+ *
+ * @returns #hipSuccess, #hipErrorInvalidValue
+ *
+ * @note  This API is implemented on Windows, under development on Linux.
+ *
+ */
+hipError_t hipMipmappedArrayGetLevel(
+    hipArray_t* pLevelArray,
+    hipMipmappedArray_t hMipMappedArray,
+    unsigned int level);
+
 /**
  *
  *  @addtogroup TextureD Texture Management [Deprecated]
  *  @{
  *  @ingroup Texture
  *  This section describes the deprecated texture management functions of HIP runtime API.
  */
+
+/**
+ * @brief  Binds a mipmapped array to a texture.
+ *
+ * @param [in] tex  pointer to the texture reference to bind
+ * @param [in] mipmappedArray memory mipmapped array on the device
+ * @param [in] desc  opointer to the channel format
+ *
+ * @returns #hipSuccess, #hipErrorInvalidValue
+ *
+ */
+DEPRECATED(DEPRECATED_MSG)
+hipError_t hipBindTextureToMipmappedArray(
+    const textureReference* tex,
+    hipMipmappedArray_const_t mipmappedArray,
+    const hipChannelFormatDesc* desc);
+
 /**
  * @brief Gets the texture reference related with the symbol.
  *
@@ -5878,7 +5936,6 @@ DEPRECATED(DEPRECATED_MSG)
 hipError_t hipTexRefGetMipmapFilterMode(
     enum hipTextureFilterMode* pfm,
     const textureReference* texRef);
-DEPRECATED(DEPRECATED_MSG)
 /**
  * @brief Gets the mipmap level bias for a texture reference.
  *
@@ -5888,6 +5945,7 @@ DEPRECATED(DEPRECATED_MSG)
  * @warning This API is deprecated.
  *
  */
+DEPRECATED(DEPRECATED_MSG)
 hipError_t hipTexRefGetMipmapLevelBias(
     float* pbias,
     const textureReference* texRef);
@@ -6036,53 +6094,6 @@ hipError_t hipTexRefSetMipmappedArray(
     struct hipMipmappedArray* mipmappedArray,
     unsigned int Flags);
 
-/**
- *
- *  @addtogroup TextureU Texture Management [Not supported]
- *  @{
- *  @ingroup Texture
- *  This section describes the texture management functions currently unsupported in HIP runtime.
- */
-/**
- * @brief Create a mipmapped array.
- *
- * @param [out] pHandle  pointer to mipmapped array
- * @param [in] pMipmappedArrayDesc  mipmapped array descriptor
- * @param [in] numMipmapLevels  mipmap level
- *
- * @returns #hipSuccess, #hipErrorNotSupported, #hipErrorInvalidValue
- *
- */
-DEPRECATED(DEPRECATED_MSG)
-hipError_t hipMipmappedArrayCreate(
-    hipMipmappedArray_t* pHandle,
-    HIP_ARRAY3D_DESCRIPTOR* pMipmappedArrayDesc,
-    unsigned int numMipmapLevels);
-/**
- * @brief Destroy a mipmapped array.
- *
- * @param [out] hMipmappedArray  pointer to mipmapped array to destroy
- *
- * @returns #hipSuccess, #hipErrorInvalidValue
- *
- */
-DEPRECATED(DEPRECATED_MSG)
-hipError_t hipMipmappedArrayDestroy(hipMipmappedArray_t hMipmappedArray);
-/**
- * @brief Get a mipmapped array on a mipmapped level.
- *
- * @param [in] pLevelArray Pointer of array
- * @param [out] hMipMappedArray Pointer of mipmapped array on the requested mipmap level
- * @param [out] level  Mipmap level
- *
- * @returns #hipSuccess, #hipErrorInvalidValue
- *
- */
-DEPRECATED(DEPRECATED_MSG)
-hipError_t hipMipmappedArrayGetLevel(
-    hipArray_t* pLevelArray,
-    hipMipmappedArray_t hMipMappedArray,
-    unsigned int level);
 // doxygen end deprecated texture management
 /**
  * @}