pyktx (Python bindings for libktx) (KhronosGroup#698)

Add Python bindings, documentation and tests. Add to CI. Adds a manual Publish step for publishing to PyPl. See KhronosGroup#663 for details. Fixes KhronosGroup#663. Co-authored-by: Mark Callow <[email protected]>
KaperD · Nov 29, 2023 · c94d610 · c94d610
1 parent 4a08813
commit c94d610
Show file tree

Hide file tree

Showing 5 changed files with 59 additions and 20 deletions.
diff --git a/.gitignore b/.gitignore
@@ -39,6 +39,7 @@ version.h
 # Visual Studio
 .vs/
 CMakeSettings.json
+out/
 
 # Visual Studio Code
 .vscode/

diff --git a/.travis.yml b/.travis.yml
@@ -41,38 +41,41 @@ env:
     # them during CI. CI runs on x86_64 and there is a PostBuild command
     # that attempts to execute the compiled-for-m1 tests to have gtest
     # add the list of tests to the cmake test runner.
+    #
+    # FEATURE_PY is off for arm64 macOS because we'd need a cross-compiled version
+    # of Python for it to correctly build the Python extensions (the CI
+    # runs on x86_64)
     - CONFIGURATION=Debug,Release PLATFORM=macOS ARCHS=x86_64
-      FEATURE_DOC=ON FEATURE_JNI=ON FEATURE_LOADTESTS=OpenGL+Vulkan FEATURE_TOOLS=ON
-      FEATURE_TOOLS_CTS=ON LOADTESTS_USE_LOCAL_DEPENDENCIES=ON SUPPORT_SSE=ON
-      SUPPORT_OPENCL=OFF DEPLOY_DOCS=YES PACKAGE=YES
+      FEATURE_DOC=ON FEATURE_JNI=ON FEATURE_PY=ON FEATURE_LOADTESTS=OpenGL+Vulkan FEATURE_TOOLS=ON
+      FEATURE_TOOLS_CTS=ON LOADTESTS_USE_LOCAL_DEPENDENCIES=ON SUPPORT_SSE=ON SUPPORT_OPENCL=OFF DEPLOY_DOCS=YES PACKAGE=YES
     - CONFIGURATION=Release PLATFORM=macOS ARCHS=arm64
-      FEATURE_DOC=ON FEATURE_JNI=ON FEATURE_LOADTESTS=OpenGL+Vulkan FEATURE_TESTS=OFF
+      FEATURE_DOC=ON FEATURE_JNI=ON FEATURE_PY=OFF FEATURE_LOADTESTS=OpenGL+Vulkan FEATURE_TESTS=OFF
       FEATURE_TOOLS=ON FEATURE_TOOLS_CTS=OFF SUPPORT_SSE=ON SUPPORT_OPENCL=OFF PACKAGE=YES
 
     - CONFIGURATION=Release PLATFORM=macOS ARCHS=x86_64
-      FEATURE_DOC=OFF FEATURE_JNI=OFF FEATURE_LOADTESTS=OFF FEATURE_TOOLS=OFF
+      FEATURE_DOC=OFF FEATURE_JNI=OFF FEATURE_PY=OFF FEATURE_LOADTESTS=OFF FEATURE_TOOLS=OFF
       FEATURE_TOOLS_CTS=OFF SUPPORT_SSE=ON SUPPORT_OPENCL=ON
     - CONFIGURATION=Release PLATFORM=macOS ARCHS=arm64
-      FEATURE_DOC=OFF FEATURE_JNI=OFF FEATURE_LOADTESTS=OFF FEATURE_TESTS=OFF
+      FEATURE_DOC=OFF FEATURE_JNI=OFF FEATURE_PY=OFF FEATURE_LOADTESTS=OFF FEATURE_TESTS=OFF
       FEATURE_TOOLS=OFF FEATURE_TOOLS_CTS=OFF SUPPORT_SSE=ON SUPPORT_OPENCL=ON
 
     - CONFIGURATION=Release PLATFORM=macOS ARCHS=x86_64
-      FEATURE_DOC=OFF FEATURE_JNI=OFF FEATURE_LOADTESTS=OFF FEATURE_TOOLS=OFF
+      FEATURE_DOC=OFF FEATURE_JNI=OFF FEATURE_PY=OFF FEATURE_LOADTESTS=OFF FEATURE_TOOLS=OFF
       FEATURE_TOOLS_CTS=OFF SUPPORT_SSE=OFF SUPPORT_OPENCL=ON
     - CONFIGURATION=Release PLATFORM=macOS ARCHS=arm64
-      FEATURE_DOC=OFF FEATURE_JNI=OFF FEATURE_LOADTESTS=OFF FEATURE_TESTS=OFF
+      FEATURE_DOC=OFF FEATURE_JNI=OFF FEATURE_PY=OFF FEATURE_LOADTESTS=OFF FEATURE_TESTS=OFF
       FEATURE_TOOLS=OFF FEATURE_TOOLS_CTS=OFF SUPPORT_SSE=OFF SUPPORT_OPENCL=ON
 
     - CONFIGURATION=Release PLATFORM=macOS ARCHS=x86_64
-      FEATURE_DOC=OFF FEATURE_JNI=OFF FEATURE_LOADTESTS=OFF FEATURE_TOOLS=OFF
+      FEATURE_DOC=OFF FEATURE_JNI=OFF FEATURE_PY=OFF FEATURE_LOADTESTS=OFF FEATURE_TOOLS=OFF
       FEATURE_TOOLS_CTS=OFF SUPPORT_SSE=OFF SUPPORT_OPENCL=OFF
     - CONFIGURATION=Release PLATFORM=macOS ARCHS=arm64
-      FEATURE_DOC=OFF FEATURE_JNI=OFF FEATURE_LOADTESTS=OFF FEATURE_TESTS=OFF
+      FEATURE_DOC=OFF FEATURE_JNI=OFF FEATURE_PY=OFF FEATURE_LOADTESTS=OFF FEATURE_TESTS=OFF
       FEATURE_TOOLS=OFF FEATURE_TOOLS_CTS=OFF SUPPORT_SSE=OFF
       SUPPORT_OPENCL=OFF
 
     - CONFIGURATION=Debug,Release PLATFORM=iOS
-      FEATURE_DOC=OFF FEATURE_JNI=OFF FEATURE_LOADTESTS=OpenGL+Vulkan FEATURE_TOOLS=OFF
+      FEATURE_DOC=OFF FEATURE_JNI=OFF FEATURE_PY=OFF FEATURE_LOADTESTS=OpenGL+Vulkan FEATURE_TOOLS=OFF
       FEATURE_TOOLS_CTS=OFF SUPPORT_SSE=OFF SUPPORT_OPENCL=OFF PACKAGE=YES
 
 jobs:
@@ -83,36 +86,51 @@ jobs:
         - CHECK_REUSE: ONLY
     - os: linux
       dist: jammy
+      addons:
+        apt:
+          packages:
+            - python3
+            - python3-venv
       compiler: gcc # clang is tested by macOS build
       env:
         # NB: This must not have the fourth component of the version number.
         - VULKAN_SDK_VER: "1.3.243"
         - CMAKE_GEN: Ninja
         - CONFIGURATION=Debug
-          FEATURE_DOC=OFF FEATURE_JNI=ON FEATURE_LOADTESTS=OpenGL+Vulkan FEATURE_TOOLS=ON
+          FEATURE_DOC=OFF FEATURE_JNI=ON FEATURE_PY=ON FEATURE_LOADTESTS=OpenGL+Vulkan FEATURE_TOOLS=ON
           SUPPORT_SSE=ON SUPPORT_OPENCL=OFF WERROR=ON
     - os: linux
       dist: jammy
+      addons:
+        apt:
+          packages:
+            - python3
+            - python3-venv
       compiler: gcc
       #jdk: openjdk17 # Reminder to find correct way to select jdk 17
       env:
         # NB: This must not have the fourth component of the version number.
         - VULKAN_SDK_VER: "1.3.243"
         - CMAKE_GEN: Ninja
         - CONFIGURATION=Release
-          FEATURE_DOC=ON FEATURE_JNI=ON FEATURE_LOADTESTS=OpenGL+Vulkan FEATURE_TOOLS=ON
+          FEATURE_DOC=ON FEATURE_JNI=ON FEATURE_PY=ON FEATURE_LOADTESTS=OpenGL+Vulkan FEATURE_TOOLS=ON
           SUPPORT_SSE=ON SUPPORT_OPENCL=OFF WERROR=ON PACKAGE=YES
     - os: linux
       arch: arm64
       dist: jammy
+      addons:
+        apt:
+          packages:
+            - python3
+            - python3-venv
       compiler: gcc
       #jdk: openjdk17
       env:
         # NB: This must not have the fourth component of the version number.
         - VULKAN_SDK_VER: "1.3.243"
         - CMAKE_GEN: Ninja
         - CONFIGURATION=Release
-          FEATURE_DOC=ON FEATURE_JNI=ON FEATURE_LOADTESTS=OpenGL
+          FEATURE_DOC=ON FEATURE_JNI=ON FEATURE_PY=ON FEATURE_LOADTESTS=OpenGL
           FEATURE_TOOLS=ON FEATURE_TOOLS_CTS=OFF
           SUPPORT_SSE=OFF SUPPORT_OPENCL=OFF WERROR=ON PACKAGE=YES
     - os: linux
@@ -121,7 +139,7 @@ jobs:
       env:
         - CMAKE_GEN: Ninja
         - CONFIGURATION=Release
-          FEATURE_DOC=OFF FEATURE_JNI=OFF FEATURE_LOADTESTS=OFF
+          FEATURE_DOC=OFF FEATURE_JNI=OFF FEATURE_PY=OFF FEATURE_LOADTESTS=OFF
           FEATURE_TOOLS=OFF FEATURE_TOOLS_CTS=OFF
           SUPPORT_SSE=ON SUPPORT_OPENCL=ON WERROR=ON PACKAGE=NO
     - os: linux
@@ -130,7 +148,7 @@ jobs:
       env:
         - CMAKE_GEN: Ninja
         - CONFIGURATION=Release
-          FEATURE_DOC=OFF FEATURE_JNI=OFF FEATURE_LOADTESTS=OFF
+          FEATURE_DOC=OFF FEATURE_JNI=OFF FEATURE_PY=OFF FEATURE_LOADTESTS=OFF
           FEATURE_TOOLS=OFF FEATURE_TOOLS_CTS=OFF
           SUPPORT_SSE=OFF SUPPORT_OPENCL=ON WERROR=ON PACKAGE=NO
     - os: linux
@@ -139,7 +157,7 @@ jobs:
       env:
         - CMAKE_GEN: Ninja
         - CONFIGURATION=Release
-          FEATURE_DOC=OFF FEATURE_JNI=OFF FEATURE_LOADTESTS=OFF
+          FEATURE_DOC=OFF FEATURE_JNI=OFF FEATURE_PY=OFF FEATURE_LOADTESTS=OFF
           FEATURE_TOOLS=OFF FEATURE_TOOLS_CTS=OFF
           SUPPORT_SSE=OFF SUPPORT_OPENCL=OFF WERROR=ON PACKAGE=NO
     - os: linux
@@ -149,7 +167,7 @@ jobs:
       env:
         - WASM_BUILD=YES
         - CONFIGURATION=Debug
-          FEATURE_DOC=OFF FEATURE_JNI=OFF FEATURE_LOADTESTS=OpenGL
+          FEATURE_DOC=OFF FEATURE_JNI=OFF FEATURE_PY=OFF FEATURE_LOADTESTS=OpenGL
           SUPPORT_SSE=OFF SUPPORT_OPENCL=OFF WERROR=ON
     - os: linux
       dist: jammy
@@ -158,7 +176,7 @@ jobs:
       env:
         - WASM_BUILD=YES
         - CONFIGURATION=Release
-          FEATURE_DOC=OFF FEATURE_JNI=OFF FEATURE_LOADTESTS=OpenGL
+          FEATURE_DOC=OFF FEATURE_JNI=OFF FEATURE_PY=OFF FEATURE_LOADTESTS=OpenGL
           SUPPORT_SSE=OFF SUPPORT_OPENCL=OFF WERROR=ON PACKAGE=YES
 
 # Phase 1: Git clone - done automatically.
@@ -378,7 +396,7 @@ deploy:
 
   - provider: script
     edge: true
-    script: ruby ci_scripts/github_release.rb -s ${GITHUB_TOKEN} -r ${TRAVIS_REPO_SLUG} -c $REL_DESC_FILE -t ${TRAVIS_TAG} --overwrite true --draft true --prerelease true $BUILD_DIR/KTX-Software-*-*
+    script: ruby ci_scripts/github_release.rb -s ${GITHUB_TOKEN} -r ${TRAVIS_REPO_SLUG} -c $REL_DESC_FILE -t ${TRAVIS_TAG} --overwrite true --draft true --prerelease true $BUILD_DIR/KTX-Software-*-* $BUILD_DIR/interface/python_binding/dist/*.whl
     on:
       tags: true
       #branch: master

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -50,6 +50,7 @@ CMAKE_DEPENDENT_OPTION( KTX_FEATURE_TOOLS
 option( KTX_FEATURE_DOC "Create KTX documentation." OFF )
 option( KTX_FEATURE_STATIC_LIBRARY "Create static libraries (shared otherwise)." ${LIB_TYPE_DEFAULT} )
 option( KTX_FEATURE_JNI "Create Java bindings for libktx." OFF )
+option( KTX_FEATURE_PY "Create Python source distribution." OFF )
 option( KTX_FEATURE_TESTS "Create unit tests." ON )
 option( KTX_FEATURE_TOOLS_CTS "Enable KTX CLI Tools CTS tests (requires CTS submodule)." OFF )
 
@@ -731,6 +732,10 @@ if(KTX_FEATURE_JNI)
     add_subdirectory(interface/java_binding)
 endif()
 
+if(KTX_FEATURE_PY)
+    add_subdirectory(interface/python_binding)
+endif()
+
 create_version_header(lib ktx)
 create_version_file()
 

diff --git a/README.md b/README.md
@@ -48,6 +48,7 @@ Version 2 file. [`tools/ktx2ktx2`](https://github.com/KhronosGroup/KTX-Software/
 human readable form. [`tools/ktxinfo`](https://github.com/KhronosGroup/KTX-Software/tree/main/tools/ktxinfo)
 - *ktxsc* - a tool to supercompress a KTX Version 2 file that
 contains uncompressed images.[`tools/ktxsc`](https://github.com/KhronosGroup/KTX-Software/tree/main/tools/ktxsc)
+- *pyktx* - Python wrapper
 - *toktx* - a tool to create KTX files from PNG, Netpbm or JPEG format images. It supports mipmap generation, encoding to
 Basis Universal formats and Zstd supercompression.[`tools/toktx`](https://github.com/KhronosGroup/KTX-Software/tree/main/tools/toktx)
 

diff --git a/cmake/docs.cmake b/cmake/docs.cmake
@@ -189,6 +189,17 @@ function( CreateDocJSWrappers )
     add_docs_cmake_plus( jswrappers.doc pkgdoc/jswrappersDoxyLayout.xml )
 endfunction()
 
+# pyktxwrappers.doc
+function( CreateDocPyktxWrappers )
+    add_custom_command(
+        TARGET libktx.doc
+        POST_BUILD
+        COMMAND
+            ${CMAKE_COMMAND} -E copy_directory ${KTX_BUILD_DIR}/interface/python_binding/docs/html/pyktx/html ${KTX_BUILD_DIR}/docs/html/pyktx
+    )
+    add_dependencies( libktx.doc pyktx )
+endfunction()
+
 # ktxpkg.doc
 function( CreateDocKTX )
     set( DOXYGEN_PROJECT_NAME "Khronos Texture Software" )
@@ -215,6 +226,9 @@ endfunction()
 CreateDocLibKTX()
 CreateDocTools()
 CreateDocJSWrappers()
+if (KTX_FEATURE_PY)
+    CreateDocPyktxWrappers()
+endif()
 CreateDocKTX()
 
 add_dependencies( libktx.doc ktxpkg.doc ktx_version )