jessikitty/crunch
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(readme): Convert to Markdown

Browse Source 
Includes small tweaks to the original text for a nicer look.
This commit is contained in:
Jake
2016-06-16 09:20:43 +02:00
parent 97b8233acc
commit 9e7a5e80c7
1 changed files with 298 additions and 310 deletions
Download Patch File Download Diff File Expand all files Collapse all files
readme.txt → README.md
+48 -60
View File
@@ -12,34 +12,14 @@ written by Igor Pavlov (LZMA), RYG (crn_ryg_dxt*), and Sean Barrett (stb_image.c
If you use this software in a product, an acknowledgment in the product If you use this software in a product, an acknowledgment in the product
documentation would be highly appreciated but is not required. documentation would be highly appreciated but is not required.
Note: crunch originally used to live on Google Code: Note: crunch originally used to live on Google Code: https://code.google.com/p/crunch/
https://code.google.com/p/crunch/
## Overview
New for v1.04 [11/24/12]: KTX file format, basic ETC1 support, DDS format fixes, simple makefile
------------------------------------------------
Lots of higher level changes to get crnlib into a state where I can carry it forward to
support other file and texture compression formats. No major codec-level changes.
I've regression tested the codec writing .CRN and RDO .DDS files at various bitrates.
Everything seems OK, but with all the changes I made to support KTX and other formats like ETC1.
New for v1.03 [4/26/12]: crnlib more portable, Linux Port
------------------------------------------------
v1.03 has been ported to Linux. It's still a work in progress. A few features
of the command line tool don't work under Linux yet (such as -timestamp),
but the core functionality (compression/decompression/transcoding) should work
OK. I'm currently testing crnlib/crunch with Codeblocks 10.05 under Ubuntu x86.
Overview
--------
crnlib is a lossy texture compression library for developers that ship crnlib is a lossy texture compression library for developers that ship
content using the DXT1/5/N or 3DC compressed color/normal map/cubemap content using the DXT1/5/N or 3DC compressed color/normal map/cubemap
mipmapped texture formats. It was written by the same author as the open mipmapped texture formats. It was written by the same author as the open
source LZHAM lossless data compression library: source [LZHAM compression library](http://code.google.com/p/lzham/).
http://code.google.com/p/lzham/
It can compress mipmapped 2D textures, normal maps, and cubemaps to It can compress mipmapped 2D textures, normal maps, and cubemaps to
approx. 1-1.25 bits/texel, and normal maps to 1.75-2 bits/texel. The approx. 1-1.25 bits/texel, and normal maps to 1.75-2 bits/texel. The
@@ -68,21 +48,17 @@ It also supports several popular swizzled variants (several are
also supported by AMD's Compressonator): also supported by AMD's Compressonator):
DXT5_XGBR, DXT5_xGxR, DXT5_AGBR, and DXT5_CCxY (experimental luma-chroma YCoCg). DXT5_XGBR, DXT5_xGxR, DXT5_AGBR, and DXT5_CCxY (experimental luma-chroma YCoCg).
Recommended Software ## Recommended Software
--------------------
AMD's Compressonator tool is recommended to view the .DDS files created by AMD's [Compressonator tool](http://developer.amd.com/gpu/compressonator/pages/default.aspx)
the crunch tool and the included example projects: is recommended to view the .DDS files created by the crunch tool and the included example projects.
http://developer.amd.com/gpu/compressonator/pages/default.aspx
Note: Some of the swizzled DXTn .DDS output formats (such as DXT5_xGBR) Note: Some of the swizzled DXTn .DDS output formats (such as DXT5_xGBR)
read/written by the crunch tool or examples deviate from the DX9 DDS read/written by the crunch tool or examples deviate from the DX9 DDS
standard, so DXSDK tools such as DXTEX.EXE won't load them at all or standard, so DXSDK tools such as DXTEX.EXE won't load them at all or
they won't be properly displayed. they won't be properly displayed.
Compression Algorithm Details ## Compression Algorithm Details
-----------------------------
The compression process employed in creating both .CRN and The compression process employed in creating both .CRN and
clustered .DDS files utilizes a very high quality, scalable DXTn clustered .DDS files utilizes a very high quality, scalable DXTn
@@ -103,8 +79,7 @@ version will also utilize adaptive binary arithmetic coding and higher
order context modeling using already developed tech from the my LZHAM order context modeling using already developed tech from the my LZHAM
compression library. compression library.
Supported File Formats ## Supported File Formats
----------------------
crnlib supports two compressed texture file formats. The first crnlib supports two compressed texture file formats. The first
format (clustered .DDS) is simple to integrate into an existing project format (clustered .DDS) is simple to integrate into an existing project
@@ -114,7 +89,8 @@ the second, higher quality custom format (.CRN) requires a few
typically straightforward engine modifications to integrate the typically straightforward engine modifications to integrate the
.CRN->DXTn transcoder header file library into your tools/engine. .CRN->DXTn transcoder header file library into your tools/engine.
.DDS ### .DDS
crnlib can compress textures to standard DX9-style .DDS files using crnlib can compress textures to standard DX9-style .DDS files using
clustered DXTn compression, which is a subset of the approach used to clustered DXTn compression, which is a subset of the approach used to
create .CRN files.(For completeness, crnlib also supports vanilla, block create .CRN files.(For completeness, crnlib also supports vanilla, block
@@ -135,7 +111,8 @@ data.)
Clustered .DDS files are intended to be the simplest/fastest way to Clustered .DDS files are intended to be the simplest/fastest way to
integrate crnlib's tech into a project. integrate crnlib's tech into a project.
.CRN ### .CRN
The second, better, option is to compress your textures to .CRN files The second, better, option is to compress your textures to .CRN files
using crnlib. To read the resulting .CRN data, you must add the .CRN using crnlib. To read the resulting .CRN data, you must add the .CRN
transcoder library (located in the included single file, stand-alone transcoder library (located in the included single file, stand-alone
@@ -147,7 +124,7 @@ further lossless compression because they're already highly compressed.
.CRN files are a bit more difficult/risky to integrate into a project, but .CRN files are a bit more difficult/risky to integrate into a project, but
the resulting compression ratio and quality is superior vs. clustered .DDS files. the resulting compression ratio and quality is superior vs. clustered .DDS files.
.KTX ### .KTX
crnlib and crunch can read/write the .KTX file format in various pixel formats. crnlib and crunch can read/write the .KTX file format in various pixel formats.
Rate distortion optimization (clustered DXTc compression) is not yet supported Rate distortion optimization (clustered DXTc compression) is not yet supported
@@ -159,8 +136,7 @@ found that support .KTX are fairly (to very) buggy, or are limited to only a han
of pixel formats, so there's no guarantee that the .KTX files written by crnlib can of pixel formats, so there's no guarantee that the .KTX files written by crnlib can
be reliably read by other tools. be reliably read by other tools.
Building the Examples ## Building the Examples
---------------------
This release contains the source code and projects for three simple This release contains the source code and projects for three simple
example projects: example projects:
@@ -171,11 +147,14 @@ VS2005, VS2010, and gcc 4.5.0 (TDM GCC+MinGW). A codeblocks 10.05
workspace and project file is also included, but compiling crnlib this workspace and project file is also included, but compiling crnlib this
way hasn't been tested much. way hasn't been tested much.
example1: Demonstrates how to use crnlib's high-level C-helper ### example1
Demonstrates how to use crnlib's high-level C-helper
compression/decompression/transcoding functions in inc/crnlib.h. It's a compression/decompression/transcoding functions in inc/crnlib.h. It's a
fairly complete example of crnlib's functionality. fairly complete example of crnlib's functionality.
example2: Shows how to transcodec .CRN files to .DDS using *only* ### example2
Shows how to transcodec .CRN files to .DDS using **only**
the functionality in inc/crn_decomp.h. It does not link against against the functionality in inc/crn_decomp.h. It does not link against against
crnlib.lib or depend on it in any way. (Note: The complete source code, crnlib.lib or depend on it in any way. (Note: The complete source code,
approx. 4800 lines, to the CRN transcoder is included in inc/crn_decomp.h.) approx. 4800 lines, to the CRN transcoder is included in inc/crn_decomp.h.)
@@ -183,15 +162,15 @@ approx. 4800 lines, to the CRN transcoder is included in inc/crn_decomp.h.)
example2 is intended to show how simple it is to integrate CRN textures example2 is intended to show how simple it is to integrate CRN textures
into your application. into your application.
example3: Shows how to use the regular, low-level DXTn block compressor ### example3
Shows how to use the regular, low-level DXTn block compressor
functions in inc/crnlib.h. This functionality is included for functions in inc/crnlib.h. This functionality is included for
completeness. (Your engine or toolchain most likely already has its own completeness. (Your engine or toolchain most likely already has its own
DXTn compressor. crnlib's compressor is typically very competitive or DXTn compressor. crnlib's compressor is typically very competitive or
superior to most available closed and open source CPU-based superior to most available closed and open source CPU-based
compressors.) compressors.)
Creating Compressed Textures from the Command Line (crunch.exe) ## Creating Compressed Textures from the Command Line (crunch.exe)
---------------------------------------------------------------
The simplest way to create compressed textures using crnlib is to The simplest way to create compressed textures using crnlib is to
integrate the bin\crunch.exe or bin\crunch_x64.exe) command line tool integrate the bin\crunch.exe or bin\crunch_x64.exe) command line tool
@@ -208,25 +187,25 @@ form under inc/crn_decomp.h.
Here are a few example crunch.exe command lines: Here are a few example crunch.exe command lines:
1. Compress blah.tga to blah.dds using normal DXT1 compression: 1. Compress blah.tga to blah.dds using normal DXT1 compression:
crunch -file blah.tga -fileformat dds -dxt1 * `crunch -file blah.tga -fileformat dds -dxt1`
2. Compress blah.tga to blah.dds using clustered DXT1 at an effective bitrate of 1.5 bits/texel, display image statistic: 2. Compress blah.tga to blah.dds using clustered DXT1 at an effective bitrate of 1.5 bits/texel, display image statistic:
crunch -file blah.tga -fileformat dds -dxt1 -bitrate 1.5 -imagestats * `crunch -file blah.tga -fileformat dds -dxt1 -bitrate 1.5 -imagestats`
3. Compress blah.tga to blah.dds using clustered DXT1 at quality level 100 (from [0,255]), with no mipmaps, display LZMA statistics: 3. Compress blah.tga to blah.dds using clustered DXT1 at quality level 100 (from [0,255]), with no mipmaps, display LZMA statistics:
crunch -file blah.tga -fileformat dds -dxt1 -quality 100 -mipmode none -lzmastats * `crunch -file blah.tga -fileformat dds -dxt1 -quality 100 -mipmode none -lzmastats`
3. Compress blah.tga to blah.crn using clustered DXT1 at a bitrate of 1.2 bits/texel, no mipmaps: 3. Compress blah.tga to blah.crn using clustered DXT1 at a bitrate of 1.2 bits/texel, no mipmaps:
crunch -file blah.tga -dxt1 -bitrate 1.2 -mipmode none * `crunch -file blah.tga -dxt1 -bitrate 1.2 -mipmode none`
4. Decompress blah.dds to a .tga file: 4. Decompress blah.dds to a .tga file:
crunch -file blah.dds -fileformat tga * `crunch -file blah.dds -fileformat tga`
5. Transcode blah.crn to a .dds file: 5. Transcode blah.crn to a .dds file:
crunch -file blah.crn * `crunch -file blah.crn`
6. Decompress blah.crn, writing each mipmap level to a separate .tga file: 6. Decompress blah.crn, writing each mipmap level to a separate .tga file:
crunch -split -file blah.crn -fileformat tga * `crunch -split -file blah.crn -fileformat tga`
crunch.exe can do a lot more, like rescale/crop images before crunch.exe can do a lot more, like rescale/crop images before
compression, convert images from one file format to another, compare compression, convert images from one file format to another, compare
@@ -238,8 +217,7 @@ time to address. This version of crunch.exe has some reduced
functionality compared to an earlier eval release. For example, XML file functionality compared to an earlier eval release. For example, XML file
support is not included in this version. support is not included in this version.
Using crnlib ## Using crnlib
------------
The most flexible and powerful way of using crnlib is to integrate the The most flexible and powerful way of using crnlib is to integrate the
library into your editor/toolchain/etc. and directly supply it your library into your editor/toolchain/etc. and directly supply it your
@@ -248,30 +226,40 @@ inc/crnlib.h.
To compress, you basically fill in a few structs in and call one function: To compress, you basically fill in a few structs in and call one function:
void *crn_compress(const crn_comp_params &comp_params, crn_uint32 &compressed_size, crn_uint32 *pActual_quality_level = NULL, float *pActual_bitrate = NULL); ```c
void *crn_compress( const crn_comp_params &comp_params,
crn_uint32 &compressed_size,
crn_uint32 *pActual_quality_level = NULL,
float *pActual_bitrate = NULL);
```
Or, if you want crnlib to also generate mipmaps, you call this function: Or, if you want crnlib to also generate mipmaps, you call this function:
void *crn_compress(const crn_comp_params &comp_params, const crn_mipmap_params &mip_params, crn_uint32 &compressed_size, crn_uint32 *pActual_quality_level = NULL, float *pActual_bitrate = NULL); ```c
void *crn_compress( const crn_comp_params &comp_params,
const crn_mipmap_params &mip_params,
crn_uint32 &compressed_size,
crn_uint32 *pActual_quality_level = NULL,
float *pActual_bitrate = NULL);
```
You can also transcode/uncompress .DDS/.CRN files to raw 32bpp images You can also transcode/uncompress .DDS/.CRN files to raw 32bpp images
using crn_decompress_crn_to_dds() and crn_decompress_dds_to_images(). using `crn_decompress_crn_to_dds()` and `crn_decompress_dds_to_images()`.
Internally, crnlib just uses inc/crn_decomp.h to transcode textures to Internally, crnlib just uses inc/crn_decomp.h to transcode textures to
DXTn. If you only need to transcode .CRN format files to raw DXTn bits DXTn. If you only need to transcode .CRN format files to raw DXTn bits
at runtime (and not compress), you don't actually need to compile or at runtime (and not compress), you don't actually need to compile or
link against crnlib at all. Just include inc/crn_decomp.h, which link against crnlib at all. Just include inc/crn_decomp.h, which
contains a completely self-contained CRN transcoder in the "crnd" contains a completely self-contained CRN transcoder in the "crnd"
namespace. The crnd_get_texture_info(), crnd_unpack_begin(), namespace. The `crnd_get_texture_info()`, `crnd_unpack_begin()`,
crnd_unpack_level(), etc. functions are all you need to efficiently get `crnd_unpack_level()`, etc. functions are all you need to efficiently get
at the raw DXTn bits, which can be directly supplied to whatever API or at the raw DXTn bits, which can be directly supplied to whatever API or
GPU you're using. (See example2.) GPU you're using. (See example2.)
Important note: When compiling under native client, be sure to define Important note: When compiling under native client, be sure to define
the PLATFORM_NACL macro before including the inc/crn_decomp.h header file library. the `PLATFORM_NACL` macro before including the `inc/crn_decomp.h` header file library.
Known Issues/Bugs ## Known Issues/Bugs
-----------------
* crnlib currently assumes you'll be further losslessly compressing its * crnlib currently assumes you'll be further losslessly compressing its
output .DDS files using LZMA. However, some engines use weaker codecs output .DDS files using LZMA. However, some engines use weaker codecs