The MDL SDK is a software component that you can embed in your application to provide MDL support in your application.

The MDL SDK API is a C++ API. The MDL SDK is provided as a dynamic library, which can be linked to your application or dynamically loaded at runtime.

Overview

The MDL SDK release contains the following parts:

A platform-dependent shared library (a.k.a. DLL) named libmdl_sdk.
A set of platform-independent C++ include files, see the Include Files section for all available module specific include files.
A collection of example programs; see the Tutorial and Example Programs section.
A programmers manual (this document).
Installation instructions.

Recommendation

It is recommended that you read the brief Library Design section and continue with the Tutorial and Example Programs section. The Configuration Options section describes how to configure aspects of the library to your particular integration demands.

Building the examples

The MDL SDK release contains a set of example programs. It is recommended that you compile them and take them as a starting point for your own development.

The MDL SDK uses CMake to generate build files for the examples. It is required to use CMake 3.12 or later (3.21 or later on Windows), which can be downloaded from the CMake Website. When using a Unix-like system, you can install the cmake package using the respective package management systems.

Dependencies

The example source code requires a C++17 compiler. Some examples require additional third-party libraries.

The build with the following x64-platform-compiler combinations has been successfully tested:

Windows 10: Microsoft Visual Studio 2022 (msvc v143)
CentOS 7, Debian 12: GCC 12 (on x86-64 or aarch64)
Mac OS X 12.6: Xcode 14.2 (Apple Clang 14.0.0, on x86-64 or aarch64)

The versions listed with the following dependencies have been successfully tested. Where not mentioned otherwise, other versions might work as well.

The following third-party dependencies are used by several and/or major examples. Installation is strongly recommended unless the corresponding group of examples is of no interest to you.

vcpkg (git commit ID 5d675c7e5) Vcpkg is the recommended way to install other dependencies like GLEW and GLFW. The vcpkg version mentioned above corresponds to the versions mentioned for these dependencies below.
Windows: It is strongly recommended to select the same toolset that is used later to build the examples, e.g., by adding set(VCPKG_PLATFORM_TOOLSET v143)* (or similar) to triplets/x64-windows-static.cmake*. See the corresponding section in the vcpkg documentation for further details. Add the vcpkg option --triplet=x64-windows-static to the install command. There is no need to run the integrate command.
DirectX Raytracing support (Windows only)
Building the DXR example requires Windows 10 version 1909 and the corresponding SDK 10.0.18362.0. Additionally the optional Graphic Tools feature has to be installed.
DirectX Shader Compiler support (July 2022) (Windows only)
Building the DXR example requires an updated version of the DirectX Shader Compiler.
Download and extract the pre-compiled x64 binaries from github.
GLEW (2.2.0)
This dependency is required for all OpenGL-based examples.
Installation via vcpkg is strongly recommended. Install the vcpkg package glew.
GLFW (3.4)
This dependency is required for all OpenGL- and Vulkan-based examples.
Installation via vcpkg is strongly recommended. Install the vcpkg package glfw3.
NVIDIA CUDA Toolkit (12.x)
This dependency is required for all CUDA-based examples.
Please follow the instructions on the CUDA Developer Website.
Vulkan SDK (Windows: 1.3.275.0, Linux: 1.2.198.1)
This dependency is required for all Vulkan-based examples.
Please follow the instructions on the Vulkan SDK Website.
For debug builds on Windows, the debug libraries are required to be installed.
Note that the prebuilt binaries for version 1.3.275.0 do not work on CentOS 7.x.

The following third-party dependencies are only used by fewer or single examples, or add additional features to other examples. Installation can be safely skipped unless you are specifically interested in those examples or features.

Clang (12.0.1)
This dependency is required to build the OptiX 7 example.
Using version 12.0.1 is mandatory.
Pre-compiled binaries can be found on llvm.org.
MaterialX (github repository, tag: v1.38.9, Windows only)
This dependency adds MaterialX support to the DXR example.
Please download a release from github.
The pre-built packages do not contain libs for debug. If those are needed, a build from source is required.
NVIDIA CUDA Toolkit (8.0)
This exact version is required by the OptiX 7 example to generate LLVM bitcode for the closest hit shader with Clang 12.0.1.
The old version is available in the CUDA Toolkit Archive.
OptiX (7.0.0 to 8.0.0)
This dependency is required to build the OptiX 7 example.
Please follow the instructions on the OptiX Website.
Python3 (3.8.0)
This dependency is required to build the Python bindings examples.
Linux: Install the python package.
Windows and Max OS X: Download and install Python 3.8 from python.org.
Python3 Development Package (3.8.0)
This dependency is required to build the Python bindings.
Linux: Install the python-dev package in addition to python.
Windows and Max OS X: Download and install Python 3.8 from python.org.
Qt (5.10.1)
This dependency is required for the MDL browser example, a Qt-based browser for MDL modules and materials. This browser is also accessible from the DXR example.
Please follow the instructions on the Qt Website.
X-Rite AxF SDK (1.9.0)
This dependency is required to build the AxF-to-MDL example.
Please send the "Request AxF SDK" document from the X-Rite AxF Website.

Building on Windows

Before generating the Visual Studio solution, be sure to download and extract or install the third-party libraries listed above. The following steps assume you have extracted the pre-compiled binaries to a common third-party directory that is:
```
C:/projects/thirdparty
```
Open CMake-Gui, click Browse Source... and select the example directory of the extracted mdl-sdk. This directory contains the top-level CMakeLists.txt. Pick a build directory that will contain the files for your build system and eventually, the compiled example binaries.

It is recommended that you build into a subdirectory, not into the example root. C:/projects/mdl-sdk/examples/build/vs2022 for example is fine, assuming you extracted the mdl-sdk to:
```
C:/projects/mdl-sdk
```
After clicking Configure, CMake asks you to choose the Generator. Select Visual Studio 17 2022 (or higher) and click Finish. CMake starts to configure the build and stops several times when user input is required to resolve dependencies.
Optionally, you can select or deselect Additional CMake Options (see below) by checking and un-checking the boxes next to the entries that start with MDL. Click Configure again to continue.
When red error messages appear in the log, identify the dependency path that is requested and resolve the error by specifying the corresponding entry in CMake-Gui. Then, click Configure again to continue. Repeat this step until no further errors occur.

During this process, you may need to setup the following entries based on the selected components:
- ARNOLD_SDK_DIR in Ungrouped Entries,
  for example: C:/projects/thirdparty/Arnold-6.2.0.1-windows
- clang_PATH in Ungrouped Entries (only if not found in the PATH),
  for example: C:/Program Files/LLVM-12/bin/clang.exe
- CUDA8_PATH in Ungrouped Entries,
  for example: C:/Program Files/NVIDIA GPU Computing Toolkit/CUDA/v8.0
  Version 8 is mandatory here, used for the OptiX 7 example.
- DXC_DIR in Ungrouped Entries,
  for example: C:/projects/thirdparty/dxc_2022_07_18
- MATERIALX_DIR in Ungrouped Entries,
  for example: C:/projects/thirdparty/git/MaterialX
  For MaterialX support, the option MDL_MSVC_DYNAMIC_RUNTIME_EXAMPLES has to be enabled.
- python_PATH in Ungrouped Entries (only if not found in the PATH),
  for example: C:/projects/thirdparty/python_3_8_0/bin/python.exe
- Qt5_DIR in Ungrouped Entries (only if not installed using the installer)
  for example: C:/Qt/5.10.1/msvc2017_64
- VULKAN_SDK_DIR in Ungrouped Entries (only if not installed using the installer)
  for example: C:/VulkanSDK/1.3.275.0
- PANTORA_AXF_DIR in Ungrouped Entries
  for example: C:/projects/thirdparty/pantora-axf-1.9.0
Note: when you installed a new Visual Studio version after installing CUDA, you may have to reinstall CUDA to register it correctly with Visual Studio. Otherwise, CMake won't find the CUDA compiler.
When all dependencies have been resolved or the corresponding examples have been disabled as indicated in the CMake error messages, the log will show that the configuration is done.

Generate the Visual Studio solution by clicking Generate and open it afterwards using Open Project. CMake-Gui is not needed anymore and can be closed.

You can also open the Visual Studio solution directly from the build directory.
Use Visual Studio to build the examples. When running the examples using the Visual Studio debugger, you can provide additional command line arguments by specifying them in the individual Visual Studio project settings. To run the examples by double-clicking the executable in the build directories or by using the command line you need to add the location of the libmdl_sdk.dll or the plugins to your environment PATH or copy them into the corresponding example folder.

Building on Linux

Before generating make files, you need to install the required tools and libraries as listed above.
Before running CMake, create a build directory that will contain your make files and switch to that directory. It is recommended that you build into a subdirectory, not the example root folder:
```
mkdir $HOME/mdl-sdk/examples/build
cd $HOME/mdl-sdk/examples/build
```
To generate your build files, run CMake with the path to the top-level CMakeLists.txt* as the last argument.
1. When all dependencies are installed correctly, the default settings should complete the configuration without any further interactions necessary. In this case, you can continue with step 4.
```
cmake ../..
```
2. Optionally, you can use CMake options and the -D flags to customize your build.
  
  One or multiple of these flags can be used to enable and disable examples, for example:
```
cmake -DMDL_ENABLE_QT_EXAMPLES=OFF ../..
```
  You can also use the flags to point CMake to custom installation directories for third party libraries. Please refer to Windows build for a list of supported flags. On Unix-like systems, it is assumed that the specified paths contain a directory named include for headers files and subdirectories named lib64 or lib that contains shared libraries. For the Vulkan SDK for example, the call to CMake could look as follows:
```
cmake -DVULKAN_SDK_DIR=$HOME/projects/thirdparty/vulkansdk-linux-x86_64-1.2.198.1/1.2.198.1/x86_64 ../..
```
  For builds using a different compiler version, you need to pass the compiler names when calling CMake as follows:
```
sudo apt-get install gcc-11 g++-11
cmake -DCMAKE_C_COMPILER=/usr/bin/gcc-11 -DCMAKE_CXX_COMPILER=/usr/bin/g++-11 ../..
```
3. In case CMake is not able to find a working CUDA compiler for the examples, make sure the nvcc is reachable through the system PATH variable before running CMake:
```
export PATH=<;CUDA_SDK_DIR>/bin:$PATH
```
4. If Qt5 cannot be found, or you want to use an extracted package rather than installing Qt on your system, you can optionally set an additional environment variable before calling CMake:
```
export Qt5_DIR=$HOME/Qt/5.10.1/gcc_64
```
  or pass the Qt5_DIR as CMake option:
```
cmake -DQt5_DIR=$HOME/Qt/5.10.1/gcc_64 ../..
```
After a successful configuration, you can run make from within the specified build directory or any subdirectory that corresponds to a source directory containing a CMakeLists.txt:
```
make
```
Because the different MDL SDK libraries are loaded at runtime, the location has to be provided in order to run an example. Therefore, specify the paths to the built MDL SDK library and the image plugins using the LD_LIBRARY_PATH variable (on x86-64):
```
export LD_LIBRARY_PATH=$HOME/mdl-sdk/linux-x86-64/lib:${LD_LIBRARY_PATH}
```
or (on aarch64):
```
export LD_LIBRARY_PATH=$HOME/mdl-sdk/linux-aarch64/lib:${LD_LIBRARY_PATH}
```
To run the MDL SDK Modules example for instance use:
```
cd $HOME/mdl-sdk/examples/build/examples/mdl_sdk/modules/Debug
./modules
```

Building on Mac OS X

Before generating make files, you need to install the required tools and libraries as listed above.
Depending on your workflow, you can use CMake-Gui and follow the Windows instructions or use the command line as described in the Linux section. In each case, begin with step 2 of the respective instructions.

If the brew packages, CUDA, and Qt have been installed correctly, the following CMake option needs to be specified:
- Qt5_DIR in Ungrouped Entries,
  for example: $HOME/Qt/5.10.1/clang_64
After successfully configuring and generating make files, switch to the selected build directory and run make:
```
make
```
Because the different MDL SDK libraries are loaded at runtime, the location has to be provided in order to run an example. Therefore, specify the paths to the built MDL SDK library and the image plugins using the DYLD_LIBRARY_PATH variable:
```
export Qt5_DIR=$HOME/Qt/5.10.1/clang_64
export DYLD_LIBRARY_PATH=$HOME/mdl-sdk/macosx-x86-64/lib:${Qt5_DIR}/lib:${Qt5_DIR}/plugins/imageformats:${DYLD_LIBRARY_PATH}
```
To run the MDL SDK Modules example for instance use:
```
cd $HOME/mdl-sdk/examples/build/examples/mdl_sdk/modules/Debug
./modules
```

Additional CMake Options

The following options enable you to select the components to be built:

MDL_BUILD_SDK_EXAMPLES
[ON/OFF] enable/disable the MDL SDK examples (see also below for ways to enable/disable examples based on their required thirdparty dependencies).
MDL_ENABLE_PYTHON_BINDINGS
[ON/OFF] enable/disable the generation and compilation of the MDL Python Bindings.

The following options enable you to select particular logging information useful for debugging the CMake setup:

MDL_LOG_PLATFORM_INFOS
[ON/OFF] enable/disable the logging of platform and CMake settings.
MDL_LOG_DEPENDENCIES
[ON/OFF] enable/disable the logging of dependencies of the individual targets.
MDL_LOG_FILE_DEPENDENCIES
[ON/OFF] enable/disable the logging of files that copied to the output folder.

In case of any help request, please attach the log messages generated when the log options are enabled.

The following options affect how various components are built:

MDL_MSVC_DYNAMIC_RUNTIME_EXAMPLES
[ON/OFF] links the MSVC dynamic runtime (/MD) instead of static (/MT) when creating the example executables.

The following options enable you to select the examples to be built based on their required thirdparty dependencies (see also MDL_BUILD_SDK_EXAMPLES above):

MDL_ENABLE_CUDA_EXAMPLES
[ON/OFF] enable/disable examples that require CUDA.
MDL_ENABLE_D3D12_EXAMPLES
[ON/OFF] enable/disable examples that require D3D12 (Windows only).
MDL_ENABLE_OPENGL_EXAMPLES
[ON/OFF] enable/disable examples that require OpenGL.
MDL_ENABLE_VULKAN_EXAMPLES
[ON/OFF] enable/disable examples that require Vulkan.
MDL_ENABLE_OPTIX7_EXAMPLES
[ON/OFF] enable/disable examples that require OptiX 7 (Linux and Windows only).
MDL_ENABLE_QT_EXAMPLES
[ON/OFF] enable/disable examples that require Qt.
MDL_ENABLE_AXF_EXAMPLES
[ON/OFF] enable/disable the AxF to MDL example.
MDL_BUILD_ARNOLD_PLUGIN
[ON/OFF] enable/disable the build of the MDL Arnold Plugin.
MDL_ENABLE_MATERIALX
[ON/OFF] enable/disable MaterialX in examples that support it.

Custom build environments

You can integrate the MDL SDK easily in other build environments. You can also compile the examples by hand following the steps below. Let the environment variable $MDL_SDK_ROOT refer to the installation root of the MDL SDK.

Use the MDL SDK include files in your source:
#include <mi/mdl_sdk.h>

mdl_sdk.h
MDL SDK API.

Load the MDL SDK library dynamically and access the API entry point:
mi::neuraylib::INeuray* neuray = load_and_get_ineuray();

mi::neuraylib::INeuray
This is an object representing the MDL SDK library.
Definition: ineuray.h:44

See examples/example_shared.h for the definition of this convenience method. Alternatively, if you want to use the mi::base::Handle class:
mi::base::Handle<mi::neuraylib::INeuray> neuray( load_and_get_ineuray());

mi::base::Handle
Handle class template for interfaces, automatizing the lifetime control via reference counting.
Definition: handle.h:113

For a start, you can copy the examples that come with the MDL SDK release, make them writable, and change into that directory:
cp -r $MDL_SDK_ROOT/examples .

chmod -R u+w examples

cd examples
Compile the program with the appropriate include path switch that points the compiler to the location of the MDL SDK include files. A g++ compiler call could look like this:
g++ -I$MDL_SDK_ROOT/include -c example_start_shutdown.cpp -o example_start_shutdown.o -pthread
Link the program with the library that provides dlopen(). A g++ linker call could look like this:
g++ -o example_start_shutdown example_start_shutdown.o -ldl -pthread
Make the shared library (a.k.a. DLL) known to your runtime system so that it is found when starting the example program. You can do this by placing the shared library in an appropriate location, and/or setting environment variables such as PATH (on Windows), LD_LIBRARY_PATH (on Linux), or DYLD_LIBRARY_PATH and DYLD_FRAMEWORK_PATH (on MacOS X). Note: This step is platform and installation dependent.