Pure-C-API-Transcoding

This content was automatically converted from the project's wiki Markdown to HTML. See the Basis Universal GitHub wiki for the latest content.

This documentation is based off Basis Universal v2.10.

Table of Contents

• Intro
• ASTC Block Size Format Matching
• Initialization
• Memory Management
• Basis Texture Format Helpers
• Transcoder Texture Format Helpers
• KTX2 File Operations
  • Opening and Closing
  • Basic Properties
  • Format Detection
  • KTX2 Data Format Descriptor (DFD)
  • HDR Properties
  • Per-Level / Per-Layer / Per-Face Properties
  • Transcoding
• Typical Usage
• See Also

Intro

See Header: basisu_wasm_transcoder_api.h

This header provides the C-style transcoder API for Basis Universal. It supports opening .ktx2 files, querying their properties, and transcoding image levels to a wide range of GPU texture formats (BC1–BC7, ETC1/2, ASTC, PVRTC, etc.) and uncompressed pixel formats (RGBA32, half-float, RGB 9E5, etc.).

The transcoder library (or module) does not depend on the encoder, i.e. it's a fully stand-alone library. However the encoder depends on the transcoder internally.

All common constants, types, and flags referenced below are defined in Pure C API — Common Definitions page (or see basisu_wasm_api_common.h).

These API's are essentially C-style wrappers to the C++ transcoder class basist::ktx2_transcoder, defined in transcoder/basisu_transcoder.h.

Note the transcoder itself doesn't do any sort of multithreaded synchronization on behalf of the caller. The transcoder doesn't use any threading related API's. Parallel transcoding is supported at the file level, or the mipmap level by most codecs. The primary exception is ETC1S, which supports global codebooks, which must be unpacked before parallel transcoding. ETC1S texture video frames must be decompressed serially (in order). If you're going to call the transcoder on the same file to transcode different levels across multiple threads, use state objects: bt_ktx2_create_transcode_state() etc.

The ASTC and XUASTC Usage Guide contains more information about transcoding ASTC/XUASTC LDR format files.

Native code specific performance note: The API and examples below are for either WASM or native builds. In WASM builds, the transcoder has its own linear WASM address space. In native builds, the uint64_t offsets (allocated by bt_alloc()) are really just casted memory pointers, and the transcoder and the caller both can read and write to the same linear address spaces. For example, the key transcoder function (bt_ktx2_transcode_image_level()) accepts a uint64_t offset to the output buffer: output_block_mem_ofs. For maximum performance in native code, you can pass a user-managed buffer pointer to this function casted to a uint64_t, instead of allocating a buffer, memcpy'ing from it, and then freeing the buffer.

Note: These API's aren't just for WASM WASI module usage, they are also available for calling the native library via plain C API's, and for native Python support.

ASTC Block Size Format Matching

When compressing, your choice of block size is "baked in" for ASTC-to-ASTC LDR/HDR transcoding:

LDR

ASTC LDR and XUASTC LDR, of any ASTC block size, can be transcoded to most other supported LDR texture formats, even if the target block size is different. For BC7 it can do this directly via ASTC latent to BC7 latent conversion for several common ASTC block sizes (4x4, 6x6, 8x6), otherwise it'll unpack the ASTC/XUASTC blocks to texels on the fly and use analytical block encoders to pack to the output format. Importantly, when you're transcoding to an ASTC LDR format, the target ASTC block size must match the input file's block size (i.e. when the transcoder is outputting specifically ASTC LDR, it cannot change the input block size).

HDR

The transcoding "ASTC to ASTC" block size constraint applies to the HDR formats, too. When transcoding to any ASTC HDR target format, the output block size must match the input block size: ASTC HDR 6x6 or UASTC HDR 6x6i must be transcoded to ASTC HDR 6x6 (or any other supported HDR format). When transcoding HDR content to non-ASTC formats, the block size can change (i.e. ASTC HDR 6x6 content can be transcoded to BC6H, which is 4x4).

See the bt_basis_get_transcoder_texture_format_from_basis_tex_format() helper function below which makes it easier to match source and target ASTC block sizes.

This constraint is in place because most of our latent formats are ASTC-based internally, and it makes little (if any) practical sense to decode ASTC and re-encode to ASTC at another block size.

Initialization

bt_get_version()

uint32_t bt_get_version();

Returns the Basis Universal library version number (decimal 200 for library version v2.00).

bt_enable_debug_printf()

void bt_enable_debug_printf(uint32_t flag);

Enables or disables internal debug printf output globally.

bt_init()

void bt_init();

Initializes the Basis Universal transcoder. MUST be called once before any other bt_* functions.

Memory Management

Use bt_alloc and bt_free to manage heap allocated buffers that you pass to the API. In WASI modules, the returned uint64_t's are casted pointers into the module's internal address space. In WASM mode, all heap buffers you pass to the C API must be allocated via these API's.

bt_alloc()

uint64_t bt_alloc(uint64_t size);

Allocates a block of memory (alias to the module's malloc() function).

Returns: Module offset (address) of the allocated block, or 0 on failure.

bt_free()

void bt_free(uint64_t ofs);

Frees a block of memory previously allocated by bt_alloc. Alias to the module's free() function.

Basis Texture Format Helpers

These functions query properties of basis_tex_format values (the BTF_* constants). They are useful for determining the characteristics of the format stored in a .ktx2 or .basis file before transcoding.

bt_basis_tex_format_is_xuastc_ldr()

wasm_bool_t bt_basis_tex_format_is_xuastc_ldr(uint32_t basis_tex_fmt_u32);

Returns: Non-zero if the format is an XUASTC LDR format (BTF_XUASTC_LDR_4X4 through BTF_XUASTC_LDR_12X12).

bt_basis_tex_format_is_astc_ldr()

wasm_bool_t bt_basis_tex_format_is_astc_ldr(uint32_t basis_tex_fmt_u32);

Returns: Non-zero if the format is a standard ASTC LDR format (BTF_ASTC_LDR_4X4 through BTF_ASTC_LDR_12X12).

bt_basis_tex_format_get_block_width()

uint32_t bt_basis_tex_format_get_block_width(uint32_t basis_tex_fmt_u32);

Returns: The block width in texels for the given basis texture format (e.g. 4 for BTF_UASTC_LDR_4X4, 12 for BTF_XUASTC_LDR_12X12).

bt_basis_tex_format_get_block_height()

uint32_t bt_basis_tex_format_get_block_height(uint32_t basis_tex_fmt_u32);

Returns: The block height in texels for the given basis texture format.

bt_basis_tex_format_is_hdr()

wasm_bool_t bt_basis_tex_format_is_hdr(uint32_t basis_tex_format_u32);

Returns: Non-zero if the format is an HDR format (BTF_UASTC_HDR_4X4, BTF_ASTC_HDR_6X6, BTF_UASTC_HDR_6X6).

bt_basis_tex_format_is_ldr()

wasm_bool_t bt_basis_tex_format_is_ldr(uint32_t basis_tex_format_u32);

Returns: Non-zero if the format is an LDR format (ETC1S, UASTC LDR, XUASTC LDR, ASTC LDR).

Transcoder Texture Format Helpers

These functions query properties of transcoder_texture_format values (the TF_* constants). They are useful for determining output buffer sizes and characteristics before transcoding.

bt_basis_get_bytes_per_block_or_pixel()

uint32_t bt_basis_get_bytes_per_block_or_pixel(uint32_t transcoder_texture_format_u32);

Returns: The number of bytes per compressed block or per uncompressed pixel for the given transcoder format.

bt_basis_transcoder_format_has_alpha()

wasm_bool_t bt_basis_transcoder_format_has_alpha(uint32_t transcoder_texture_format_u32);

Returns: Non-zero if the transcoder format includes an alpha channel.

bt_basis_transcoder_format_is_hdr()

wasm_bool_t bt_basis_transcoder_format_is_hdr(uint32_t transcoder_texture_format_u32);

Returns: Non-zero if the transcoder format is an HDR format (e.g. TF_BC6H, TF_ASTC_HDR_4X4_RGBA, TF_RGB_HALF, TF_RGBA_HALF, TF_RGB_9E5).

bt_basis_transcoder_format_is_ldr()

wasm_bool_t bt_basis_transcoder_format_is_ldr(uint32_t transcoder_texture_format_u32);

Returns: Non-zero if the transcoder format is an LDR format.

bt_basis_transcoder_texture_format_is_astc()

wasm_bool_t bt_basis_transcoder_texture_format_is_astc(uint32_t transcoder_texture_format_u32);

Returns: Non-zero if the transcoder format is any ASTC format (LDR or HDR, any block size).

bt_basis_transcoder_format_is_uncompressed()

wasm_bool_t bt_basis_transcoder_format_is_uncompressed(uint32_t transcoder_texture_format_u32);

Returns: Non-zero if the format is an uncompressed pixel format (TF_RGBA32, TF_RGB565, TF_BGR565, TF_RGBA4444, TF_RGB_HALF, TF_RGBA_HALF, TF_RGB_9E5).

bt_basis_get_uncompressed_bytes_per_pixel()

uint32_t bt_basis_get_uncompressed_bytes_per_pixel(uint32_t transcoder_texture_format_u32);

Returns: The number of bytes per pixel for uncompressed formats. Returns 0 for block-compressed formats.

bt_basis_get_block_width()

uint32_t bt_basis_get_block_width(uint32_t transcoder_texture_format_u32);

Returns: The block width in texels for the given transcoder format (always 4 or higher).

bt_basis_get_block_height()

uint32_t bt_basis_get_block_height(uint32_t transcoder_texture_format_u32);

Returns: The block height in texels for the given transcoder format (always 4 or higher).

bt_basis_get_transcoder_texture_format_from_basis_tex_format()

uint32_t bt_basis_get_transcoder_texture_format_from_basis_tex_format(uint32_t basis_tex_format_u32);

Returns the matching ASTC LDR or HDR transcoder texture format (TF_*) for a given basis texture format (BTF_*). For example, BTF_XUASTC_LDR_6X6 → TF_ASTC_LDR_6X6_RGBA.

This function is useful when matching the target format's ASTC block size to the source file codec's ASTC block size (which cannot be changed while transcoding).

Returns: The corresponding TF_* constant.

bt_basis_is_format_supported()

wasm_bool_t bt_basis_is_format_supported(
    uint32_t transcoder_texture_format_u32,
    uint32_t basis_tex_format_u32);

Checks whether a given transcoder output format is supported for a given basis texture format. The returned value may change depending on how the transcoder was compiled.

Returns: Non-zero if the transcoding path is supported, 0 otherwise.

bt_basis_compute_transcoded_image_size_in_bytes()

uint32_t bt_basis_compute_transcoded_image_size_in_bytes(
    uint32_t transcoder_texture_format_u32,
    uint32_t orig_width,
    uint32_t orig_height);

Computes the output buffer size in bytes needed to transcode an image of the given dimensions to the given format.

The orig_width and orig_height parameters are the unpadded image dimensions, which don't need to be aligned or padded to the block dimensions. This is a wrapper on top of the transcoder's basis_compute_transcoded_image_size_in_bytes() function, which works with plain raster images or GPU block formats.

Note PVRTC1 textures have odd required minimum size conventions concerning the smallest mipmap levels, which this function factors in.

Returns: Required output buffer size in bytes.

KTX2 File Operations

Opening and Closing

bt_ktx2_open()

uint64_t bt_ktx2_open(uint64_t data_mem_ofs, uint32_t data_len);

Opens and validates a .ktx2 file from memory. The file data must remain valid (allocated via bt_alloc) for the lifetime of the returned handle.

Returns: A non-zero handle on success, or 0 on failure (invalid file, corrupt data, etc.).

bt_ktx2_close()

void bt_ktx2_close(uint64_t handle);

Closes a KTX2 file handle and frees associated internal resources. Does not free the original file data buffer — call bt_free() on that separately.

Basic Properties

bt_ktx2_get_width()

uint32_t bt_ktx2_get_width(uint64_t handle);

Returns: Base mip level unpadded width in pixels. Note: May not be divisible by the codec's block width in pixels.

bt_ktx2_get_height()

uint32_t bt_ktx2_get_height(uint64_t handle);

Returns: Base mip level unpadded height in pixels. Note: May not be divisible by the codec's block height in pixels.

bt_ktx2_get_levels()

uint32_t bt_ktx2_get_levels(uint64_t handle);

Returns: Number of mipmap levels in the file.

bt_ktx2_get_faces()

uint32_t bt_ktx2_get_faces(uint64_t handle);

Returns: Number of faces (1 for 2D textures, 6 for cubemaps).

bt_ktx2_get_layers()

uint32_t bt_ktx2_get_layers(uint64_t handle);

Returns: Number of array layers (0 for non-array textures).

bt_ktx2_get_basis_tex_format()

uint32_t bt_ktx2_get_basis_tex_format(uint64_t handle);

Returns: The basis texture format (BTF_* constant) (or codec) used in the file.

bt_ktx2_get_block_width()

uint32_t bt_ktx2_get_block_width(uint64_t handle);

Returns: Block width in texels for the file's format.

bt_ktx2_get_block_height()

uint32_t bt_ktx2_get_block_height(uint64_t handle);

Returns: Block height in texels for the file's format.

bt_ktx2_has_alpha()

wasm_bool_t bt_ktx2_has_alpha(uint64_t handle);

Returns: Non-zero if the texture contains alpha channel data, according to the KTX2 header's DFD.

bt_ktx2_is_video()

wasm_bool_t bt_ktx2_is_video(uint64_t handle);

Returns: Non-zero if the file contains texture video frame data (used by ETC1S texture video).

Format Detection

bt_ktx2_is_etc1s()

wasm_bool_t bt_ktx2_is_etc1s(uint64_t handle);

Returns: Non-zero if the file uses ETC1S format (BTF_ETC1S).

bt_ktx2_is_uastc_ldr_4x4()

wasm_bool_t bt_ktx2_is_uastc_ldr_4x4(uint64_t handle);

Returns: Non-zero if the file uses UASTC LDR 4×4 format (BTF_UASTC_LDR_4X4).

bt_ktx2_is_hdr()

wasm_bool_t bt_ktx2_is_hdr(uint64_t handle);

Returns: Non-zero if the file uses any HDR format.

bt_ktx2_is_hdr_4x4()

wasm_bool_t bt_ktx2_is_hdr_4x4(uint64_t handle);

Returns: Non-zero if the file uses UASTC HDR 4×4 format (BTF_UASTC_HDR_4X4).

bt_ktx2_is_hdr_6x6()

wasm_bool_t bt_ktx2_is_hdr_6x6(uint64_t handle);

Returns: Non-zero if the file uses an HDR 6×6 format (BTF_ASTC_HDR_6X6 or BTF_UASTC_HDR_6X6).

bt_ktx2_is_ldr()

wasm_bool_t bt_ktx2_is_ldr(uint64_t handle);

Returns: Non-zero if the file uses any LDR format.

bt_ktx2_is_astc_ldr()

wasm_bool_t bt_ktx2_is_astc_ldr(uint64_t handle);

Returns: Non-zero if the file uses a standard ASTC LDR format (BTF_ASTC_LDR_4X4 through BTF_ASTC_LDR_12X12).

bt_ktx2_is_xuastc_ldr()

wasm_bool_t bt_ktx2_is_xuastc_ldr(uint64_t handle);

Returns: Non-zero if the file uses an XUASTC LDR format (BTF_XUASTC_LDR_4X4 through BTF_XUASTC_LDR_12X12).

KTX2 Data Format Descriptor (DFD)

These functions expose fields from the KTX2 file's Data Format Descriptor, which describes color model, primaries, transfer function, and channel layout.

bt_ktx2_get_dfd_color_model()

uint32_t bt_ktx2_get_dfd_color_model(uint64_t handle);

Returns: The DFD color model value (e.g. KHR_DF_MODEL_ASTC for ASTC formats, KHR_DF_MODEL_ETC1S for ETC1S).

bt_ktx2_get_dfd_color_primaries()

uint32_t bt_ktx2_get_dfd_color_primaries(uint64_t handle);

Returns: The DFD color primaries value (e.g. KHR_DF_PRIMARIES_BT709 for sRGB/Rec.709, KHR_DF_PRIMARIES_BT2020 for Rec.2020).

bt_ktx2_get_dfd_transfer_func()

uint32_t bt_ktx2_get_dfd_transfer_func(uint64_t handle);

Returns: The DFD transfer function value (e.g. KHR_DF_TRANSFER_SRGB for sRGB, KHR_DF_TRANSFER_LINEAR for linear).

bt_ktx2_is_srgb()

wasm_bool_t bt_ktx2_is_srgb(uint64_t handle);

Returns: Non-zero if the file's DFD transfer function is sRGB.

bt_ktx2_get_dfd_flags()

uint32_t bt_ktx2_get_dfd_flags(uint64_t handle);

Returns: The DFD flags value.

bt_ktx2_get_dfd_total_samples()

uint32_t bt_ktx2_get_dfd_total_samples(uint64_t handle);

Returns: The total number of DFD sample entries.

bt_ktx2_get_dfd_channel_id0()

uint32_t bt_ktx2_get_dfd_channel_id0(uint64_t handle);

Returns: The channel ID of the first DFD sample.

bt_ktx2_get_dfd_channel_id1()

uint32_t bt_ktx2_get_dfd_channel_id1(uint64_t handle);

Returns: The channel ID of the second DFD sample.

HDR Properties

bt_ktx2_get_ldr_hdr_upconversion_nit_multiplier()

float bt_ktx2_get_ldr_hdr_upconversion_nit_multiplier(uint64_t handle);

Returns: The nit multiplier used when upconverting LDR content to HDR output. Returns 0.0 if not applicable. For upconverted SDR/LDR content using library defaults compressed to HDR, this will typically be 100.0.

Per-Level / Per-Layer / Per-Face Properties

These functions query properties of individual image levels within the KTX2 file. All take the same (handle, level_index, layer_index, face_index) parameters.

Note there is some overhead in using these simple API's: the C API retrieves the level's description structure, then returns the requested value (throwing away the rest of the description structure). This design tradeoff was chosen to make the C API as useable as possible across different languages.

bt_ktx2_get_level_orig_width()

uint32_t bt_ktx2_get_level_orig_width(uint64_t handle, uint32_t level_index, uint32_t layer_index, uint32_t face_index);

Returns: Original (unpadded) width of the image at this level, in pixels.

bt_ktx2_get_level_orig_height()

uint32_t bt_ktx2_get_level_orig_height(uint64_t handle, uint32_t level_index, uint32_t layer_index, uint32_t face_index);

Returns: Original (unpadded) height of the image at this level, in pixels.

bt_ktx2_get_level_actual_width()

uint32_t bt_ktx2_get_level_actual_width(uint64_t handle, uint32_t level_index, uint32_t layer_index, uint32_t face_index);

Returns: Actual (physical, block-padded) width of the image at this level, in pixels.

bt_ktx2_get_level_actual_height()

uint32_t bt_ktx2_get_level_actual_height(uint64_t handle, uint32_t level_index, uint32_t layer_index, uint32_t face_index);

Returns: Actual (physical, block-padded) height of the image at this level, in pixels.

bt_ktx2_get_level_num_blocks_x()

uint32_t bt_ktx2_get_level_num_blocks_x(uint64_t handle, uint32_t level_index, uint32_t layer_index, uint32_t face_index);

Returns: Number of blocks in the horizontal direction at this level.

bt_ktx2_get_level_num_blocks_y()

uint32_t bt_ktx2_get_level_num_blocks_y(uint64_t handle, uint32_t level_index, uint32_t layer_index, uint32_t face_index);

Returns: Number of blocks in the vertical direction at this level.

bt_ktx2_get_level_total_blocks()

uint32_t bt_ktx2_get_level_total_blocks(uint64_t handle, uint32_t level_index, uint32_t layer_index, uint32_t face_index);

Returns: Total number of blocks at this level (num_blocks_x * num_blocks_y).

bt_ktx2_get_level_alpha_flag()

wasm_bool_t bt_ktx2_get_level_alpha_flag(uint64_t handle, uint32_t level_index, uint32_t layer_index, uint32_t face_index);

Returns: Non-zero if this level contains alpha data.

bt_ktx2_get_level_iframe_flag()

wasm_bool_t bt_ktx2_get_level_iframe_flag(uint64_t handle, uint32_t level_index, uint32_t layer_index, uint32_t face_index);

Returns: Non-zero if this level is an I-frame (ETC1S video only). I-frames can be decoded independently; P-frames depend on the previous frame.

Transcoding

bt_ktx2_start_transcoding()

wasm_bool_t bt_ktx2_start_transcoding(uint64_t handle);

Prepares the KTX2 file for transcoding. This must be called once after bt_ktx2_open() and before any calls to bt_ktx2_transcode_image_level(). For ETC1S files, this decompresses the global codebooks.

Returns: Non-zero on success, 0 on failure.

bt_ktx2_create_transcode_state()

uint64_t bt_ktx2_create_transcode_state();

Creates a thread-local transcoding state object. Using per-thread state allows multiple threads to transcode from the same KTX2 handle concurrently.

Returns: A non-zero state handle on success, or 0 on failure.

bt_ktx2_destroy_transcode_state()

void bt_ktx2_destroy_transcode_state(uint64_t handle);

Destroys a transcode state object previously created by bt_ktx2_create_transcode_state().

bt_ktx2_transcode_image_level()

wasm_bool_t bt_ktx2_transcode_image_level(
    uint64_t ktx2_handle,
    uint32_t level_index, uint32_t layer_index, uint32_t face_index,
    uint64_t output_block_mem_ofs,
    uint32_t output_blocks_buf_size_in_blocks_or_pixels,
    uint32_t transcoder_texture_format_u32,
    uint32_t decode_flags,
    uint32_t output_row_pitch_in_blocks_or_pixels,
    uint32_t output_rows_in_pixels,
    int      channel0, int channel1,
    uint64_t state_handle);

Transcodes a single image level from a KTX2 file to the specified GPU texture format.

Returns: Non-zero on success, 0 on failure.

Typical Usage

See the C API Example.

This example (with error checking omitted for brevity) opens a .KTX2 file, retrieves the top mipmap level's dimensions, and transcodes it to the ASTC LDR with the right block size.

// Initialize library
bt_init();

// Load KTX2 file into memory (assume you have file_data and file_size)
uint64_t ktx2_ofs = bt_alloc(file_size);
memcpy((void*)ktx2_ofs, file_data, file_size);

// Open and validate
uint64_t ktx2_handle = bt_ktx2_open(ktx2_ofs, file_size);

// Start transcoding (decompresses global tables for ETC1S)
bt_ktx2_start_transcoding(ktx2_handle);

// Get image properties
uint32_t width = bt_ktx2_get_width(ktx2_handle);
uint32_t height = bt_ktx2_get_height(ktx2_handle);

// Determine the ASTC format that matches the source file's block size
// (e.g., BTF_XUASTC_LDR_6X6 → TF_ASTC_LDR_6X6_RGBA)
uint32_t basis_tex_format = bt_ktx2_get_basis_tex_format(ktx2_handle);
uint32_t astc_format = bt_basis_get_transcoder_texture_format_from_basis_tex_format(basis_tex_format);

// Allocate output buffer
uint32_t output_size = bt_basis_compute_transcoded_image_size_in_bytes(astc_format, width, height);
uint64_t output_ofs = bt_alloc(output_size);

// Transcode level 0 to ASTC
bt_ktx2_transcode_image_level(
    ktx2_handle,
    0, 0, 0,  // level 0, layer 0, face 0
    output_ofs, output_size / 16,  // output buffer (size parameter is number of blocks or pixels, NOT bytes; ASTC uses 16 bytes/block)
    astc_format,
    0,  // decode_flags
    0, 0, -1, -1,  // default pitch/rows/channels
    0  // no thread-local state
);

// ... use transcoded ASTC data ...

// Cleanup
bt_free(output_ofs);
bt_ktx2_close(ktx2_handle);
bt_free(ktx2_ofs);

See Also

• basisu_wasm_api_common.h — Common definitions
• basisu_wasm_api.h — Encoder / compressor API
• C++ API: Transcoder Module Definitions and Classes