A set of utilities commonly used in applications utilizing the OptiX ray tracing API.
See the CHANGELOG for recent changes.
After checking out the toolkit, be sure to initialize the submodules before building:
git submodule update --init --recursive
If you cloned the OptiX Tookit repository prior to v1.0.0, we recommend cloning a fresh repository.
We restructured the repository, merging multiple submodules into the main repository, which
complicates performing a pull operation. (If you are intent on pulling, use git submodule deinit
on all of the submodules except vcpkg
before pulling.)
On some Linux systems it may be necessary to install some commonly used developer packages with the following commands:
sudo apt-get install curl git-lfs pkg-config
git lfs install
Building the examples included with the OptiX Toolkit requires an OpenGL development environment. On most Linux systems the necessary packages can be installed using the following command:
sudo apt-get install libx11-dev libxcursor-dev libxi-dev libxinerama-dev libxrandr-dev mesa-common-dev
The OptiX Toolkit will do it's best to locate the highest installed version of the OptiX SDK.
On Windows, the standard installation location %ProgramData%/NVIDIA Corporation
is searched;
on Linux, the locations /opt
, /usr/local
, $HOME
and $HOME/Downloads
are searched for
the default SDK directory name.
If you installed the OptiX SDK in another location, or using a different directory name than the
suggested default, you can specify the location of the OptiX SDK by setting the CMake variable
OptiX_INSTALL_DIR
(case sensitive) at CMake configure time. Set the variable to the path to
the directory containing the OptiX SDK include
directory.
CMake presets provide a convenient
means of specifying CMake configure settings, build settings and test settings as a named collection.
A CMakePresets.json
file is provided with the toolkit to cover some basic use cases and
for use as building blocks for creating your own preset that covers your specific use case.
To build the toolkit with default settings, issue the following command from the source code directory.
cmake --preset otk-default
cmake --build --preset otk-default -j
The following command runs the tests using the default preset. (Note that ctest
requires a value for the -j
option.)
ctest --preset otk-default -j 16
All supplied presets begin with the prefix otk-
so that they won't conflict with your personal
presets. It is recommended that you store your personal presets in the file CMakeUserPresets.json
in the source directory so that future updates to the toolkit won't conflict with your
personal presets.
The supplied presets create build directories as children of the source directory with the name
of the preset in the build directory name, e.g. build-otk-default
. This gives each preset a
distinct build directory allowing you to experiment with different presets without them interfering
with one another.
Consult the CMakePresets.json
file for the available building blocks for use in creating your
own customized preset that suits your individual needs.
Building the toolkit follows the standard CMake worfklow: configure, build and test.
build
and cd
to that directory.
mkdir build
cd build
..
specifies the path to the source code from the build directory.)
cmake ..
This will configure the toolkit with the default options create a build project using the default CMake generator for your platform.
cmake --build . --config Release
ctest -C Release
If you wish to customize the build of the toolkit, see the section on options.
If you encounter problems or if you have any questions, we encourage you to post on the OptiX developer forum.
The following options may be supplied to CMake at configure time to customize the toolkit:
Variable | Type | Default | Description |
---|---|---|---|
OTK_USE_VCPKG |
BOOL |
ON |
Use vcpkg for dependencies. |
OTK_USE_VCPKG_OPENEXR |
BOOL |
${OTK_USE_VCPKG} |
Obtain OpenEXR via vcpkg. |
OTK_USE_OIIO |
BOOL |
OFF |
Use OpenImageIO to read PNG and JPEG files as image sources. |
OTK_FETCH_CONTENT |
BOOL |
ON |
Use FetchContent for dependencies if OTK_USE_VCPKG is OFF . |
OTK_BUILD_EXAMPLES |
BOOL |
ON |
Build the examples. |
OTK_BUILD_TESTS |
BOOL |
ON |
Build the tests. |
OTK_BUILD_DOCS |
BOOL |
ON |
Build the doxygen documentation. |
OTK_BUILD_PYOPTIX |
BOOL |
OFF |
Build the PyOptiX python module. |
OTK_PROJECT_NAME |
STRING |
OptiXToolkit |
Project name for the generated build scripts. |
OTK_LIBRARIES |
STRING |
ALL |
List of libraries to build. |
If both OTK_USE_VCPKG
and OTK_FETCH_CONTENT
are ON
, vcpkg will be used for dependencies.
If the option OTK_LIBRARIES
is used to configure the libraries to build, the value should be a semi-colon
separated list of one or more of the names DemandLoading
, Memory
, OmmBaking
or ShaderUtil
.
The default value ALL
is the same as specifying DemandLoading;Memory;OmmBaking;ShaderUtil
.
Some libraries depend on other libraries. The CMake build script includes dependent libraries as needed.
The toolkit depends on third party libraries for texture file format parsing, a GUI framework for the examples and a unit test framework for the tests.
Component | Dependency |
---|---|
DemandLoading | Imath 3.1.5 or later |
OpenEXR 3.1.5 or later | |
(optional) OpenImageIO | |
Examples | imgui |
GLFW 3.3 or later | |
glad (any recent version) | |
stb | |
Tests | gtest |
The toolkit can automatically obtain these third party libraries in one of two ways: via a vcpkg manifest or via FetchContent as described below.
Using vcpkg is the recommended method of obtaining third-party libraries.
The toolkit repository contains a vcpkg manifest to download and build
third party libraries. The repository includes the vcpkg
repository as a submodule to select
the specific versions of dependencies used. A vcpkg manifest, vcpkg.json
, specifies
the dependencies to be used. The vcpkg standard CMake integration via a toolchain file
is used to bootstrap vcpkg and obtain the dependencies.
The use of vcpkg
can be disabled by configuring with OTK_USE_VCPKG=OFF
, which will
cause the toolkit to use FetchContent for third party libraries.
When the toolkit is used as a subdirectory, e.g. a git submodule, of another project, the vcpkg manifest for toolkit must be incorporated into the parent project's manifest for vcpkg to correctly fetch the third party libraries used by the toolkit.
The CMake module ProjectOptions
(from the toolkit's CMake
directory) should be included by
the parent project's CMakeLists.txt
before the first call to project
.
This gives the toolkit the chance to configure optional features from the manifest
and configure options controlling how the toolkit is built.
If the variable CMAKE_TOOLCHAIN_FILE
is not set when ProjectOptions
is included, it will
be set to point to the CMake integration in the toolkit's vcpkg
submodule. A parent
project using vcpkg for dependency management may be using its own submodule of vcpkg for
toolchain integration and should set CMAKE_TOOLCHAIN_FILE
as appropriate before including
the toolkit's ProjectOptions
module.
If vcpkg
is disabled, the toolkit will use CMake's FetchContent
feature to download and build
any missing third-party libraries. The use of FetchContent
can be disabled by setting
OTK_FETCH_CONTENT=OFF
during CMake configuration, which is necessary when building statically
linked libraries, as described below.
When FetchContent
is disabled, the following CMake configuration variables should be used to
specify the locations of the third-party libraries: Imath_DIR
, OpenEXR_DIR
, glfw3_DIR
, and
glad_DIR
. The directory specified for each of these variables should be the location of the
project's CMake configuration file. For example:
cd build
cmake \
-DBUILD_SHARED_LIBS:BOOL=OFF \
-DOTK_FETCH_CONTENT:BOOL=OFF \
-DOTK_BUILD_EXAMPLES:BOOL=OFF \
-DOTK_BUILD_TESTS:BOOL=OFF \
-DImath_DIR:PATH=/usr/local/Imath/lib/cmake/Imath \
-DOpenEXR_DIR:PATH=/usr/local/OpenEXR/lib/cmake/OpenEXR \
-Dglfw3_DIR:PATH=/usr/local/glfw3/lib/cmake/glfw3 \
-Dglad_DIR:PATH=/usr/local/glad/lib/cmake/glad \
-DOptiX_ROOT_DIR:PATH=/usr/local/OptiX-SDK-7.5 \
../optix-toolkit
When FetchContent
is disabled, using vcpkg
as described above is recommended. Alternatively,
the necessary third-party libraries from source code downloaded from the following locations:
OptiX Toolkit components are compiled into dynamic libraries (DSOs/DLLs) to simplify linking client applications. This eliminates the need for client applications to link with third-party libraries like OpenEXR and GLFW.
Some clients of the toolkit might prefer to use statically linked libraries. This can be accomplished
by setting the CMake configuration variable BUILD_SHARED_LIBS=OFF
.
Important: when building statically linked libraries, the CMake configuration variable
OTK_FETCH_CONTENT
should be set to OFF
, and various third-party libraries must be installed as
described above.
Problem: CMake configuration error: "OTK_USE_VCPKG
is ON, but could not locate vcpkg toolchain file"
Solution: vcpkg submodule must be initialized, e.g. git submodule update --init --recursive
Problem: add_library cannot create ALIAS target "OpenEXR::Config" because another target with the same name already exists.
Solution: Install OpenEXR 3.1 or later or set OpenEXR_DIR
to such an installation.
Problem: CMake configuration error: "could not find git for clone of glad-populate"
Solution: git is required in order to download third party libraries (e.g. glad)
Problem: Runtime error: OPTIX_ERROR_UNSUPPORTED_ABI_VERSION
: Optix call 'optixInit()' failed
Solution: Download newer driver
Problem: CMake configuration error: "Failed to detect a default cuda architecture"
Solution: Set configuration variable CMAKE_CUDA_COMPILER
to the full path of the NVCC compiler.
Problem: Tests fail with "Cannot read image file filename.exr. File is not an image file."
Solution: Install git lfs (git lfs install
) and re-clone repository.
If you encounter a problem, we encourage you to post on the OptiX forums or open a ticket on the OptiX Toolkit issues page on GitHub.
This project contains build logic from the OptiX Wrapper Library (OWL), which is redistributed under the terms of the Apache License Version 2.0.