add a manpage for the cli tool

Author: twolife

crunch/CMakeLists.txt

@@ -20,3 +20,8 @@ target_link_libraries(${CRUNCH_EXE_NAME} ${CRUNCH_LIBRARY_NAME} ${CMAKE_THREAD_L
 
 install(TARGETS ${CRUNCH_EXE_NAME} DESTINATION bin)
 set_property(TARGET ${CRUNCH_EXE_NAME} PROPERTY POSITION_INDEPENDENT_CODE 1)
+
+if (UNIX)
+    include(GNUInstallDirs)
+    install(FILES crunch.1 DESTINATION ${CMAKE_INSTALL_MANDIR}/man1)
+endif ()

crunch/crunch.1

@@ -0,0 +1,265 @@
+.\" First draft generated by help2man 1.49.3.
+.TH CRUNCH 1 "October 2025"
+
+.SH NAME
+crunch \- Advanced DXTn Texture Compressor
+ 
+.SH SYNOPSIS
+.BR "" crunch
+[options]
+
+.SH DESCRIPTION
+.B crunch
+is a lossy texture compression command line tool for developers that
+distribute and use content in the DXT1/5/N or 3DC/BC5 compressed mipmapped
+GPU texture formats.
+
+This version has been upgraded with Unity improvements, added features,
+extended system and hardware support.
+
+.SH OPTIONS
+.TP
+\fB\-file\fR filename \- Required input filename, wildcards, multiple \fB\-file\fR params OK.
+.TP
+\fB\-file\fR @list.txt \- List of files to convert.
+
+.IP
+Supported source file formats: dds,ktx,crn,tga,bmp,png,jpg/jpeg,psd
+Note: 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/
+
+.P
+Path/file related parameters:
+.PP
+\fB\-out\fR filename \- Output filename
+.br
+\fB\-outdir\fR dir \- Output directory
+.br
+\fB\-outsamedir\fR \- Write output file to input directory
+.br
+\fB\-deep\fR \- Recurse subdirectories, default=false
+.br
+\fB\-nooverwrite\fR \- Don't overwrite existing files
+.br
+\fB\-timestamp\fR \- Update only changed files
+.br
+\fB\-forcewrite\fR \- Overwrite read\-only files
+.br
+\fB\-recreate\fR \- Recreate directory structure
+.br
+\fB\-fileformat\fR [dds,ktx,crn,tga,bmp,png] \- Output file format, default=crn or dds
+
+.P
+Modes:
+.PP
+\fB\-compare\fR \- Compare input and output files (no output files are written).
+.br
+\fB\-info\fR \- Only display input file statistics (no output files are written).
+
+.P
+Misc. options:
+.PP
+\fB\-helperThreads\fR # \- Set number of helper threads, 0\-15, default=(# of CPU's)\-1
+.br
+\fB\-noTitle\fR \- Disable title output at run time
+.br
+\fB\-noprogress\fR \- Disable progress output
+.br
+\fB\-quiet\fR \- Disable all console output
+.br
+\fB\-ignoreerrors\fR \- Continue processing files after errors.
+Note: The default behavior is to immediately exit whenever an error occurs.
+.br
+\fB\-logfile\fR filename \- Append output to log file
+.br
+\fB\-pause\fR \- Wait for keypress on error
+.br
+\fB\-window\fR <left> <top> <right> <bottom> \- Crop window before processing
+.br
+\fB\-clamp\fR <width> <height> \- Crop image if larger than width/height
+.br
+\fB\-clampscale\fR <width> <height> \- Scale image if larger than width/height
+.br
+\fB\-nostats\fR \- Disable all output file statistics (faster)
+.br
+\fB\-imagestats\fR \- Print various image quality statistics
+.br
+\fB\-mipstats\fR \- Print statistics for each mipmap, not just the top mip
+.br
+\fB\-lzmastats\fR \- Print size of output file compressed with LZMA codec
+.br
+\fB\-split\fR \- Write faces/mip levels to multiple separate output PNG files
+.br
+\fB\-yflip\fR \- Always flip texture on Y axis before processing
+.br
+\fB\-unflip\fR \- Unflip texture if read from source file as flipped
+
+.P
+Image rescaling (mutually exclusive options)
+.PP
+\fB\-rescale\fR <int> <int> \- Rescale image to specified resolution
+.br
+\fB\-relscale\fR <float> <float> \- Rescale image to specified relative resolution
+.br
+\fB\-rescalemode\fR <nearest | hi | lo> \- Auto\-rescale non\-power of two images.
+.IP
+nearest \- Use nearest power of 2
+.br
+hi \- Use next
+.br
+lo \- Use previous
+
+.P
+DDS/CRN compression quality control:
+.PP
+\fB\-quality\fR # (or \fI\,/q\/\fP #) \- Set Clustered DDS/CRN quality factor [0\-255] 255=best
+DDS default quality is best possible. CRN default quality is 128.
+.br
+\fB\-bitrate\fR # \- Set the desired output bitrate of DDS or CRN output files.
+.IP
+This option causes crunch to find the quality factor
+closest to the desired bitrate using a binary search.
+
+.P
+Low\-level CRN specific options:
+.PP
+\fB\-c\fR # \- Color endpoint palette size, 32\-8192, default=3072
+.br
+\fB\-s\fR # \- Color selector palette size, 32\-8192, default=3072
+.br
+\fB\-ca\fR # \- Alpha endpoint palette size, 32\-8192, default=3072
+.br
+\fB\-sa\fR # \- Alpha selector palette size, 32\-8192, default=3072
+
+.P
+Mipmap filtering options:
+.PP
+\fB\-mipMode\fR [UseSourceOrGenerate,UseSource,Generate,None]
+.IP
+Default mipMode is UseSourceOrGenerate
+.br
+UseSourceOrGenerate: Use source mipmaps if possible, or create new mipmaps.
+.br
+UseSource: Always use source mipmaps, if any (never generate new mipmaps)
+.br
+Generate: Always generate a new mipmap chain (ignore source mipmaps)
+.br
+None: Do not output any mipmaps
+
+.PP
+\fB\-mipFilter\fR [box,tent,lanczos4,mitchell,kaiser], default=kaiser
+.br
+\fB\-gamma\fR # \- Mipmap gamma correction value, default=2.2, use 1.0 for linear
+.br
+\fB\-blurriness\fR # \- Scale filter kernel, >1=blur, <1=sharpen, .01\-8, default=.9
+.br
+\fB\-wrap\fR \- Assume texture is tiled when filtering, default=clamping
+.br
+\fB\-renormalize\fR \- Renormalize filtered normal map texels, default=disabled
+.br
+\fB\-rtopmip\fR \- Renormalize on the top mip\-level too, default=disabled
+.br
+\fB\-maxmips\fR # \- Limit number of generated texture mipmap levels, 1\-16, default=16
+.br
+\fB\-minmipsize\fR # \- Smallest allowable mipmap resolution, default=1
+
+.P
+Compression options:
+.PP
+\fB\-alphaThreshold\fR # \- Set DXT1A alpha threshold, 0\-255, default=128
+.IP
+Note: \fB\-alphaThreshold\fR also changes the compressor's behavior to
+prefer DXT1A over DXT5 for images with alpha channels (.DDS only).
+.PP
+\fB\-uniformMetrics\fR \- Use uniform color metrics, default=use perceptual metrics
+.br
+\fB\-noAdaptiveBlocks\fR \- Disable adaptive block sizes (i.e. disable macroblocks).
+.br
+\fB\-noNormalDetection\fR \- Disable normal map detection, default=disabled
+.br
+\fB\-compressor\fR [CRN,CRNF,RYG,ATI] \- Set DXTn compressor, default=CRN
+.br
+\fB\-dxtQuality\fR [superfast,fast,normal,better,uber] \- Endpoint optimizer speed.
+.IP
+Sets endpoint optimizer's max iteration depth. Default=uber.
+.PP
+\fB\-noendpointcaching\fR \- Don't try reusing previous DXT endpoint solutions.
+.br
+\fB\-grayscalesampling\fR \- Assume shader will convert fetched results to luma (Y).
+.br
+\fB\-forceprimaryencoding\fR \- Only use DXT1 color4 and DXT5 alpha8 block encodings.
+.br
+\fB\-usetransparentindicesforblack\fR \- Try DXT1 transparent indices for dark pixels.
+
+.P
+Output pixel format options:
+.IP
+\fB\-usesourceformat\fR \- Use input file's format for output format (when possible).
+
+.IP
+All supported texture formats (Note: .CRN only supports DXTn pixel formats):
+.IP
+\fB\-DXT1\fR
+.br
+\fB\-DXT2\fR
+.br
+\fB\-DXT3\fR
+.br
+\fB\-DXT4\fR
+.br
+\fB\-DXT5\fR
+.br
+\fB\-3DC\fR
+.br
+\fB\-DXN\fR
+.br
+\fB\-DXT5A\fR
+.br
+\fB\-DXT5_CCxY\fR
+.br
+\fB\-DXT5_xGxR\fR
+.br
+\fB\-DXT5_xGBR\fR
+.br
+\fB\-DXT5_AGBR\fR
+.br
+\fB\-DXT1A\fR
+.br
+\fB\-ETC1\fR
+.br
+\fB\-ETC2\fR
+.br
+\fB\-ETC2A\fR
+.br
+\fB\-ETC1S\fR
+.br
+\fB\-ETC2AS\fR
+.br
+\fB\-R8G8B8\fR
+.br
+\fB\-L8\fR
+.br
+\fB\-A8\fR
+.br
+\fB\-A8L8\fR
+.br
+\fB\-A8R8G8B8\fR
+
+.SH AUTHOR
+Crunch is brought to you by:
+.PP
+\- 2014\-2024 Daemon Developers and contributors
+.IP
+https://github.com/DaemonEngine/crunch
+.PP
+\- 2017\-2018 Alexander Suvorov and Unity Software Inc.
+.IP
+https://github.com/Unity\-Technologies/crunch/tree/unity
+.PP
+\- 2010\-2017 Richard Geldreich, Jr. and Binomial LLC and contributors
+.IP
+https://github.com/BinomialLLC/crunch
+
+.SH REPORTING BUGS
+Please report bugs here: https://github.com/DaemonEngine/crunch/issues