CRUNCH(1)

📦
version 0.56.2 · 2 versions
, in ubuntu stonking

✨ NAME ✨

crunch — Advanced DXTn Texture Compressor 🎀

welcome to CRUNCH(1), bestie — straight outta the General Commands Manual, section 1. hydrate, sit up straight, we're compressing textures 💖

💅 SYNOPSIS 💅

crunch [options]

🦋 DESCRIPTION 🦋

okay so crunch is a lossy texture compression command line tool, and it's for developers who distribute and use content in the DXT1/5/N or 3DC/BC5 compressed mipmapped GPU texture formats. it's giving "pipeline go brrr" 🔥

this version has been upgraded with Unity improvements, added features, and extended system + hardware support. slay 💅

🌈 OPTIONS 🌈

📁 file stuff

  • -file filename — the required input filename. wildcards? yes. multiple -file params? also yes, stack 'em bestie 🫶
  • -file @list.txt — a whole list of files to convert, in a text file, fancy 💖

Supported source file formats: dds, ktx, crn, tga, bmp, png, jpg/jpeg, psd

⚠️ real talk: some file format variants are unsupported. see the docs for stb_image.h: https://github.com/nothings/stb Progressive JPEG files are supported, see: http://code.google.com/p/jpeg-compressor/
  • -out filename — name of the output file
  • -outdir dir — directory to drop output into
  • -outsamedir — write the output file into the input directory
  • -deep — recurse subdirectories, default=false
  • -nooverwrite — don't overwrite files that already exist
  • -timestamp — update only the files that actually changed
  • -forcewrite — overwrite even read-only files 😤
  • -recreate — recreate the directory structure
  • -fileformat [dds,ktx,crn,tga,bmp,png] — output file format, default=crn or dds

🎮 modes

  • -compare — compare input and output files (no output files are written. none. zero. nada 🙈)
  • -info — only display input file statistics (also writes no output files)

🧃 misc. options

  • -helperThreads # — set number of helper threads, 0-15, default=(# of CPU's)-1
  • -noTitle — disable title output at run time
  • -noprogress — disable progress output
  • -quiet — disable all console output 🤫
  • -ignoreerrors — keep processing files after errors. Note: the default behavior is to immediately exit whenever an error occurs 💀
  • -logfile filename — append output to a log file
  • -pause — wait for keypress on error
  • -window <left> <top> <right> <bottom> — crop window before processing
  • -clamp <width> <height> — crop the image if it's larger than width/height
  • -clampscale <width> <height> — scale the image if it's larger than width/height
  • -nostats — disable all output file statistics (faster ⚡)
  • -imagestats — print various image quality statistics
  • -mipstats — print statistics for each mipmap, not just the top mip
  • -lzmastats — print size of output file compressed with LZMA codec
  • -split — write faces/mip levels to multiple separate output PNG files
  • -yflip — always flip texture on Y axis before processing
  • -unflip — unflip texture if read from source file as flipped

🔍 image rescaling (mutually exclusive options)

these are mutually exclusive bestie, pick ONE, don't be greedy 🙈

  • -rescale <int> <int> — rescale image to specified resolution
  • -relscale <float> <float> — rescale image to specified relative resolution
  • -rescalemode <nearest | hi | lo> — auto-rescale non-power of two images
    • nearest — use nearest power of 2
    • hi — use next
    • lo — use previous

💎 DDS/CRN compression quality control

  • -quality # (or /q #) — set Clustered DDS/CRN quality factor [0-255]. 255=best DDS default quality is best possible. CRN default quality is 128.
  • -bitrate # — set the desired output bitrate of DDS or CRN output files.

this option causes crunch to find the quality factor closest to the desired bitrate using a binary search. it's giving overachiever energy ✨

🧬 low-level CRN specific options

  • -c # — color endpoint palette size, 32-8192, default=3072
  • -s # — color selector palette size, 32-8192, default=3072
  • -ca # — alpha endpoint palette size, 32-8192, default=3072
  • -sa # — alpha selector palette size, 32-8192, default=3072

🪄 mipmap filtering options

  • -mipMode [UseSourceOrGenerate,UseSource,Generate,None] — default mipMode is UseSourceOrGenerate
    • UseSourceOrGenerate: use source mipmaps if possible, or create new mipmaps.
    • UseSource: always use source mipmaps, if any (never generate new mipmaps)
    • Generate: always generate a new mipmap chain (ignore source mipmaps)
    • None: do not output any mipmaps
  • -mipFilter [box,tent,lanczos4,mitchell,kaiser] — default=kaiser
  • -gamma # — mipmap gamma correction value, default=2.2, use 1.0 for linear
  • -blurriness # — scale filter kernel, >1=blur, <1=sharpen, .01-8, default=.9
  • -wrap — assume texture is tiled when filtering, default=clamping
  • -renormalize — renormalize filtered normal map texels, default=disabled
  • -rtopmip — renormalize on the top mip-level too, default=disabled
  • -maxmips # — limit number of generated texture mipmap levels, 1-16, default=16
  • -minmipsize # — smallest allowable mipmap resolution, default=1

🗜️ compression options

  • -alphaThreshold # — set DXT1A alpha threshold, 0-255, default=128
Note: -alphaThreshold also changes the compressor's behavior to prefer DXT1A over DXT5 for images with alpha channels (.DDS only).
  • -uniformMetrics — use uniform color metrics, default=use perceptual metrics
  • -noAdaptiveBlocks — disable adaptive block sizes (i.e. disable macroblocks).
  • -noNormalDetection — disable normal map detection, default=disabled
  • -compressor [CRN,CRNF,RYG,ATI] — set DXTn compressor, default=CRN
  • -dxtQuality [superfast,fast,normal,better,uber] — endpoint optimizer speed.

sets the endpoint optimizer's max iteration depth. Default=uber. yes the setting is literally called uber, main character energy 👑

  • -noendpointcaching — don't try reusing previous DXT endpoint solutions.
  • -grayscalesampling — assume shader will convert fetched results to luma (Y).
  • -forceprimaryencoding — only use DXT1 color4 and DXT5 alpha8 block encodings.
  • -usetransparentindicesforblack — try DXT1 transparent indices for dark pixels.

🎨 output pixel format options

  • -usesourceformat — use input file's format for output format (when possible).

All supported texture formats (Note: .CRN only supports DXTn pixel formats):

  • -DXT1
  • -DXT2
  • -DXT3
  • -DXT4
  • -DXT5
  • -3DC
  • -DXN
  • -DXT5A
  • -DXT5_CCxY
  • -DXT5_xGxR
  • -DXT5_xGBR
  • -DXT5_AGBR
  • -DXT1A
  • -ETC1
  • -ETC2
  • -ETC2A
  • -ETC1S
  • -ETC2AS
  • -R8G8B8
  • -L8
  • -A8
  • -A8L8
  • -A8R8G8B8

👑 AUTHOR 👑

Crunch is brought to you by, and bestie they ATE 💖:

🐛 REPORTING BUGS 🐛

found a bug? not on my watch. please report bugs here: https://github.com/DaemonEngine/crunch/issues

okay that's the whole page bestie, you're officially crunch-pilled 🫶 this was the October 2025 edition of CRUNCH(1), no cap — go compress something gorgeous 💅✨
📦 where this page comes from