docs docs docs, adjust to comments and test on 01 after updates

Author: AnastaZIuk

01_HelloCoreSystemAsset/main.cpp

@@ -3,7 +3,7 @@
 // For conditions of distribution and use, see copyright notice in nabla.h
 
 // <nabla.h> public interface and common examples API, always include first before std:: headers
-#include "nbl/examples/api.hpp"
+#include "nbl/examples/examples.hpp"
 
 #include "nbl/system/IApplicationFramework.h"
 

CMakeLists.txt

@@ -9,6 +9,17 @@ if(NBL_BUILD_EXAMPLES)
 		nbl_android_create_media_storage_apk()
 	endif()
 
+	#! Common api library & precompiled headers for Nabla framework examples
+	add_subdirectory(common EXCLUDE_FROM_ALL)
+
+	#! use "EXCLUDE_FROM_ALL" to exclude an example from the NablaExamples project
+	#[[
+		useful if we don't want the example to be tested by CI but still want
+		the example's project to be generated
+
+		https://cmake.org/cmake/help/latest/prop_tgt/EXCLUDE_FROM_ALL.html
+	]]
+
 	# showcase the use of `nbl::core`,`nbl::system` and `nbl::asset`
 	add_subdirectory(01_HelloCoreSystemAsset)
 	# showcase the use of `system::IApplicationFramework` and `nbl::video`
@@ -31,7 +42,6 @@ if(NBL_BUILD_EXAMPLES)
 	# showcase use of FFT for post-FX Bloom  effect
 	add_subdirectory(11_FFT)
 
-
 	# Waiting for a refactor
 	#add_subdirectory(27_PLYSTLDemo)
 	#add_subdirectory(33_Draw3DLine)
@@ -42,7 +52,7 @@ if(NBL_BUILD_EXAMPLES)
 	add_subdirectory(22_CppCompat)
 	add_subdirectory(23_Arithmetic2UnitTest)
 	add_subdirectory(24_ColorSpaceTest)
-	add_subdirectory(25_FilterTest)
+	add_subdirectory(25_FilterTest EXCLUDE_FROM_ALL)
 	add_subdirectory(26_Blur)
 	add_subdirectory(27_MPMCScheduler)	
 	add_subdirectory(28_FFTBloom)
@@ -58,27 +68,29 @@ if(NBL_BUILD_EXAMPLES)
 	# endif()
 
 	#add_subdirectory(43_SumAndCDFFilters)
-	add_subdirectory(47_DerivMapTest)
-	add_subdirectory(54_Transformations)
-	add_subdirectory(55_RGB18E7S3)
+	add_subdirectory(47_DerivMapTest EXCLUDE_FROM_ALL)
+	add_subdirectory(54_Transformations EXCLUDE_FROM_ALL)
+	add_subdirectory(55_RGB18E7S3 EXCLUDE_FROM_ALL)
 	add_subdirectory(61_UI)
 	add_subdirectory(62_CAD)
-	add_subdirectory(62_SchusslerTest)
+	add_subdirectory(62_SchusslerTest EXCLUDE_FROM_ALL)
 	add_subdirectory(64_EmulatedFloatTest)
-	add_subdirectory(0_ImportanceSamplingEnvMaps) #TODO: integrate back into 42
+	add_subdirectory(0_ImportanceSamplingEnvMaps EXCLUDE_FROM_ALL) #TODO: integrate back into 42
 
-	add_subdirectory(66_HLSLBxDFTests)
+	add_subdirectory(66_HLSLBxDFTests EXCLUDE_FROM_ALL)
 	add_subdirectory(67_RayQueryGeometry)
 	add_subdirectory(68_JpegLoading)
 
   	add_subdirectory(70_FLIPFluids)
 	add_subdirectory(71_RayTracingPipeline)
 
+	# add new examples *before* NBL_GET_ALL_TARGETS invocation, it gathers recursively all targets created so far in this subdirectory
 	NBL_GET_ALL_TARGETS(TARGETS)
 
-	# PCH & CommonAPI library for Nabla framework examples
-	add_subdirectory(common EXCLUDE_FROM_ALL)
+	# we want to loop only over the examples so we exclude examples' interface libraries created in common subdirectory
+	list(REMOVE_ITEM TARGETS ${NBL_EXAMPLES_API_TARGET} ${NBL_EXAMPLES_API_LIBRARIES})
 
+	# we link common example api library and force examples to reuse its PCH
 	foreach(T IN LISTS TARGETS)
         target_link_libraries(${T} PUBLIC ${NBL_EXAMPLES_API_TARGET})
 		target_include_directories(${T} PUBLIC $<TARGET_PROPERTY:${NBL_EXAMPLES_API_TARGET},INCLUDE_DIRECTORIES>)

common/CMakeLists.txt

@@ -1,7 +1,48 @@
+#! Examples API proxy library
+#[[
+    We create the Nabla Examples API as a static library extension, this
+    allows all examples to reuse a single precompiled header (PCH)
+    instead of generating their own
+
+    The PCH includes Nabla.h + example common interface headers and takes 
+    around 1 GB per configuration, so sharing it avoids significant disk space waste
+]]
+
 nbl_create_ext_library_project(ExamplesAPI "" "${CMAKE_CURRENT_SOURCE_DIR}/src/nbl/examples/pch.cpp" "${CMAKE_CURRENT_SOURCE_DIR}/include" "" "")
 
 set_target_properties(${LIB_NAME} PROPERTIES DISABLE_PRECOMPILE_HEADERS OFF)
 target_precompile_headers(${LIB_NAME} PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}/include/nbl/examples/PCH.hpp")
 
+#! Examples API common libraries
+#[[
+    The rule is to avoid creating additional libraries as part of the examples' common
+    interface in order to prevent generating another precompiled header (PCH) and wasting disk space
+
+    If you have new utilities that could be shared across examples then try to implement them as header only
+    and include in the PCH or in `examples.h` *if you cannot* (open the header to see details)
+
+    but If you have a good reason to create library because you cannot make it header only 
+    AND you *can REUSE* the examples' PCH then go ahead anyway and put it under `src/nbl/examples`, 
+    otherwise keep it header only - a good example would be to use our embedded-whatever-you-want tool
+    which does create library but can reuse example's PCH
+]]
+
+#! NOTE: as I write it we don't have any targets there yet
 add_subdirectory("src/nbl/examples" EXCLUDE_FROM_ALL)
-set(NBL_EXAMPLES_API_TARGET ${LIB_NAME} PARENT_SCOPE)
+
+NBL_GET_ALL_TARGETS(TARGETS)
+list(REMOVE_ITEM TARGETS ${LIB_NAME})
+
+# the Examples API proxy library CMake target name
+#[[
+    this one gets linked to each executable automatically
+]]
+set(NBL_EXAMPLES_API_TARGET ${LIB_NAME} PARENT_SCOPE)
+
+#! names of CMake targets created in src/nbl/examples
+#[[
+    if your example wants to use anything from src/nbl/examples
+    then you must target_link_libraries() the lib you want as we 
+    don't link all those libraries to each executable automatically
+]]
+set(NBL_EXAMPLES_API_LIBRARIES ${TARGETS} PARENT_SCOPE)

common/include/nbl/examples/PCH.hpp

@@ -4,17 +4,29 @@
 #ifndef _NBL_EXAMPLES_PCH_HPP_
 #define _NBL_EXAMPLES_PCH_HPP_
 
-//! public Nabla declarations
+//! Precompiled header (PCH) for Nabla Examples
 /*
     NOTE: currently our whole public and private interface is broken
     and private headers leak to public includes
 */
+
+//! Nabla declarations
 #include "nabla.h"
 
-//! common example headers
+//! Common example interface headers
 
 // why isnt this in `nabla.h` ?
-#include "nbl/application_templates/MonoAssetManagerAndBuiltinResourceApplication.hpp"
+/*
+    because it does stuff like
+
+    #ifdef NBL_EMBED_BUILTIN_RESOURCES
+    #include "nbl/this_example/builtin/CArchive.h"
+    #endif
+
+    hence also cannot be there in PCH but rather in examples.h -> compile errors
+    but only *if* we decide each example handles builtins on NBL_EMBED_BUILTIN_RESOURCES
+*/
+// #include "nbl/application_templates/MonoAssetManagerAndBuiltinResourceApplication.hpp"
 
 #include "nbl/examples/common/SimpleWindowedApplication.hpp"
 #include "nbl/examples/common/MonoWindowApplication.hpp"

common/include/nbl/examples/api.hpp

@@ -4,8 +4,16 @@
 #ifndef _NBL_EXAMPLES_HPP_
 #define _NBL_EXAMPLES_HPP_
 
-
+//! Precompiled header shared across all examples
 #include "nbl/examples/PCH.hpp"
 
+//! Example specific headers that must not be included in the PCH
+/*
+    NOTE: Add here if they depend on preprocessor definitions
+    or macros that are specific to individual example targets
+    (eg. defined in CMake)
+*/
+
+// #include "..."
 
 #endif // _NBL_EXAMPLES_HPP_

common/include/nbl/examples/examples.hpp

@@ -1,16 +1,4 @@
 # TODO builtin SPIR-V shaders
 # add_subdirectory(geometry EXCLUDE_FROM_ALL)
 
-# TODO: slightly redo and make docs once I get n4ce embed SPIRV tool to build system
-
-# we get all available targets inclusive & below this directory
-# NBL_GET_ALL_TARGETS(NBL_SUBDIRECTORY_TARGETS)
-
-# then we expose common include search directories to all common libraries + create link interface
-# foreach(NBL_TARGET IN LISTS NBL_SUBDIRECTORY_TARGETS)
-#    target_include_directories(${NBL_TARGET} PUBLIC $<TARGET_PROPERTY:nblExamplesAPI,INTERFACE_INCLUDE_DIRECTORIES>)
-#    target_link_libraries(nblExamplesAPI INTERFACE ${NBL_TARGET})
-#endforeach()
-
-#
-# set(NBL_COMMON_API_TARGETS ${NBL_SUBDIRECTORY_TARGETS} PARENT_SCOPE)
+# TODO: make docs once I get n4ce embed SPIRV tool to build system and then use the tool with Matts new shader