Expose HDR support in Python binding (KhronosGroup#1150)

Fixes KhronosGroup#1145.

Additional fixes:
- Adds `num_layers` property that was curiously missing.
- Exposes ktxTexture[12]_IsHDR in the c API.
- Reformats documentation comments for UASTC HDR ktxBasisParams to
   reduce line width.

Author: MarkCallow

interface/python_binding/buildscript.py

@@ -81,11 +81,16 @@
                                       uint32_t faceSlice,
                                       void *src,
                                       size_t srcSize);
+    bool ktxTexture_IsHDR(ktxTexture *);
+    bool ktxTexture_IsTranscodable(ktxTexture *);
+    bool ktxTexture_NeedsTranscoding(ktxTexture *);
+    int ktxTexture2_DecodeAstc(void *);
     int ktxTexture2_TranscodeBasis(void *, int outputFormat, int transcodeFlags);
     int ktxTexture2_DeflateZstd(void *, uint32_t compressionLevel);
-    uint32_t ktxTexture2_GetOETF(void *);
+    uint32_t ktxTexture2_GetColorModel_e(void *);
+    uint32_t ktxTexture2_GetPrimaries_e(void *);
+    uint32_t ktxTexture2_GetTransferFunction_e(void *);
     bool ktxTexture2_GetPremultipliedAlpha(void *);
-    bool ktxTexture2_NeedsTranscoding(void *);
 
     int ktxHashList_AddKVPair(ktxHashList *, const char *key, unsigned int valueLen, const void *value);
     int ktxHashList_DeleteKVPair(ktxHashList *, const char *key);
@@ -108,6 +113,7 @@
     uint32_t PY_ktxTexture_get_baseHeight(ktxTexture *);
     uint32_t PY_ktxTexture_get_baseDepth(ktxTexture *);
     uint32_t PY_ktxTexture_get_numDimensions(ktxTexture *);
+    uint32_t PY_ktxTexture_get_numLayers(ktxTexture *);
     uint32_t PY_ktxTexture_get_numLevels(ktxTexture *);
     uint32_t PY_ktxTexture_get_numFaces(ktxTexture *);
     uint32_t PY_ktxTexture_get_kvDataLen(ktxTexture *);
@@ -159,7 +165,7 @@
                                       bool perceptual,
                                       char *inputSwizzle);
     int PY_ktxTexture2_CompressBasisEx(void *texture,
-                                       bool uastc,
+                                       uint32_t codec,
                                        bool verbose,
                                        bool noSSE,
                                        uint32_t threadCount,
@@ -182,7 +188,14 @@
                                        float uastcRDOMaxSmoothBlockErrorScale,
                                        float uastcRDOMaxSmoothBlockStdDev,
                                        bool uastcRDODontFavorSimplerModes,
-                                       bool uastcRDONoMultithreading);
+                                       bool uastcRDONoMultithreading,
+                                       uint32_t uastcHDRQuality,
+                                       bool uastcHDRUberMode,
+                                       bool uastcHDRUltraQuant,
+                                       bool uastcHDRFavorAstc,
+                                       bool rec2020,
+                                       float uastcHDRLambda,
+                                       uint32_t uastcHDRLevel);
     uint32_t PY_ktxTexture2_get_vkFormat(void *);
     uint32_t PY_ktxTexture2_get_supercompressionScheme(void *);
     """

interface/python_binding/conf.py

@@ -41,6 +41,7 @@
     'sphinx.ext.napoleon',
 ]
 
+autodoc_member_order = 'bysource'
 templates_path = ['_templates']
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 

interface/python_binding/pyktx/khr_df_model.py

@@ -0,0 +1,126 @@
+# Copyright (c) 2026, Mark Callow
+# SPDX-License-Identifier: Apache-2.0
+
+from enum import IntEnum
+
+class KhrDfModel(IntEnum):
+    """Model in which the color coordinate space is defined."""
+
+    UNSPECIFIED  = 0
+    """No interpretation of color channels defined."""
+
+    RGBSDA       = 1
+    """Color primaries (red, green, blue) + alpha, depth and stencil."""
+
+    YUVSDA       = 2
+    """Color differences (Y', Cb, Cr) + alpha, depth and stencil."""
+
+    YIQSDA       = 3
+    """Color differences (Y', I, Q) + alpha, depth and stencil."""
+
+    LABSDA       = 4
+    """Perceptual color (CIE L*a*b*) + alpha, depth and stencil."""
+
+    CMYKA        = 5
+    """Subtractive colors (cyan, magenta, yellow, black) + alpha."""
+
+    XYZW         = 6
+    """Non-color coordinate data (X, Y, Z, W)."""
+
+    HSVA_ANG     = 7
+    """Hue, saturation, value, hue angle on color circle, plus alpha."""
+
+    HSLA_ANG     = 8
+    """Hue, saturation, lightness, hue angle on color circle, plus alpha."""
+
+    HSVA_HEX     = 9
+    """Hue, saturation, value, hue on color hexagon, plus alpha."""
+
+    HSLA_HEX     = 10
+    """Hue, saturation, lightness, hue on color hexagon, plus alpha."""
+
+    YCGCOA       = 11
+    """Lightweight approximate color difference (luma, orange, green)."""
+
+    YCCBCCRC     = 12
+    """ITU BT.2020 constant luminance YcCbcCrc."""
+
+    ICTCP        = 13
+    """ITU BT.2100 constant intensity ICtCp."""
+
+    CIEXYZ       = 14
+    """CIE 1931 XYZ color coordinates (X, Y, Z)."""
+
+    CIEXYY       = 15
+    """CIE 1931 xyY color coordinates (X, Y, Y)."""
+
+
+    DXT1A         = 128
+    BC1A          = 128
+    """Compressed formats start at 128."""
+    """
+    Direct3D (and S3) compressed formats.
+        DXT1 "channels" are RGB (0), Alpha (1).
+        DXT1/BC1 with one channel is opaque.
+        DXT1/BC1 with a cosited alpha sample is transparent.
+    """
+
+    DXT2          = 129
+    DXT3          = 129
+    BC2           = 129
+    """DXT2/DXT3/BC2, with explicit 4-bit alpha."""
+
+    DXT4          = 130
+    DXT5          = 130
+    BC3           = 130
+    """DXT4/DXT5/BC3, with interpolated alpha."""
+
+    ATI1N         = 131
+    DXT5A         = 131
+    BC4           = 131
+    """ATI1n/DXT5A/BC4 - single channel interpolated 8-bit data.
+       (The UNORM/SNORM variation is recorded in the channel data)."""
+
+    ATI2N_XY      = 132
+    DXN           = 132
+    BC5           = 132
+    """ATI2n_XY/DXN/BC5 - two channel interpolated 8-bit data.
+       (The UNORM/SNORM variation is recorded in the channel data)."""
+
+    BC6H          = 133
+    """BC6H - DX11 format for 16-bit float channels."""
+
+    BC7           = 134
+    """BC7 - DX11 format."""
+
+    ETC1          = 160
+    """A format of ETC1 indicates that the format shall be decodable
+       by an ETC1-compliant decoder and not rely on ETC2 features."""
+
+    ETC2          = 161
+    """A format of ETC2 is permitted to use ETC2 encodings on top of
+       the baseline ETC1 specification.
+       The ETC2 format has channels "red", "green", "RGB" and "alpha",
+       which should be cosited samples.
+       Punch-through alpha can be distinguished from full alpha by
+       the plane size in bytes required for the texel block."""
+
+    ASTC          = 162
+    """Adaptive Scalable Texture Compression."""
+    """ASTC HDR vs LDR is determined by the float flag in the channel."""
+    """ASTC block size can be distinguished by texel block size."""
+
+    ETC1S         = 163
+    """ETC1S is a simplified subset of ETC1."""
+
+    PVRTC         = 164
+    PVRTC2        = 165
+    """PowerVR Texture Compression."""
+
+    UASTC         = 166
+    UASTC_LDR_4x4 = 166
+    UASTC_HDR_4x4 = 167
+    UASTC_HDR_6x6 = 168
+    """UASTC for BASIS supercompression."""
+
+    MAX = 0xFF

interface/python_binding/pyktx/khr_df_primaries.py

@@ -0,0 +1,51 @@
+# Copyright (c) 2026, Mark Callow
+# SPDX-License-Identifier: Apache-2.0
+
+from enum import IntEnum
+
+class KhrDfPrimaries(IntEnum):
+    """The primary colors of an image."""
+
+    UNSPECIFIED = 0
+    """No color primaries defined"""
+
+    BT709       = 1
+    """Color primaries of ITU-R BT.709 and sRGB"""
+
+    SRGB        = 1
+    """Synonym for BT709"""
+
+    BT601_EBU   = 2
+    """Color primaries of ITU-R BT.601 (625-line EBU variant)"""
+
+    BT601_SMPTE = 3
+    """Color primaries of ITU-R BT.601 (525-line SMPTE C variant)"""
+
+    BT2020      = 4
+    """Color primaries of ITU-R BT.2020"""
+
+    BT2100      = 4
+    """ITU-R BT.2100 uses the same primaries as BT.2020"""
+
+    CIEXYZ      = 5
+    """CIE theoretical color coordinate space"""
+
+    ACES        = 6
+    """Academy Color Encoding System primaries"""
+
+    ACESCC      = 7
+    """Color primaries of ACEScc"""
+
+    NTSC1953    = 8
+    """Legacy NTSC 1953 primaries"""
+
+    PAL525      = 9
+    """Legacy PAL 525-line primaries"""
+
+    DISPLAYP3   = 10
+    """Color primaries of Display P3"""
+
+    ADOBERGB    = 11
+    """Color primaries of Adobe RGB (1998)"""
+
+    MAX         = 0xFF

interface/python_binding/pyktx/khr_df_transfer.py

@@ -0,0 +1,94 @@
+# Copyright (c) 2026, Mark Callow
+# SPDX-License-Identifier: Apache-2.0
+
+from enum import IntEnum
+
+class KhrDfTransfer(IntEnum):
+    """The transfer function of an image."""
+
+    UNSPECIFIED = 0
+    """No transfer function defined."""
+
+    LINEAR      = 1
+    """Linear transfer function (value proportional to intensity."""
+
+    SRGB        = 2
+    SRGB_EOTF   = 2
+    SCRGB       = 2
+    SCRGB_EOTF  = 2
+    """Perceptually-linear transfer function of sRGB (~2.2); also used for scRGB."""
+
+    ITU         = 3
+    ITU_OETF    = 3
+    BT601       = 3
+    BT601_OETF  = 3
+    BT709       = 3
+    BT709_OETF  = 3
+    BT2020      = 3
+    BT2020_OETF = 3
+    """Perceptually-linear transfer function of ITU BT.601, BT.709 and BT.2020 (~1/.45)."""
+
+    SMTPE170M      = 3
+    SMTPE170M_OETF = 3
+    SMTPE170M_EOTF = 3
+    """SMTPE170M (digital NTSC) defines an alias for the ITU transfer function (~1/.45) and a linear OOTF."""
+
+    NTSC        = 4
+    NTSC_EOTF   = 4
+    """Perceptually-linear gamma function of original NTSC (simple 2.2 gamma)."""
+
+    SLOG        = 5
+    SLOG_OETF   = 5
+    """Sony S-log used by Sony video cameras."""
+
+    SLOG2       = 6
+    SLOG2_OETF  = 6
+    """Sony S-log 2 used by Sony video cameras."""
+
+    BT1886      = 7
+    BT1886_EOTF = 7
+    """ITU BT.1886 EOTF."""
+
+    HLG_OETF    = 8
+    """ITU BT.2100 HLG OETF (typical scene-referred content), linear light normalized 0..1."""
+
+    HLG_EOTF    = 9
+    """ITU BT.2100 HLG EOTF (nominal HDR display of HLG content), linear light normalized 0..1."""
+
+    PQ_EOTF     = 10
+    """ITU BT.2100 PQ EOTF (typical HDR display-referred PQ content)."""
+
+    PQ_OETF     = 11
+    """ITU BT.2100 PQ OETF (nominal scene described by PQ HDR content)."""
+
+    DCIP3       = 12
+    DCIP3_EOTF  = 12
+    """DCI P3 transfer function."""
+
+    PAL_OETF    = 13
+    """Legacy PAL OETF."""
+
+    PAL625_EOTF = 14
+    """Legacy PAL 625-line EOTF."""
+
+    ST240       = 15
+    ST240_OETF  = 15
+    ST240_EOTF  = 15
+    """Legacy ST240 transfer function."""
+
+    ACESCC      = 16
+    ACESCC_OETF = 16
+    """ACEScc transfer function."""
+
+    ACESCCT      = 17
+    ACESCCT_OETF = 17
+    """ACEScct transfer function."""
+
+    ADOBERGB      = 18
+    ADOBERGB_EOTF = 18
+    """Adobe RGB (1998) transfer function."""
+
+    HLG_UNNORMALIZED_OETF = 19
+    """Legacy ITU BT.2100 HLG OETF (typical scene-referred content), linear light normalized 0..12."""
+
+    MAX                   = 0xFF

interface/python_binding/pyktx/ktx_basis_codec.py

@@ -0,0 +1,18 @@
+# Copyright (c) 2026, Mark Callow
+# SPDX-License-Identifier: Apache-2.0
+
+from enum import IntEnum
+
+class KtxBasisCodec(IntEnum):
+    """Options specifiying basis codec."""
+
+    NONE  = 0
+    """NONE."""
+    ETC1S   = 1
+    """BasisLZ."""
+    UASTC_LDR_4x4   = 2
+    """UASTC."""
+    UASTC_HDR_4x4   = 3
+    """UASTC_HDR_4x4."""
+    UASTC_HDR_6x6_INTERMEDIATE = 4
+    """UASTC_HDR_6x6i."""