| 1 |
# Etc2Comp - Texture to ETC2 compressor |
| 2 |
|
| 3 |
Etc2Comp is a command line tool that converts textures (e.g. bitmaps) |
| 4 |
into the [ETC2](https://en.wikipedia.org/wiki/Ericsson_Texture_Compression) |
| 5 |
format. The tool is built with a focus on encoding performance |
| 6 |
to reduce the amount of time required to compile asset heavy applications as |
| 7 |
well as reduce overall application size. |
| 8 |
|
| 9 |
This repo provides source code that can be compiled into a binary. The |
| 10 |
binary can then be used to convert textures to the ETC2 format. |
| 11 |
|
| 12 |
Important: This is not an official Google product. It is an experimental |
| 13 |
library published as-is. Please see the CONTRIBUTORS.md file for information |
| 14 |
about questions or issues. |
| 15 |
|
| 16 |
## Setup |
| 17 |
This project uses [CMake](https://cmake.org/) to generate platform-specific |
| 18 |
build files: |
| 19 |
- Linux: make files |
| 20 |
- OS X: Xcode workspace files |
| 21 |
- Microsoft Windows: Visual Studio solution files |
| 22 |
- Note: CMake supports other formats, but this doc only provides steps for |
| 23 |
one of each platform for brevity. |
| 24 |
|
| 25 |
Refer to each platform's setup section to setup your environment and build |
| 26 |
an Etc2Comp binary. Then skip to the usage section of this page for examples |
| 27 |
of how to use the library. |
| 28 |
|
| 29 |
### Setup for OS X |
| 30 |
build tested on this config: |
| 31 |
OS X 10.9.5 i7 16GB RAM |
| 32 |
Xcode 5.1.1 |
| 33 |
cmake 3.2.3 |
| 34 |
|
| 35 |
Start by downloading and installing the following components if they are not |
| 36 |
already installed on your development machine. |
| 37 |
- *Xcode* version 5.1.1, or greater |
| 38 |
- [CMake](https://cmake.org/download/) version 3.2.3, or greater |
| 39 |
|
| 40 |
To build the Etc2Comp binary: |
| 41 |
1. Open a *Terminal* window and navigate to the project directory. |
| 42 |
1. Run `mkdir build_xcode` |
| 43 |
1. Run `cd build_xcode` |
| 44 |
1. Run `cmake -G Xcode ../` |
| 45 |
1. Open *Xcode* and import the `build_xcode/EtcTest.xcodeproj` file. |
| 46 |
1. Open the Product menu and choose Build For -> Running. |
| 47 |
1. Once the build succeeds the binary located at `build_xcode/EtcTool/Debug/EtcTool` |
| 48 |
can be executed. |
| 49 |
|
| 50 |
Optional |
| 51 |
Xcode EtcTool ‘Run’ preferences |
| 52 |
note: if the build_xcode/EtcTest.xcodeproj is manually deleted then some Xcode preferences |
| 53 |
will need to be set by hand after cmake is run (these prefs are retained across |
| 54 |
cmake updates if the .xcodeproj is not deleted/removed) |
| 55 |
|
| 56 |
1. Set the active scheme to ‘EtcTool’ |
| 57 |
1. Edit the scheme |
| 58 |
1. Select option ‘Run EtcTool’, then tab ‘Arguments’. |
| 59 |
Add this launch argument: ‘-argfile ../../EtcTool/args.txt’ |
| 60 |
1. Select tab ‘Options’ and set a custom working directory to: ‘$(SRCROOT)/Build_Xcode/EtcTool’ |
| 61 |
|
| 62 |
### SetUp for Windows |
| 63 |
|
| 64 |
1. Open a *Terminal* window and navigate to the project directory. |
| 65 |
1. Run `mkdir build_vs` |
| 66 |
1. Run `cd build_vs` |
| 67 |
1. Run CMAKE, noting what build version you need, and pointing to the parent directory as the source root; |
| 68 |
For VS 2013 : `cmake -G "Visual Studio 12 2013 Win64" ../` |
| 69 |
For VS 2015 : `cmake -G "Visual Studio 14 2015 Win64" ../` |
| 70 |
NOTE: To see what supported Visual Studio outputs there are, run `cmake -G` |
| 71 |
1. open the 'EtcTest' solution |
| 72 |
1. make the 'EtcTool' project the start up project |
| 73 |
1. (optional) in the project properties, under 'Debugging ->command arguments' |
| 74 |
add the argfile textfile thats included in the EtcTool directory. |
| 75 |
example: -argfile C:\etc2\EtcTool\Args.txt |
| 76 |
|
| 77 |
### Setup For Linux |
| 78 |
The Linux build was tested on this config: |
| 79 |
Ubuntu desktop 14.04 |
| 80 |
gcc/g++ 4.8 |
| 81 |
cmake 2.8.12.2 |
| 82 |
|
| 83 |
1. Verify linux has cmake and C++-11 capable g++ installed |
| 84 |
1. Open shell |
| 85 |
1. Run `mkdir build_linux` |
| 86 |
1. Run `cd build_linux` |
| 87 |
1. Run `cmake ../` |
| 88 |
1. Run `make` |
| 89 |
1. navigate to the newly created EtcTool directory `cd EtcTool` |
| 90 |
1. run the executable: `./EtcTool -argfile ../../EtcTool/args.txt` |
| 91 |
|
| 92 |
Skip to the <a href="#usage">Usage</a> section for more information about using the |
| 93 |
tool. |
| 94 |
|
| 95 |
## Usage |
| 96 |
|
| 97 |
### Command Line Usage |
| 98 |
EtcTool can be run from the command line with the following usage: |
| 99 |
etctool.exe source_image [options ...] -output encoded_image |
| 100 |
|
| 101 |
The encoder will use an array of RGBA floats read from the source_image to create |
| 102 |
an ETC1 or ETC2 encoded image in encoded_image. The RGBA floats should be in the |
| 103 |
range [0:1]. |
| 104 |
|
| 105 |
Options: |
| 106 |
|
| 107 |
-analyze <analysis_folder> |
| 108 |
-argfile <arg_file> additional command line arguments read from a file |
| 109 |
-blockAtHV <H V> encodes a single block that contains the |
| 110 |
pixel specified by the H V coordinates |
| 111 |
-compare <comparison_image> compares source_image to comparison_image |
| 112 |
-effort <amount> number between 0 and 100 to specify the encoding quality |
| 113 |
(100 is the highest quality) |
| 114 |
-errormetric <error_metric> specify the error metric, the options are |
| 115 |
rgba, rgbx, rec709, numeric and normalxyz |
| 116 |
-format <etc_format> ETC1, RGB8, SRGB8, RGBA8, SRGB8, RGB8A1, |
| 117 |
SRGB8A1 or R11 |
| 118 |
-help prints this message |
| 119 |
-jobs or -j <thread_count> specifies the number of threads (default=1) |
| 120 |
-normalizexyz normalize RGB to have a length of 1 |
| 121 |
-verbose or -v shows status information during the encoding |
| 122 |
process |
| 123 |
-mipmaps or -m <mip_count> sets the maximum number of mipaps to generate (default=1) |
| 124 |
-mipwrap or -w <x|y|xy> sets the mipmap filter wrap mode (default=clamp) |
| 125 |
|
| 126 |
* -analyze will run an analysis of the encoding and place it in folder |
| 127 |
"analysis_folder" (e.g. ../analysis/kodim05). within the analysis_folder, a folder |
| 128 |
will be created with a name of the current date/time (e.g. 20151204_153306). this |
| 129 |
date/time folder is used to compare encodings of the same texture over time. |
| 130 |
within the date/time folder is a text file with several encoding stats and a 2x png |
| 131 |
image showing the encoding mode for each 4x4 block. |
| 132 |
|
| 133 |
* -argfile allows additional command line arguments to be placed in a text file |
| 134 |
|
| 135 |
* -blockAtHV selects the 4x4 pixel subset of the source image at position (H,V). |
| 136 |
This is mainly used for debugging |
| 137 |
|
| 138 |
* -compare compares the source image to the created encoded image. The encoding |
| 139 |
will dictate what error analysis is used in the comparison. |
| 140 |
|
| 141 |
* -effort uses an "amount" between 0 and 100 to determine how much additional effort |
| 142 |
to apply during the encoding. |
| 143 |
|
| 144 |
* -errormetric selects the fitting algorithm used by the encoder. "rgba" calculates |
| 145 |
RMS error using RGB components that are weighted by A. "rgbx" calculates RMS error |
| 146 |
using RGBA components, where A is treated as an additional data channel, instead of |
| 147 |
as alpha. "rec709" is similar to "rgba", except the RGB components are also weighted |
| 148 |
according to Rec709. "numeric" calculates RMS error using unweighted RGBA components. |
| 149 |
"normalize" calculates error based on dot product and vector length for RGB and RMS |
| 150 |
error for A. |
| 151 |
|
| 152 |
* -help prints out the usage message |
| 153 |
|
| 154 |
* -jobs enables multi-threading to speed up image encoding |
| 155 |
|
| 156 |
* -normalizexyz normalizes the source RGB to have a length of 1. |
| 157 |
|
| 158 |
* -verbose shows information on the current encoding process. It will then display the |
| 159 |
PSNR and time time it took to encode the image. |
| 160 |
|
| 161 |
* -mipmaps takes an argument that specifies how many mipmaps to generate from the |
| 162 |
source image. The mipmaps are generated with a lanczos3 filter using edge clamping. |
| 163 |
If the mipmaps option is not specified no mipmaps are created. |
| 164 |
|
| 165 |
* -mipwrap takes an argument that specifies the mipmap filter wrap mode. The options |
| 166 |
are "x", "y" and "xy" which specify wrapping in x only, y only or x and y respectively. |
| 167 |
The default options are clamping in both x and y. |
| 168 |
|
| 169 |
Note: Path names can use slashes or backslashes. The tool will convert the |
| 170 |
slashes to the appropriate polarity for the current platform. |
| 171 |
|
| 172 |
|
| 173 |
## API |
| 174 |
|
| 175 |
The library supports two different APIs - a C-like API that is not heavily |
| 176 |
class-based and a class-based API. |
| 177 |
|
| 178 |
main() in EtcTool.cpp contains an example of both APIs. |
| 179 |
|
| 180 |
The Encode() method now returns an EncodingStatus that contains bit flags for |
| 181 |
reporting various warnings and flags encountered when encoding. |
| 182 |
|
| 183 |
|
| 184 |
## Copyright |
| 185 |
Copyright 2015 Etc2Comp Authors. |
| 186 |
|
| 187 |
Licensed under the Apache License, Version 2.0 (the "License"); |
| 188 |
you may not use this file except in compliance with the License. |
| 189 |
You may obtain a copy of the License at |
| 190 |
|
| 191 |
http://www.apache.org/licenses/LICENSE-2.0 |
| 192 |
|
| 193 |
Unless required by applicable law or agreed to in writing, software |
| 194 |
distributed under the License is distributed on an "AS IS" BASIS, |
| 195 |
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 196 |
See the License for the specific language governing permissions and |
| 197 |
limitations under the License. |