Add JS bindings for full libktx (#874)

The PR makes the following minor API changes to libktx:
* Adds `ktxTexture_GetLevelSize` function.
* Makes the parameters to `ktxTexture[12]_Create` `const`.
* Adds `ktxTexture2_{GetPrimaries_e, SetOETF and SetPrimaries}`
functions.

It adds the following functions to the JS binding while modernizing and
greatly improving the binding code:
* A constructor equivalent to `ktxTexture_Create`.
* `createCopy`
* `findKeyValue`
* `getDataSize`
* `getOETF`
* `getPrimaries`
* `getImage` for retrieving an image from the texture. Fixes #288.
* `setImageFromMemory`
* `compressAstc`
* `compressBasis`
* `deflateZstd`
* `deflateZLIB`
* `addKVPairString` and `addKVPairByte`
* `deleteKVPair`
* `setOETF`
* `setPrimaries`
* `writeToMemory`

It makes available two bindings. First is a read-only binding,
`libktx_read.js` which has the previously available functions plus
`findKeyValue`, `getDataSize`, `getOETF`, `getPrimaries` and `getImage`.
The second, using the original name `libktx.js`, has functions for
creating new KTX texture objects and writing them to files.

The JS `ktxTexture` class has been renamed `texture` as typical usage is
with an Emscripten module instance name of `ktx` and `new
ktx.ktxTexture()` looks weird. Newly added classes do not have `ktx`
prefixes.

Compared to the Phasmatic bindings it:
* Removes `compressBasisU` which was bundling calls to
`ktxTexture2_CompressBasisEx`, `ktxTexture2_DeflateZstd`,
`ktxTexture2_WriteToMemory` and `ktxHashList_addKVPair`. Instead each
function now has a binding and can be called by the JS client.
* Removes `createFromBuffer` which was using parameters passed from
Javascript to determine the VKFormat and size of the texture then
creating it with `ktxTexture2_Create` and finally loading an image from
a passed ArrayBufferView into the texture via
`ktxTexture_SetImageFromMemory`. Instead a `ktxCreateInfo` can be
initialized in the JS code which can call `new ktxTexture` to create the
texture then call `setImageFromMemory` to put the image into the texture
object.

---------

Co-authored-by: Mark Callow <[email protected]>

Author: aqnuep

.reuse/dep5

@@ -170,7 +170,7 @@ Files: tests/webgl/libktx-gltf/*
 Copyright: 2020 Don McCurdy, Austin Eng, Shrek Shao, and Mark Callow
 License: Apache-2.0
 
-Files: tests/webgl/libktx-webgl/*
+Files: tests/webgl/libktx-webgl/* tests/webgl/libktx-read-webgl/*
 Copyright: 2020 Mark Callow
 License: Apache-2.0
 

BUILDING.md

@@ -290,9 +290,10 @@ cmake --build build-web
 
 To include the load test application into the build add `-DKTX_FEATURE_LOADTEST_APPS=ON` to either of the above configuration steps.
 
-Web builds create two additional targets:
+Web builds create three additional targets:
 
-- `ktx_js`, (libktx javascript wrapper)
+- `ktx_js` (libktx javascript wrapper - with write support)
+- `ktx_js_read` (libktx_read javascript wrapper - read-only)
 - `msc_basis_transcoder_js` (transcoder wrapper)
 
 > **Note:** The libktx wrapper does not use the transcoder wrapper. It directly uses the underlying c++ transcoder.
@@ -490,8 +491,10 @@ The following files related to the the VkFormat enum are generated from `vulkan_
 - lib/vkformat_typesize.c
 - lib/dfd/dfd2vk.inl
 - lib/dfd/vk2dfd.inl
-- interface/java_binding/src/main/java/org/khronos/ktxVkFormat.java
+- interface/java\_binding/src/main/java/org/khronos/ktxVkFormat.java
 - interface/python\_binding/pyktx/vk\_format.py
+- interface/js\_binding/vk\_format.inl
+
 
 The following files are generated from the mapping database in the KTX-Specification repo by `generate_format_switches.rb`:
 

CMakeLists.txt

@@ -911,19 +911,38 @@ if(EMSCRIPTEN)
     set(
         KTX_EMC_LINK_FLAGS
         --bind
+        --pre-js ${CMAKE_CURRENT_SOURCE_DIR}/interface/js_binding/class_compat.js
+        --extern-post-js ${CMAKE_CURRENT_SOURCE_DIR}/interface/js_binding/module_create_compat.js
         "SHELL:-s MODULARIZE=1"
+        "SHELL:-s EXPORTED_RUNTIME_METHODS=[\'GL\']"
+        "SHELL:-s GL_PREINITIALIZED_CONTEXT=1"
+    )
+
+    set(
+        KTX_JS_COMMON_SOURCE
+        interface/js_binding/ktx_wrapper.cpp
+        interface/js_binding/class_compat.js
+        interface/js_binding/module_create_compat.js
     )
 
-    add_executable( ktx_js interface/js_binding/ktx_wrapper.cpp )
-    target_link_libraries( ktx_js ktx_read )
-    target_include_directories( ktx_js PRIVATE $<TARGET_PROPERTY:ktx_read,INTERFACE_INCLUDE_DIRECTORIES> )
+    add_executable( ktx_js
+        ${KTX_JS_COMMON_SOURCE}
+        interface/js_binding/vk_format.inl
+    )
+    target_compile_definitions(ktx_js PUBLIC KTX_FEATURE_WRITE)
+    target_link_libraries( ktx_js ktx )
+    target_include_directories(
+        ktx_js
+    PRIVATE
+        ${CMAKE_CURRENT_SOURCE_DIR}/other_include
+        ${CMAKE_CURRENT_SOURCE_DIR}/lib
+        $<TARGET_PROPERTY:ktx,INTERFACE_INCLUDE_DIRECTORIES>
+    )
     target_link_options(
         ktx_js
     PUBLIC
         ${KTX_EMC_LINK_FLAGS}
-        "SHELL:-s EXPORT_NAME=LIBKTX"
-        "SHELL:-s EXPORTED_RUNTIME_METHODS=[\'GL\']"
-        "SHELL:-s GL_PREINITIALIZED_CONTEXT=1"
+        "SHELL:-s EXPORT_NAME=createKtxModule"
     )
     set_target_properties( ktx_js PROPERTIES OUTPUT_NAME "libktx")
 
@@ -945,6 +964,43 @@ if(EMSCRIPTEN)
         COMPONENT ktx_js
     )
 
+    add_executable( ktx_js_read
+        ${KTX_JS_COMMON_SOURCE}
+    )
+    target_link_libraries( ktx_js_read ktx_read )
+    target_include_directories(
+        ktx_js_read
+    PRIVATE
+        ${CMAKE_CURRENT_SOURCE_DIR}/other_include
+        ${CMAKE_CURRENT_SOURCE_DIR}/lib
+        $<TARGET_PROPERTY:ktx_read,INTERFACE_INCLUDE_DIRECTORIES>
+    )
+    target_link_options(
+        ktx_js_read
+    PUBLIC
+        ${KTX_EMC_LINK_FLAGS}
+        "SHELL:-s EXPORT_NAME=createKtxReadModule"
+    )
+    set_target_properties( ktx_js_read PROPERTIES OUTPUT_NAME "libktx_read")
+
+    add_custom_command(
+        TARGET ktx_js_read
+        POST_BUILD
+        COMMAND ${CMAKE_COMMAND} -E copy "$<TARGET_FILE_DIR:ktx_js_read>/$<TARGET_FILE_PREFIX:ktx_js_read>$<TARGET_FILE_BASE_NAME:ktx_js_read>.js" "${PROJECT_SOURCE_DIR}/tests/webgl"
+        COMMAND ${CMAKE_COMMAND} -E copy "$<TARGET_FILE_DIR:ktx_js_read>/$<TARGET_FILE_PREFIX:ktx_js_read>$<TARGET_FILE_BASE_NAME:ktx_js_read>.wasm" "${PROJECT_SOURCE_DIR}/tests/webgl"
+        COMMENT "Copy libktx_read.js and libktx_read.wasm to tests/webgl"
+    )
+
+    install(TARGETS ktx_js_read
+        RUNTIME
+            DESTINATION .
+            COMPONENT ktx_js_read
+    )
+    install(FILES ${CMAKE_BINARY_DIR}/libktx_read.wasm
+        DESTINATION .
+        COMPONENT ktx_js_read
+    )
+
     add_executable( msc_basis_transcoder_js interface/js_binding/transcoder_wrapper.cpp )
     target_link_libraries( msc_basis_transcoder_js ktx_read )
     target_include_directories( msc_basis_transcoder_js
@@ -1354,6 +1410,7 @@ elseif(WIN32)
 elseif(EMSCRIPTEN)
     set(CPACK_GENERATOR ZIP)
     set(CPACK_ARCHIVE_KTX_JS_FILE_NAME "${CMAKE_PROJECT_NAME}-${KTX_VERSION_FULL}-Web-libktx")
+    set(CPACK_ARCHIVE_KTX_JS_READ_FILE_NAME "${CMAKE_PROJECT_NAME}-${KTX_VERSION_FULL}-Web-libktx_read")
     set(CPACK_ARCHIVE_MSC_BASIS_TRANSCODER_JS_FILE_NAME "${CMAKE_PROJECT_NAME}-${KTX_VERSION_FULL}-Web-msc_basis_transcoder")
 
     set(CPACK_ARCHIVE_COMPONENT_INSTALL ON)
@@ -1405,6 +1462,7 @@ cpack_add_component_group(LoadTestApps
 if(EMSCRIPTEN)
     set(CPACK_COMPONENTS_ALL
         ktx_js
+        ktx_js_read
         msc_basis_transcoder_js
     )
 else()

cmake/mkvk.cmake

@@ -80,6 +80,7 @@ list(APPEND mkvkformatfiles_input
     scripts/mkvkformatfiles)
 list(APPEND mkvkformatfiles_output
     "${PROJECT_SOURCE_DIR}/interface/java_binding/src/main/java/org/khronos/ktx/VkFormat.java"
+    "${PROJECT_SOURCE_DIR}/interface/js_binding/vk_format.inl"
     "${PROJECT_SOURCE_DIR}/interface/python_binding/pyktx/vk_format.py"
     "${PROJECT_SOURCE_DIR}/lib/vkformat_enum.h"
     "${PROJECT_SOURCE_DIR}/lib/vkformat_typesize.c"

include/ktx.h

@@ -455,6 +455,8 @@ typedef ktx_size_t
     (KTX_APIENTRY* PFNKTEXGETDATASIZEUNCOMPRESSED)(ktxTexture* This);
 typedef ktx_size_t
     (KTX_APIENTRY* PFNKTEXGETIMAGESIZE)(ktxTexture* This, ktx_uint32_t level);
+typedef ktx_size_t
+    (KTX_APIENTRY* PFNKTEXGETLEVELSIZE)(ktxTexture* This, ktx_uint32_t level);
 typedef KTX_error_code
     (KTX_APIENTRY* PFNKTEXITERATELEVELS)(ktxTexture* This, PFNKTXITERCB iterCb,
                                          void* userdata);
@@ -506,6 +508,7 @@ typedef KTX_error_code
     PFNKTEXGETIMAGEOFFSET GetImageOffset;
     PFNKTEXGETDATASIZEUNCOMPRESSED GetDataSizeUncompressed;
     PFNKTEXGETIMAGESIZE GetImageSize;
+    PFNKTEXGETLEVELSIZE GetLevelSize;
     PFNKTEXITERATELEVELS IterateLevels;
     PFNKTEXITERATELOADLEVELFACES IterateLoadLevelFaces;
     PFNKTEXNEEDSTRANSCODING NeedsTranscoding;
@@ -557,6 +560,14 @@ typedef KTX_error_code
 #define ktxTexture_GetImageSize(This, level) \
             (This)->vtbl->GetImageSize(This, level)
 
+/**
+ * @~English
+ * @brief Helper for calling the GetImageSize virtual method of a ktxTexture.
+ * @copydoc ktxTexture2.ktxTexture2_GetImageSize
+ */
+#define ktxTexture_GetLevelSize(This, level) \
+            (This)->vtbl->GetLevelSize(This, level)
+
 /**
  * @~English
  * @brief Helper for calling the IterateLevels virtual method of a ktxTexture.
@@ -985,7 +996,7 @@ ktxTexture_IterateLevelFaces(ktxTexture* This, PFNKTXITERCB iterCb,
  * Create a new ktxTexture1.
  */
 KTX_API KTX_error_code KTX_APIENTRY
-ktxTexture1_Create(ktxTextureCreateInfo* createInfo,
+ktxTexture1_Create(const ktxTextureCreateInfo* const createInfo,
                    ktxTextureCreateStorageEnum storageAllocation,
                    ktxTexture1** newTex);
 
@@ -1046,7 +1057,7 @@ ktxTexture1_WriteKTX2ToStream(ktxTexture1* This, ktxStream *dststr);
  * Create a new ktxTexture2.
  */
 KTX_API KTX_error_code KTX_APIENTRY
-ktxTexture2_Create(ktxTextureCreateInfo* createInfo,
+ktxTexture2_Create(const ktxTextureCreateInfo* const createInfo,
                    ktxTextureCreateStorageEnum storageAllocation,
                    ktxTexture2** newTex);
 
@@ -1111,9 +1122,18 @@ ktxTexture2_GetColorModel_e(ktxTexture2* This);
 KTX_API ktx_bool_t KTX_APIENTRY
 ktxTexture2_GetPremultipliedAlpha(ktxTexture2* This);
 
+KTX_API khr_df_primaries_e KTX_APIENTRY
+ktxTexture2_GetPrimaries_e(ktxTexture2* This);
+
 KTX_API ktx_bool_t KTX_APIENTRY
 ktxTexture2_NeedsTranscoding(ktxTexture2* This);
 
+KTX_API ktx_error_code_e KTX_APIENTRY
+ktxTexture2_SetOETF(ktxTexture2* This, khr_df_transfer_e oetf);
+
+KTX_API ktx_error_code_e KTX_APIENTRY
+ktxTexture2_SetPrimaries(ktxTexture2* This, khr_df_primaries_e primaries);
+
 /**
  * @~English
  * @brief Flags specifiying UASTC encoding options.
@@ -1363,21 +1383,23 @@ typedef struct ktxBasisParams {
         /*!< A swizzle to apply before encoding. It must match the regular
              expression /^[rgba01]{4}$/. If both this and preSwizzle
              are specified ktxTexture_CompressBasisEx will raise
-             KTX_INVALID_OPERATION.
+             KTX_INVALID_OPERATION. Usable with both ETC1S and UASTC.
          */
     ktx_bool_t normalMap;
         /*!< Tunes codec parameters for better quality on normal maps (no
              selector RDO, no endpoint RDO) and sets the texture's DFD appropriately.
              Only valid for linear textures.
          */
     ktx_bool_t separateRGToRGB_A;
-        /*!< @deprecated. This was and is a no-op. 2-component inputs have always been
-             automatically separated using an "rrrg" inputSwizzle. @sa inputSwizzle and normalMode.
+        /*!< @deprecated. This was and is a no-op. 2-component inputs have
+            always been automatically separated using an "rrrg" inputSwizzle.
+            @sa inputSwizzle and normalMode.
          */
     ktx_bool_t preSwizzle;
         /*!< If the texture has @c KTXswizzle metadata, apply it before
              compressing. Swizzling, like @c rabb may yield drastically
-             different error metrics if done after supercompression.
+             different error metrics if done after supercompression. Usable
+             for both ETC1S and UASTC.
          */
     ktx_bool_t noEndpointRDO;
         /*!< Disable endpoint rate distortion optimizations. Slightly faster,

interface/js_binding/class_compat.js

@@ -0,0 +1,17 @@
+// -*- tab-width: 4; -*-
+// vi: set sw=2 ts=4 expandtab textwidth=80:
+
+//
+// Copyright 2024 Khronos Group, Inc.
+// SPDX-License-Identifier: Apache-2.0
+//
+
+// Provide old name for backward compatibility.
+
+Module.onRuntimeInitialized = function() {
+  Module['ktxTexture'] = Module.texture;
+  Module['ErrorCode'] = Module.error_code;
+  Module['TranscodeTarget'] = Module.texture_transcode_fmt;
+  Module['TranscodeFlags'] = Module.transcode_flag_bits;
+}
+