The NVIDIA MDL SDK enables the easy integration of MDL support into rendering and material editing applications. The SDK contains components for loading, inspecting, and editing of material definitions as well as compiling MDL materials and functions to PTX and LLVM-IR.
The NVIDIA Material Definition Language (MDL) is a domain-specific programming language for defining physically-based materials for rendering. It allows you to define materials and functions, which you can organize in modules and packages to create flexible, custom-built material catalogs.
Material definitions are written in a declarative style; they define what to compute -- not how to compute it. This is the central premise in MDL where one material definition delivers the same appearance in many rendering algorithms. Following is a simple example of a diffuse material in MDL:
material diffuse ( color diffuse_color = color(0.7))
= material(
surface: material_surface (
scattering: df::diffuse_reflection_bsdf (
tint: diffuse_color
)
)
);
The function definitions in MDL are written in a procedural programming style. Their use is limited to computing material parameters in a side-effect-free manner.
The clear separation of material definitions from function definitions and their respective constraints makes possible the optimization of rendering algorithms independently of the material definition.
NVIDIA offers a binary release of the MDL SDK, see https://developer.nvidia.com/mdl-sdk. The binary release is different in some functionality as documented in the Change Log.
MDL uses CMake to generate build files for a particular development environment. It is required to use CMake 3.12 or later, 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. On the Mac OS X platform, third party dependencies can be resolved using the Homebrew Package Manager.
The source code requires a C++17 compiler and several third-party libraries and tools to build the MDL SDK. Additional third-party libraries are used in the examples.
The build with the following 64-bit platform-compiler combinations has been successfully tested:
- Windows 10: Microsoft Visual Studio 2017 (msvc v141) or 2019 (msvc v142)
- Ubuntu 18.04: GCC 7, GCC 8, or GCC 9 (on x86-64 or aarch64)
- Mac OS X 10.13: Xcode 8.3.3 (Apple Clang 8.1)
The versions listed with the following dependencies have been successfully tested. Where not mentioned otherwise, other versions might work as well. The tested versions include the ones specified in the VFX Reference Platform CY2021.
The following third-party libraries are required to build the MDL SDK:
-
Boost (1.67.0 or 1.73.0) (headers)
Linux: Install the libboost-dev package.
Windows: Download and extract the boost source code from boost.org.
Mac OS X: Install the boost package using brew. -
FreeImage (3.18.0)
Linux: Install the libfreeimage-dev package.
Windows: Download and extract the pre-compiled binaries from freeimage.sourceforge.net.
Mac OS X: Install the freeimage package using brew. -
Python3 (3.7.5)
Linux: Install the python package.
Windows and Max OS X: Download and install Python 3.7 from python.org. -
Clang 7.0.0
Using version 7.0.0 is mandatory.
Pre-compiled binaries can be found on llvm.org.
For generating and compiling MDL Python Bindings, the following additional dependencies are required:
-
Python3 Development Package (3.7.5)
Linux: Install the python-dev package in addition to python.
Windows and Max OS X: Download and install Python 3.7 from python.org. -
SWIG (4.0.2)
Follow the instructions for downloading or building on python.org.
In order to build and run all examples, you need additional third-party libraries. These additional libraries are:
-
GLEW (2.1.0)
Linux: Install the libglew-dev package.
Windows: Download and extract the pre-compiled binaries from glew.sourceforge.net.
Mac OS X: Install the glew package using brew. -
GLFW (3.2.1)
Linux: Install the libglfw3-dev package.
Windows: Download and extract the pre-compiled x64 binaries from glfw.org.
Mac OS X: Install the glfw package using brew. -
NVIDIA CUDA Toolkit (9.0 or later)
Please follow the instructions on the CUDA Developer Website. -
Qt (5.10.1)
Please follow the instructions on the Qt Website.
To build with Qt support on Linux, your system's GLIBC needs to be release 2.14 or later. -
DirectX Raytracing support
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
Building the DXR example on Windows 10 with an SDK older than 10.0.20348.0, requires an updated version of the DirectX Shader Compiler.
Download and extract the pre-compiled x64 binaries from github. -
Arnold SDK (6.0.0.0) Please follow the instructions on the Arnold Website to download the Arnold SDK.
-
MaterialX (github repository, tag: v1.38.1)
Please checkout the repository from github and build the libraries using CMake for Debug, Release and RelWithDebInfo.
Required tools to build the documentation:
-
Doxygen (1.8.4)
See the Doxygen project page and the archive of all releases. -
dot from GraphViz (2.40.1) (optional)
See the GraphViz project page.
-
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 root directory of the MDL SDK source checkout. 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 binaries.It is recommended that you build into a subdirectory, not into the repository root. C:/projects/mdl-sdk/build/vs2017 for example is fine, assuming you cloned the repository to:
C:/projects/mdl-sdk
-
After clicking
Configure
, CMake asks you to choose the Generator. SelectVisual Studio 14 2017 Win64
(for newer CMake versions selectx64
as platform), enterhost=x64
as toolset and clickFinish
. 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 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 will need to setup the following entries:
-
BOOST_INCLUDEDIR in Ungrouped Entries,
for example: C:/projects/thirdparty/boost_1_67_0, which contains the boost directory. -
FREEIMAGE_DIR in the FREEIMAGE group,
for example: C:/projects/thirdparty/freeimage_3_17_0/Dist/x64 -
GLEW_DIR in the GLEW group,
for example: C:/projects/thirdparty/glew-2.1.0 -
GLFW_DIR in Ungrouped Entries,
for example: C:/projects/thirdparty/glfw-3.2.1.bin.WIN64 -
PYTHON_DIR in Ungrouped Entries (only if not found in the PATH),
for example: C:/Python37 -
clang_PATH in Ungrouped Entries (only if not found in the PATH),
for example: C:/Program Files/LLVM-7/bin/clang.exe -
python_PATH in Ungrouped Entries (only if not found in the PATH),
for example: C:/projects/thirdparty/python_2_7_1/bin/python.exe -
swig_PATH in Ungrouped Entries (only if not found in the PATH),
for example: C:/projects/thirdparty/swigwin-4.0.2/swig.exe -
Qt5_DIR in Ungrouped Entries,
for example: C:/Qt/5.10.1/msvc2017_64 -
ARNOLD_SDK_DIR in Ungrouped Entries, for example: C:/projects/thirdparty/Arnold-6.0.3.0-windows
-
MATERIALX_REPOSITORY and MATERIALX_BUILD, for example: C:/projects/thirdparty/git/MaterialX and C:/projects/thirdparty/git/MaterialX/build respectively. Here, MATERIALX_BUILD has to point to the build directory selected while building the MaterialX libraries using CMake. For MaterialX support, the option MDL_MSVC_DYNAMIC_RUNTIME_EXAMPLES has to be enabled.
-
DXC_DIR in Ungrouped Entries,
for example: C:/projects/thirdparty/dxc_2021_07_01
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 usingOpen 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 MDL SDK library, the MDL Core library, and 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.
You can find the example binaries in the corresponding subfolders in build/examples. 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 built libraries and plugins to your environment PATH or copy them into the corresponding example binary folder.
For the mdl_sdk examples, you need libmdl_sdk.dll from build/src/prod/lib/mdl_sdk and additionally, freeimage.dll and nv_freeimage.dll from build/src/shaders/plugin/freeimage.
For the mdl_core examples, you need libmdl_core.dll from build/src/prod/lib/mdl_core and the freeimage.dll from build/src/shaders/plugin/freeimage or your third-party downloads.
-
Before generating make files, you need to install the required tools and libraries as listed above.
Building on Linux requires a developer environment including Python and CMake, which can be installed using the package manager (first command below). The second command will install the third-party libraries that are available in the package management system:
sudo apt-get install git git-lfs build-essential python cmake sudo apt-get install libboost-dev libfreeimage-dev libglew-dev libglfw3-dev
Please note that the build also requires clang 7.0.0. Please download the binary as described above. In the following, it is assumed that the extracted clang is the only clang compiler found in the system path or, for step 3.ii, that it has been extracted to (on x86-64):
$HOME/projects/thirdparty/clang+llvm-7.0.0-x86_64-linux-gnu-ubuntu-16.04/bin/clang
or (on aarch64):
$HOME/projects/thirdparty/clang+llvm-7.0.0-aarch64-linux-gnu/bin/clang
-
It is assumed that you checked out the repository in your home directory as follows:
export MDL_SDK_ROOT=$HOME/projects/mdl-sdk git lfs install git clone https://github.com/NVIDIA/MDL-SDK.git $MDL_SDK_ROOT
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 repository root:
export MDL_SDK_BUILD=$MDL_SDK_ROOT/build mkdir -p $MDL_SDK_BUILD cd $MDL_SDK_BUILD
-
To generate your build files, run CMake with the path to the top-level CMakeLists.txt as the last argument.
-
When all dependencies are installed correctly, the default settings should complete the configuration without any further user interactions:
cmake ..
In this case, you can continue with Step 4.
-
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 and logging (see Additional CMake Options), for example:
cmake -DMDL_BUILD_SDK_EXAMPLES=OFF -DMDL_BUILD_CORE_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
orlib
that contain shared libraries. For a custom build of the GLEW library for example, the call to CMake could look as follows:cmake -DGLEW_DIR=$HOME/projects/thirdparty/glew-2.1.0 ..
When a different clang compiler is installed on your system, you can provide the path to a clang 7.0.0 by setting the 'clang_Path' option (on x86-64):
cmake -Dclang_PATH=$HOME/projects/thirdparty/clang+llvm-7.0.0-x86_64-linux-gnu-ubuntu-16.04/bin/clang ..
or (on aarch64):
cmake -Dclang_PATH=$HOME/projects/thirdparty/clang+llvm-7.0.0-aarch64-linux-gnu/bin/clang ..
The same applies to other dependencies like Python 2.7.
For builds using a different compiler version, you need to pass the compiler names when calling CMake as follows:
sudo apt-get install gcc-7 g++-7 cmake -DCMAKE_C_COMPILER=/usr/bin/gcc-7 -DCMAKE_CXX_COMPILER=/usr/bin/g++-7 ..
To create an optimized build on a Unix-like system, set the build type to Release:
cmake -DCMAKE_BUILD_TYPE=Release ..
and replace
Debug
byRelease
below. -
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
-
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 -j8
-
Because the different MDL SDK libraries are loaded at runtime, their location has to be provided in order to run an example. Therefore, specify the paths to the built MDL SDK library, MDL Core library, and the image plugins using the
LD_LIBRARY_PATH
variable:export LD_LIBRARY_PATH=$MDL_SDK_BUILD/src/prod/lib/mdl_sdk/Debug:$MDL_SDK_BUILD/src/prod/lib/mdl_core/Debug:$MDL_SDK_BUILD/src/shaders/plugin/freeimage/Debug:${LD_LIBRARY_PATH}
For example, to run the MDL SDK modules example, use:
cd $MDL_SDK_BUILD/examples/mdl_sdk/modules/Debug ./modules
-
Before generating make files, you need to install the required tools and libraries as listed above.
Please note that the build requires clang 7.0.0. Please download the binary as described above. In the following, it is assumed that it has been extracted to:
$HOME/projects/thirdparty/clang+llvm-7.0.0-x86_64-apple-darwin/bin/clang
-
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, Python 2.7, CUDA, and Qt have been installed correctly, the following CMake options need to be specified:
-
clang_PATH in Ungrouped Entries,
for example: $HOME/projects/thirdparty/clang+llvm-7.0.0-x86_64-apple-darwin/bin/clang -
python_PATH in Ungrouped Entries (only if not found in the PATH),
for example: /usr/bin/python -
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:
cd $MDL_SDK_BUILD make -j8
-
Because the different MDL SDK libraries are loaded at runtime, their location has to be provided in order to run an example. Therefore, specify the paths to the built MDL SDK library, MDL Core 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=$MDL_SDK_BUILD/src/prod/lib/mdl_sdk/Debug:$MDL_SDK_BUILD/src/prod/lib/mdl_core/Debug:$MDL_SDK_BUILD/src/shaders/plugin/freeimage/Debug:${Qt5_DIR}/lib:${Qt5_DIR}/plugins/imageformats:${DYLD_LIBRARY_PATH}
For example, to run the MDL SDK modules example, use:
cd $MDL_SDK_BUILD/examples/mdl_sdk/modules/Debug ./modules
The following options enable you to select the components to be built and to select particular logging information:
-
MDL_BUILD_SDK_EXAMPLES
[ON/OFF] enable/disable the MDL SDK examples. -
MDL_BUILD_CORE_EXAMPLES
[ON/OFF] enable/disable the MDL Core examples. -
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_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_PYTHON_BINDINGS
[ON/OFF] enable/disable the generation and compilation of the MDL Python Bindings. -
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. -
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 are copied to the output folder. -
MDL_MSVC_DYNAMIC_RUNTIME_EXAMPLES
[ON/OFF] links the MSCV dynamic runtime (/MD) instead of static (/MT) when creating the example executables.
By default, all options are set to ON. For any help request, please attach the log messages generated when the log options are enabled.
To verify the build, run the examples as described above.
The documentation is stored in the doc/
subdirectory. There are two
C++ APIs -- the MDL SDK API and the MDL Core API -- for which
you need to generate the documentation with Doxygen. Please make sure
to use the specified version 1.8.4.
Additional documents are the MDL Specification (PDF) and the base.mdl
and core_definitions.mdl
documentation (HTML), which you do not
need to generate; they are a part of the source code release.
-
The tools required to build the documentation are listed here.
-
The use of the
dot
tool is optional and disabled by default. Enabling it gives you nicer inheritance diagrams. It is only supported on Linux and Mac, since a custom bash script is used to process the diagrams. You can enable thedot
tool as follows:-
Set the
HAVE_DOT
configuration setting in the respectiveDoxyfile
toYES
indoc/mdl_sdkapi
anddoc/mdl_coreapi
. -
Set the
GRAPHVIZ_DOT_HOME
environment variable to the directory containing the GraphVizdot
command (not the localdoc/mdl_sdkapi
ordoc/mdl_coreapi
directory with the equally nameddot
shell script, which is just a wrapper). Defaults to /usr/bin on Linux. -
On Mac, set the
PLATFORM
environment variable to a suitable setting starting withmacosx-x86
.
-
-
Build the MDL SDK API documentation with a plain
doxygen
call:cd $MDL_SDK_ROOT/doc/mdl_sdkapi doxygen
The resulting documentation is placed in an
html/
subdirectory with the start page:$MDL_SDK_ROOT/doc/mdl_sdkapi/html/index.html
-
Build the MDL Core API documentation with a plain
doxygen
call:cd $MDL_SDK_ROOT/doc/mdl_coreapi doxygen
The resulting documentation is placed in an
html/
subdirectory with the start page:$MDL_SDK_ROOT/doc/mdl_coreapi/html/index.html
A start page that links all documents can be found in the doc directory:
$MDL_SDK_ROOT/doc/index.html
The NVIDIA MDL SDK repository consists of the following directories and files:
include/ - C++ API header files
examples/ - example programs and MDL files
src/ - source code for the SDK libraries
doc/ - API documentation, MDL specification,
core_definitions.mdl and base.mdl documentation
cmake/ - support files for the CMAKE build system
README.md - this file: introduction and build instructions
CHANGELOG.md - change log and difference to the binary MDL SDK release
LICENSE.md - license for the MDL SDK and references to
third-party licenses
CMakeLists.txt - top level CMAKE file