From a6e967f3d06a6b9d498b026e120060c00971a6ab Mon Sep 17 00:00:00 2001 From: Mark Callow <2244683+MarkCallow@users.noreply.github.com> Date: Fri, 22 Sep 2023 08:48:18 +0900 Subject: [PATCH] Major non-content documentation fixes. (#773) - Fix inter-class and intra-class cross-reference issues that appeared with Doxygen 1.9.7 caused partially by the presence of the same-named ktxTexture macro. Fixed by changing TYPEDEF_HIDES_STRUCT from YES to NO in config. - Fix intra-class ktxTexture references broken due to presence of the same-named ktxTexture macro. Fixed by using fully qualified "class" names. - Fix many, but by no means all, of the remaining references broken by Doxygen 1.9.6's requirement for fully qualified "class" names for inter-class references. - Move methods incorrectly labelled as belonging to ktxTexture to their correct ktxTexture1 "class". - Restore Topics item to Doxygen navindex for access to the *Loader, Reader and Writer groups. - Remove confusions caused by use of @copydetails across classes. - Document the ktxTexture macro. --- cmake/docs.cmake | 7 ++-- include/ktx.h | 14 +++++--- lib/gl_funcs.c | 82 ++++++++++++++++++++++----------------------- lib/texture.c | 68 ++++++++++--------------------------- lib/texture1.c | 41 +++++++++++------------ lib/texture2.c | 26 ++++++++------- lib/vkloader.c | 87 +++++++++++++++++++++++++----------------------- lib/writer1.c | 12 +++---- 8 files changed, 159 insertions(+), 178 deletions(-) diff --git a/cmake/docs.cmake b/cmake/docs.cmake index 09fc951c39..332642e5b7 100644 --- a/cmake/docs.cmake +++ b/cmake/docs.cmake @@ -23,7 +23,6 @@ set( DOXYGEN_SHOW_USED_FILES NO ) set( DOXYGEN_VERBATIM_HEADERS NO ) set( DOXYGEN_CLANG_ASSISTED_PARSING NO ) set( DOXYGEN_ALPHABETICAL_INDEX NO ) -set( DOXYGEN_HTML_TIMESTAMP YES ) set( DOXYGEN_DISABLE_INDEX YES ) set( DOXYGEN_DISABLE_INDEX NO ) set( DOXYGEN_GENERATE_TREEVIEW YES ) @@ -31,6 +30,10 @@ set( DOXYGEN_GENERATE_LATEX NO ) set( DOXYGEN_GENERATE_HTML YES ) set( DOXYGEN_GENERATE_MAN YES ) set( DOXYGEN_MAN_OUTPUT ../man ) +# This is to get timestamps with older versions of doxygen. +# older +set( DOXYGEN_HTML_TIMESTAMP YES ) +set( DOXYGEN_TIMESTAMP YES ) function( add_sources target sources ) # Make ${sources} show up in IDE/project @@ -66,7 +69,7 @@ function( CreateDocLibKTX ) set( DOXYGEN_PROJECT_NAME "libktx Reference" ) set( DOXYGEN_ALIASES error=\"\\par Errors\\n\" ) set( DOXYGEN_LAYOUT_FILE pkgdoc/libktxDoxyLayout.xml ) - set( DOXYGEN_TYPEDEF_HIDES_STRUCT YES ) + set( DOXYGEN_TYPEDEF_HIDES_STRUCT NO ) set( DOXYGEN_EXCLUDE lib/uthash.h ) set( DOXYGEN_EXCLUDE_PATTERNS ktxint.h ) set( DOXYGEN_EXAMPLE_PATH examples lib ) diff --git a/include/ktx.h b/include/ktx.h index fd321c3014..7eb82494a8 100644 --- a/include/ktx.h +++ b/include/ktx.h @@ -176,7 +176,7 @@ typedef enum ktx_error_code_e { KTX_FILE_WRITE_ERROR, /*!< An error occurred while writing to the file. */ KTX_GL_ERROR, /*!< GL operations resulted in an error. */ KTX_INVALID_OPERATION, /*!< The operation is not allowed in the current state. */ - KTX_INVALID_VALUE, /*!< A parameter value was not valid */ + KTX_INVALID_VALUE, /*!< A parameter value was not valid. */ KTX_NOT_FOUND, /*!< Requested metadata key or required dynamically loaded GPU function was not found. */ KTX_OUT_OF_MEMORY, /*!< Not enough memory to complete the operation. */ KTX_TRANSCODE_FAILED, /*!< Transcoding of block compressed texture failed. */ @@ -706,15 +706,21 @@ typedef struct ktxTexture2 { struct ktxTexture2_private* _private; /*!< Private data. */ } ktxTexture2; +/** + * @brief Helper for casting ktxTexture1 and ktxTexture2 to ktxTexture. + * + * Use with caution. + */ #define ktxTexture(t) ((ktxTexture*)t) /** * @memberof ktxTexture * @~English - * @brief Structure for passing texture information to ktxTexture1_Create() and - * ktxTexture2_Create(). + * @brief Structure for passing texture information to ktxTexture1\_Create() and + * ktxTexture2\_Create(). * - * @sa ktxTexture1_Create() and ktxTexture2_Create(). + * @sa @ref ktxTexture1::ktxTexture1\_Create() "ktxTexture1_Create()" + * @sa @ref ktxTexture2::ktxTexture2\_Create() "ktxTexture2_Create()" */ typedef struct { diff --git a/lib/gl_funcs.c b/lib/gl_funcs.c index c937eb1ff9..8947f0e0cb 100644 --- a/lib/gl_funcs.c +++ b/lib/gl_funcs.c @@ -102,7 +102,7 @@ struct glFuncPtrs gl; *(void **)(&gl.func) = LoadProcAddr(ktxOpenGLModuleHandle, #func); \ if ( !gl.func && required ) { \ fprintf(stderr, noloadmsg, #func); \ - return KTX_NOT_FOUND; \ + return KTX_NOT_FOUND; \ } #else #define GL_FUNCTION(type, func, required) \ @@ -112,55 +112,55 @@ struct glFuncPtrs gl; gl.func = (type)LoadProcAddr(ktxOpenGLModuleHandle, #func); \ if ( !gl.func && required) { \ fprintf(stderr, noloadmsg, #func); \ - return KTX_NOT_FOUND; \ + return KTX_NOT_FOUND; \ } #endif #if WINDOWS static HMODULE ktxFindOpenGL() { - HMODULE module = 0; + HMODULE module = 0; BOOL found; // Use GetModule not LoadLibrary so we only succeed if the process // has already loaded some OpenGL library. - // Check current module to see if we are statically linked to GL. - found = GetModuleHandleExA( - GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS, - (LPCSTR)ktxFindOpenGL, - &module - ); - if (found) { - if (LoadProcAddr(module, "glGetError") != NULL) - return module; - } - // Not statically linked. See what dll the process has loaded. - // Emulators probably also have opengl32.lib loaded so check that last. - found = GetModuleHandleExA( - 0, - "libGLESv2.dll", - &module - ); - if (found) return module; - found = GetModuleHandleExA( - 0, - "libGLES_CM.dll", - &module - ); - if (found) return module; - found = GetModuleHandleExA( - 0, - "opengl32.dll", - &module - ); - if (found) { - // Need wglGetProcAddr for non-OpenGL-2 functions. - wglGetProcAddressPtr = - (PFNWGLGETPROCADDRESS)LoadProcAddr(module, - "wglGetProcAddress"); - if (wglGetProcAddressPtr != NULL) + // Check current module to see if we are statically linked to GL. + found = GetModuleHandleExA( + GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS, + (LPCSTR)ktxFindOpenGL, + &module + ); + if (found) { + if (LoadProcAddr(module, "glGetError") != NULL) return module; - } - return module; // Keep the compiler happy! + } + // Not statically linked. See what dll the process has loaded. + // Emulators probably also have opengl32.lib loaded so check that last. + found = GetModuleHandleExA( + 0, + "libGLESv2.dll", + &module + ); + if (found) return module; + found = GetModuleHandleExA( + 0, + "libGLES_CM.dll", + &module + ); + if (found) return module; + found = GetModuleHandleExA( + 0, + "opengl32.dll", + &module + ); + if (found) { + // Need wglGetProcAddr for non-OpenGL-2 functions. + wglGetProcAddressPtr = + (PFNWGLGETPROCADDRESS)LoadProcAddr(module, + "wglGetProcAddress"); + if (wglGetProcAddressPtr != NULL) + return module; + } + return module; // Keep the compiler happy! } #endif @@ -171,7 +171,7 @@ ktxLoadOpenGLLibrary(void) return KTX_SUCCESS; ktxOpenGLModuleHandle = GetOpenGLModuleHandle(RTLD_LAZY); - if (ktxOpenGLModuleHandle == NULL) { + if (ktxOpenGLModuleHandle == NULL) { fprintf(stderr, "OpenGL lib not linked or loaded by application.\n"); // Normal use is for this constructor to be called by an // application that has completed OpenGL initialization. In that diff --git a/lib/texture.c b/lib/texture.c index 5dab9945c9..a4b046543f 100644 --- a/lib/texture.c +++ b/lib/texture.c @@ -8,7 +8,7 @@ /** * @internal - * @file writer.c + * @file texture.c * @~English * * @brief ktxTexture implementation. @@ -305,10 +305,13 @@ ktxDetermineFileType_(ktxStream* pStream, ktxFileType_* pFileType, /** * @memberof ktxTexture * @~English - * @brief Construct (initialize) a ktx1 or ktx2 texture according to the stream + * @brief Create a ktx1 or ktx2 texture according to the stream * data. * - * @copydetails ktxTexture_CreateFromStdioStream + * See @ref ktxTexture1::ktxTexture1_CreateFromStream + * "ktxTexture1_CreateFromStream" or + * @ref ktxTexture2::ktxTexture2_CreateFromStream + * "ktxTexture2_CreateFromStream" for details. */ KTX_error_code ktxTexture_CreateFromStream(ktxStream* pStream, @@ -359,7 +362,10 @@ ktxTexture_CreateFromStream(ktxStream* pStream, * @brief Create a ktxTexture1 or ktxTexture2 from a stdio stream according * to the stream data. * - * @copydetails ktxTexture1_CreateFromStdioStream() + * See @ref ktxTexture1::ktxTexture1_CreateFromStdioStream + * "ktxTexture1_CreateFromStdioStream" or + * @ref ktxTexture2::ktxTexture2_CreateFromStdioStream + * "ktxTexture2_CreateFromStdioStream" for details. */ KTX_error_code ktxTexture_CreateFromStdioStream(FILE* stdioStream, @@ -385,29 +391,10 @@ ktxTexture_CreateFromStdioStream(FILE* stdioStream, * @brief Create a ktxTexture1 or ktxTexture2 from a named KTX file according * to the file contents. * - * The address of a newly created ktxTexture reflecting the contents of the - * file is written to the location pointed at by @p newTex. - * - * The create flag KTX_TEXTURE_CREATE_LOAD_IMAGE_DATA_BIT should not be set, - * if the ktxTexture is ultimately to be uploaded to OpenGL or Vulkan. This - * will minimize memory usage by allowing, for example, loading the images - * directly from the source into a Vulkan staging buffer. - * - * The create flag KTX_TEXTURE_CREATE_RAW_KVDATA_BIT should not be used. It is - * provided solely to enable implementation of the @e libktx v1 API on top of - * ktxTexture. - * - * @param[in] filename pointer to a char array containing the file name. - * @param[in] createFlags bitmask requesting specific actions during creation. - * @param[in,out] newTex pointer to a location in which store the address of - * the newly created texture. - * - * @return KTX_SUCCESS on success, other KTX_* enum values on error. - - * @exception KTX_FILE_OPEN_FAILED The file could not be opened. - * @exception KTX_INVALID_VALUE @p filename is @c NULL. - * - * For other exceptions, see ktxTexture_CreateFromStdioStream(). + * See @ref ktxTexture1::ktxTexture1_CreateFromNamedFile + * "ktxTexture1_CreateFromNamedFile" or + * @ref ktxTexture2::ktxTexture2_CreateFromNamedFile + * "ktxTexture2_CreateFromNamedFile" for details. */ KTX_error_code ktxTexture_CreateFromNamedFile(const char* const filename, @@ -438,29 +425,10 @@ ktxTexture_CreateFromNamedFile(const char* const filename, * @brief Create a ktxTexture1 or ktxTexture2 from KTX-formatted data in memory * according to the data contents. * - * The address of a newly created ktxTexture reflecting the contents of the - * serialized KTX data is written to the location pointed at by @p newTex. - * - * The create flag KTX_TEXTURE_CREATE_LOAD_IMAGE_DATA_BIT should not be set, - * if the ktxTexture is ultimately to be uploaded to OpenGL or Vulkan. This - * will minimize memory usage by allowing, for example, loading the images - * directly from the source into a Vulkan staging buffer. - * - * The create flag KTX_TEXTURE_CREATE_RAW_KVDATA_BIT should not be used. It is - * provided solely to enable implementation of the @e libktx v1 API on top of - * ktxTexture. - * - * @param[in] bytes pointer to the memory containing the serialized KTX data. - * @param[in] size length of the KTX data in bytes. - * @param[in] createFlags bitmask requesting specific actions during creation. - * @param[in,out] newTex pointer to a location in which store the address of - * the newly created texture. - * - * @return KTX_SUCCESS on success, other KTX_* enum values on error. - * - * @exception KTX_INVALID_VALUE Either @p bytes is NULL or @p size is 0. - * - * For other exceptions, see ktxTexture_CreateFromStdioStream(). + * See @ref ktxTexture1::ktxTexture1_CreateFromMemory + * "ktxTexture1_CreateFromMemory" or + * @ref ktxTexture2::ktxTexture2_CreateFromMemory + * "ktxTexture2_CreateFromMemory" for details. */ KTX_error_code ktxTexture_CreateFromMemory(const ktx_uint8_t* bytes, ktx_size_t size, diff --git a/lib/texture1.c b/lib/texture1.c index 8420f402b2..23a6b7d9c5 100644 --- a/lib/texture1.c +++ b/lib/texture1.c @@ -614,7 +614,7 @@ ktxTexture1_Create(ktxTextureCreateInfo* createInfo, * @~English * @brief Create a ktxTexture1 from a stdio stream reading from a KTX source. * - * The address of a newly created ktxTexture1 reflecting the contents of the + * The address of a newly created texture reflecting the contents of the * stdio stream is written to the location pointed at by @p newTex. * * The create flag KTX_TEXTURE_CREATE_LOAD_IMAGE_DATA_BIT should not be set, @@ -673,12 +673,12 @@ ktxTexture1_CreateFromStdioStream(FILE* stdioStream, return result; } -/* +/** * @memberof ktxTexture1 * @~English * @brief Create a ktxTexture1 from a named KTX file. * - * The address of a newly created ktxTexture1 reflecting the contents of the + * The address of a newly created texture reflecting the contents of the * file is written to the location pointed at by @p newTex. * * The create flag KTX_TEXTURE_CREATE_LOAD_IMAGE_DATA_BIT should not be set, @@ -700,7 +700,7 @@ ktxTexture1_CreateFromStdioStream(FILE* stdioStream, * @exception KTX_FILE_OPEN_FAILED The file could not be opened. * @exception KTX_INVALID_VALUE @p filename is @c NULL. * - * For other exceptions, see ktxTexture_CreateFromStdioStream(). + * For other exceptions, see ktxTexture1_CreateFromStdioStream(). */ KTX_error_code ktxTexture1_CreateFromNamedFile(const char* const filename, @@ -731,7 +731,7 @@ ktxTexture1_CreateFromNamedFile(const char* const filename, * @~English * @brief Create a ktxTexture1 from KTX-formatted data in memory. * - * The address of a newly created ktxTexture1 reflecting the contents of the + * The address of a newly created texture reflecting the contents of the * serialized KTX data is written to the location pointed at by @p newTex. * * The create flag KTX_TEXTURE_CREATE_LOAD_IMAGE_DATA_BIT should not be set, @@ -753,7 +753,7 @@ ktxTexture1_CreateFromNamedFile(const char* const filename, * * @exception KTX_INVALID_VALUE Either @p bytes is NULL or @p size is 0. * - * For other exceptions, see ktxTexture_CreateFromStdioStream(). + * For other exceptions, see ktxTexture1_CreateFromStdioStream(). */ KTX_error_code ktxTexture1_CreateFromMemory(const ktx_uint8_t* bytes, ktx_size_t size, @@ -784,7 +784,7 @@ ktxTexture1_CreateFromMemory(const ktx_uint8_t* bytes, ktx_size_t size, * @~English * @brief Create a ktxTexture1 from KTX-formatted data from a `ktxStream`. * - * The address of a newly created ktxTexture1 reflecting the contents of the + * The address of a newly created texture reflecting the contents of the * serialized KTX data is written to the location pointed at by @p newTex. * * The create flag KTX_TEXTURE_CREATE_LOAD_IMAGE_DATA_BIT should not be set, @@ -796,19 +796,17 @@ ktxTexture1_CreateFromMemory(const ktx_uint8_t* bytes, ktx_size_t size, * provided solely to enable implementation of the @e libktx v1 API on top of * ktxTexture1. * - * @param[in] stream pointer to the stream to read KTX data from. + * @param[in] pStream pointer to the stream to read KTX data from. * @param[in] createFlags bitmask requesting specific actions during creation. * @param[in,out] newTex pointer to a location in which store the address of * the newly created texture. * * @return KTX_SUCCESS on success, other KTX_* enum values on error. * - * @exception KTX_INVALID_VALUE Either @p bytes is NULL or @p size is 0. - * - * For other exceptions, see ktxTexture_CreateFromStdioStream(). + * For exceptions, see ktxTexture1_CreateFromStdioStream(). */ KTX_error_code -ktxTexture1_CreateFromStream(ktxStream* stream, +ktxTexture1_CreateFromStream(ktxStream* pStream, ktxTextureCreateFlags createFlags, ktxTexture1** newTex) { @@ -820,7 +818,7 @@ ktxTexture1_CreateFromStream(ktxStream* stream, if (tex == NULL) return KTX_OUT_OF_MEMORY; - result = ktxTexture1_constructFromStream(tex, stream, createFlags); + result = ktxTexture1_constructFromStream(tex, pStream, createFlags); if (result == KTX_SUCCESS) *newTex = (ktxTexture1*)tex; else { @@ -1044,9 +1042,9 @@ ktxTexture1_glTypeSize(ktxTexture1* This) * @~English * @brief Iterate over the mip levels in a ktxTexture1 object. * - * This is almost identical to ktxTexture_IterateLevelFaces(). The difference is - * that the blocks of image data for non-array cube maps include all faces of - * a mip level. + * This is almost identical to @ref ktxTexture::ktxTexture_IterateLevelFaces + * "ktxTexture_IterateLevelFaces". The difference is that the blocks of image + * data for non-array cube maps include all faces of a mip level. * * This function works even if @p This->pData == 0 so it can be used to * obtain offsets and sizes for each level by callers who have loaded the data @@ -1114,11 +1112,12 @@ ktxTexture1_IterateLevels(ktxTexture1* This, PFNKTXITERCB iterCb, void* userdata * @brief Iterate over the images in a ktxTexture1 object while loading the * image data. * - * This operates similarly to ktxTexture_IterateLevelFaces() except that it - * loads the images from the ktxTexture1's source to a temporary buffer - * while iterating. The callback function must copy the image data if it - * wishes to preserve it as the temporary buffer is reused for each level and - * is freed when this function exits. + * This operates similarly to @ref ktxTexture::ktxTexture_IterateLevelFaces + * "ktxTexture_IterateLevelFaces" except that it loads the images from the + * ktxTexture1's source to a temporary buffer while iterating. The callback + * function must copy the image data if it wishes to preserve it as the + * temporary buffer is reused for each level and is freed when this function + * exits. * * This function is helpful for reducing memory usage when uploading the data * to a graphics API. diff --git a/lib/texture2.c b/lib/texture2.c index 2e881f1194..436f9bcf39 100644 --- a/lib/texture2.c +++ b/lib/texture2.c @@ -1953,15 +1953,17 @@ ktxTexture2_NeedsTranscoding(ktxTexture2* This) /** * @memberof ktxTexture2 * @~English - * @brief Return the total size in bytes of the uncompressed data of a ktxTexture2. - * - * If supercompressionScheme == KTX_SS_NONE or - * KTX_SS_BASIS_LZ, returns the value of @c This->dataSize - * else if supercompressionScheme == KTX_SS_ZSTD or KTX_SS_ZLIB, it returns the - * sum of the uncompressed sizes of each mip level plus space for the level padding. With no - * supercompression the data size and uncompressed data size are the same. For Basis - * supercompression the uncompressed size cannot be known until the data is transcoded - * so the compressed size is returned. + * @brief Return the total size in bytes of the uncompressed data of a + * ktxTexture2. + * + * If supercompressionScheme == @c KTX_SS_NONE or + * @c KTX_SS_BASIS_LZ, returns the value of @c This->dataSize + * else if supercompressionScheme == @c KTX_SS_ZSTD or @c KTX_SS_ZLIB, it + * returns the sum of the uncompressed sizes of each mip level plus space for + * the level padding. With no supercompression the data size and uncompressed + * data size are the same. For Basis supercompression the uncompressed size + * cannot be known until the data is transcoded so the compressed size is + * returned. * * @param[in] This pointer to the ktxTexture1 object of interest. */ @@ -2336,12 +2338,12 @@ ktxTexture2_inflateZLIBInt(ktxTexture2* This, ktx_uint8_t* pDeflatedData, * @~English * @brief Load all the image data from the ktxTexture2's source. * - * The data will be inflated if supercompressionScheme == KTX_SS_ZSTD or - * KTX_SS_ZLIB. + * The data will be inflated if supercompressionScheme == @c KTX_SS_ZSTD or + * @c KTX_SS_ZLIB. * The data is loaded into the provided buffer or to an internally allocated * buffer, if @p pBuffer is @c NULL. Callers providing their own buffer must * ensure the buffer large enough to hold the inflated data for files deflated - * with Zstd or ZLIB. See ktxTexture2_GetDataSizeUncompressed(). + * with Zstd or ZLIB. See ktxTexture2\_GetDataSizeUncompressed(). * * The texture's levelIndex, dataSize, DFD and supercompressionScheme will * all be updated after successful inflation to reflect the inflated data. diff --git a/lib/vkloader.c b/lib/vkloader.c index 7e7dbdb38f..145bc32ff6 100644 --- a/lib/vkloader.c +++ b/lib/vkloader.c @@ -34,6 +34,11 @@ #include "texture2.h" #include "vk_format.h" +/* + * N.B. See comment at top of ./glloader.c regarding references to + * "non0class" members in Doxygen comments. + */ + // Macro to check and display Vulkan return results. // Use when the only possible errors are caused by invalid usage by this loader. #if defined(_DEBUG) @@ -94,7 +99,8 @@ generateMipmaps(ktxVulkanTexture* vkTexture, ktxVulkanDeviceInfo* vdi, * * @return a pointer to the constructed ktxVulkanDeviceInfo. * - * @sa ktxVulkanDeviceInfo\_Construct(), ktxVulkanDeviceInfo\_Destroy() + * @sa ktxVulkanDeviceInfo\_Construct() + * @sa ktxVulkanDeviceInfo\_Destroy() */ ktxVulkanDeviceInfo* ktxVulkanDeviceInfo_Create(VkPhysicalDevice physicalDevice, VkDevice device, @@ -116,7 +122,8 @@ ktxVulkanDeviceInfo_Create(VkPhysicalDevice physicalDevice, VkDevice device, * * @return a pointer to the constructed ktxVulkanDeviceInfo. * - * @sa ktxVulkanDeviceInfo\_Construct(), ktxVulkanDeviceInfo\_Destroy() + * @sa ktxVulkanDeviceInfo\_Construct() + * @sa ktxVulkanDeviceInfo\_Destroy() */ ktxVulkanDeviceInfo* ktxVulkanDeviceInfo_CreateEx(VkInstance instance, @@ -149,19 +156,20 @@ ktxVulkanDeviceInfo_CreateEx(VkInstance instance, * device memory properties for ease of use when allocating device memory for * the images. * - * If @c VK_IMAGE_TILING_OPTIMAL will be passed to ktxTexture_VkUploadEx(), the + * If @c VK_IMAGE_TILING_OPTIMAL will be passed to ktxTexture\_VkUploadEx(), the * family of the @a queue parameter must support transfers. This is true if * any of @c VK_QUEUE_GRAPHICS_BIT, @c VK_QUEUE_COMPUTE_BIT or * @c VK_QUEUE_TRANSFER_BIT is set in the @c queueFlags property of the queue's * @c VkQueueFamilyProperties. If protected memory is being used, i.e * @c queueFlags has the @c VK_QUEUE_PROTECTED_BIT set, then - * @c VK_IMAGE_TILING_OPTIMAL must be passed to ktxTexture_VkUploadEx(). + * @c VK_IMAGE_TILING_OPTIMAL must be passed to ktxTexture\_VkUploadEx(). * - * VkImages created in VkUploadEx() will have @c VK_SHARING_MODE_EXCLUSIVE set. + * VkImages created in @ref ktxTexture::ktxTexture\_VkUploadEx() + * "ktxTexture_VkUploadEx()" will have @c VK_SHARING_MODE_EXCLUSIVE set. * Thus the resulting image will be usable only with queues of the same family * as @a queue. * - * Pass a valid ktxVulkanDeviceInfo* to any Vulkan KTX image loading + * Pass a valid ktxVulkanDeviceInfo\* to any Vulkan KTX image loading * function to provide it with the information. * * @returns KTX\_SUCCESS on success, other KTX\_\* enum values on error. @@ -221,7 +229,7 @@ do { \ if ((member).fun == NULL) { \ (member).fun = (PFN_##fun)ktxLoadVulkanFunction(#fun); \ if ((member).fun == NULL) { \ - return KTX_NOT_FOUND; \ + return KTX_NOT_FOUND; \ }\ } \ } while (0) @@ -231,7 +239,7 @@ do { \ if ((member).fun == NULL) { \ (member).fun = (PFN_##fun)((member).vkGetInstanceProcAddr)((instance), #fun); \ if ((member).fun == NULL) { \ - return KTX_NOT_FOUND; \ + return KTX_NOT_FOUND; \ }\ } \ } while (0) @@ -241,7 +249,7 @@ do { \ if ((member).fun == NULL) { \ (member).fun = (PFN_##fun)((member).vkGetDeviceProcAddr)((device), #fun); \ if ((member).fun == NULL) { \ - return KTX_NOT_FOUND; \ + return KTX_NOT_FOUND; \ }\ } \ } while (0) @@ -800,7 +808,7 @@ linearTilingPadCallback(int miplevel, int face, * @exception KTX_UNSUPPORTED_FEATURE Attempting to sparsely bind KTX textures * for the time being will report this error. * - * @sa ktxVulkanDeviceInfo_construct() + * @sa @ref ktxVulkanDeviceInfo::ktxVulkanDeviceInfo\_Construct "ktxVulkanDeviceInfo_Construct()" */ KTX_error_code ktxTexture_VkUploadEx_WithSuballocator(ktxTexture* This, ktxVulkanDeviceInfo* vdi, @@ -1436,11 +1444,9 @@ ktxTexture_VkUploadEx_WithSuballocator(ktxTexture* This, ktxVulkanDeviceInfo* vd * @~English * @brief Create a Vulkan image object from a ktxTexture object. * - * Calls ktxTexture_VkUploadEx_WithSuballocator() with no supplied suballocator - * callbacks. - * - * @sa ktxTexture_VkUploadEx_WithSuballocator() for details and use that for complete - * control. + * Calls @ref ktxTexture::ktxTexture\_VkUploadEx_WithSuballocator + * "ktxTexture_VkUploadEx_WithSuballocator()" with no supplied suballocator + * callbacks. Use that for complete control. */ KTX_error_code ktxTexture_VkUploadEx(ktxTexture* This, ktxVulkanDeviceInfo* vdi, @@ -1453,16 +1459,16 @@ ktxTexture_VkUploadEx(ktxTexture* This, ktxVulkanDeviceInfo* vdi, tiling, usageFlags, finalLayout, NULL); } -/** @memberof ktxTexture +/** + * @memberof ktxTexture * @~English * @brief Create a Vulkan image object from a ktxTexture object. * - * Calls ktxTexture_VkUploadEx() with the most commonly used options: - * VK_IMAGE_TILING_OPTIMAL, VK_IMAGE_USAGE_SAMPLED_BIT and - * VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL. - * - * @sa ktxTexture_VkUploadEx() for details and use that for complete - * control. + * Calls @ref ktxTexture::ktxTexture\_VkUploadEx "ktxTexture_VkUploadEx()" with + * the most commonly used options: @c VK_IMAGE_TILING_OPTIMAL, + * @c VK_IMAGE_USAGE_SAMPLED_BIT and + * @c VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL. Use that for complete + * control. */ KTX_error_code ktxTexture_VkUpload(ktxTexture* texture, ktxVulkanDeviceInfo* vdi, @@ -1478,7 +1484,8 @@ ktxTexture_VkUpload(ktxTexture* texture, ktxVulkanDeviceInfo* vdi, * @~English * @brief Create a Vulkan image object from a ktxTexture1 object. * - * This simplly calls ktxTexture_VkUploadEx_WithSuballocator. + * This simply calls @ref ktxTexture::ktxTexture\_VkUploadEx_WithSuballocator + * "ktxTexture_VkUploadEx_WithSuballocator()" * * @copydetails ktxTexture::ktxTexture_VkUploadEx_WithSuballocator */ @@ -1499,8 +1506,6 @@ ktxTexture1_VkUploadEx_WithSuballocator(ktxTexture1* This, ktxVulkanDeviceInfo* * @~English * @brief Create a Vulkan image object from a ktxTexture1 object. * - * This simplly calls ktxTexture_VkUploadEx. - * * @copydetails ktxTexture::ktxTexture_VkUploadEx */ KTX_error_code @@ -1518,12 +1523,10 @@ ktxTexture1_VkUploadEx(ktxTexture1* This, ktxVulkanDeviceInfo* vdi, * @~English * @brief Create a Vulkan image object from a ktxTexture1 object. * - * Calls ktxTexture_VkUploadEx() with the most commonly used options: - * VK_IMAGE_TILING_OPTIMAL, VK_IMAGE_USAGE_SAMPLED_BIT and - * VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL. - * - * @sa ktxTexture_VkUploadEx() for details and use that for complete - * control. + * Calls @ref ktxTexture::ktxTexture\_VkUploadEx "ktxTexture_VkUploadEx()" with + * the most commonly used options: @c VK_IMAGE_TILING_OPTIMAL, + * @c VK_IMAGE_USAGE_SAMPLED_BIT and + * @c VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL. Use that for complete control. */ KTX_error_code ktxTexture1_VkUpload(ktxTexture1* texture, ktxVulkanDeviceInfo* vdi, @@ -1539,7 +1542,8 @@ ktxTexture1_VkUpload(ktxTexture1* texture, ktxVulkanDeviceInfo* vdi, * @~English * @brief Create a Vulkan image object from a ktxTexture2 object. * - * This simplly calls ktxTexture_VkUploadEx_WithSuballocator. + * This simplly calls @ref ktxTexture::ktxTexture_VkUploadEx_WithSuballocator + * "ktxTexture_VkUploadEx_WithSuballocator()". * * @copydetails ktxTexture::ktxTexture_VkUploadEx_WithSuballocator */ @@ -1560,7 +1564,7 @@ ktxTexture2_VkUploadEx_WithSuballocator(ktxTexture2* This, ktxVulkanDeviceInfo* * @~English * @brief Create a Vulkan image object from a ktxTexture2 object. * - * This simplly calls ktxTexture_VkUploadEx. + * This simply calls @ref ktxTexture::ktxTexture\_VkUploadEx "ktxTexture_VkUploadEx()". * * @copydetails ktxTexture::ktxTexture_VkUploadEx */ @@ -1579,12 +1583,10 @@ ktxTexture2_VkUploadEx(ktxTexture2* This, ktxVulkanDeviceInfo* vdi, * @~English * @brief Create a Vulkan image object from a ktxTexture2 object. * - * Calls ktxTexture_VkUploadEx() with the most commonly used options: - * VK_IMAGE_TILING_OPTIMAL, VK_IMAGE_USAGE_SAMPLED_BIT and - * VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL. - * - * @sa ktxTexture2_VkUploadEx() for details and use that for complete - * control. + * Calls @ref ktxTexture::ktxTexture\_VkUploadEx "ktxTexture_VkUploadEx()" with + * the most commonly used options: @c VK_IMAGE_TILING_OPTIMAL, + * @c VK_IMAGE_USAGE_SAMPLED_BIT and + * @c VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL. Use that for complete control. */ KTX_error_code ktxTexture2_VkUpload(ktxTexture2* This, ktxVulkanDeviceInfo* vdi, @@ -1600,7 +1602,7 @@ ktxTexture2_VkUpload(ktxTexture2* This, ktxVulkanDeviceInfo* vdi, * @~English * @brief Return the VkFormat enum of a ktxTexture1 object. * - * @return The VkFormat of the ktxTexture. May return VK_FORMAT_UNDEFINED if + * @return The VkFormat of the texture object. May return VK_FORMAT_UNDEFINED if * there is no mapping from the GL internalformat and format. */ VkFormat @@ -1620,7 +1622,7 @@ ktxTexture1_GetVkFormat(ktxTexture1* This) * @~English * @brief Return the VkFormat enum of a ktxTexture2 object. * - * @copydetails ktxTexture1::ktxTexture1_GetVkFormat + * @return The VkFormat of the texture object. */ VkFormat ktxTexture2_GetVkFormat(ktxTexture2* This) @@ -1634,7 +1636,8 @@ ktxTexture2_GetVkFormat(ktxTexture2* This) * * In ordert to ensure that the Vulkan uploader is not linked into an application unless explicitly called, * this is not a virtual function. It determines the texture type then dispatches to the correct function. - * @copydetails ktxTexture1::ktxTexture1_GetVkFormat + * @sa @ref ktxTexture1::ktxTexture1_GetVkFormat "ktxTexture1_GetVkFormat()" + * @sa @ref ktxTexture2::ktxTexture2_GetVkFormat "ktxTexture2_GetVkFormat()" */ VkFormat ktxTexture_GetVkFormat(ktxTexture* This) diff --git a/lib/writer1.c b/lib/writer1.c index 2a531f2310..7408917705 100644 --- a/lib/writer1.c +++ b/lib/writer1.c @@ -146,7 +146,7 @@ ktxTexture1_setImageFromStream(ktxTexture1* This, ktx_uint32_t level, } /** - * @memberof ktxTexture + * @memberof ktxTexture1 * @~English * @brief Set image for level, layer, faceSlice from a stdio stream source. * @@ -192,7 +192,7 @@ ktxTexture1_SetImageFromStdioStream(ktxTexture1* This, ktx_uint32_t level, } /** - * @memberof ktxTexture + * @memberof ktxTexture1 * @~English * @brief Set image for level, layer, faceSlice from an image in memory. * @@ -240,7 +240,7 @@ ktxTexture1_SetImageFromMemory(ktxTexture1* This, ktx_uint32_t level, } /** - * @memberof ktxTexture + * @memberof ktxTexture1 * @~English * @brief Write a ktxTexture object to a ktxStream in KTX format. * @@ -356,7 +356,7 @@ ktxTexture1_WriteToStream(ktxTexture1* This, ktxStream* dststr) } /** - * @memberof ktxTexture + * @memberof ktxTexture1 * @~English * @brief Write a ktxTexture object to a stdio stream in KTX format. * @@ -393,7 +393,7 @@ ktxTexture1_WriteToStdioStream(ktxTexture1* This, FILE* dstsstr) } /** - * @memberof ktxTexture + * @memberof ktxTexture1 * @~English * @brief Write a ktxTexture object to a named file in KTX format. * @@ -433,7 +433,7 @@ ktxTexture1_WriteToNamedFile(ktxTexture1* This, const char* const dstname) } /** - * @memberof ktxTexture + * @memberof ktxTexture1 * @~English * @brief Write a ktxTexture object to block of memory in KTX format. *