Etc2Comp - Texture to ETC2 compressor

Etc2Comp is a command line tool that converts textures (e.g. bitmaps) into the ETC2 format. The tool is built with a focus on encoding performance to reduce the amount of time required to compile asset heavy applications as well as reduce overall application size.

This repo provides source code that can be compiled into a binary. The binary can then be used to convert textures to the ETC2 format.

Important: This is not an official Google product. It is an experimental library published as-is. Please see the CONTRIBUTORS.md file for information about questions or issues.

Setup

This project uses CMake to generate platform-specific build files:

Linux: make files
OS X: Xcode workspace files
Microsoft Windows: Visual Studio solution files
Note: CMake supports other formats, but this doc only provides steps for one of each platform for brevity.

Refer to each platform's setup section to setup your environment and build an Etc2Comp binary. Then skip to the usage section of this page for examples of how to use the library.

Setup for OS X

build tested on this config: OS X 10.9.5 i7 16GB RAM Xcode 5.1.1 cmake 3.2.3

Start by downloading and installing the following components if they are not already installed on your development machine.

Xcode version 5.1.1, or greater
CMake version 3.2.3, or greater

To build the Etc2Comp binary:

Open a Terminal window and navigate to the project directory.
Run mkdir build_xcode
Run cd build_xcode
Run cmake -G Xcode ../
Open Xcode and import the build_xcode/EtcTest.xcodeproj file.
Open the Product menu and choose Build For -> Running.
Once the build succeeds the binary located at build_xcode/EtcTool/Debug/EtcTool can be executed.

Optional Xcode EtcTool ‘Run’ preferences note: if the build_xcode/EtcTest.xcodeproj is manually deleted then some Xcode preferences will need to be set by hand after cmake is run (these prefs are retained across cmake updates if the .xcodeproj is not deleted/removed)

Set the active scheme to ‘EtcTool’
Edit the scheme
Select option ‘Run EtcTool’, then tab ‘Arguments’. Add this launch argument: ‘-argfile ../../EtcTool/args.txt’
Select tab ‘Options’ and set a custom working directory to: ‘$(SRCROOT)/Build_Xcode/EtcTool’

SetUp for Windows

Make a build_vs2015 directory.
Invoke cmake to create the Visual Studio project.
open the 'EtcTest' solution
make the 'EtcTool' project the start up project
(optional) in the project properties, under 'Debugging ->command arguments' add the argfile textfile thats included in the EtcTool directory. example: -argfile C:\etc2\EtcTool\Args.txt

Setup For Linux

The Linux build was tested on this config: Ubuntu desktop 14.04 gcc/g++ 4.8 cmake 2.8.12.2

Verify linux has cmake and C++-11 capable g++ installed
Open shell 1 Run mkdir build_linux 1 Run cd build_linux
Invoke cmake to create the make files.
Run ‘make’
navigate to the newly created EtcTool directory ‘cd EtcTool’
run the executable: ‘./EtcTool -argfile ../../EtcTool/args.txt’

Skip to the Usage section for more information about using the tool.

Usage

Command Line Usage

EtcTool can be run from the command line with the following usage: etctool.exe source_image [options ...] -output encoded_image

The encoder will use an array of RGBA floats read from the source_image to create an ETC1 or ETC2 encoded image in encoded_image. The RGBA floats should be in the range [0:1].

Options:

-analyze <analysis_folder>
-argfile <arg_file>           additional command line arguments read from a file
-blockAtHV <H V>              encodes a single block that contains the
                              pixel specified by the H V coordinates
-compare <comparison_image>   compares source_image to comparison_image
-effort <amount>              number between 0 and 100 to specify the encoding quality 
                              (100 is the highest quality)
-errormetric <error_metric>   specify the error metric, the options are
                              rgba, rec709, numeric and normalxyz
-format <etc_format>          ETC1, RGB8, SRGB8, RGBA8, SRGB8, RGB8A1,
                              SRGB8A1 or R11
-help                         prints this message
-jobs or -j <thread_count>    specifies the number of threads (default=1)
-normalizexyz                 normalize RGB to have a length of 1
-verbose or -v                shows status information during the encoding
                              process

-analyze will run an analysis of the encoding and place it in folder "analysis_folder" (e.g. ../analysis/kodim05). within the analysis_folder, a folder will be created with a name of the current date/time (e.g. 20151204_153306). this date/time folder is used to compare encodings of the same texture over time.
within the date/time folder is a text file with several encoding stats and a 2x png image showing the encoding mode for each 4x4 block.
-argfile allows additional command line arguments to be placed in a text file
-blockAtHV selects the 4x4 pixel subset of the source image at position (H,V).
This is mainly used for debugging
-compare compares the source image to the created encoded image. The encoding will dictate what error analysis is used in the comparison.
-effort uses an "amount" between 0 and 100 to determine how much additional effort to apply during the encoding.
-errormetric selects the fitting algorithm used by the encoder. "rgba" calculates RMS error using RGB components that are weighted by A. "rec709" is similar to "rgba", except the RGB components are also weighted according to Rec709. "numeric" calculates RMS error using unweighted RGBA components. "normalize" calculates error based on dot product and vector length for RGB and RMS error for A.
-help prints out the usage message
-jobs enables multi-threading to speed up image encoding
-normalizexyz normalizes the source RGB to have a length of 1.
-verbose shows information on the current encoding process. It will then display the PSNR and time time it took to encode the image.

Note: Path names can use slashes or backslashes. The tool will convert the slashes to the appropriate polarity for the current platform.

API

The library supports two different APIs - a C-like API that is not heavily class-based and a class-based API.

main() in EtcTool.cpp contains an example of both APIs.

The Encode() method now returns an EncodingStatus that contains bit flags for reporting various warnings and flags encountered when encoding.

Copyright

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

billhibazzz / etc2comp