docs(readme): Convert to Markdown
Includes small tweaks to the original text for a nicer look.
This commit is contained in:
Jake
+298
-310
@@ -1,310 +1,298 @@
|
|||||||
crunch/crnlib v1.04 - Advanced DXTn texture compression library
|
crunch/crnlib v1.04 - Advanced DXTn texture compression library
|
||||||
Copyright (C) 2010-2016 Binomial LLC http://binomial.info
|
Copyright (C) 2010-2016 Binomial LLC http://binomial.info
|
||||||
|
|
||||||
For bugs or support contact Binomial <info@binomial.info>.
|
For bugs or support contact Binomial <info@binomial.info>.
|
||||||
|
|
||||||
This software uses the ZLIB license, which is located in license.txt.
|
This software uses the ZLIB license, which is located in license.txt.
|
||||||
http://opensource.org/licenses/Zlib
|
http://opensource.org/licenses/Zlib
|
||||||
|
|
||||||
Portions of this software make use of public domain code originally
|
Portions of this software make use of public domain code originally
|
||||||
written by Igor Pavlov (LZMA), RYG (crn_ryg_dxt*), and Sean Barrett (stb_image.c).
|
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
|
crnlib is a lossy texture compression library for developers that ship
|
||||||
------------------------------------------------
|
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
|
||||||
Lots of higher level changes to get crnlib into a state where I can carry it forward to
|
source [LZHAM compression library](http://code.google.com/p/lzham/).
|
||||||
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.
|
It can compress mipmapped 2D textures, normal maps, and cubemaps to
|
||||||
Everything seems OK, but with all the changes I made to support KTX and other formats like ETC1.
|
approx. 1-1.25 bits/texel, and normal maps to 1.75-2 bits/texel. The
|
||||||
|
actual bitrate depends on the complexity of the texture itself, the
|
||||||
New for v1.03 [4/26/12]: crnlib more portable, Linux Port
|
specified quality factor/target bitrate, and ultimately on the desired
|
||||||
------------------------------------------------
|
quality needed for a particular texture.
|
||||||
|
|
||||||
v1.03 has been ported to Linux. It's still a work in progress. A few features
|
crnlib's differs significantly from other approaches because its
|
||||||
of the command line tool don't work under Linux yet (such as -timestamp),
|
compressed texture data format was carefully designed to be quickly
|
||||||
but the core functionality (compression/decompression/transcoding) should work
|
transcodable directly to DXTn with no intermediate recompression step.
|
||||||
OK. I'm currently testing crnlib/crunch with Codeblocks 10.05 under Ubuntu x86.
|
The typical (single threaded) transcode to DXTn rate is generally
|
||||||
|
between 100-250 megatexels/sec. The current library supports PC
|
||||||
Overview
|
(Win32/x64) and Xbox 360. Fast random access to individual mipmap levels
|
||||||
--------
|
is supported.
|
||||||
|
|
||||||
crnlib is a lossy texture compression library for developers that ship
|
crnlib can also generates standard .DDS files at specified quality
|
||||||
content using the DXT1/5/N or 3DC compressed color/normal map/cubemap
|
setting, which results in files that are much more compressible by
|
||||||
mipmapped texture formats. It was written by the same author as the open
|
LZMA/Deflate/etc. compared to files generated by standard DXTn texture
|
||||||
source LZHAM lossless data compression library:
|
tools (see below). This feature allows easy integration into any engine
|
||||||
http://code.google.com/p/lzham/
|
or graphics library that already supports .DDS files.
|
||||||
|
|
||||||
It can compress mipmapped 2D textures, normal maps, and cubemaps to
|
The .CRN file format supports the following core DXTn texture formats:
|
||||||
approx. 1-1.25 bits/texel, and normal maps to 1.75-2 bits/texel. The
|
DXT1 (but not DXT1A), DXT5, DXT5A, and DXN/3DC
|
||||||
actual bitrate depends on the complexity of the texture itself, the
|
|
||||||
specified quality factor/target bitrate, and ultimately on the desired
|
It also supports several popular swizzled variants (several are
|
||||||
quality needed for a particular texture.
|
also supported by AMD's Compressonator):
|
||||||
|
DXT5_XGBR, DXT5_xGxR, DXT5_AGBR, and DXT5_CCxY (experimental luma-chroma YCoCg).
|
||||||
crnlib's differs significantly from other approaches because its
|
|
||||||
compressed texture data format was carefully designed to be quickly
|
## Recommended Software
|
||||||
transcodable directly to DXTn with no intermediate recompression step.
|
|
||||||
The typical (single threaded) transcode to DXTn rate is generally
|
AMD's [Compressonator tool](http://developer.amd.com/gpu/compressonator/pages/default.aspx)
|
||||||
between 100-250 megatexels/sec. The current library supports PC
|
is recommended to view the .DDS files created by the crunch tool and the included example projects.
|
||||||
(Win32/x64) and Xbox 360. Fast random access to individual mipmap levels
|
|
||||||
is supported.
|
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
|
||||||
crnlib can also generates standard .DDS files at specified quality
|
standard, so DXSDK tools such as DXTEX.EXE won't load them at all or
|
||||||
setting, which results in files that are much more compressible by
|
they won't be properly displayed.
|
||||||
LZMA/Deflate/etc. compared to files generated by standard DXTn texture
|
|
||||||
tools (see below). This feature allows easy integration into any engine
|
## Compression Algorithm Details
|
||||||
or graphics library that already supports .DDS files.
|
|
||||||
|
The compression process employed in creating both .CRN and
|
||||||
The .CRN file format supports the following core DXTn texture formats:
|
clustered .DDS files utilizes a very high quality, scalable DXTn
|
||||||
DXT1 (but not DXT1A), DXT5, DXT5A, and DXN/3DC
|
endpoint optimizer capable of processing any number of pixels (instead
|
||||||
|
of the typical hard coded 16), optional adaptive switching between
|
||||||
It also supports several popular swizzled variants (several are
|
several macroblock sizes/configurations (currently any combination of
|
||||||
also supported by AMD's Compressonator):
|
4x4, 8x4, 4x8, and 8x8 pixel blocks), endpoint clusterization using
|
||||||
DXT5_XGBR, DXT5_xGxR, DXT5_AGBR, and DXT5_CCxY (experimental luma-chroma YCoCg).
|
top-down cluster analysis, vector quantization (VQ) of the selector
|
||||||
|
indices, and several custom algorithms for compressing the resulting
|
||||||
Recommended Software
|
endpoint/selector codebooks and macroblock indices. Multiple feedback
|
||||||
--------------------
|
passes are performed between the clusterization and VQ steps to optimize
|
||||||
|
quality, and several steps use a brute force refinement approach to improve
|
||||||
AMD's Compressonator tool is recommended to view the .DDS files created by
|
quality. The majority of compression steps are multithreaded.
|
||||||
the crunch tool and the included example projects:
|
|
||||||
|
The .CRN format currently utilizes canonical Huffman coding for speed
|
||||||
http://developer.amd.com/gpu/compressonator/pages/default.aspx
|
(similar to Deflate but with much larger tables), but the next major
|
||||||
|
version will also utilize adaptive binary arithmetic coding and higher
|
||||||
Note: Some of the swizzled DXTn .DDS output formats (such as DXT5_xGBR)
|
order context modeling using already developed tech from the my LZHAM
|
||||||
read/written by the crunch tool or examples deviate from the DX9 DDS
|
compression library.
|
||||||
standard, so DXSDK tools such as DXTEX.EXE won't load them at all or
|
|
||||||
they won't be properly displayed.
|
## Supported File Formats
|
||||||
|
|
||||||
Compression Algorithm Details
|
crnlib supports two compressed texture file formats. The first
|
||||||
-----------------------------
|
format (clustered .DDS) is simple to integrate into an existing project
|
||||||
|
(typically, no code changes are required), but it doesn't offer the
|
||||||
The compression process employed in creating both .CRN and
|
highest quality/compression ratio that crnlib is capable of. Integrating
|
||||||
clustered .DDS files utilizes a very high quality, scalable DXTn
|
the second, higher quality custom format (.CRN) requires a few
|
||||||
endpoint optimizer capable of processing any number of pixels (instead
|
typically straightforward engine modifications to integrate the
|
||||||
of the typical hard coded 16), optional adaptive switching between
|
.CRN->DXTn transcoder header file library into your tools/engine.
|
||||||
several macroblock sizes/configurations (currently any combination of
|
|
||||||
4x4, 8x4, 4x8, and 8x8 pixel blocks), endpoint clusterization using
|
### .DDS
|
||||||
top-down cluster analysis, vector quantization (VQ) of the selector
|
|
||||||
indices, and several custom algorithms for compressing the resulting
|
crnlib can compress textures to standard DX9-style .DDS files using
|
||||||
endpoint/selector codebooks and macroblock indices. Multiple feedback
|
clustered DXTn compression, which is a subset of the approach used to
|
||||||
passes are performed between the clusterization and VQ steps to optimize
|
create .CRN files.(For completeness, crnlib also supports vanilla, block
|
||||||
quality, and several steps use a brute force refinement approach to improve
|
by block DXTn compression too, but that's not very interesting.)
|
||||||
quality. The majority of compression steps are multithreaded.
|
Clustered DXTn compressed .DDS files are much more compressible than
|
||||||
|
files created by other libraries/tools. Apart from increased
|
||||||
The .CRN format currently utilizes canonical Huffman coding for speed
|
compressibility, the .DDS files generated by this process are completely
|
||||||
(similar to Deflate but with much larger tables), but the next major
|
standard so they should be fairly easy to add to a project with little
|
||||||
version will also utilize adaptive binary arithmetic coding and higher
|
to no code changes.
|
||||||
order context modeling using already developed tech from the my LZHAM
|
|
||||||
compression library.
|
To actually benefit from clustered DXTn .DDS files, your engine needs to
|
||||||
|
further losslessly compress the .DDS data generated by crnlib using a
|
||||||
Supported File Formats
|
lossless codec such as zlib, lzo, LZMA, LZHAM, etc. Most likely, your
|
||||||
----------------------
|
engine does this already. (If not, you definitely should because DXTn
|
||||||
|
compressed textures generally contain a large amount of highly redundant
|
||||||
crnlib supports two compressed texture file formats. The first
|
data.)
|
||||||
format (clustered .DDS) is simple to integrate into an existing project
|
|
||||||
(typically, no code changes are required), but it doesn't offer the
|
Clustered .DDS files are intended to be the simplest/fastest way to
|
||||||
highest quality/compression ratio that crnlib is capable of. Integrating
|
integrate crnlib's tech into a project.
|
||||||
the second, higher quality custom format (.CRN) requires a few
|
|
||||||
typically straightforward engine modifications to integrate the
|
### .CRN
|
||||||
.CRN->DXTn transcoder header file library into your tools/engine.
|
|
||||||
|
The second, better, option is to compress your textures to .CRN files
|
||||||
.DDS
|
using crnlib. To read the resulting .CRN data, you must add the .CRN
|
||||||
crnlib can compress textures to standard DX9-style .DDS files using
|
transcoder library (located in the included single file, stand-alone
|
||||||
clustered DXTn compression, which is a subset of the approach used to
|
header file library inc/crn_decomp.h) into your application. .CRN files
|
||||||
create .CRN files.(For completeness, crnlib also supports vanilla, block
|
provide noticeably higher quality at the same effective bitrate compared
|
||||||
by block DXTn compression too, but that's not very interesting.)
|
to clustered DXTn compressed .DDS files. Also, .CRN files don't require
|
||||||
Clustered DXTn compressed .DDS files are much more compressible than
|
further lossless compression because they're already highly compressed.
|
||||||
files created by other libraries/tools. Apart from increased
|
|
||||||
compressibility, the .DDS files generated by this process are completely
|
.CRN files are a bit more difficult/risky to integrate into a project, but
|
||||||
standard so they should be fairly easy to add to a project with little
|
the resulting compression ratio and quality is superior vs. clustered .DDS files.
|
||||||
to no code changes.
|
|
||||||
|
### .KTX
|
||||||
To actually benefit from clustered DXTn .DDS files, your engine needs to
|
|
||||||
further losslessly compress the .DDS data generated by crnlib using a
|
crnlib and crunch can read/write the .KTX file format in various pixel formats.
|
||||||
lossless codec such as zlib, lzo, LZMA, LZHAM, etc. Most likely, your
|
Rate distortion optimization (clustered DXTc compression) is not yet supported
|
||||||
engine does this already. (If not, you definitely should because DXTn
|
when writing .KTX files.
|
||||||
compressed textures generally contain a large amount of highly redundant
|
|
||||||
data.)
|
The .KTX file format is just like .DDS, except it's a fairly well specified
|
||||||
|
standard created by the Khronos Group. Unfortunately, almost all of the tools I've
|
||||||
Clustered .DDS files are intended to be the simplest/fastest way to
|
found that support .KTX are fairly (to very) buggy, or are limited to only a handful
|
||||||
integrate crnlib's tech into a project.
|
of pixel formats, so there's no guarantee that the .KTX files written by crnlib can
|
||||||
|
be reliably read by other tools.
|
||||||
.CRN
|
|
||||||
The second, better, option is to compress your textures to .CRN files
|
## Building the Examples
|
||||||
using crnlib. To read the resulting .CRN data, you must add the .CRN
|
|
||||||
transcoder library (located in the included single file, stand-alone
|
This release contains the source code and projects for three simple
|
||||||
header file library inc/crn_decomp.h) into your application. .CRN files
|
example projects:
|
||||||
provide noticeably higher quality at the same effective bitrate compared
|
|
||||||
to clustered DXTn compressed .DDS files. Also, .CRN files don't require
|
crn_examples.2008.sln is a Visual Studio 2008 (VC9) solution file
|
||||||
further lossless compression because they're already highly compressed.
|
containing projects for Win32 and x64. crnlib itself also builds with
|
||||||
|
VS2005, VS2010, and gcc 4.5.0 (TDM GCC+MinGW). A codeblocks 10.05
|
||||||
.CRN files are a bit more difficult/risky to integrate into a project, but
|
workspace and project file is also included, but compiling crnlib this
|
||||||
the resulting compression ratio and quality is superior vs. clustered .DDS files.
|
way hasn't been tested much.
|
||||||
|
|
||||||
.KTX
|
### example1
|
||||||
|
|
||||||
crnlib and crunch can read/write the .KTX file format in various pixel formats.
|
Demonstrates how to use crnlib's high-level C-helper
|
||||||
Rate distortion optimization (clustered DXTc compression) is not yet supported
|
compression/decompression/transcoding functions in inc/crnlib.h. It's a
|
||||||
when writing .KTX files.
|
fairly complete example of crnlib's functionality.
|
||||||
|
|
||||||
The .KTX file format is just like .DDS, except it's a fairly well specified
|
### example2
|
||||||
standard created by the Khronos Group. Unfortunately, almost all of the tools I've
|
Shows how to transcodec .CRN files to .DDS using **only**
|
||||||
found that support .KTX are fairly (to very) buggy, or are limited to only a handful
|
the functionality in inc/crn_decomp.h. It does not link against against
|
||||||
of pixel formats, so there's no guarantee that the .KTX files written by crnlib can
|
crnlib.lib or depend on it in any way. (Note: The complete source code,
|
||||||
be reliably read by other tools.
|
approx. 4800 lines, to the CRN transcoder is included in inc/crn_decomp.h.)
|
||||||
|
|
||||||
Building the Examples
|
example2 is intended to show how simple it is to integrate CRN textures
|
||||||
---------------------
|
into your application.
|
||||||
|
|
||||||
This release contains the source code and projects for three simple
|
### example3
|
||||||
example projects:
|
Shows how to use the regular, low-level DXTn block compressor
|
||||||
|
functions in inc/crnlib.h. This functionality is included for
|
||||||
crn_examples.2008.sln is a Visual Studio 2008 (VC9) solution file
|
completeness. (Your engine or toolchain most likely already has its own
|
||||||
containing projects for Win32 and x64. crnlib itself also builds with
|
DXTn compressor. crnlib's compressor is typically very competitive or
|
||||||
VS2005, VS2010, and gcc 4.5.0 (TDM GCC+MinGW). A codeblocks 10.05
|
superior to most available closed and open source CPU-based
|
||||||
workspace and project file is also included, but compiling crnlib this
|
compressors.)
|
||||||
way hasn't been tested much.
|
|
||||||
|
## Creating Compressed Textures from the Command Line (crunch.exe)
|
||||||
example1: Demonstrates how to use crnlib's high-level C-helper
|
|
||||||
compression/decompression/transcoding functions in inc/crnlib.h. It's a
|
The simplest way to create compressed textures using crnlib is to
|
||||||
fairly complete example of crnlib's functionality.
|
integrate the bin\crunch.exe or bin\crunch_x64.exe) command line tool
|
||||||
|
into your texture build toolchain or export process. It can write DXTn
|
||||||
example2: Shows how to transcodec .CRN files to .DDS using *only*
|
compressed 2D/cubemap textures to regular DXTn compressed .DDS,
|
||||||
the functionality in inc/crn_decomp.h. It does not link against against
|
clustered (or reduced entropy) DXTn compressed .DDS, or .CRN files. It
|
||||||
crnlib.lib or depend on it in any way. (Note: The complete source code,
|
can also transcode or decompress files to several standard image
|
||||||
approx. 4800 lines, to the CRN transcoder is included in inc/crn_decomp.h.)
|
formats, such as TGA or BMP. Run crunch.exe with no options for help.
|
||||||
|
|
||||||
example2 is intended to show how simple it is to integrate CRN textures
|
The .CRN files created by crunch.exe can be efficiently transcoded to
|
||||||
into your application.
|
DXTn using the included CRN transcoding library, located in full source
|
||||||
|
form under inc/crn_decomp.h.
|
||||||
example3: Shows how to use the regular, low-level DXTn block compressor
|
|
||||||
functions in inc/crnlib.h. This functionality is included for
|
Here are a few example crunch.exe command lines:
|
||||||
completeness. (Your engine or toolchain most likely already has its own
|
|
||||||
DXTn compressor. crnlib's compressor is typically very competitive or
|
1. Compress blah.tga to blah.dds using normal DXT1 compression:
|
||||||
superior to most available closed and open source CPU-based
|
* `crunch -file blah.tga -fileformat dds -dxt1`
|
||||||
compressors.)
|
|
||||||
|
2. Compress blah.tga to blah.dds using clustered DXT1 at an effective bitrate of 1.5 bits/texel, display image statistic:
|
||||||
Creating Compressed Textures from the Command Line (crunch.exe)
|
* `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:
|
||||||
The simplest way to create compressed textures using crnlib is to
|
* `crunch -file blah.tga -fileformat dds -dxt1 -quality 100 -mipmode none -lzmastats`
|
||||||
integrate the bin\crunch.exe or bin\crunch_x64.exe) command line tool
|
|
||||||
into your texture build toolchain or export process. It can write DXTn
|
3. Compress blah.tga to blah.crn using clustered DXT1 at a bitrate of 1.2 bits/texel, no mipmaps:
|
||||||
compressed 2D/cubemap textures to regular DXTn compressed .DDS,
|
* `crunch -file blah.tga -dxt1 -bitrate 1.2 -mipmode none`
|
||||||
clustered (or reduced entropy) DXTn compressed .DDS, or .CRN files. It
|
|
||||||
can also transcode or decompress files to several standard image
|
4. Decompress blah.dds to a .tga file:
|
||||||
formats, such as TGA or BMP. Run crunch.exe with no options for help.
|
* `crunch -file blah.dds -fileformat tga`
|
||||||
|
|
||||||
The .CRN files created by crunch.exe can be efficiently transcoded to
|
5. Transcode blah.crn to a .dds file:
|
||||||
DXTn using the included CRN transcoding library, located in full source
|
* `crunch -file blah.crn`
|
||||||
form under inc/crn_decomp.h.
|
|
||||||
|
6. Decompress blah.crn, writing each mipmap level to a separate .tga file:
|
||||||
Here are a few example crunch.exe command lines:
|
* `crunch -split -file blah.crn -fileformat tga`
|
||||||
|
|
||||||
1. Compress blah.tga to blah.dds using normal DXT1 compression:
|
crunch.exe can do a lot more, like rescale/crop images before
|
||||||
crunch -file blah.tga -fileformat dds -dxt1
|
compression, convert images from one file format to another, compare
|
||||||
|
images, process multiple images, etc.
|
||||||
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
|
Note: I would have included the full source to crunch.exe, but it still
|
||||||
|
has some low-level dependencies to crnlib internals which I didn't have
|
||||||
3. Compress blah.tga to blah.dds using clustered DXT1 at quality level 100 (from [0,255]), with no mipmaps, display LZMA statistics:
|
time to address. This version of crunch.exe has some reduced
|
||||||
crunch -file blah.tga -fileformat dds -dxt1 -quality 100 -mipmode none -lzmastats
|
functionality compared to an earlier eval release. For example, XML file
|
||||||
|
support is not included in this version.
|
||||||
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
|
## Using crnlib
|
||||||
|
|
||||||
4. Decompress blah.dds to a .tga file:
|
The most flexible and powerful way of using crnlib is to integrate the
|
||||||
crunch -file blah.dds -fileformat tga
|
library into your editor/toolchain/etc. and directly supply it your
|
||||||
|
raw/source texture bits. See the C-style API's and comments in
|
||||||
5. Transcode blah.crn to a .dds file:
|
inc/crnlib.h.
|
||||||
crunch -file blah.crn
|
|
||||||
|
To compress, you basically fill in a few structs in and call one function:
|
||||||
6. Decompress blah.crn, writing each mipmap level to a separate .tga file:
|
|
||||||
crunch -split -file blah.crn -fileformat tga
|
```c
|
||||||
|
void *crn_compress( const crn_comp_params &comp_params,
|
||||||
crunch.exe can do a lot more, like rescale/crop images before
|
crn_uint32 &compressed_size,
|
||||||
compression, convert images from one file format to another, compare
|
crn_uint32 *pActual_quality_level = NULL,
|
||||||
images, process multiple images, etc.
|
float *pActual_bitrate = NULL);
|
||||||
|
```
|
||||||
Note: I would have included the full source to crunch.exe, but it still
|
|
||||||
has some low-level dependencies to crnlib internals which I didn't have
|
Or, if you want crnlib to also generate mipmaps, you call this function:
|
||||||
time to address. This version of crunch.exe has some reduced
|
|
||||||
functionality compared to an earlier eval release. For example, XML file
|
```c
|
||||||
support is not included in this version.
|
void *crn_compress( const crn_comp_params &comp_params,
|
||||||
|
const crn_mipmap_params &mip_params,
|
||||||
Using crnlib
|
crn_uint32 &compressed_size,
|
||||||
------------
|
crn_uint32 *pActual_quality_level = NULL,
|
||||||
|
float *pActual_bitrate = NULL);
|
||||||
The most flexible and powerful way of using crnlib is to integrate the
|
```
|
||||||
library into your editor/toolchain/etc. and directly supply it your
|
|
||||||
raw/source texture bits. See the C-style API's and comments in
|
You can also transcode/uncompress .DDS/.CRN files to raw 32bpp images
|
||||||
inc/crnlib.h.
|
using `crn_decompress_crn_to_dds()` and `crn_decompress_dds_to_images()`.
|
||||||
|
|
||||||
To compress, you basically fill in a few structs in and call one function:
|
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
|
||||||
void *crn_compress(const crn_comp_params &comp_params, crn_uint32 &compressed_size, crn_uint32 *pActual_quality_level = NULL, float *pActual_bitrate = NULL);
|
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
|
||||||
Or, if you want crnlib to also generate mipmaps, you call this function:
|
contains a completely self-contained CRN transcoder in the "crnd"
|
||||||
|
namespace. The `crnd_get_texture_info()`, `crnd_unpack_begin()`,
|
||||||
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);
|
`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
|
||||||
You can also transcode/uncompress .DDS/.CRN files to raw 32bpp images
|
GPU you're using. (See example2.)
|
||||||
using crn_decompress_crn_to_dds() and crn_decompress_dds_to_images().
|
|
||||||
|
Important note: When compiling under native client, be sure to define
|
||||||
Internally, crnlib just uses inc/crn_decomp.h to transcode textures to
|
the `PLATFORM_NACL` macro before including the `inc/crn_decomp.h` header file library.
|
||||||
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
|
## Known Issues/Bugs
|
||||||
link against crnlib at all. Just include inc/crn_decomp.h, which
|
|
||||||
contains a completely self-contained CRN transcoder in the "crnd"
|
* crnlib currently assumes you'll be further losslessly compressing its
|
||||||
namespace. The crnd_get_texture_info(), crnd_unpack_begin(),
|
output .DDS files using LZMA. However, some engines use weaker codecs
|
||||||
crnd_unpack_level(), etc. functions are all you need to efficiently get
|
such as LZO, zlib, or custom codecs, so crnlib's bitrate measurements
|
||||||
at the raw DXTn bits, which can be directly supplied to whatever API or
|
will be inaccurate. It should be easy to allow the caller to plug-in
|
||||||
GPU you're using. (See example2.)
|
custom lossless compressors for bitrate measurement.
|
||||||
|
|
||||||
Important note: When compiling under native client, be sure to define
|
* Compressing to a desired bitrate can be time consuming, especially when
|
||||||
the PLATFORM_NACL macro before including the inc/crn_decomp.h header file library.
|
processing large (2k or 4k) images to the .CRN format. There are several
|
||||||
|
high-level optimizations employed when compressing to clustered DXTn .DDS
|
||||||
Known Issues/Bugs
|
files using multiple trials, but not so for .CRN.
|
||||||
-----------------
|
|
||||||
|
* The .CRN compressor does not currently use 3 color (transparent) DXT1
|
||||||
* crnlib currently assumes you'll be further losslessly compressing its
|
blocks at all, only 4 color blocks. So it doesn't support DXT1A
|
||||||
output .DDS files using LZMA. However, some engines use weaker codecs
|
transparency, and its output quality suffers a little due to this
|
||||||
such as LZO, zlib, or custom codecs, so crnlib's bitrate measurements
|
limitation. (Note that the clustered DXTn compressor used when
|
||||||
will be inaccurate. It should be easy to allow the caller to plug-in
|
writing clustered .DDS files does *not* have this limitation.)
|
||||||
custom lossless compressors for bitrate measurement.
|
|
||||||
|
* Clustered DXT5/DXT5A compressor is able to group DXT5A blocks into
|
||||||
* Compressing to a desired bitrate can be time consuming, especially when
|
clusters only if they use absolute (black/white) selector indices. This
|
||||||
processing large (2k or 4k) images to the .CRN format. There are several
|
hurts performance at very low bitrates, because too many bits are
|
||||||
high-level optimizations employed when compressing to clustered DXTn .DDS
|
effectively given to alpha.
|
||||||
files using multiple trials, but not so for .CRN.
|
|
||||||
|
* DXT3 is not supported when writing .CRN or clustered DXTn DDS files.
|
||||||
* The .CRN compressor does not currently use 3 color (transparent) DXT1
|
(DXT3 is supported by crnlib's when compressing to regular DXTn DDS
|
||||||
blocks at all, only 4 color blocks. So it doesn't support DXT1A
|
files.) You'll get DXT5 files if you request DXT3. However, DXT3 is
|
||||||
transparency, and its output quality suffers a little due to this
|
supported by the regular DXTn block compressor. (DXT3's 4bpp fixed alpha
|
||||||
limitation. (Note that the clustered DXTn compressor used when
|
sucks verses DXT5 alpha blocks, so I don't see this as a bug deal.)
|
||||||
writing clustered .DDS files does *not* have this limitation.)
|
|
||||||
|
* The DXT5_CCXY format uses a simple YCoCg encoding that is workable but
|
||||||
* Clustered DXT5/DXT5A compressor is able to group DXT5A blocks into
|
hasn't been tuned for max. quality yet.
|
||||||
clusters only if they use absolute (black/white) selector indices. This
|
|
||||||
hurts performance at very low bitrates, because too many bits are
|
* Clustered (or rate distortion optimized) DXTc compression is only
|
||||||
effectively given to alpha.
|
supported when writing to .DDS, not .KTX. Also, only plain block by block
|
||||||
|
compression is supported when writing to ETC1, and .CRN does not support ETC1.
|
||||||
* DXT3 is not supported when writing .CRN or clustered DXTn DDS files.
|
|
||||||
(DXT3 is supported by crnlib's when compressing to regular DXTn DDS
|
|
||||||
files.) You'll get DXT5 files if you request DXT3. However, DXT3 is
|
|
||||||
supported by the regular DXTn block compressor. (DXT3's 4bpp fixed alpha
|
|
||||||
sucks verses DXT5 alpha blocks, so I don't see this as a bug deal.)
|
|
||||||
|
|
||||||
* The DXT5_CCXY format uses a simple YCoCg encoding that is workable but
|
|
||||||
hasn't been tuned for max. quality yet.
|
|
||||||
|
|
||||||
* Clustered (or rate distortion optimized) DXTc compression is only
|
|
||||||
supported when writing to .DDS, not .KTX. Also, only plain block by block
|
|
||||||
compression is supported when writing to ETC1, and .CRN does not support ETC1.
|
|
||||||
|
|
||||||
Reference in New Issue
Block a user