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