libultrahdr is an image compression library that uses gain map technology to store and distribute HDR images. Conceptually on the encoding side, the library accepts SDR and HDR rendition of an image and from these a Gain Map (quotient between the two renditions) is computed. The library then uses backward compatible means to store the base image (SDR), gain map image and some associated metadata. Legacy readers that do not support handling the gain map image and/or metadata, will display the base image. Readers that support the format combine the base image with the gain map and render a high dynamic range image on compatible displays.
For additional information about libultrahdr, see android hdr-image-format guide.
- CMake v3.13 or later
- C++ compiler, supporting at least C++17.
- libultrahdr uses jpeg compression format to store sdr image and gainmap quotient. So, libjpeg or any other jpeg codec that is ABI and API compatible with libjpeg.
The library offers a way to skip installing libjpeg by passing UHDR_BUILD_DEPS=1
at the time of configure. That is, cmake -DUHDR_BUILD_DEPS=1
will clone jpeg codec
from link and include it in
the build process. This is however not recommended.
If jpeg is included in the build process then,
- C compiler
- For building x86/x86_64 SIMD optimizations, NASM or
Yasm.
- If using NASM, 2.13 or later is required.
- If using Yasm, 1.2.0 or later is required.
To build libultrahdr, examples, unit tests:
mkdir build_directory
cd build_directory
cmake -G "Unix Makefiles" -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DUHDR_BUILD_TESTS=1 ../
make
ctest
make install
This will generate the following files under build_directory
:
libuhdr.so or libuhdr.dylib
ultrahdr shared library
libuhdr.pc
ultrahdr pkg-config file
ultrahdr_app
Statically linked sample application demonstrating ultrahdr API usage
ultrahdr_unit_test
Unit tests
make install
will install libuhdr.so, ultrahdr_api.h, libuhdr.pc for system-wide usage and
make uninstall
will remove the same.
NOTE: This assumes that you are building on a Windows machine using the MSYS environment.
mkdir build_directory
cd build_directory
cmake -G "MSYS Makefiles" -DUHDR_BUILD_TESTS=1 ../
cmake --build ./
ctest
mkdir build_directory
cd build_directory
cmake -G "MinGW Makefiles" -DUHDR_BUILD_TESTS=1 ../
cmake --build ./
ctest
This will generate the following files under build_directory
:
libuhdr.dll
ultrahdr shared library
ultrahdr_app.exe
Sample application demonstrating ultrahdr API
ultrahdr_unit_test.exe
Unit tests
mkdir build_directory
cd build_directory
cmake -G "Visual Studio 16 2019" -DUHDR_BUILD_DEPS=1 -DUHDR_BUILD_TESTS=1 ../
cmake --build ./ --config=Release
ctest -C Release
This will generate the following files under build_directory/Release
:
ultrahdr_app.exe
Sample application demonstrating ultrahdr API
ultrahdr_unit_test.exe
Unit tests
mkdir build_directory
cd build_directory
cmake -G "NMake Makefiles" -DUHDR_BUILD_DEPS=1 -DUHDR_BUILD_TESTS=1 ../
cmake --build ./
ctest
This will generate the following files under build_directory
:
ultrahdr_app.exe
Sample application demonstrating ultrahdr API
ultrahdr_unit_test.exe
Unit tests
NOTE: To not build unit tests, skip passing -DUHDR_BUILD_TESTS=1
To build libultrahdr, examples:
NOTE: This assumes that you are building on a machine that has toolchain for 32-bit Armv7 GNU/Linux systems.
mkdir build_directory
cd build_directory
cmake -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/arm-linux-gnueabihf.cmake -DUHDR_BUILD_DEPS=1 ../
make
NOTE: This assumes that you are building on a machine that has toolchain for 64-bit Armv8 GNU/Linux systems.
mkdir build_directory
cd build_directory
cmake -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/arm-linux-gnueabihf.cmake -DUHDR_BUILD_DEPS=1 ../
make
NOTE: This assumes that you are building on a machine that has Android NDK.
mkdir build_directory
cd build_directory
cmake -G Ninja \
-DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/android.cmake\
-DUHDR_ANDROID_NDK_PATH=/opt/android-ndk-r26d/\
-DUHDR_BUILD_DEPS=1\
-DANDROID_ABI=armeabi-v7a\
-DANDROID_PLATFORM=android-23 ../
make
mkdir build_directory
cd build_directory
cmake -G Ninja \
-DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/android.cmake\
-DUHDR_ANDROID_NDK_PATH=/opt/android-ndk-r26d/\
-DUHDR_BUILD_DEPS=1\
-DANDROID_ABI=arm64-v8a\
-DANDROID_PLATFORM=android-23 ../
make
mkdir build_directory
cd build_directory
cmake -G Ninja \
-DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/android.cmake\
-DUHDR_ANDROID_NDK_PATH=/opt/android-ndk-r26d/\
-DUHDR_BUILD_DEPS=1\
-DANDROID_ABI=x86\
-DANDROID_PLATFORM=android-23 ../
make
mkdir build_directory
cd build_directory
cmake -G Ninja \
-DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/android.cmake\
-DUHDR_ANDROID_NDK_PATH=/opt/android-ndk-r26d/\
-DUHDR_BUILD_DEPS=1\
-DANDROID_ABI=x86_64\
-DANDROID_PLATFORM=android-23 ../
make
This will generate the following files under build_directory
:
libuhdr.so
ultrahdr shared library
ultrahdr_app
Statically linked sample application demonstrating ultrahdr API usage
To build benchmarks, pass -DUHDR_BUILD_BENCHMARK=1
to cmake configure command and build.
This will additionally generate,
ultrahdr_bm
Benchmark tests
Refer to README.md for complete instructions.
A detailed description of libultrahdr encode and decode api is included in ultrahdr_api.h and for sample usage refer demo app.
libultrahdr includes two classes of APIs, one to compress and the other to decompress HDR images:
Scenario | Hdr intent raw | Sdr intent raw | Sdr intent compressed | Gain map compressed | Quality | Exif | Use Case |
---|---|---|---|---|---|---|---|
API - 0 | P010 or rgb1010102 | No | No | No | Optional | Optional | Used if, only hdr raw intent is present. 1 |
API - 1 | P010 or rgb1010102 | YUV420 or rgba8888 | No | No | Optional | Optional | Used if, hdr raw and sdr raw intents are present.2 |
API - 2 | P010 or rgb1010102 | YUV420 or rgba8888 | Yes | No | No | No | Used if, hdr raw, sdr raw and sdr compressed intents are present.3 |
API - 3 | P010 or rgb1010102 | No | Yes | No | No | No | Used if, hdr raw and sdr compressed intents are present.4 |
API - 4 | No | No | Yes | Yes | No | No | Used if, sdr compressed, gain map compressed and GainMap Metadata are present.5 |
Configure display device characteristics (display transfer characteristics, max display boost) for optimal usage.
Input | Usage | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
max_display_boost | (optional, >= 1.0) the maximum available boost supported by a display. | ||||||||||
supported color transfer format pairs |
|
Footnotes
-
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. ↩
-
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. ↩
-
Compute gain map from hdr and raw sdr. Compress gainmap. Combine sdr compressed, gainmap in multi picture format with gainmap metadata. ↩
-
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. ↩
-
Combine sdr compressed, gainmap in multi picture format with gainmap metadata. ↩