Nabla

Nabla (previously called IrrlichtBaW ) is a new renovated version of older Irrlicht engine. The name change to Nabla allows for using Nabla side by side with the legacy Irrlicht and IrrlichtBaW engines. The project currently aims for a thread-able and Vulkan-centered API, but currently works on OpenGL only.

This framework has been kindly begun by the founder @devshgraphicsprogramming of Devsh Graphics Programming Sp. z O.O. and almost entirely sponsored by Build A World Aps. in it's early days, and now picked up by the Ditt company. The stable-ish branch is used in production releases of Build A World EDU, since 2015. The framework has been used both for game development and ArchViz.

(Get Hired) Jobs and Internships

If you are a programmer with a passion for High Performance Computing, Mathematics and Computer Graphics

If you can work 100% remotely and be in charge of your own time managment

Then make something impressive using Nabla, open a PR and contact us (jobs devsh.eu) with your CV.

We would also be happy to sponsor your master thesis as long as:

You are an above average student with an interest in Graphics
It will be written in English
It will produce contributions to Nabla which we can license under Apache 2.0

(Hire Us) Contracting

The members of Devsh Graphics Programming Sp. z O.O. (Company Registration (KRS) #: 0000764661) are available (individually or collectively) for contracts on projects of various scopes and timescales, especially on foreign frameworks, codebases and third-party 3D frameworks.

We provide expertise in:

OpenGL
OpenGL ES
WebGL
Vulkan
OpenCL
CUDA
D3D12 and D3D11
computer vision
Audio programming
DSP
video encoding and decoding
High Performance Computing

Our language of choice is C++17 with C++11 and C11 coming in close second, however we're also amenable to Java, Python and related languages.

Contact @devshgraphicsprogramming (e-mail available in the GitHub profile) with inquires into contracting.

Showcase

Videos

Multiple Importance Sampling and Depth of Field

Bathroom Scene Raytracing

Stairs Scene Raytracing

Tonemapping with AutoExposure and Temporal Adaptation

Raytracing With Optix AI Denoising [Albedo and Normals]

Raytracing flythrough

Screenshots

Pseudo Spectral rendering

Thindielectric

Stairs raytracing

Bathroom raytracing

Raytracing sample

1 Megapixel, 1 Million Samples

BRDF Explorer

.OBJ Loader with MTL pipeline integration

Different Shape Area Light emitters

Main Features

Thread safe and context pollution safe OpenGL
Asset management pipeline
Automatic pipeline layout creation
Shader introspection
Using SPIR-V shaders in OpenGL and ES
Libraries of GLSL shader functions
Compute shaders
Virtual Texturing
Virtual Geometry (programmable and non programmble fetching) with triangle batching
CUDA and OpenGL interop
OpenCL and OpenGL interop
CPU asset manipulation (image filtering, image format transcoding, mesh optimization and manipulation)

Main Delivered Extensions

Auto Exposure
Tonemapper
Mitsuba scene loader (auto-generated shaders)
Fastest blur on the planet
Radeon rays interop
OptiX interop
Bullet physics beginner integration

Platforms

Required Build Tools and SDK's

Vanilla Build - most extensions disabled

CMake
MSVC or GCC
Vulkan SDK
Perl
NASM
Python 3.8 or later

Vanilla + CUDA Build

Nabla only supports CUDA interop using the Driver API not the Runtime API. We use the runtime compiled CUDA.

Because CUDA needs its own version the GeForce (Quadro or Tesla) Driver, its often a few minor versions behind your automatically updated Windows driver, the install will fail even if it prompts you to agree to installing an older driver.

So basically first remove your driver, then install CUDA SDK.

CUDA Toolkit

CMake warnings in reference CUDA and notes

On Windows CMake has trouble finding new packages installed after CMake, so its the perfect time to visit it's website and check for a new version installer after installing CUDA SDK.

You can also thank NVidia for making the CUDA SDK a whole whopping 2.5 GB on Windows.

Vanilla + CUDA + Optix Build

After dealing with CUDA installing just install Optix SKD.

OptiX SDK

External Dependencies

gl.h header for OpenGL (possible to obtain even on headless servers from mesa-libgl-devel)
OpenCL SDK (can get rid of it by compiling without the two OpenCL files)

Future Boost Library Dependencies

Nabla uses or will use the following Boost libraries:

Bimap
Context (maybe, and if yes only the fcontext_t variant)
Interprocess
Special
Stacktrace (we already have stack tracing on Linux, might be less work to do it on Windows)

The maybe's depend on how xplatform and easy to operate the boost::context is, esp w.r.t. Linux, Windows and Android. We will not use boost::fibers as we need our own complex scheduler.

Building Nabla library

Cloning the project

Begin with cloning Nabla with:

git clone --recurse-submodules -j8 https://github.com/Devsh-Graphics-Programming/Nabla.git

If you haven't cloned recursively, you have to also perform:

git submodule init
git submodule update

CMake config script will try to initialize submodules for you however as well, but it doesn't mean the initialization attempt will be successful.

Submodules

If you haven't initialized the submodules yourself before the CMake configure step, and out CMake submodule update script destroyed them (badly/half initialized), you can run the following set of commands, but beware - it will completely wipe any changes to submodules.

git submodule foreach --recursive git clean -xfd
git submodule foreach --recursive git reset --hard
git submodule update --init --recursive

Weird CMake behaviour, notes

Sometimes it may appear that there won't be any files in submodules directories. If so, you have to bring them back by using:

git reset --hard

on each submodule's directory required! Furthermore you have to:

git checkout tags/glew-cmake-2.1.0

in glew directory that you can find in 3rdparty/CEGUI/glew directory because of glew commiting politics. Having done it you can switch to your master/root directory and commit those changes if you want, but it isn't necessary to compile entire library.

CMake notes

Make sure Python's executable is found

The paragraph concerns Windows system only

Unfortunately on Windows there are often troubles with Python 3.0+ versions, because it isn't able to find and determine PYTHON_EXECUTABLE variable, so you have to fill it manually. If you use CMake-GUI you will find it in advanced options.

Consider CMake and Visual Studio version, important!

The paragraph concerns Visual Studio only

Make sure you have installed the latest version of Visual Studio and CMake. Within older versions sometimes there may occur that Visual Studio outputs an error associated with compiler heap space. If you don't get any error, just skip the point. It's because having x64 project opened the solution still uses 32 bit compiler exe and cannot allocate more than 4G of memory, therefore Nabla is unbuildable. Furthermore Visual Studio doesn't provide any option to change that. Because of that you have to manually modify .vcxproj xml and add x64 to PropertyGroup nodes. Pay attention that CMake generates a standard PropertyGroup node, but it isn't enough, because you need to put it into the target where building type is directly specified. It should look for instance as following:

<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|x64'" Label="Configuration">
    <PreferredToolArchitecture>x64</PreferredToolArchitecture>
    <ConfigurationType>StaticLibrary</ConfigurationType>
    <CharacterSet>MultiByte</CharacterSet>
    <PlatformToolset>v142</PlatformToolset>
</PropertyGroup>

Current example above shows Release mode, but you should consider Debug as well. Having it done, 64bit cl.exe binary usage will be assured. When u get this problem, don't bother with editing all the .vcxprojs. It will probably only matter while building the engine, so the only thing you have to do is edit that .vcxproj you actually use - Nabla.vcxproj for instance and that's it.

If you know a way to make CMake generating .vcxprojs already having those changes that will solve the issue, it will be great if you let us know about it :)

CMake on 64bit Windows

Best to use cmake-gui

Run cmake-gui and, as usually, give CMake root Nabla directory and where you want CMake to put project files and click "Configure" field. When CMake asks you to choose compiler/IDE, make sure to check whether there's a distinct option for 64bit mode and, if this is the case, choose this one.

For single-config IDEs (Code::Blocks) you'll have to manually set CMAKE_BUILD_TYPE to Debug or Release. Release is default.

You also have options BUILD_EXAMPLES and BUILD_TOOLS which do exactly what they say. By "tools" you should currently understand just convert2baw.

For Windows MSVC required, MinGW build system maintenance will be delegated to the community.

CMake on 64bit Linux

Same as Windows, except that currently we have no way of setting the correct working directory for executing the examples from within the IDE (for debugging). If you care about this please submit an issue/PR/MR to CMake's gitlab.

We recommend the Codelite IDE as that has a CMake-gui generator and has been tested and works relatively nice.

Visual Studio Code suffers from a number of issues such as configuring the CMake every time you want to build a target and slow build times. Here are the issues:

Clang toolset is unmaintained and untested on Linux.

First examples launching, significant notes

Remember you have to set up starting target project in Visual Studio before you begin to launch your example. To do that click on Solution Explorer, find the example name, hover on it and click on Set as StartUp Project. You can disable building examples by NBL_BUILD_EXAMPLES option in CMake.

Use Nabla in your project!

To get Nabla to be used by an external application without adding it as a subdirectory,but still using a submodule, you should perform following:

list(APPEND NBL_CMAKE_ARGS "-DIRR_BUILD_DOCS:BOOL=OFF") # enable only if you have doxygen installed and detectable by cmake
list(APPEND NBL_CMAKE_ARGS "-DIRR_BUILD_EXAMPLES:BOOL=OFF")
list(APPEND NBL_CMAKE_ARGS "-DIRR_BUILD_TOOLS:BOOL=OFF") # the tools don't work yet (Apr 2020 status, might have changed since then)
list(APPEND NBL_CMAKE_ARGS "-DIRR_BUILD_MITSUBA_LOADER:BOOL=OFF") # you probably don't want this extension
list(APPEND NBL_CMAKE_ARGS "-DCMAKE_INSTALL_PREFIX:PATH=${NBL_INSTALL_DIR}") # because of https://gitlab.kitware.com/cmake/cmake/-/issues/18790
ExternalProject_Add(Nabla
    DOWNLOAD_COMMAND  ""
    SOURCE_DIR        "${NBL_SOURCE_DIR}"
    BINARY_DIR        "${NBL_BINARY_DIR}"
    CMAKE_ARGS        ${NBL_CMAKE_ARGS}
    TEST_COMMAND      ""
)

# replace with whatever you need ${PROJECT_NAME}
target_include_directories(${PROJECT_NAME}
    PUBLIC
        $<$<CONFIG:Debug>:${NBL_INSTALL_DIR}/debug/include>
        $<$<CONFIG:RelWithDebInfo>:${NBL_INSTALL_DIR}/relwithdebinfo/include>
        $<$<CONFIG:Release>:${NBL_INSTALL_DIR}/include>
     # these are needed because we haven't cleaned up the API properly yet
        $<$<CONFIG:Debug>:${NBL_INSTALL_DIR}/debug/source/Nabla>
        $<$<CONFIG:RelWithDebInfo>:${NBL_INSTALL_DIR}/relwithdebinfo/source/Nabla>
        $<$<CONFIG:Release>:${NBL_INSTALL_DIR}/source/Nabla>
)
target_link_libraries(${PROJECT_NAME} 
	 $<$<CONFIG:Debug>:${NBL_INSTALL_DIR}/debug/lib/Nabla_debug.lib>
	 $<$<CONFIG:RelWithDebInfo>:${NBL_INSTALL_DIR}/relwithdebinfo/lib/Nabla_rwdi.lib>
	 $<$<CONFIG:Release>:${NBL_INSTALL_DIR}/lib/Nabla.lib>
)
function(link_nbl_dependency DEPENDENCY_NAME)
	target_link_libraries(${PROJECT_NAME} 
		 $<$<CONFIG:Debug>:${NBL_INSTALL_DIR}/debug/lib/${DEPENDENCY_NAME}d.lib>
		 $<$<CONFIG:RelWithDebInfo>:${NBL_INSTALL_DIR}/relwithdebinfo/lib/${DEPENDENCY_NAME}.lib>
		 $<$<CONFIG:Release>:${NBL_INSTALL_DIR}/lib/${DEPENDENCY_NAME}.lib>
	)
endfunction()
function(link_nbl_dependency_ DEPENDENCY_NAME)
	target_link_libraries(${PROJECT_NAME} 
		 $<$<CONFIG:Debug>:${NBL_INSTALL_DIR}/debug/lib/${DEPENDENCY_NAME}_d.lib>
		 $<$<CONFIG:RelWithDebInfo>:${NBL_INSTALL_DIR}/relwithdebinfo/lib/${DEPENDENCY_NAME}.lib>
		 $<$<CONFIG:Release>:${NBL_INSTALL_DIR}/lib/${DEPENDENCY_NAME}.lib>
	)
endfunction()
link_nbl_dependency(glslang)
link_nbl_dependency_(jpeg)
link_nbl_dependency_(IlmImf-2_4)
link_nbl_dependency_(IexMath-2_4)
link_nbl_dependency_(Iex-2_4)
link_nbl_dependency_(IlmThread-2_4)
link_nbl_dependency_(Half-2_4)
link_nbl_dependency_(Imath-2_4)
link_nbl_dependency(libpng16_static)
# OpenSSL only ever exists in the Release variant
if(WIN32)
	target_link_libraries(${PROJECT_NAME} 
		 ${NBL_INSTALL_DIR}/lib/libeay32.lib
		 ${NBL_INSTALL_DIR}/lib/ssleay32.lib
	)
else()
	target_link_libraries(${PROJECT_NAME} 
		 ${NBL_INSTALL_DIR}/lib/libcrypto.lib
		 ${NBL_INSTALL_DIR}/lib/libssl.lib
	)
endif()
link_nbl_dependency_(shaderc)
link_nbl_dependency_(shaderc_util)
link_nbl_dependency(SPIRV)
link_nbl_dependency_(SPIRV-Tools)
link_nbl_dependency_(SPIRV-Tools-opt)
link_nbl_dependency(OGLCompiler)
link_nbl_dependency(OSDependent)
link_nbl_dependency(HLSL)
link_nbl_dependency(zlibstatic)

If you want to use git (without a submodule) then you can use ExternalProject_Add with the GIT_ properties instead.

I recommend you use ExternalProject_Add instead of add_subdirectory for Nabla as we haven't tested its use by 3rdparty applications that use CMake to build themselves yet (BaW EDU uses it directly from MSVC/make like it's still the stone-age of build systems).

License

Nabla is released under the Apache 2.0 license. See LICENSE.md for more details.

API documentation, help and extra improvements

If you would like to take care of documenting some files, please click it. If you feel like you'd be interesting in improving and maintaining this repository's wiki, contact @devshgraphicsprogramming on Discord.

Official Support (Discord)

Permament members of Devsh Graphics Programming Sp. z O.O. use this to organise publicly visible work. Join to the server to get into more details. There's also a skype support group, reach @devshgraphicsprogramming for a private invite.

Credits and Attribution

The authors of Nabla are:

Mateusz Kielan @devshgraphicsprogramming (Lead)
Krzysztof Szenk @crisspl (Core Engineer)
Arkadiusz Lachowicz @AnastaZIuk (Junior Programmer)
Przemysław Pachytel @Przemog1 (Junior Programmer)
Cyprian Skrzypczak @Hazardu (Junior Programmer)
Søren Gronbech

Past Authors and Contributors:

@khom-khun (Bullet Physics Extension + Example and the irrBaW-test repository of easy to understand demos)
@manhnt9 Nguyễn Tiến Mạnh (CEGUI, Build System and Radeon Rays Proof-of-Concept Integration in Prime Engine X with IrrlichtBaW back-end)
@florastamine Nguyễn Ngọc Huy (sRGB-Correct Image Loaders, CEGUI and BRDF Explorer GUI)

Words of appreciation for developers whose software has been used in Nabla, currently and in the past:

The initial Irrlicht 1.8.3 codebase
OpenSSL and aesGladman
SPIRV-Cross
shaderc
zlib, bzip, libzip2, lzma and lz4
libjpeg-turbo, jpeglib (past), libpng
Unicode convert_utf and utf8cpp

achalpandeyy/Nabla