The MDL API is a software component that you can embed in your application to provide MDL support in your application.
The MDL API is a C++ API. The MDL API is provided as a dynamic library, which can be linked to your application or dynamically loaded at runtime.
The MDL API release contains the following parts:
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.
The MDL API 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 API uses CMake to generate build files for the examples. It is suggested to use CMake 3.11 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 example source code requires a C++11 compiler. Some examples require additional third-party libraries.
The build with the following x64-platform-compiler combinations has been successfully tested:
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 libraries are required:
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/vs2015 for example is fine, assuming you extracted the mdl-sdk to:
C:/projects/mdl-sdk
Configure
, CMake asks you to choose the Generator. Select Visual Studio 14 2015 Win64
and click Finish
. CMake starts to configure the build and stops several times when user input is required to resolve dependencies.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:
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.
mkdir ~/mdl-sdk/examples/build/linux-x64-gcc cd ~/mdl-sdk/examples/build/linux-x64-gcc
cmake ../../
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 contain shared libraries. For a custom build of the GLEW library for example, the call to CMake could look as follows:
cmake -DGLEW_DIR=~/thirdparty/glew-2.1.0 ../../
For builds using a different compiler version, you need to pass the compiler names when calling CMake as follows:
sudo apt-get install gcc-6 g++-6 g++-6-multilib cmake -DCMAKE_C_COMPILER=/usr/bin/gcc-6 -DCMAKE_CXX_COMPILER=/usr/bin/g++-6 ../../
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=~/Qt/5.10.1/gcc_64
or pass the Qt5_DIR as CMake option:
cmake -DQt5_DIR=~/Qt/5.10.1/gcc_64 ../../
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_LIBRARAY_PATH
variable:
export LD_LIBRARY_PATH=~/mdl-sdk/linux-x86-64/lib:${LD_LIBRARY_PATH}
To run the MDL SDK Modules example for instance use:
cd ~/mdl-sdk/examples/build/linux-x64-gcc/mdl_sdk/modules ./mdl_sdk_example-modules
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:
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_LIBRARAY_PATH
variable:
export Qt5_DIR=~/Qt/5.10.1/clang_64 export DYLD_LIBRARAY_PATH=~/mdl-sdk/macosx-x86-64/lib:${Qt5_DIR}/lib:${Qt5_DIR}/plugins/imageformats${DYLD_LIBRARAY_PATH:+:${DYLD_LIBRARAY_PATH}}
To run the MDL SDK Modules example for instance use:
cd ~/mdl-sdk/examples/build/macosx-x64-gcc/mdl_sdk/modules ./mdl_sdk_example-modules
The following options allow to select the components to build and particular logging information:
MDL_ENABLE_CUDA_EXAMPLES
[ON/OFF] enable/disable examples that require CUDA.
By default, all options are set to ON. In case of any help request, please attach the log messages generated when the log options are enabled.
You can integrate the MDL API 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 API.
examples/example_shared.h
for the definition of this convenience method. Alternatively, if you want to use the mi::base::Handle class: g++
compiler call could look like this: dlopen()
. A g++
linker call could look like this: 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.