Merge branch 'master' into erfan_device_features

Author: Erfan-Ahmadi

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

examples_tests

@@ -51,6 +51,7 @@ class NBL_API IDescriptorSet : public virtual core::IReferenceCounted
                 };
                 struct SImageInfo
                 {
+					// This will be ignored if the DS layout already has an immutable sampler specified for the binding.
                     core::smart_refctd_ptr<typename layout_t::sampler_type> sampler;
                     //! Irrelevant in OpenGL backend
                     E_IMAGE_LAYOUT imageLayout;

include/nbl/asset/IDescriptorSet.h

@@ -87,6 +87,8 @@ class NBL_API IDescriptorSetLayout : public virtual core::IReferenceCounted
 			E_DESCRIPTOR_TYPE type;
 			uint32_t count;
 			IShader::E_SHADER_STAGE stageFlags;
+			// Use this if you want an immutable sampler that is baked into the DS layout itself.
+			// If its `nullptr` then the sampler used is mutable and can be specified while writing the image descriptor to a binding while updating the DS.
 			const core::smart_refctd_ptr<sampler_type>* samplers;
 
 			bool operator<(const SBinding& rhs) const

include/nbl/asset/IDescriptorSetLayout.h

@@ -104,9 +104,10 @@ class NBL_API IImage : public IDescriptor
 		};
 		enum E_TYPE : uint32_t
 		{
-			ET_1D,
+			ET_1D = 0,
 			ET_2D,
-			ET_3D
+			ET_3D,
+			ET_COUNT
 		};
 		enum E_SAMPLE_COUNT_FLAGS : uint32_t
 		{