Merge branch 'master' into gpu_blit_filter

Author: achalpandeyy

CMakeLists.txt

@@ -268,7 +268,7 @@ option(NBL_BUILD_EXAMPLES "Enable building examples" ON)
 
 option(NBL_BUILD_TOOLS "Enable building tools (just convert2BAW as for now)" ON)
 
-option(NBL_BUILD_MITSUBA_LOADER "Enable nbl::ext::MitsubaLoader?" ON)
+option(NBL_BUILD_MITSUBA_LOADER "Enable nbl::ext::MitsubaLoader?" OFF) # TODO: once it compies turn this ON by default!
 
 option(NBL_BUILD_OPTIX "Enable nbl::ext::OptiX?" OFF)
 if(NBL_COMPILE_WITH_CUDA)

README.md

@@ -414,6 +414,59 @@ If you want to use git (without a submodule) then you can use `ExternalProject_A
 
 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.
 
+# 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](https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkSurfaceTransformFlagBitsKHR.html); 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](https://github.com/Devsh-Graphics-Programming/Nabla/tree/master/include/nbl/builtin/glsl/utils/surface_transform.glsl)
+
+Note that it is common to apply surface transformation to projection matrices to account for this fact. See [getSurfaceTransformationMatrix](https://github.com/Devsh-Graphics-Programming/Nabla/tree/master/include/nbl/video/surface/ISurface.h) and [Android Developers Guide to Pre-rotation](https://developer.android.com/games/optimize/vulkan-prerotation)
+
+Use [`ISwapchain getSurfaceTransform()`](https://github.com/Devsh-Graphics-Programming/Nabla/tree/master/include/nbl/video/ISwapchain.h) to get the transformation from swapchain.
+
+- When generating projection matricies, take into account the aspect ratio (which is changed when rotating 90 or 270 degrees). For this, we have helper functions in both GLSL and the ISurface class:
+    - [`float getTransformedAspectRatio(const E_SURFACE_TRANSFORM_FLAGS transform, uint32_t w, uint32_t h)`](https://github.com/Devsh-Graphics-Programming/Nabla/tree/master/include/nbl/video/surface/ISurface.h)
+    - [`nbl_glsl_surface_transform_transformedExtents`](https://github.com/Devsh-Graphics-Programming/Nabla/tree/master/include/nbl/builtin/glsl/utils/surface_transform.glsl)
+
+- On the swapchain rendering pass, perform **one** of the following transforms:
+    - If rendering **directly to the swapchain**, you can apply the (post) transform matrix to your projection or combined view-projection matrix **for rendering** (don't pre-multiply with projection matrix for use outside rendering):
+        - [`matrix4SIMD ISurface::getSurfaceTransformationMatrix(const E_SURFACE_TRANSFORM_FLAGS transform)`](https://github.com/Devsh-Graphics-Programming/Nabla/tree/master/include/nbl/video/surface/ISurface.h)
+        - [`nbl_glsl_surface_transform_applyToNDC`](https://github.com/Devsh-Graphics-Programming/Nabla/tree/master/include/nbl/builtin/glsl/utils/surface_transform.glsl) (This takes in an NDC coordinate and multiplies it with the transform matrix in one function)
+
+    - If using `imageStore` to write **directly to the swapchain**, you can either:
+        - Apply a transform to the screen-space coordinates being written to the swapchain:
+            - [`nbl_glsl_surface_transform_applyToScreenSpaceCoordinate`](https://github.com/Devsh-Graphics-Programming/Nabla/tree/master/include/nbl/builtin/glsl/utils/surface_transform.glsl)
+        - Apply an **inverse** transform to the screen-space coordinates (taken from `gl_GlobalInvocationID.xy`) before turning them into UV/world-space coordinates for rendering:
+            - [`nbl_glsl_surface_transform_applyInverseToScreenSpaceCoordinate`](https://github.com/Devsh-Graphics-Programming/Nabla/tree/master/include/nbl/builtin/glsl/utils/surface_transform.glsl)
+
 ## Automated Builds (TODO)
 
 ## License

cmake/common.cmake

@@ -39,19 +39,6 @@ macro(nbl_create_executable_project _EXTRA_SOURCES _EXTRA_OPTIONS _EXTRA_INCLUDE
 	if(ANDROID)
 		add_library(${EXECUTABLE_NAME} SHARED main.cpp ${_EXTRA_SOURCES})
 	else()
-		if(NOT NBL_STATIC_BUILD)
-			set(NBL_CONFIG_OUTPUT_DIRECTORY "${PROJECT_SOURCE_DIR}/bin")
-			set(NBL_CONFIG_OUTPUT_FILE ${NBL_CONFIG_OUTPUT_DIRECTORY}/${EXECUTABLE_NAME}$<IF:$<CONFIG:Release>,,$<IF:$<CONFIG:Debug>,_d,_rwdi>>.exe.config)
-			
-			add_custom_command(OUTPUT "${NBL_CONFIG_OUTPUT_FILE}"
-				COMMAND ${CMAKE_COMMAND} -DNBL_ROOT_PATH:PATH=${NBL_ROOT_PATH} -DNBL_GEN_DIRECTORY:PATH=${NBL_CONFIG_OUTPUT_DIRECTORY} -DNBL_DLL_PATH:FILEPATH=$<TARGET_FILE:Nabla> -DNBL_TARGET_PATH:FILEPATH=$<TARGET_FILE:${EXECUTABLE_NAME}> -P ${NBL_ROOT_PATH}/cmake/scripts/nbl/applicationMSVCConfig.cmake
-				COMMENT "Launching ${EXECUTABLE_NAME}.exe.config generation script!"
-				VERBATIM
-			)
-			
-			add_custom_target(${EXECUTABLE_NAME}_with_config ALL DEPENDS ${NBL_CONFIG_OUTPUT_FILE} ${NBL_ROOT_PATH}/cmake/scripts/nbl/applicationMSVCConfig.cmake)
-		endif()
-	
 		set(NBL_EXECUTABLE_SOURCES 
 			main.cpp
 			${_EXTRA_SOURCES}
@@ -61,19 +48,22 @@ macro(nbl_create_executable_project _EXTRA_SOURCES _EXTRA_OPTIONS _EXTRA_INCLUDE
 
 		if(NBL_DYNAMIC_MSVC_RUNTIME)
 			set_property(TARGET ${EXECUTABLE_NAME} PROPERTY MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>DLL")
+			
+			if(WIN32 AND MSVC)
+				set(_NABLA_OUTPUT_DIR_ "${NBL_ROOT_PATH_BINARY}/src/nbl/$<CONFIG>/devshgraphicsprogramming.nabla")
+				
+				target_link_options(${EXECUTABLE_NAME} PUBLIC "/DELAYLOAD:$<TARGET_FILE_NAME:Nabla>")
+				target_compile_definitions(${EXECUTABLE_NAME} PUBLIC 
+					_NABLA_DLL_NAME_="$<TARGET_FILE_NAME:Nabla>";_NABLA_OUTPUT_DIR_="${_NABLA_OUTPUT_DIR_}";_NABLA_INSTALL_DIR_="${CMAKE_INSTALL_PREFIX}"
+				)
+			endif()
 		else()
 			set_property(TARGET ${EXECUTABLE_NAME} PROPERTY MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")
 		endif()
 	endif()
 
 	# EXTRA_SOURCES is var containing non-common names of sources (if any such sources, then EXTRA_SOURCES must be set before including this cmake code)
-	if(NBL_STATIC_BUILD)
-		add_dependencies(${EXECUTABLE_NAME} Nabla)
-	else()
-		add_dependencies(${EXECUTABLE_NAME}_with_config Nabla_with_manifest)
-		#target_link_options(${EXECUTABLE_NAME} PRIVATE "/manifestdependency:\"type='win32' name='devshgraphicsprogramming.nabla' version='1.2.3.4' processorArchitecture='x86' language='*'\"")
-	endif()
-	
+	add_dependencies(${EXECUTABLE_NAME} Nabla)
 	get_target_property(NBL_EGL_INCLUDE_DIRECORIES egl INCLUDE_DIRECTORIES)
 
 	target_include_directories(${EXECUTABLE_NAME}
@@ -324,6 +314,12 @@ function(nbl_install_headers _HEADERS _BASE_HEADERS_DIR)
 	endforeach()
 endfunction()
 
+function(nbl_install_file _FILE _RELATIVE_DESTINATION)
+	install(FILES ${_FILE} DESTINATION include/${_RELATIVE_DESTINATION} CONFIGURATIONS Release)
+	install(FILES ${_FILE} DESTINATION debug/include/${_RELATIVE_DESTINATION} CONFIGURATIONS Debug)
+	install(FILES ${_FILE} DESTINATION relwithdebinfo/include/${_RELATIVE_DESTINATION} CONFIGURATIONS RelWithDebInfo)
+endfunction()
+
 function(nbl_install_config_header _CONF_HDR_NAME)
 	nbl_get_conf_dir(dir_deb Debug)
 	nbl_get_conf_dir(dir_rel Release)

cmake/install/nbl/sharedDefines.h.in

@@ -0,0 +1,7 @@
+/*
+	Those defines are included to the installed define.h header 
+	if the library has been built as DLL.
+*/
+
+#define _NABLA_DLL_NAME_ "@_NABLA_DLL_NAME_@"
+#define _NABLA_INSTALL_DIR_ @_NABLA_INSTALL_DIR_@

cmake/scripts/nbl/nablaHeader.cmake renamed to cmake/scripts/nbl/nablaDefines.cmake

@@ -38,11 +38,17 @@ else()
 	message(FATAL_ERROR  "NBL_GEN_DIRECTORY variable must be specified for this script!")
 endif()
 
-file(READ "${NBL_ROOT_PATH}/include/nabla.h.in" NBL_NABLA_IMPORT_HEADER_CODE)
-file(READ "${NBL_WRAPPER_FILE}" NBL_WRAPPER_CODE)
+if(NOT DEFINED _NABLA_DLL_NAME_)
+	message(FATAL_ERROR  "_NABLA_DLL_NAME_ variable must be specified for this script!")
+endif()
 
-string(APPEND NBL_NABLA_HEADER "${NBL_WRAPPER_CODE}")
-string(APPEND NBL_NABLA_HEADER "${NBL_NABLA_IMPORT_HEADER_CODE}")
+if(NOT DEFINED _NABLA_INSTALL_DIR_)
+	message(FATAL_ERROR  "_NABLA_INSTALL_DIR_ variable must be specified for this script!")
+endif()
+
+configure_file("${NBL_ROOT_PATH}/cmake/install/nbl/sharedDefines.h.in" "${NBL_GEN_DIRECTORY}/define.h")
+file(READ "${NBL_WRAPPER_FILE}" NBL_WRAPPER_CODE)
+file(READ "${NBL_GEN_DIRECTORY}/define.h" NBL_WRAPPER_CODE_2)
 
-file(WRITE "${NBL_GEN_DIRECTORY}/nabla.h.in" "${NBL_NABLA_HEADER}")
-configure_file("${NBL_GEN_DIRECTORY}/nabla.h.in" "${NBL_GEN_DIRECTORY}/nabla.h") # TODO: replace it with string(CONFIGURE ...) when CMake dev team fix this utility
+string(APPEND NBL_NABLA_INSTALL_HEADER "${NBL_WRAPPER_CODE}${NBL_WRAPPER_CODE_2}")
+file(WRITE "${NBL_GEN_DIRECTORY}/define.h" "${NBL_NABLA_INSTALL_HEADER}")

examples_tests

@@ -11,6 +11,7 @@
 #include "nbl/asset/format/EFormat.h"
 #include "aabbox3d.h"
 #define uint uint32_t
+#include <compare>
 #include "nbl/builtin/glsl/utils/acceleration_structures.glsl"
 #undef uint
 

include/nbl/asset/IAccelerationStructure.h

@@ -62,6 +62,11 @@ struct NBL_API SBufferBinding
 template<typename BufferType>
 struct NBL_API SBufferRange
 {
+	// Temp Fix, If you want to uncomment this then fix every example having compile issues -> add core::smart_refctd_ptr around the buffer to be an r-value ref
+	// SBufferRange(const size_t& _offset, const size_t& _size, core::smart_refctd_ptr<BufferType>&& _buffer)
+	// 	: offset(_offset), size(_size), buffer(core::smart_refctd_ptr<BufferType>(_buffer)) {}
+	// SBufferRange() : offset(0ull), size(0ull), buffer(nullptr) {}
+
 	inline bool isValid() const
 	{
 		return buffer && size && (offset+size<=buffer->getSize());
@@ -70,6 +75,7 @@ struct NBL_API SBufferRange
 	size_t offset = 0ull;
 	size_t size = 0ull;
 	core::smart_refctd_ptr<BufferType> buffer = nullptr;
+
 	inline bool operator==(const SBufferRange<BufferType>& rhs) const { return buffer==rhs.buffer && offset==rhs.offset && size==rhs.size; }
 	inline bool operator!=(const SBufferRange<BufferType>& rhs) const { return !operator==(rhs); }
 };

include/nbl/asset/IBuffer.h

@@ -99,7 +99,7 @@ class NBL_API ICPUAnimationLibrary final : public IAnimationLibrary<ICPUBuffer>,
 			SBufferBinding<ICPUBuffer> _keyframeStorageBinding = {m_keyframeStorageBinding.offset,_depth>0u ? core::smart_refctd_ptr_static_cast<ICPUBuffer>(m_keyframeStorageBinding.buffer->clone(_depth-1u)):m_keyframeStorageBinding.buffer};
 			SBufferBinding<ICPUBuffer> _timestampStorageBinding = {m_timestampStorageBinding.offset,_depth>0u ? core::smart_refctd_ptr_static_cast<ICPUBuffer>(m_timestampStorageBinding.buffer->clone(_depth-1u)):m_timestampStorageBinding.buffer};
 
-			SBufferRange<ICPUBuffer> _animationStorageRange = {m_animationStorageRange.offset,m_animationStorageRange.size,_depth>0u&&m_animationStorageRange.buffer ? core::smart_refctd_ptr_static_cast<ICPUBuffer>(m_animationStorageRange.buffer->clone(_depth-1u)):m_animationStorageRange.buffer};
+			SBufferRange<ICPUBuffer> _animationStorageRange = {m_animationStorageRange.offset,m_animationStorageRange.size,_depth>0u&&m_animationStorageRange.buffer ? core::smart_refctd_ptr_static_cast<ICPUBuffer>(m_animationStorageRange.buffer->clone(_depth-1u)):core::smart_refctd_ptr(m_animationStorageRange.buffer)};
 
  			auto cp = core::make_smart_refctd_ptr<ICPUAnimationLibrary>(std::move(_keyframeStorageBinding),std::move(_timestampStorageBinding),m_keyframeCount,std::move(_animationStorageRange));
 			clone_common(cp.get());

include/nbl/asset/ICPUAnimationLibrary.h

@@ -6,6 +6,7 @@
 #define _NBL_ASSET_I_DESCRIPTOR_SET_H_INCLUDED_
 
 #include <algorithm>
+#include <compare>
 
 
 #include "nbl/core/declarations.h"