Home

Awesome

Nabla

License

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, the Vulkan backend is almost complete, and OpenGL and ES backends are currently in maintenance mode.

This framework has been kindly begun by the founder @devshgraphicsprogramming of Devsh Graphics Programming Sp. z O.O. and was almost entirely sponsored by Build A World Aps in its early days, now it has been picked up by Ditt B.V..

(Get Hired) Jobs and Internships

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

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

Then make something impressive using Nabla, open a PR and contact us (jobs@devsh.eu or discord) with your CV. Check our Free Task List for contribution ideas!

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

For internships contact us with:

(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:

Our language of choice is C++20 however we're also amenable to C#, Java, Python and related languages.

Contact newclients@devsh.eu with inquires into contracting.

Showcase

Screenshots

<u>Our Production Mitsuba Compatible Path Tracer made for Ditt B.V.</u>

Currently working on the ditt branch, in the process of being ported to Vulkan KHR Raytracing.

You can download a stable build here

Multiple Importance Sampling and Depth of Field

Main Features

Main Delivered Extensions

Platforms

Build summary

ReleaseRWDIDebug
Windows MSVC x64
Android Clang x86_64
Linux GCC x64

Quick start

Use Nabla from package

TODO - soon

Build Nabla with Docker

TODO - soon

Build Nabla manually

Minimal required dependencies

Cloning the project

git clone git@github.com:Devsh-Graphics-Programming/Nabla.git <target directory>

Force HTTPS protocol (optional)

We support cloning Nabla with ssh only, however you can still clone Nabla and it's all submodules with https by overriding global git configuration (sorry, must be global for it to work, currently we don't have smart scripts to change local configuration for each nested submodule).

git init
git config --global protocol.*.allow always
git config --global url."https://github.com/".insteadOf "git@github.com:"
git remote add origin https://github.com/Devsh-Graphics-Programming/Nabla.git
git fetch origin master
git checkout master

Configure & Generate with CMake

Target platform

Check individual instructions for building for a particular platform in ./docs/build directory before going further. For each platform it is assumed minimal required dependencies are installed and additional may be specified depending on the target.

Submodules

CMake will update all required submodules for you by default but it doesn't mean the initialization & update attempt will be successful (it is often not when performed on a shaky internet connection, so you may end up with dirty, locked or un-versioned submodules) - if not successful then try to re-configure CMake again. We have a few options for managing submodules by CMake, for more details and description check the update submodule script. For example sometimes it may appear that there won't be any files in submodules' directories because of an update fail or dirty git cache, you could fix it and bring them back by enabling NBL_FORCE_ON_UPDATE_GIT_SUBMODULE CMake option. Note that we do not recommend to initialize and update submodules by hand in cmd because of private submodules in the repository.

More options

You can disable generating projects for examples with NBL_BUILD_EXAMPLES. It's recommended to build Nabla as shared library however you can also build as static library by turning on NBL_STATIC_BUILD.

CMake presets

We have customised presets which may be handy to configure Nabla project for a target platform with predefined & common configurations.

Caveats and Particular Behaviour

Hardcoded Caps

Max Descriptor Sets is always 4

Debugging with RenderDoc

Non-programmatic OpenGL catpures will be delimited inconsistently

Due to our no-pollution opengl state isolation policy, we have 1 queue or swapchain = 1 thread = 1 gl context + 1 master context and thread for device calls.

Renderdoc therefore serializes all calls, and presents them inside the capture in interleaved order (records them on a single timeline "as they happened").

Furthermore it has no idea what constitutes a frame, because swap-buffers call happens on a separate thread than all the other API calls. So use the IGPUQueue start/end capture methods!

RenderDoc flips images for display in the ImageViewer tab on OpenGL captures

Ctrl+F `localRenderer in https://github.com/baldurk/renderdoc/blob/4103f6a5455b9734e9bf74e254577f5c03188136/renderdoc/core/image_viewer.cpp

OpenGL/Vulkan Inconsistencies

In certain cases same calls to Vulkan and OpenGL might result in y-flipped image relevant to the other API.

Both APIs write (-1,-1) in NDC space to (0,0) in image space (two wrongs make right), and memory-wise (0,0) always represents the lowest byte in memory.

This inconsistency comes from swapchain presentation. When presenting the swapchain, the image location (0,0) corresponds to bottom-left in OpenGL and top-left in Vulkan.

Solution by Surface Transforms

We solve this inconsistency by using surface transforms; This transforms are relative to presentation engine’s natural orientation. and we report HORIZONTAL_MIRROR_180 support in our OpenGL backend and defer handling these rotations (relative to natural orientaion) to the user.

We provide helper functions in both GLSL and C++ Nabla codebase to consider surface transforms, See surface_transform.glsl

Note that it is common to apply surface transformation to projection matrices to account for this fact. See getSurfaceTransformationMatrix and Android Developers Guide to Pre-rotation

Use ISwapchain getSurfaceTransform() to get the transformation from swapchain.

Continuous integration

Nabla Python Framework

CPU & GPU local tests shipped with the repository

Description

Nabla aims to implement full CPU & GPU tests used by our CI in-house infrastructure groovy pipelines in relocatable way allowing users to execute and debug the tests locally on their own devices as well. Each test is a Python module which part of it gets created with the CMake build system configuration. A test is defined and created as a module by

Top json configuration file contains run & build info, array of profiles and json inputs for a Python testing module. The file is processed and validated by CMake to create output profiles bound to the Python module. Single profile contains data used by the module to execute tests with and the implementation of the test is located in interface Python script - the script overrides common abstract interface defined as a integral part of Nabla Python framework module. The description is abstract and doesn't contain specific details, join our discord if you have any questions!

Development & Debug

Each valid Python module contains autogenerated .vscode's launch.json and settings.json to make development easy. You just need to Open with Codein the module's directory. Make sure to install Python extension there to enable IntelliSense (Pylance), Linting, Debugging (multi-threaded, remote), code formatting, refactoring, unit tests, and more.

A target for which Python module is available for testing lists a special Python Framework section located in its solution's project file structure (Visual Studio only!) containing Nabla Python Framework sources, target's interface Python script, autogenerated json profiles and autogenerated __main__.py module script. Unfortunately pure Visual Studio works so-so with Python (issues with search module paths defined as searchPath .pyproj's property, issues with IntelliSense and Debugging) - we encourage to use Visual Studio Code if you need to Debug an interface or develop it.

Runtime

Command line

To run all tests bound to a module with a command line you just need to execute python3 -m <module_reference>. You can also specify special arguments to have more control over the test execution, for more details see template module script

Visual Studio

You need to open a target's solution. To launch all tests bound to a module a module's __main__.py file located in Python Framework section must be selected and Debug -> Execute File in Python interactive executed.

Visual Studio Code

You need to open module's directory as workspace with Open with Code , select Run and Debug icon, select __main__.py file and run it.

License

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

Documentation

(WIP/TODO)

Official Support (Discord)

Permanent 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.

Credits and Attribution

The authors of Nabla are:

Past Authors and Contributors:

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