How do I integrate building (just) libktx(_read) into my own software?

[DanielGibson]

Hi,
I'd like to use libktx to read ktx/ktx2 files.
I'd like to build it (and only it, not the rest of KTX-Software) as part of my software (instead of building it separately and then linking it).
Is this possible?

I don't think I can disable all the things I don't want in CMake, for example, I don't want an ASTC encoder, and I don't think I need an ASTC decoder either[1] - but as far as I can tell CMake only offers the ASTENC_DECOMPRESSOR option to "enable astenc builds for decompression only", I didn't see an option to disable astenc entirely.
Furthermore, that option doesn't even work - when I set ASTCENC_DECOMPRESSOR, CMake fails:

CMake Error at CMakeLists.txt:1241 (set_property):
  set_property could not find TARGET astcenc-sse2-static.  Perhaps it has not
  yet been created.

and several additional similar errors.

This isn't really documented much as far as I can tell, but it seems like it even builds two libs: libktx.a and libktx_read.a (and also libobjUtil.a and libobj_basisu_cbind.a whatever those are for).
Probably libktx_read.a is what I want, but how can I build only that one?

I think it may be useful to have documentation explicitly on this usecase, which probably is most common for potential libktx users: Games need exactly this functionality, and so do texture/image viewers and similar software (I'm currently writing a texture viewer).

It might also be helpful if lib/ had its own CMakeLists.txt just for building the lib (explicitly allowing to build only libktx or libktx_read), so it's

1. possible to just use add_subdirectory(ktx-software/lib) in ones own CMake file
2. more obvious which source files are needed to build it so one can copy (only) the relevant parts of KTX-Software into ones own sourcedir

---

[1] and if I did, I'd probably try to integrate Androids decoder, like Basis Universal does, because it's just one source and one header file instead of.. all that stuff in external/astc-encoder.

[DanielGibson]

I also just noticed that build/libktx.a (on Linux) only includes astc_codec.cpp.o but not the actual astcenc files - those apparently are in build/external/astc-encoder/Source/libastcenc-sse2-static.a (or similar, depending on the ISA, I guess).
Shouldn't they be included in libktx.a, like basisu_*.cpp.o are?

(This isn't too relevant to my usecase, but probably for others that actually want to use libktx to encode or decode ASTC)

[DanielGibson]

Further questions:

• Why does ktx.h only include KTX_IDENTIFIER_REF which is for KTX1, not KTX2_IDENTIFIER_REF? That one is in ktxint.h which doesn't help users of the library
• How do you get the texture format of the data stored in the file? Ideally in a way that works the same for both KTX1 and KTX2.
  I mostly want this out of curiosity, but if anyone wants to use libktx with Direct3D or Metal, they need this (because they obviously can't use an included loader function like ktxTexture_GLUpload()).
  The libktx usage overview leaves out this critical detail in the "Reading a KTX file for non-GL and non-Vulkan Use" example: https://github.khronos.org/KTX-Software/libktx/index.html#readktx

[MarkCallow]

Sorry for the long delay. The astcenc files are not included in libktx.a because the astc-encoder project, which we include by way of cmake's add_subdirectory, builds a separate library. On macOS we use libtool to add the .o files from libastcenc*static.a to libktx. I do not know of a straightforward way to do this on Linux or Windows. In those cases, if your project is using CMake, the public interface of libktx will tell your project to also link with the astc-encoder library.

ktx.h includes KTX_IDENTIFIER_REF for historical reasons to avoid breaking code. It was needed for an earlier API. In the current API neither it nor KTX2_IDENTIFIER_REF are needed as you can query the object created from the KTX data.

[DanielGibson]

With some guessing and trial and error I integrated what's needed to build libktx_read, including a stripped-down CMakeLists.txt to build it:
https://github.com/DanielGibson/texview/tree/main/src/libs/ktx

Would still be good to have some official way to do this to make updating to new libktx versions (that may require additional source files) easier.

[DanielGibson]

I implemented some functions that would be useful as part of libktx, they all work for both KTX1 and KTX2. To implement them I had to use libktx internals - which in my case was possible because I'm linking it statically and have the source code integrated in my projects, people using it as a dynamic lib or even a prebuilt static lib probably could not do this without copying additional files from the libktx source into their project...

• uint32_t ktxTexture_GetVkFormat(const ktxTexture* tex) self-explanatory, I think?
• bool ktxTexture_GetOpenGLFormat(const ktxTexture* tex, GLint* glInternalFormat, GLenum* glBaseInternalformat, GLenum* glFormat, GLenum* glType) to get the OpenGL types you're interested in (set others to NULL)
• ktxTexture_FormatHasAlpha(const ktxTexture* tex) so I know whether to enable alpha blending for that texture or not
• bool ktxTexture_FormatIsSRGB(const ktxTexture* tex) so I know whether I have to call glEnable( GL_FRAMEBUFFER_SRGB ) before drawing
  • the implementation of this one maybe is a bit unorthodox =)
• const char* ktxTexture_GetFormatName(const ktxTexture* tex) in my texture viewer I use it to show information about the texture to the user, but generally it would be useful at least for error messages ("Couldn't load texture foo/bar.ktx, its type %s is unsupported", ktxTexture_GetFormatName(tex)).
  • I (ab)used vkFormatString() from lib/vkformat_str.c for this (and skip the "VK_FORMAT_" prefix), no idea if that gives the nicest-possible names, but it's better than nothing.

see https://github.com/DanielGibson/texview/blob/dev/src/libs/dg_libktx_extra.h

[MarkCallow]

Regarding these extra functions please submit a PR to add them to the library. A few changes will be needed. FormatHasAlpha should use the ktxTexture2_GetNumComponents and FormatIsSRGB the ktxTexture2_GetTransferFunction_e queries for ktx2 textures. Fix the FIXME at line 59. For GetFormatName I think it will be better to return the GL format name for ktx v1 and the VK format name for ktx v2. The mixture of GL and VK format names without prefixes that you have now will be confusing. It might be better to have two functions one that returns the VK name and one the GL name. A Vulkan program would use the former while a GL program would use the latter.

Do you have any ideas about adding functions to get DXGI and Metal formats? As with GL, we have code to generated suitable switches. The question is how to return the result and how to package the functions so that users of libktx not using these APIs do not need to have DXGI or Metal related stuff in their build environments.

[MarkCallow]

@DanielGibson, Have the PRs you submitted, PR #998 and PR #1012, helped the situation w.r.t configuring and building just libktx or libktx_read?

[MarkCallow]

I am marking this as the answer so the topic will show it has been answered. As there are multiple questions in this topic no one answer is truly THE answer.

[DanielGibson]

No they haven't, they just fixed general issues with the existing build

(Ok, the compile error when setting ASTENC_DECOMPRESSOR is worked around by not exposing that option anymore)

[MarkCallow]

When I developed the new JS wrapper for 4.4.0 I changed the ASTC code and build set up so that libktx_read now includes only the ASTC decompressor. I also made changes so that the obj_basisu_cbind target is only included if transcodetests are configured which in turn happens only if tests are configured. objUtil is still being built. The only part of that used by libktx is unused.h which can simply be added to the source list for the library. objUtil should only be included if KTX_FEATURE_TOOLS or KTX_FEATURE_LOADTEST_APPS are configured.

You can build just libktx by

set(KTX_FEATURE_TOOLS OFF)
set(KTX_FEATURE_TESTS OFF)
add_subdirectory(KTX-Software)

But I would be delighted to accept a PR to move the parts related to building the library from the root 'CMakeLists.txt' to one in the lib directory which is included in the root one via add_directory. The new CMakeLists could also let you specify building just the read-only library, just the read-write library or both.

[MarkCallow]

As of PR #1071 there is a CMake project for building just libktx.

[Wallby]

How do you use it?

I get an error because of these two sections:

KTX-Software/lib/CMakeLists.txt

Lines 39 to 47 in d578786

	if(PROJECT_IS_TOP_LEVEL)
	# Beware of using cmake_print_variables for variables with function
	# dependent values, e.g. ARGN and CMAKE_CURRENT_FUNCTION_LIST_DIR.
	include(CMakePrintHelpers)
	include(CMakeDependentOption)
	include(${KTX_ROOT_DIR}/cmake/codesign.cmake) # Needs APPLE_*_OS values.
	include(${KTX_ROOT_DIR}/cmake/cputypetest.cmake)
	endif()

KTX-Software/lib/CMakeLists.txt

Lines 94 to 96 in d578786

	if(NOT DEFINED CPU_ARCHITECTURE)
	set_target_processor_type(CPU_ARCHITECTURE)
	endif()

I.e. I am trying to do add_subdirectory(external/KTF-Software/lib) in a project, but the top level check means that set_target_processor_type is never defined, as it is in the file ${KTX_ROOT_DIR}/cmake/cputypetest.cmake.

[MarkCallow]

Ahh! That is a bug. Please open an issue for this. I don't want to convert this discussion because it contains a lot of unrelated stuff.

Our CI uses this as a top level project and as a subproject of the KTX-Software project which already includes all the things under PROJECT_IS_TOP_LEVEL. I'll have to find another way to determine if those things have been included already. Is your project including CMakePrintHelpers and CMakeDependentOption?

[Wallby]

Here it is: #1083

[MarkCallow]

#1083 fixed by PR #1089. Thanks again for reporting the issue.