Texture Optimization

TextureConverter is a specialized command-line tool provided by Apple for processing, compressing, and converting textures for use with Metal and Apple Silicon GPUs. It is distributed with Xcode’s Metal developer tools.

Supported Formats

Format	Usage	Notes
ASTC	Preferred for visionOS	Supports varying block sizes (4x4 to 12x12) and HDR.
BC1-7	Desktop / Console	Standard generic compression.
ETC2	Mobile (Legacy)	Older Android/iOS standard.

Output Types

• KTX2 (.ktx2): The preferred modern container for streaming textures.
• OpenEXR (.exr): For HDR environment maps and light probes.

---

Basic Usage

You can access the tool via xcrun:

xcrun TextureConverter [options] input.png

1. Compress for Quality (ASTC 4x4)

This provides the highest visual quality for character skins or hero assets.

xcrun TextureConverter \
    --compression_format=ASTC4x4 \
    --compression_quality=Highest \
    --output=Hero_Diff.ktx2 \
    Hero_Diff.png

2. Compress for Size (ASTC 8x8)

Best for background props or roughness/metallic maps where high frequency detail matters less.

xcrun TextureConverter \
    --compression_format=ASTC8x8 \
    --compression_quality=Medium \
    --output=Prop_Rough.ktx2 \
    Prop_Rough.png

3. Build a Cubemap

Assemble 6 faces into a single .ktx2 environment map.

xcrun TextureConverter --mode=convert --build_cubemap --output=Skybox.ktx2 \
    posx.png negx.png posy.png negy.png posz.png negz.png

---

Preflight Integration

Preflight uses TextureConverter under the hood for its fix:setTexture optimization tools.

When you choose to “Optimize Texture” in the Inspector:

1. Preflight analyzes the source image resolution (e.g., 4096x4096).
2. It selects an appropriate ASTC block size (4x4 for 4K, 6x6 for 2K).
3. It runs TextureConverter to generate a .ktx2 file.
4. It updates the USD reference to point to the new file.

Note: You must have Xcode Command Line Tools installed for this feature to work.