Some notes and stuff on NWN Crunch Enhanced Edition.
Basics
The crunch program will generate good DDS files for your textures from source files such as PNG, TGA, BMP and JPG.
...
You can also convert any format to, say, PNG for use in other programs. This is the easiest way to get NWN DDS (a sorta weird NWN only DDS format no longer required in NWN:EE) back to a usable format, which many of the game files and much Custom Content uses.
Stuff to Note
Compressed PNG files should be 32bit with alpha. We've found having a simply blank; eg entirely transparent for some reason texture doesn't load properly.
...
You can create your own simplified batch or powershell scripts using the original ones as a basis, or check the options out further down.
Readme
This is essentially the readme in the program. Some pertinent options will be described below.
| Code Block | ||||
|---|---|---|---|---|
| ||||
NWN Crunch: Texture Compression Tool
Based on crunch by Richard Geldreich, Jr. and Binomial LLC - https://github.com/BinomialLLC/crunch
libcrn version v1.04 x64 Built May 16 2021, 19:40:17
Error: No command line parameters specified!
Command line usage:
crunch [options] -file filename
-file filename - Required input filename, wildcards, multiple -file params OK.
-file @list.txt - List of files to convert.
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.c: http://www.nothings.org/stb_image.c
Progressive JPEG files are supported, see: http://code.google.com/p/jpeg-compressor/
Path/file related parameters:
-out filename - Output filename
-outdir dir - Output directory
-outsamedir - Write output file to input directory
-deep - Recurse subdirectories, default=false
-nooverwrite - Don't overwrite existing files
-timestamp - Update only changed files
-forcewrite - Overwrite read-only files
-recreate - Recreate directory structure
-fileformat [dds,ktx,crn,tga,bmp,png,nwn] - Output file format, default=crn or dds
Modes:
-compare - Compare input and output files (no output files are written).
-info - Only display input file statistics (no output files are written).
Misc. options:
-helperThreads # - Set number of helper threads, 0-16, default=(# of CPU's)-1
-noprogress - Disable progress output
-quiet - Disable all console output
-ignoreerrors - Continue processing files after errors. Note: The default
behavior is to immediately exit whenever an error occurs.
-logfile filename - Append output to log file
-pause - Wait for keypress on error
-window <left> <top> <right> <bottom> - Crop window before processing
-clamp <width> <height> - Crop image if larger than width/height
-clampscale <width> <height> - Scale image if larger than width/height
-nostats - Disable all output file statistics (faster)
-imagestats - Print various image qualilty 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
-invertcolors - Invert image colors, default=disabled
-normalize - Normalize for normal maps, default=disabled
-minvalue <int> - Minimum value for all channels [0,255], default=0
-setRGBtoY - Set RGB channels to luminosity, default=disabled
-setAtoY - Set Alpha Channel to luminosity, default=disabled
-setRGBAtoR - Set RGBA channels to Red channel, default=disabled
Image rescaling (mutually exclusive options)
-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.
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
-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).
-compressor [CRN,CRNF,RYG,ATI] - Set DXTn compressor, default=CRN
-dxtQuality [superfast,fast,normal,better,uber] - Endpoint optimizer speed.
Sets endpoint optimizer's max iteration depth. Default=uber.
-noendpointcaching - Don't try reusing previous DXT endpoint solutions.
-grayscalsampling - 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.
Ouptut pixel format options:
-usesourceformat - Use input file's format for output format (when possible).
All supported texture 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
Note: .CRN only supports DXTn pixel formats, NWN only support DXT1 and DXT5 formats.
Exit status: 1
PS E:\SVN\Tools and Utilities\Crunch\nwn_crunch_windows64_EE> .\nwn_crunch.exe
NWN Crunch: Texture Compression Tool
Based on crunch by Richard Geldreich, Jr. and Binomial LLC - https://github.com/BinomialLLC/crunch
libcrn version v1.04 x64 Built May 16 2021, 19:40:17
Error: No command line parameters specified!
Command line usage:
crunch [options] -file filename
-file filename - Required input filename, wildcards, multiple -file params OK.
-file @list.txt - List of files to convert.
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.c: http://www.nothings.org/stb_image.c
Progressive JPEG files are supported, see: http://code.google.com/p/jpeg-compressor/
Path/file related parameters:
-out filename - Output filename
-outdir dir - Output directory
-outsamedir - Write output file to input directory
-deep - Recurse subdirectories, default=false
-nooverwrite - Don't overwrite existing files
-timestamp - Update only changed files
-forcewrite - Overwrite read-only files
-recreate - Recreate directory structure
-fileformat [dds,ktx,crn,tga,bmp,png,nwn] - Output file format, default=crn or dds
Modes:
-compare - Compare input and output files (no output files are written).
-info - Only display input file statistics (no output files are written).
Misc. options:
-helperThreads # - Set number of helper threads, 0-16, default=(# of CPU's)-1
-noprogress - Disable progress output
-quiet - Disable all console output
-ignoreerrors - Continue processing files after errors. Note: The default
behavior is to immediately exit whenever an error occurs.
-logfile filename - Append output to log file
-pause - Wait for keypress on error
-window <left> <top> <right> <bottom> - Crop window before processing
-clamp <width> <height> - Crop image if larger than width/height
-clampscale <width> <height> - Scale image if larger than width/height
-nostats - Disable all output file statistics (faster)
-imagestats - Print various image qualilty 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
-invertcolors - Invert image colors, default=disabled
-normalize - Normalize for normal maps, default=disabled
-minvalue <int> - Minimum value for all channels [0,255], default=0
-setRGBtoY - Set RGB channels to luminosity, default=disabled
-setAtoY - Set Alpha Channel to luminosity, default=disabled
-setRGBAtoR - Set RGBA channels to Red channel, default=disabled
Image rescaling (mutually exclusive options)
-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.
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
-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).
-compressor [CRN,CRNF,RYG,ATI] - Set DXTn compressor, default=CRN
-dxtQuality [superfast,fast,normal,better,uber] - Endpoint optimizer speed.
Sets endpoint optimizer's max iteration depth. Default=uber.
-noendpointcaching - Don't try reusing previous DXT endpoint solutions.
-grayscalsampling - 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.
Ouptut pixel format options:
-usesourceformat - Use input file's format for output format (when possible).
All supported texture 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
Note: .CRN only supports DXTn pixel formats, NWN only support DXT1 and DXT5 formats. |
Basic Usage
The basic usage would be, eg in powershell to convert all PNGs in the "in" folder, to a DDS DTX1 (no alpha) image, with a yflip, quietly:
| Code Block |
|---|
.\nwn_crunch.exe -file -i "in\*.png" -outdir "out" -fileformat dds -DXT1 -yflip -quiet |
DDS Options
The main thing might be what DDS options you want to use, primarily you want to use these as per the convert_dds_mtr batch and convert_dds_portrait files:
| File Type | DTX type | Other options | Notes |
|---|---|---|---|
| Diffuse | -DXT5A | Not all diffuse textures require the alpha channel (ie if no transparency) so can use DTX1 for those | |
| Normal | -DXN | -normalize -uniformMetrics | DXN appears to be "3DC" compression |
| Specular | -DXT5A | ||
| Metallicness | -DXT5A | -minvalue 5 | |
| Roughness | -DXT5A | -invertcolors | |
| Glossiness | -DXT5A | ||
| Height | -DXT5A | ||
| Illumination | -DXT1 | No transparency allowed on illumination | |
| Portrait | |||
| Portrait | -DXT1 | -deep -recreate -mipmode none | See notes on mipmaps below - by default portraits won't load mipmaps meaning this isn't an issue, but if you ever do enable them and a DDS hasn't got them it will crash the game so be careful - you can always use just the -DXT1 setting and ignore the mipmode one |
Some Options Breakdown
Some of these are not in the readme or not clear from the readme how they work. I've found these to be the most relevant for most texture work on diffuse textures (the other MTR ones it is recommended to use the settings above).
...