Pure-C-API-Common-Definitions

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.

Intro

See Header: basisu_wasm_api_common.h

This header provides shared type definitions, macros, and constants used by both the Basis Universal encoder (basisu_wasm_api.h) and transcoder (basisu_wasm_transcoder_api.h) C-style API's, which is also used for native Python support and to support WASM/WASI Modules.

Beware: The ID order used by various API's for the 14 ASTC block sizes is not standardized. We try to order our ID's monotonically by the total number of ASTC block texels (4×4=16, 5×4=20, 5×5=25, etc.), but many API's use different ordering conventions.

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.

Definitions

Export Macro

BU_WASM_EXPORT(name)

Portability macro that decorates exported C functions for WASM and native builds.

Build Target	Expansion
`__wasm__` + C++	`__attribute__((export_name(name))) extern "C"`
`__wasm__` + C	`__attribute__((export_name(name)))`
Native C++	`extern "C"`
Native C	(empty — no decoration)

You do not need to use this macro directly unless you are extending the API. It is applied to every public function in both the encoder and transcoder headers.

Types

typedef uint32_t wasm_bool_t;

Boolean type used throughout the API. A value of 0 is false; any non-zero value is true. This is a uint32_t rather than _Bool for stable ABI width across WASM and native targets.

Compression Quality & Effort

Quality Level

#define BU_QUALITY_MIN   0
#define BU_QUALITY_MAX   100

The quality_level parameter passed to bu_compress_texture() ranges from 0 (lowest quality, fastest) to 100 (highest quality, slowest). This controls the internal RDO (rate-distortion optimization) target for ETC1S and related formats.

Note the recommended usable unified quality range is [1,100], but the C API accepts [0,100].

Effort Level

#define BU_EFFORT_MIN          0
#define BU_EFFORT_MAX          10

#define BU_EFFORT_SUPER_FAST   0
#define BU_EFFORT_FAST         2
#define BU_EFFORT_NORMAL       5
#define BU_EFFORT_DEFAULT      2
#define BU_EFFORT_SLOW         8
#define BU_EFFORT_VERY_SLOW    10

The effort_level parameter controls how hard the encoder searches for an optimal encoding. Higher effort means longer encode times but potentially better quality at a given file size.

Preset	Value	Use Case
`SUPER_FAST`	0	Fastest, but lowest quality
`FAST` / `DEFAULT`	2	Good balance for small/medium block sizes
`NORMAL`	5	Offline encoding, moderate quality
`SLOW`	8	High-quality offline encoding
`VERY_SLOW`	10	Maximum quality, longest encode time

Compression Flags (`flags_and_quality`)

These flags are combined (bitwise OR) into the flags_and_quality parameter of bu_compress_texture(). They control output format, color space, mipmapping, debugging, and other encoder behaviors.

General Flags

#define BU_COMP_FLAGS_NONE                    0

#define BU_COMP_FLAGS_USE_OPENCL              (1 << 8)
#define BU_COMP_FLAGS_THREADED                (1 << 9)
#define BU_COMP_FLAGS_DEBUG_OUTPUT            (1 << 10)
#define BU_COMP_FLAGS_KTX2_OUTPUT             (1 << 11)
#define BU_COMP_FLAGS_KTX2_UASTC_ZSTD         (1 << 12)
#define BU_COMP_FLAGS_SRGB                    (1 << 13)
#define BU_COMP_FLAGS_GEN_MIPS_CLAMP          (1 << 14)
#define BU_COMP_FLAGS_GEN_MIPS_WRAP           (1 << 15)
#define BU_COMP_FLAGS_Y_FLIP                  (1 << 16)
#define BU_COMP_FLAGS_PRINT_STATS             (1 << 18)
#define BU_COMP_FLAGS_PRINT_STATUS            (1 << 19)
#define BU_COMP_FLAGS_DEBUG_IMAGES            (1 << 20)
#define BU_COMP_FLAGS_REC2020                 (1 << 21)
#define BU_COMP_FLAGS_VALIDATE_OUTPUT         (1 << 22)

Flag	Description
`NONE`	No flags set. Produces a `.basis` or `.ktx2` file with default settings.
`USE_OPENCL`	Enable OpenCL GPU acceleration (if available in the build, currently ETC1S only).
`THREADED`	Enable multithreaded encoding (highly recommended).
`DEBUG_OUTPUT`	Emit detailed debug information to stdout during compression.
`KTX2_OUTPUT`	Output a `.ktx2` file instead of a `.basis` file.
`KTX2_UASTC_ZSTD`	Enable Zstandard supercompression to data in KTX2 output.
`SRGB`	Treat input images as sRGB. Affects mipmap generation, quality metrics, ASTC decode profile.
`GEN_MIPS_CLAMP`	Auto-generate mipmaps with clamped (edge) addressing.
`GEN_MIPS_WRAP`	Auto-generate mipmaps with wrapped (tiled) addressing.
`Y_FLIP`	Flip images vertically before encoding (useful for OpenGL conventions).
`PRINT_STATS`	Print compression statistics after encoding.
`PRINT_STATUS`	Print status/progress messages during encoding.
`DEBUG_IMAGES`	Write intermediate debug images to disk.
`REC2020`	Treat input as Rec. 2020/BT2100 color space vs. default Rec. 709 (for HDR workflows). Gamut value set in KTX2 header for LDR/HDR.
`VALIDATE_OUTPUT`	Validate the compressed output by trial-transcoding after encoding.

Depending on the compressor API used, the low 8-bits of the compression flags can also define the codec's quality level.

Convenience alias:

#define BU_COMP_FLAGS_VERBOSE  (BU_COMP_FLAGS_DEBUG_OUTPUT | \
                                BU_COMP_FLAGS_PRINT_STATS  | \
                                BU_COMP_FLAGS_PRINT_STATUS)

XUASTC LDR Syntax Mode (bits 23–24)

These flags select the compression syntax used for XUASTC LDR formats. They occupy a 2-bit field at bit position 23. Only one may be set.

#define BU_COMP_FLAGS_XUASTC_LDR_FULL_ARITH    0
#define BU_COMP_FLAGS_XUASTC_LDR_HYBRID        (1 << 23)
#define BU_COMP_FLAGS_XUASTC_LDR_FULL_ZSTD     (2 << 23)

#define BU_COMP_FLAGS_XUASTC_LDR_SYNTAX_SHIFT  23
#define BU_COMP_FLAGS_XUASTC_LDR_SYNTAX_MASK   3

Mode	Value	Description
`FULL_ARITH`	`0`	Fully arithmetic-coded XUASTC LDR (default).
`HYBRID`	`1 << 23`	Hybrid arithmetic + Zstandard coding.
`FULL_ZSTD`	`2 << 23`	Fully Zstandard-coded XUASTC LDR.

To extract or set this field:

/* Extract */
uint32_t syntax = (flags >> BU_COMP_FLAGS_XUASTC_LDR_SYNTAX_SHIFT)
                  & BU_COMP_FLAGS_XUASTC_LDR_SYNTAX_MASK;

/* Set (clear field first, then OR in new value) */
flags &= ~(BU_COMP_FLAGS_XUASTC_LDR_SYNTAX_MASK << BU_COMP_FLAGS_XUASTC_LDR_SYNTAX_SHIFT);
flags |= BU_COMP_FLAGS_XUASTC_LDR_HYBRID;

Texture Type (bits 25–26)

These flags specify the logical texture type of the input image set. They occupy a 2-bit field at bit position 25. Only one may be set.

#define BU_COMP_FLAGS_TEXTURE_TYPE_2D              (0 << 25)
#define BU_COMP_FLAGS_TEXTURE_TYPE_2D_ARRAY        (1 << 25)
#define BU_COMP_FLAGS_TEXTURE_TYPE_CUBEMAP_ARRAY   (2 << 25)
#define BU_COMP_FLAGS_TEXTURE_TYPE_VIDEO_FRAMES    (3 << 25)

#define BU_COMP_FLAGS_TEXTURE_TYPE_SHIFT           25
#define BU_COMP_FLAGS_TEXTURE_TYPE_MASK            3

Type	Value	Description
`2D`	`0`	Single 2D texture (default).
`2D_ARRAY`	`1 << 25`	Array of 2D textures (layered).
`CUBEMAP_ARRAY`	`2 << 25`	Cubemap or cubemap array (6 faces per element).
`VIDEO_FRAMES`	`3 << 25`	Sequence of video frames (enables inter-frame coding in ETC1S mode).

Basis Texture Formats (`BTF_*`)

These constants identify the container file-level texture codec used by the encoder and reported by the transcoder. They correspond to basist::basis_tex_format. They also correspond to our codec latent spaces.

Note BTF_UASTC_HDR_6X6 is the same as "UASTC HDR 6x6i" or "UASTC HDR 6x6 Intermediate".

// basist::basis_tex_format: the supported .ktx2 and .basis codec types
#define BTF_ETC1S 0
#define BTF_UASTC_LDR_4X4 1
#define BTF_UASTC_HDR_4X4 2
#define BTF_ASTC_HDR_6X6 3
#define BTF_UASTC_HDR_6X6 4
#define BTF_XUASTC_LDR_4X4 5
#define BTF_XUASTC_LDR_5X4 6
#define BTF_XUASTC_LDR_5X5 7
#define BTF_XUASTC_LDR_6X5 8
#define BTF_XUASTC_LDR_6X6 9
#define BTF_XUASTC_LDR_8X5 10
#define BTF_XUASTC_LDR_8X6 11
#define BTF_XUASTC_LDR_10X5 12
#define BTF_XUASTC_LDR_10X6 13
#define BTF_XUASTC_LDR_8X8 14
#define BTF_XUASTC_LDR_10X8 15
#define BTF_XUASTC_LDR_10X10 16
#define BTF_XUASTC_LDR_12X10 17
#define BTF_XUASTC_LDR_12X12 18
#define BTF_ASTC_LDR_4X4 19
#define BTF_ASTC_LDR_5X4 20
#define BTF_ASTC_LDR_5X5 21
#define BTF_ASTC_LDR_6X5 22
#define BTF_ASTC_LDR_6X6 23
#define BTF_ASTC_LDR_8X5 24
#define BTF_ASTC_LDR_8X6 25
#define BTF_ASTC_LDR_10X5 26
#define BTF_ASTC_LDR_10X6 27
#define BTF_ASTC_LDR_8X8 28
#define BTF_ASTC_LDR_10X8 29
#define BTF_ASTC_LDR_10X10 30
#define BTF_ASTC_LDR_12X10 31
#define BTF_ASTC_LDR_12X12 32
#define BTF_TOTAL_FORMATS 33

ETC1S, UASTC LDR/HDR, and ASTC HDR Formats

Constant	Value	Description
`BTF_ETC1S`	0	ETC1S.
`BTF_UASTC_LDR_4X4`	1	UASTC LDR with 4×4 block size.
`BTF_UASTC_HDR_4X4`	2	UASTC HDR with 4×4 block size. (also standard ASTC HDR 4x4)
`BTF_ASTC_HDR_6X6`	3	Standard ASTC HDR with 6×6 block size.
`BTF_UASTC_HDR_6X6`	4	UASTC HDR intermediate (UASTC HDR 6x6i) with 6×6 block size.

XUASTC LDR Formats (All 14 Standard ASTC Block Sizes)

Constant	Value	Block Size
`BTF_XUASTC_LDR_4X4`	5	4×4
`BTF_XUASTC_LDR_5X4`	6	5×4
`BTF_XUASTC_LDR_5X5`	7	5×5
`BTF_XUASTC_LDR_6X5`	8	6×5
`BTF_XUASTC_LDR_6X6`	9	6×6
`BTF_XUASTC_LDR_8X5`	10	8×5
`BTF_XUASTC_LDR_8X6`	11	8×6
`BTF_XUASTC_LDR_10X5`	12	10×5
`BTF_XUASTC_LDR_10X6`	13	10×6
`BTF_XUASTC_LDR_8X8`	14	8×8
`BTF_XUASTC_LDR_10X8`	15	10×8
`BTF_XUASTC_LDR_10X10`	16	10×10
`BTF_XUASTC_LDR_12X10`	17	12×10
`BTF_XUASTC_LDR_12X12`	18	12×12

Standard ASTC LDR Formats (All 14 Standard ASTC Block Sizes)

Constant	Value	Block Size
`BTF_ASTC_LDR_4X4`	19	4×4
`BTF_ASTC_LDR_5X4`	20	5×4
`BTF_ASTC_LDR_5X5`	21	5×5
`BTF_ASTC_LDR_6X5`	22	6×5
`BTF_ASTC_LDR_6X6`	23	6×6
`BTF_ASTC_LDR_8X5`	24	8×5
`BTF_ASTC_LDR_8X6`	25	8×6
`BTF_ASTC_LDR_10X5`	26	10×5
`BTF_ASTC_LDR_10X6`	27	10×6
`BTF_ASTC_LDR_8X8`	28	8×8
`BTF_ASTC_LDR_10X8`	29	10×8
`BTF_ASTC_LDR_10X10`	30	10×10
`BTF_ASTC_LDR_12X10`	31	12×10
`BTF_ASTC_LDR_12X12`	32	12×12

Transcoder Texture Formats (`TF_*`)

These constants identify the GPU texture format that the transcoder will output when transcoding a .ktx2 or .basis file. They correspond to basist::transcoder_texture_format.

Pass one of these to bt_ktx2_transcode_image_level() as the transcoder_texture_format_u32 parameter.

Note when transcoding to ASTC, the block size of the source file must match the block size of the target ASTC format. See the helper function bt_basis_get_transcoder_texture_format_from_basis_tex_format().

// basist::transcoder_texture_format: the supported transcode GPU texture formats
#define TF_ETC1_RGB 0
#define TF_ETC2_RGBA 1
#define TF_BC1_RGB 2
#define TF_BC3_RGBA 3
#define TF_BC4_R 4
#define TF_BC5_RG 5
#define TF_BC7_RGBA 6
#define TF_PVRTC1_4_RGB 8
#define TF_PVRTC1_4_RGBA 9
#define TF_ASTC_LDR_4X4_RGBA 10
#define TF_ATC_RGB 11
#define TF_ATC_RGBA 12
#define TF_FXT1_RGB 17
#define TF_PVRTC2_4_RGB 18
#define TF_PVRTC2_4_RGBA 19
#define TF_ETC2_EAC_R11 20
#define TF_ETC2_EAC_RG11 21
#define TF_BC6H 22
#define TF_ASTC_HDR_4X4_RGBA 23
#define TF_RGBA32 13
#define TF_RGB565 14
#define TF_BGR565 15
#define TF_RGBA4444 16
#define TF_RGB_HALF 24
#define TF_RGBA_HALF 25
#define TF_RGB_9E5 26
#define TF_ASTC_HDR_6X6_RGBA 27
#define TF_ASTC_LDR_5X4_RGBA 28
#define TF_ASTC_LDR_5X5_RGBA 29
#define TF_ASTC_LDR_6X5_RGBA 30
#define TF_ASTC_LDR_6X6_RGBA 31
#define TF_ASTC_LDR_8X5_RGBA 32
#define TF_ASTC_LDR_8X6_RGBA 33
#define TF_ASTC_LDR_10X5_RGBA 34
#define TF_ASTC_LDR_10X6_RGBA 35
#define TF_ASTC_LDR_8X8_RGBA 36
#define TF_ASTC_LDR_10X8_RGBA 37
#define TF_ASTC_LDR_10X10_RGBA 38
#define TF_ASTC_LDR_12X10_RGBA 39
#define TF_ASTC_LDR_12X12_RGBA 40
#define TF_TOTAL_TEXTURE_FORMATS 41

Block-Compressed Formats

Constant	Value	Description
`TF_ETC1_RGB`	0	ETC1 RGB (4 bpp, no alpha)
`TF_ETC2_RGBA`	1	ETC2 RGBA (8 bpp)
`TF_BC1_RGB`	2	BC1 / DXT1 RGB (4 bpp, always opaque)
`TF_BC3_RGBA`	3	BC3 / DXT5 RGBA (8 bpp)
`TF_BC4_R`	4	BC4 single-channel (4 bpp)
`TF_BC5_RG`	5	BC5 two-channel (8 bpp)
`TF_BC7_RGBA`	6	BC7 RGBA (8 bpp, high quality)
`TF_BC6H`	22	BC6H HDR RGB (8 bpp, unsigned half-float)
`TF_PVRTC1_4_RGB`	8	PVRTC1 4bpp RGB (power-of-2 only)
`TF_PVRTC1_4_RGBA`	9	PVRTC1 4bpp RGBA (power-of-2 only)
`TF_PVRTC2_4_RGB`	18	PVRTC2 4bpp RGB
`TF_PVRTC2_4_RGBA`	19	PVRTC2 4bpp RGBA
`TF_ATC_RGB`	11	ATC RGB (4 bpp)
`TF_ATC_RGBA`	12	ATC RGBA (8 bpp)
`TF_FXT1_RGB`	17	FXT1 RGB (4 bpp)
`TF_ETC2_EAC_R11`	20	ETC2 EAC R11 single-channel
`TF_ETC2_EAC_RG11`	21	ETC2 EAC RG11 two-channel

ASTC Formats

Constant	Value	Description
`TF_ASTC_LDR_4X4_RGBA`	10	ASTC LDR 4×4 RGBA
`TF_ASTC_HDR_4X4_RGBA`	23	ASTC HDR 4×4 RGBA
`TF_ASTC_HDR_6X6_RGBA`	27	ASTC HDR 6×6 RGBA
`TF_ASTC_LDR_5X4_RGBA`	28	ASTC LDR 5×4 RGBA
`TF_ASTC_LDR_5X5_RGBA`	29	ASTC LDR 5×5 RGBA
`TF_ASTC_LDR_6X5_RGBA`	30	ASTC LDR 6×5 RGBA
`TF_ASTC_LDR_6X6_RGBA`	31	ASTC LDR 6×6 RGBA
`TF_ASTC_LDR_8X5_RGBA`	32	ASTC LDR 8×5 RGBA
`TF_ASTC_LDR_8X6_RGBA`	33	ASTC LDR 8×6 RGBA
`TF_ASTC_LDR_10X5_RGBA`	34	ASTC LDR 10×5 RGBA
`TF_ASTC_LDR_10X6_RGBA`	35	ASTC LDR 10×6 RGBA
`TF_ASTC_LDR_8X8_RGBA`	36	ASTC LDR 8×8 RGBA
`TF_ASTC_LDR_10X8_RGBA`	37	ASTC LDR 10×8 RGBA
`TF_ASTC_LDR_10X10_RGBA`	38	ASTC LDR 10×10 RGBA
`TF_ASTC_LDR_12X10_RGBA`	39	ASTC LDR 12×10 RGBA
`TF_ASTC_LDR_12X12_RGBA`	40	ASTC LDR 12×12 RGBA

Uncompressed / Pixel Formats

Constant	Value	Description
`TF_RGBA32`	13	32-bit RGBA (8 bits per channel)
`TF_RGB565`	14	16-bit RGB (5-6-5)
`TF_BGR565`	15	16-bit BGR (5-6-5)
`TF_RGBA4444`	16	16-bit RGBA (4-4-4-4)
`TF_RGB_HALF`	24	48-bit RGB half-float (16 bits/channel)
`TF_RGBA_HALF`	25	64-bit RGBA half-float (16 bits/channel)
`TF_RGB_9E5`	26	32-bit shared-exponent RGB (9-9-9-e5)

Transcoder Decode Flags (`DECODE_FLAGS_*`)

These flags are combined (bitwise OR) and passed as the decode_flags parameter to bt_ktx2_transcode_image_level().

// basist::basisu_decode_flags: Transcode decode flags (bt_ktx2_transcode_image_level decode_flags parameter, logically OR'd)
#define DECODE_FLAGS_PVRTC_DECODE_TO_NEXT_POW2 2
#define DECODE_FLAGS_TRANSCODE_ALPHA_DATA_TO_OPAQUE_FORMATS 4
#define DECODE_FLAGS_BC1_FORBID_THREE_COLOR_BLOCKS 8
#define DECODE_FLAGS_OUTPUT_HAS_ALPHA_INDICES 16
#define DECODE_FLAGS_HIGH_QUALITY 32
#define DECODE_FLAGS_NO_ETC1S_CHROMA_FILTERING 64
#define DECODE_FLAGS_NO_DEBLOCK_FILTERING 128
#define DECODE_FLAGS_STRONGER_DEBLOCK_FILTERING 256
#define DECODE_FLAGS_FORCE_DEBLOCK_FILTERING 512
#define DECODE_FLAGS_XUASTC_LDR_DISABLE_FAST_BC7_TRANSCODING 1024

Flag	Value	Description
`PVRTC_DECODE_TO_NEXT_POW2`	2	Currently unsupported. Pad PVRTC output to the next power-of-2 dimensions (required by PVRTC1 hardware).
`TRANSCODE_ALPHA_DATA_TO_OPAQUE_FORMATS`	4	When transcoding to an opaque format (e.g. `TF_ETC1_RGB` or `TF_PVRTC1_4_RGB`), transcode the alpha slice instead of the color slice. Useful for extracting alpha into a separate opaque texture.
`BC1_FORBID_THREE_COLOR_BLOCKS`	8	Forbid 3-color BC1 blocks.
`OUTPUT_HAS_ALPHA_INDICES`	16	Internal hint flag that the output buffer layout includes alpha index data.
`HIGH_QUALITY`	32	Prefer higher-quality (but slower) transcode paths when available.
`NO_ETC1S_CHROMA_FILTERING`	64	Disable chroma filtering during ETC1S transcoding (currently impacts only BC7 target).
`NO_DEBLOCK_FILTERING`	128	Disable deblocking filter on ASTC LDR/XUASTC LDR transcoded output.
`STRONGER_DEBLOCK_FILTERING`	256	Apply a stronger deblocking filter (ASTC LDR/XUASTC LDR only).
`XUASTC_LDR_DISABLE_FAST_BC7_TRANSCODING`	1024	Disable the accelerated XUASTC → BC7 transcode path (for debugging or compatibility).