Debian Codegraph @

third_party/etc2comp/README.md

raw
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.