README.md
1# Background
2
3libultrahdr is an image compression library that uses gain map technology
4to store and distribute HDR images. Conceptually on the encoding side, the
5library accepts SDR and HDR rendition of an image and from these a Gain Map
6(quotient between the two renditions) is computed. The library then uses
7backward compatible means to store the base image (SDR), gain map image and
8some associated metadata. Legacy readers that do not support handling the
9gain map image and/or metadata, will display the base image. Readers that
10support the format combine the base image with the gain map and render a
11high dynamic range image on compatible displays.
12
13For additional information about libultrahdr, see android hdr-image-format
14[guide](https://developer.android.com/guide/topics/media/platform/hdr-image-format).
15
16
17## Building libultrahdr
18
19### Requirements
20
21- [CMake](http://www.cmake.org) v3.13 or later
22- C++ compiler, supporting at least C++17.
23- libultrahdr uses jpeg compression format to store sdr image and gainmap quotient.
24 So, libjpeg or any other jpeg codec that is ABI and API compatible with libjpeg.
25
26The library offers a way to skip installing libjpeg by passing `UHDR_BUILD_DEPS=1`
27at the time of configure. That is, `cmake -DUHDR_BUILD_DEPS=1` will clone jpeg codec
28from [link](https://github.com/libjpeg-turbo/libjpeg-turbo.git) and include it in
29the build process. This is however not recommended.
30
31If jpeg is included in the build process then to build jpeg with simd extensions,
32- C compiler
33- [NASM](http://www.nasm.us) or [Yasm](http://yasm.tortall.net) are needed.
34 * If using NASM, 2.13 or later is required.
35 * If using Yasm, 1.2.0 or later is required.
36
37### Build Procedure
38
39To build libultrahdr, examples, unit tests:
40
41### Un*x (including Linux, Mac)
42
43 mkdir build_directory
44 cd build_directory
45 cmake -G "Unix Makefiles" -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DUHDR_BUILD_TESTS=1 ../
46 make
47 ctest
48 make install
49
50This will generate the following files under `build_directory`:
51
52**libuhdr.so or libuhdr.dylib**<br> ultrahdr shared library
53
54**libuhdr.pc**<br> ultrahdr pkg-config file
55
56**ultrahdr_app**<br> Statically linked sample application demonstrating ultrahdr API usage
57
58**ultrahdr_unit_test**<br> Unit tests
59
60`make install` will install libuhdr.so, ultrahdr_api.h, libuhdr.pc for system-wide usage and
61`make uninstall` will remove the same.
62
63### MinGW
64
65NOTE: This assumes that you are building on a Windows machine using the MSYS
66environment.
67
68 mkdir build_directory
69 cd build_directory
70 cmake -G "MSYS Makefiles" -DUHDR_BUILD_TESTS=1 ../
71 cmake --build ./
72 ctest
73
74 mkdir build_directory
75 cd build_directory
76 cmake -G "MinGW Makefiles" -DUHDR_BUILD_TESTS=1 ../
77 cmake --build ./
78 ctest
79
80This will generate the following files under `build_directory`:
81
82**libuhdr.dll**<br> ultrahdr shared library
83
84**ultrahdr_app.exe**<br> Sample application demonstrating ultrahdr API
85
86**ultrahdr_unit_test.exe**<br> Unit tests
87
88### Visual C++ (IDE)
89
90 mkdir build_directory
91 cd build_directory
92 cmake -G "Visual Studio 16 2019" -DUHDR_BUILD_DEPS=1 -DUHDR_BUILD_TESTS=1 ../
93 cmake --build ./ --config=Release
94 ctest -C Release
95
96This will generate the following files under `build_directory/Release`:
97
98**ultrahdr_app.exe**<br> Sample application demonstrating ultrahdr API
99
100**ultrahdr_unit_test.exe**<br> Unit tests
101
102### Visual C++ (Command line)
103
104 mkdir build_directory
105 cd build_directory
106 cmake -G "NMake Makefiles" -DUHDR_BUILD_DEPS=1 -DUHDR_BUILD_TESTS=1 ../
107 cmake --build ./
108 ctest
109
110This will generate the following files under `build_directory`:
111
112**ultrahdr_app.exe**<br> Sample application demonstrating ultrahdr API
113
114**ultrahdr_unit_test.exe**<br> Unit tests
115
116
117NOTE: To not build unit tests, skip passing `-DUHDR_BUILD_TESTS=1`
118
119### Building Benchmark
120
121To build benchmarks, pass `-DUHDR_BUILD_BENCHMARK=1` to cmake configure command and build.
122
123This will additionally generate,
124
125**ultrahdr_bm**<br> Benchmark tests
126
127
128### Building Fuzzers
129
130Refer to [README.md](fuzzer/README.md) for complete instructions.
131
132## Using libultrahdr
133
134A detailed description of libultrahdr encode and decode api is included in [ultrahdr_api.h](ultrahdr_api.h)
135and for sample usage refer [demo app](examples/ultrahdr_app.cpp).
136
137libultrahdr includes two classes of APIs, one to compress and the other to decompress HDR images:
138
139### Encoding api outline:
140
141| Scenario | Hdr intent raw | Sdr intent raw | Sdr intent compressed | Gain map compressed | Quality | Exif | Use Case |
142|:---------:| :----------: | :----------: | :---------------------: | :-------------------: | :-------: | :---------: | :-------- |
143| API - 0 | P010 | No | No | No | Optional| Optional | Used if, only hdr raw intent is present. [^1] |
144| API - 1 | P010 | YUV420 | No | No | Optional| Optional | Used if, hdr raw and sdr raw intents are present.[^2] |
145| API - 2 | P010 | YUV420 | Yes | No | No | No | Used if, hdr raw, sdr raw and sdr compressed intents are present.[^3] |
146| API - 3 | P010 | No | Yes | No | No | No | Used if, hdr raw and sdr compressed intents are present.[^4] |
147| API - 4 | No | No | Yes | Yes | No | No | Used if, sdr compressed, gain map compressed and GainMap Metadata are present.[^5] |
148
149[^1]: Tonemap hdr to sdr. Compute gain map from hdr and sdr. Compress sdr and gainmap at quality configured. Add exif if provided. Combine sdr compressed, gainmap in multi picture format with gainmap metadata.
150[^2]: Compute gain map from hdr and sdr. Compress sdr and gainmap at quality configured. Add exif if provided. Combine sdr compressed, gainmap in multi picture format with gainmap metadata.
151[^3]: Compute gain map from hdr and raw sdr. Compress gainmap. Combine sdr compressed, gainmap in multi picture format with gainmap metadata.
152[^4]: Decode compressed sdr input. Compute gain map from hdr and decoded sdr. Compress gainmap. Combine sdr compressed, gainmap in multi picture format with gainmap metadata.
153[^5]: Combine sdr compressed, gainmap in multi picture format with gainmap metadata.
154
155### Decoding api outline:
156
157Configure display device characteristics (display transfer characteristics, max display boost) for optimal usage.
158
159| Input | Usage |
160| ------------- | ------------- |
161| max_display_boost | (optional, >= 1.0) the maximum available boost supported by a display. |
162| supported color transfer format pairs | <table><thead><tr><th>color transfer</th><th>Color format </th></tr></thead><tbody><tr><td>SDR</td><td>32bppRGBA8888</td></tr><tr><td>HDR_LINEAR</td><td>64bppRGBAHalfFloat</td></tr><tr><td>HDR_PQ</td><td>32bppRGBA1010102 PQ</td></tr><tr><td>HDR_HLG</td><td>32bppRGBA1010102 HLG</td></tr></tbody></table> |
163