Skip to content

Commit

Permalink
Major non-content documentation fixes. (#773)
Browse files Browse the repository at this point in the history 
- 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.
  • Loading branch information
@MarkCallow
MarkCallow authored Sep 21, 2023
1 parent a100217 commit e6a6a3b
Show file tree
Hide file tree
Showing 10 changed files with 180 additions and 198 deletions.
7 changes: 5 additions & 2 deletions cmake/docs.cmake
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,14 +23,17 @@ 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 )
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
Expand Down Expand Up @@ -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 )
Expand Down
14 changes: 10 additions & 4 deletions include/ktx.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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. */
Expand Down Expand Up @@ -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
{
Expand Down
82 changes: 41 additions & 41 deletions lib/gl_funcs.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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) \
Expand All @@ -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

Expand All @@ -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
Expand Down
40 changes: 20 additions & 20 deletions lib/glloader.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,8 +55,8 @@
* @example glloader.c
* This is an example of using the low-level ktxTexture API to create and load
* an OpenGL texture. It is a fragment of the code used by
* @ref ktxTexture1.ktxTexture1\_GLUpload "ktxTexture1_GLUpload" and
* @ref ktxTexture2.ktxTexture2\_GLUpload "ktxTexture2_GLUpload".
* @ref ktxTexture1::ktxTexture1\_GLUpload "ktxTexture1_GLUpload" and
* @ref ktxTexture2::ktxTexture2\_GLUpload "ktxTexture2_GLUpload".
*
* @code
* #include <ktx.h>
Expand All @@ -70,7 +70,7 @@
* ktxTexture1.ktxTexture1\_GLUpload "ktxTexture1_GLUpload" or
* @ref ktxTexture2.ktxTexture2\_GLUpload "ktxTexture2_GLUpload" based on the
* dimensionality and arrayness of the texture, is called from
* @ref ktxTexture.ktxTexture_IterateLevelFaces
* @ref ktxTexture::ktxTexture_IterateLevelFaces
* "ktxTexture_IterateLevelFaces" to upload the texture data to OpenGL.
* @snippet this imageCallbacks
*
Expand Down Expand Up @@ -854,17 +854,17 @@ ktxTexture_GLUploadPrivate(ktxTexture* This, ktx_glformatinfo* formatInfo,
* @~English
* @brief Create a GL texture object from a ktxTexture1 object.
*
* Sets the texture object's GL_TEXTURE_MAX_LEVEL parameter according to the
* Sets the texture object's GL\_TEXTURE\_MAX\_LEVEL parameter according to the
* number of levels in the KTX data, provided the context supports this feature.
*
* Unpacks compressed GL_ETC1_RGB8_OES and GL_ETC2_* format
* Unpacks compressed GL\_ETC1\_RGB8\_OES and GL\_ETC2\_\* format
* textures in software when the format is not supported by the GL context,
* provided the library has been compiled with SUPPORT_SOFTWARE_ETC_UNPACK
* provided the library has been compiled with @c SUPPORT_SOFTWARE_ETC_UNPACK
* defined as 1.
*
* It will also convert textures with legacy formats to their modern equivalents
* when the format is not supported by the GL context, provided the library
* has been compiled with SUPPORT_LEGACY_FORMAT_CONVERSION defined as 1.
* has been compiled with @c SUPPORT_LEGACY_FORMAT_CONVERSION defined as 1.
*
* @param[in] This handle of the ktxTexture to upload.
* @param[in,out] pTexture name of the GL texture object to load. If NULL or if
Expand All @@ -881,15 +881,15 @@ ktxTexture_GLUploadPrivate(ktxTexture* This, ktx_glformatinfo* formatInfo,
* glGetError when this function returns the error
* KTX_GL_ERROR. pGlerror can be NULL.
*
* @return KTX_SUCCESS on success, other KTX_* enum values on error.
* @return KTX\_SUCCESS on success, other KTX\_\* enum values on error.
*
* @exception KTX_GL_ERROR A GL error was raised by glBindTexture,
* glGenTextures or gl*TexImage*. The GL error
* will be returned in @p *glerror, if glerror
* is not @c NULL.
* @exception KTX_INVALID_VALUE @p This or @p target is @c NULL or the size of
* a mip level is greater than the size of the
* preceding level.
* @exception KTX_GL_ERROR A GL error was raised by glBindTexture,
* glGenTextures or gl*TexImage*. The GL error
* will be returned in @p *glerror, if glerror
* is not @c NULL.
* @exception KTX_NOT_FOUND A dynamically loaded OpenGL {,ES} function
* required by the loader was not found.
* @exception KTX_UNSUPPORTED_TEXTURE_TYPE The type of texture is not supported
Expand Down Expand Up @@ -944,12 +944,12 @@ ktxTexture1_GLUpload(ktxTexture1* This, GLuint* pTexture, GLenum* pTarget,
* @~English
* @brief Create a GL texture object from a ktxTexture2 object.
*
* Sets the texture object's GL_TEXTURE_MAX_LEVEL parameter according to the
* Sets the texture object's GL\_TEXTURE\_MAX\_LEVEL parameter according to the
* number of levels in the KTX data, provided the context supports this feature.
*
* Unpacks compressed GL_ETC1_RGB8_OES and GL_ETC2_* format
* Unpacks compressed GL\_ETC1\_RGB8\_OES and GL\_ETC2\_\* format
* textures in software when the format is not supported by the GL context,
* provided the library has been compiled with SUPPORT_SOFTWARE_ETC_UNPACK
* provided the library has been compiled with @c SUPPORT_SOFTWARE_ETC_UNPACK
* defined as 1.
*
* @param[in] This handle of the ktxTexture to upload.
Expand All @@ -967,15 +967,15 @@ ktxTexture1_GLUpload(ktxTexture1* This, GLuint* pTexture, GLenum* pTarget,
* glGetError when this function returns the error
* KTX_GL_ERROR. pGlerror can be NULL.
*
* @return KTX_SUCCESS on success, other KTX_* enum values on error.
* @return KTX\_SUCCESS on success, other KTX\_\* enum values on error.
*
* @exception KTX_GL_ERROR A GL error was raised by glBindTexture,
* glGenTextures or gl*TexImage*. The GL error
* will be returned in @p *glerror, if glerror
* is not @c NULL.
* @exception KTX_INVALID_VALUE @p This or @p target is @c NULL or the size of
* a mip level is greater than the size of the
* preceding level.
* @exception KTX_GL_ERROR A GL error was raised by glBindTexture,
* glGenTextures or gl*TexImage*. The GL error
* will be returned in @p *glerror, if glerror
* is not @c NULL.
* @exception KTX_NOT_FOUND A dynamically loaded OpenGL {,ES} function
* required by the loader was not found.
* @exception KTX_UNSUPPORTED_TEXTURE_TYPE The type of texture is not supported
Expand Down
68 changes: 18 additions & 50 deletions lib/texture.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

/**
* @internal
* @file writer.c
* @file texture.c
* @~English
*
* @brief ktxTexture implementation.
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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,
Expand All @@ -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,
Expand Down Expand Up @@ -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,
Expand Down
Loading

0 comments on commit e6a6a3b

Please sign in to comment.