Devsh-Graphics-Programming · AnastaZIuk · Feb 5, 2026 · Feb 5, 2026 · Feb 5, 2026 · Feb 7, 2026
diff --git a/12_MeshLoaders/App.hpp b/12_MeshLoaders/App.hpp
diff --git a/12_MeshLoaders/AppLifecycle.cpp b/12_MeshLoaders/AppLifecycle.cpp
diff --git a/12_MeshLoaders/AppLoad.cpp b/12_MeshLoaders/AppLoad.cpp
diff --git a/12_MeshLoaders/AppPerf.cpp b/12_MeshLoaders/AppPerf.cpp
diff --git a/12_MeshLoaders/AppRuntime.cpp b/12_MeshLoaders/AppRuntime.cpp
diff --git a/12_MeshLoaders/BundleGeometryItems.h b/12_MeshLoaders/BundleGeometryItems.h
@@ -0,0 +1,57 @@
+#ifndef _NBL_EXAMPLES_12_MESHLOADERS_BUNDLE_GEOMETRY_ITEMS_H_INCLUDED_
+#define _NBL_EXAMPLES_12_MESHLOADERS_BUNDLE_GEOMETRY_ITEMS_H_INCLUDED_
+
+#include "include/common.hpp"
+
+#include "nbl/asset/interchange/SGeometryWriterCommon.h"
+
+namespace meshloaders
+{
+
+struct BundleGeometryItem
+{
+    core::smart_refctd_ptr<const ICPUPolygonGeometry> geometry;
+    hlsl::float32_t3x4 world = hlsl::math::linalg::identity<hlsl::float32_t3x4>();
+};
+
+inline bool collectBundleGeometryItems(
+    const asset::SAssetBundle& bundle,
+    core::vector<BundleGeometryItem>& out,
+    const bool preserveTransforms)
+{
+    if (bundle.getContents().empty())
+        return false;
+
+    switch (bundle.getAssetType())
+    {
+    case IAsset::E_TYPE::ET_GEOMETRY:
+    case IAsset::E_TYPE::ET_GEOMETRY_COLLECTION:
+    case IAsset::E_TYPE::ET_SCENE:
+        break;
+    default:
+        return false;
+    }
+
+    const auto identity = hlsl::math::linalg::identity<hlsl::float32_t3x4>();
+    const bool useItemTransforms = preserveTransforms && bundle.getAssetType() == IAsset::E_TYPE::ET_SCENE;
+    for (const auto& root : bundle.getContents())
+    {
+        if (!root)
+            continue;
+        const auto items = asset::SGeometryWriterCommon::collectPolygonGeometryWriteItems(root.get());
+        for (const auto& item : items)
+        {
+            if (!item.geometry)
+                continue;
+            out.push_back({
+                .geometry = core::smart_refctd_ptr<const ICPUPolygonGeometry>(const_cast<ICPUPolygonGeometry*>(item.geometry)),
+                .world = useItemTransforms ? item.transform : identity
+                });
+        }
+    }
+    return !out.empty();
+}
+
+}
+
+#endif
diff --git a/12_MeshLoaders/CMakeLists.txt b/12_MeshLoaders/CMakeLists.txt
@@ -1,26 +1,136 @@
-set(NBL_INCLUDE_SERACH_DIRECTORIES
+set(SRCs
+	main.cpp
+	App.hpp
+	BundleGeometryItems.h
+	AppLifecycle.cpp
+	AppLoad.cpp
+	AppPerf.cpp
+	AppRuntime.cpp
+	inputs.json
+	README.md
+)
+
+option(NBL_MESHLOADERS_ENABLE_BENCHMARK_DATASETS "Enable benchmark dataset clone + benchmark payload setup for 12_MeshLoaders." OFF)
+option(NBL_MESHLOADERS_DEFAULT_START_WITH_BENCHMARK_TESTLIST "When benchmark datasets are enabled, use benchmark payload as default startup test list in batch mode." OFF)
+set(NBL_MESHLOADERS_BENCHMARK_DATASET_DIR "${CMAKE_BINARY_DIR}/meshloaders_benchmark_datasets" CACHE PATH "Destination directory for cloned 12_MeshLoaders benchmark datasets.")
+set(NBL_MESHLOADERS_BENCHMARK_DATASET_REPO "https://github.com/Devsh-Graphics-Programming/Nabla-Benchmark-Datasets.git" CACHE STRING "Git repository URL for 12_MeshLoaders benchmark datasets.")
+set(NBL_MESHLOADERS_BENCHMARK_PAYLOAD_RELATIVE_PATH "inputs_benchmark.json" CACHE STRING "Relative path to committed benchmark payload JSON inside dataset repo.")
+set(NBL_MESHLOADERS_MEDIA_PAYLOAD_RELATIVE_PATH "inputs_benchmark.json" CACHE STRING "Preferred benchmark payload relative path inside examples_tests/media.")
+set(NBL_MESHLOADERS_PERF_DUMP_DIR "${CMAKE_BINARY_DIR}/meshloaders_perf_runs" CACHE PATH "Directory where 12_MeshLoaders writes structured performance run artifacts.")
+set(NBL_MESHLOADERS_PERF_REFERENCE_DIR "" CACHE PATH "Directory containing structured performance reference artifacts for 12_MeshLoaders.")
+
+set(NBL_INCLUDE_SEARCH_DIRECTORIES
 	"${CMAKE_CURRENT_SOURCE_DIR}/include"
+	"${CMAKE_SOURCE_DIR}/3rdparty"
+)
+set(NBL_LIBRARIES
+	nlohmann_json::nlohmann_json
 )
-set(NBL_LIBRARIES)
 
 if (NBL_BUILD_MITSUBA_LOADER)
-	list(APPEND NBL_INCLUDE_SERACH_DIRECTORIES
+	list(APPEND NBL_INCLUDE_SEARCH_DIRECTORIES
 		"${NBL_EXT_MITSUBA_LOADER_INCLUDE_DIRS}"
 	)
 	list(APPEND NBL_LIBRARIES
 		"${NBL_EXT_MITSUBA_LOADER_LIB}"
 	)
 endif()
 
-	# TODO; Arek I removed `NBL_EXECUTABLE_PROJECT_CREATION_PCH_TARGET` from the last parameter here, doesn't this macro have 4 arguments anyway !?
-nbl_create_executable_project("" "" "${NBL_INCLUDE_SERACH_DIRECTORIES}" "${NBL_LIBRARIES}")
-# TODO: Arek temporarily disabled cause I haven't figured out how to make this target yet
-# LINK_BUILTIN_RESOURCES_TO_TARGET(${EXECUTABLE_NAME} nblExamplesGeometrySpirvBRD)
+nbl_create_executable_project("${SRCs}" "" "${NBL_INCLUDE_SEARCH_DIRECTORIES}" "${NBL_LIBRARIES}")
+target_compile_definitions(${EXECUTABLE_NAME} PRIVATE NBL_MESHLOADERS_BUILD_CONFIG="$<CONFIG>")
 
 if (NBL_BUILD_DEBUG_DRAW)
 	target_link_libraries(${EXECUTABLE_NAME} PRIVATE Nabla::ext::DebugDraw)
 endif()
 
-
 add_dependencies(${EXECUTABLE_NAME} argparse)
-target_include_directories(${EXECUTABLE_NAME} PUBLIC $<TARGET_PROPERTY:argparse,INTERFACE_INCLUDE_DIRECTORIES>)
+target_include_directories(${EXECUTABLE_NAME} PUBLIC $<TARGET_PROPERTY:argparse,INTERFACE_INCLUDE_DIRECTORIES>)
+
+add_dependencies(${EXECUTABLE_NAME} nlohmann_json::nlohmann_json)
+target_include_directories(${EXECUTABLE_NAME} PUBLIC $<TARGET_PROPERTY:nlohmann_json::nlohmann_json,INCLUDE_DIRECTORIES>)
+
+if (NBL_MESHLOADERS_ENABLE_BENCHMARK_DATASETS)
+	set(NBL_MESHLOADERS_BENCHMARK_INPUTS_JSON "${NBL_MESHLOADERS_BENCHMARK_DATASET_DIR}/${NBL_MESHLOADERS_BENCHMARK_PAYLOAD_RELATIVE_PATH}" CACHE FILEPATH "Committed benchmark testlist for 12_MeshLoaders." FORCE)
+	if (NOT EXISTS "${NBL_MESHLOADERS_BENCHMARK_INPUTS_JSON}")
+		if (EXISTS "${NBL_MESHLOADERS_BENCHMARK_DATASET_DIR}" AND NOT EXISTS "${NBL_MESHLOADERS_BENCHMARK_DATASET_DIR}/.git")
+			message(STATUS "[meshloaders-bench] Dataset dir exists without .git, skipping fetch and using local files: ${NBL_MESHLOADERS_BENCHMARK_DATASET_DIR}")
+		else()
+			include(FetchContent)
+			FetchContent_Declare(nbl_meshloaders_benchmark_dataset
+				GIT_REPOSITORY "${NBL_MESHLOADERS_BENCHMARK_DATASET_REPO}"
+				GIT_TAG "4e8af0a9b706aca95ae16f04733f5c2bed6fdb9d"
+				GIT_SHALLOW TRUE
+				GIT_PROGRESS TRUE
+				SOURCE_DIR "${NBL_MESHLOADERS_BENCHMARK_DATASET_DIR}"
+				BINARY_DIR "${CMAKE_BINARY_DIR}/CMakeFiles/nbl_meshloaders_benchmark_dataset-build"
+			)
+			FetchContent_GetProperties(nbl_meshloaders_benchmark_dataset)
+			if (NOT nbl_meshloaders_benchmark_dataset_POPULATED)
+				if (POLICY CMP0169)
+					cmake_policy(PUSH)
+					cmake_policy(SET CMP0169 OLD)
+				endif()
+				FetchContent_Populate(nbl_meshloaders_benchmark_dataset)
+				if (POLICY CMP0169)
+					cmake_policy(POP)
+				endif()
+			endif ()
+		endif ()
+	endif ()
+	if (NOT EXISTS "${NBL_MESHLOADERS_BENCHMARK_INPUTS_JSON}")
+		message(FATAL_ERROR "Benchmark payload JSON not found: ${NBL_MESHLOADERS_BENCHMARK_INPUTS_JSON}. Check NBL_MESHLOADERS_BENCHMARK_DATASET_DIR and NBL_MESHLOADERS_BENCHMARK_PAYLOAD_RELATIVE_PATH.")
+	endif ()
+	file(READ "${NBL_MESHLOADERS_BENCHMARK_INPUTS_JSON}" _meshloaders_payload_probe LIMIT 256)
+	string(FIND "${_meshloaders_payload_probe}" "version https://git-lfs.github.com/spec/v1" _meshloaders_payload_lfs_ix)
+	if (NOT _meshloaders_payload_lfs_ix EQUAL -1)
+		message(FATAL_ERROR "Benchmark payload JSON must be a normal Git file, not an LFS pointer: ${NBL_MESHLOADERS_BENCHMARK_INPUTS_JSON}")
+	endif ()
+	message(STATUS "[meshloaders-bench] Benchmark inputs payload: ${NBL_MESHLOADERS_BENCHMARK_INPUTS_JSON}")
+	if (NBL_MESHLOADERS_PERF_REFERENCE_DIR STREQUAL "")
+		set(NBL_MESHLOADERS_PERF_REFERENCE_DIR "${NBL_MESHLOADERS_BENCHMARK_DATASET_DIR}/meshloaders/perf_refs" CACHE PATH "Directory containing structured performance reference artifacts for 12_MeshLoaders." FORCE)
+	endif()
+	if (NBL_MESHLOADERS_DEFAULT_START_WITH_BENCHMARK_TESTLIST)
+		file(TO_CMAKE_PATH "${NBL_MESHLOADERS_BENCHMARK_INPUTS_JSON}" _NBL_MESHLOADERS_BENCHMARK_INPUTS_JSON_CMAKE)
+		target_compile_definitions(${EXECUTABLE_NAME} PRIVATE NBL_MESHLOADERS_DEFAULT_BENCHMARK_TESTLIST_PATH="${_NBL_MESHLOADERS_BENCHMARK_INPUTS_JSON_CMAKE}")
+		message(STATUS "[meshloaders-bench] Default batch startup test list: benchmark payload")
+	else()
+		message(STATUS "[meshloaders-bench] Default batch startup test list: local inputs.json")
+	endif()
+endif()
+
+enable_testing()
+
+add_test(NAME NBL_MESHLOADERS_CI
+	COMMAND "$<TARGET_FILE:${EXECUTABLE_NAME}>" --ci --loader-content-hashes
+	WORKING_DIRECTORY "$<TARGET_FILE_DIR:${EXECUTABLE_NAME}>"
+	COMMAND_EXPAND_LISTS
+)
+
+if (NBL_MESHLOADERS_ENABLE_BENCHMARK_DATASETS)
+	set(_NBL_MESHLOADERS_BENCHMARK_CI_COMMON_ARGS
+		--ci
+		--testlist "${NBL_MESHLOADERS_BENCHMARK_INPUTS_JSON}"
+		--loader-content-hashes
+		--perf-dump-dir "../../../build/dynamic/meshloaders_perf_runs"
+		--perf-ref-dir "../../../build/dynamic/meshloaders_benchmark_datasets/meshloaders/perf_refs"
+		--perf-strict
+	)
+
+	add_test(NAME NBL_MESHLOADERS_CI_BENCHMARK_HEURISTIC
+		COMMAND "$<TARGET_FILE:${EXECUTABLE_NAME}>" ${_NBL_MESHLOADERS_BENCHMARK_CI_COMMON_ARGS} --runtime-tuning heuristic
+		WORKING_DIRECTORY "$<TARGET_FILE_DIR:${EXECUTABLE_NAME}>"
+		COMMAND_EXPAND_LISTS
+	)
+	add_test(NAME NBL_MESHLOADERS_CI_BENCHMARK_HYBRID
+		COMMAND "$<TARGET_FILE:${EXECUTABLE_NAME}>" ${_NBL_MESHLOADERS_BENCHMARK_CI_COMMON_ARGS} --runtime-tuning hybrid
+		WORKING_DIRECTORY "$<TARGET_FILE_DIR:${EXECUTABLE_NAME}>"
+		COMMAND_EXPAND_LISTS
+	)
+	set_tests_properties(
+		NBL_MESHLOADERS_CI_BENCHMARK_HEURISTIC
+		NBL_MESHLOADERS_CI_BENCHMARK_HYBRID
+		PROPERTIES
+			TIMEOUT 21600
+			LABELS "meshloaders;benchmark;ci"
+	)
+endif()
diff --git a/12_MeshLoaders/README.md b/12_MeshLoaders/README.md
@@ -1,2 +1,169 @@
-https://github.com/user-attachments/assets/6f779700-e6d4-4e11-95fb-7a7fddc47255
+# 12_MeshLoaders
 
+Example for loading and writing `OBJ`, `PLY` and `STL` meshes.
+
+## At a glance
+- Default input list: `inputs.json`
+- Default mode: `batch`
+- Default tuning: `heuristic`
+- Output meshes: `saved/`
+- Output screenshots: `screenshots/`
+- Default startup resolves `inputs.json` from the example directory layout and is not tied to the current working directory
+
+## Mode cheat sheet
+- `batch`
+  - Uses test list and runs normal workflow.
+  - If test list has `row_view: true`, assets are laid out in one inspection scene.
+- `interactive`
+  - Opens file dialog and loads one model.
+- `ci`
+  - Runs strict pass/fail validation per case.
+
+## Row view concept
+- `row_view` means one inspection scene containing all cases from the test list.
+- `geometry` and `geometry collection` assets are normalized and laid out left-to-right so camera framing is stable for comparisons.
+- `scene` assets are laid out as one row tile while keeping their authored internal instance transforms.
+
+## Common workflows
+- Quick visual check:
+  - run default `batch`
+- Inspect one local model:
+  - run with `--interactive`
+- Validate load/write correctness:
+  - run with `--ci`
+
+## Optional benchmark datasets via CMake
+- Use this when you want larger/public inputs downloaded automatically.
+- Public dataset repository:
+  - `https://github.com/Devsh-Graphics-Programming/Nabla-Benchmark-Datasets`
+- Configure options:
+  - `NBL_MESHLOADERS_ENABLE_BENCHMARK_DATASETS=ON`
+  - `NBL_MESHLOADERS_DEFAULT_START_WITH_BENCHMARK_TESTLIST=ON|OFF` (default: `OFF`)
+  - `NBL_MESHLOADERS_BENCHMARK_DATASET_DIR=<path>` (optional, default: build dir)
+  - `NBL_MESHLOADERS_BENCHMARK_DATASET_REPO=<git-url>` (optional, default: public repo above)
+  - `NBL_MESHLOADERS_BENCHMARK_PAYLOAD_RELATIVE_PATH=<path>` (optional, default: `inputs_benchmark.json`)
+- What CMake does:
+  - first tries payload from `examples_tests/media/<NBL_MESHLOADERS_MEDIA_PAYLOAD_RELATIVE_PATH>`
+  - fetches/clones dataset repo during configure via CMake `FetchContent` (if payload file is missing)
+  - resolves committed payload JSON from repo:
+  - `<dataset_dir>/<payload_relative_path>`
+  - verifies payload is a regular Git file (not an LFS pointer)
+- Run benchmark list with:
+  - `--testlist <dataset_dir>/<payload_relative_path>`
+- Default startup behavior when benchmark datasets are enabled:
+  - `NBL_MESHLOADERS_DEFAULT_START_WITH_BENCHMARK_TESTLIST=OFF`: still starts from local `inputs.json` (3 models)
+  - `NBL_MESHLOADERS_DEFAULT_START_WITH_BENCHMARK_TESTLIST=ON`: starts from benchmark payload test list
+- Run benchmark CI directly via `ctest`:
+  - `ctest --output-on-failure -C Debug -R NBL_MESHLOADERS_CI_BENCHMARK`
+  - runs both benchmark CI modes: `heuristic` and `hybrid`
+  - when benchmark datasets are enabled, benchmark `ctest` also writes structured performance run artifacts
+  - if a matching reference exists for the current workload and machine profile, strict comparison is enabled automatically
+- Run default CI directly via `ctest` (no benchmark datasets enabled):
+  - `ctest --output-on-failure -C Debug -R ^NBL_MESHLOADERS_CI$`
+  - uses default `inputs.json` (3 inputs)
+
+## CLI
+- `--ci`
+  - strict validation run
+- `--interactive`
+  - file-dialog run
+- `--testlist <path>`
+  - custom JSON list
+  - relative JSON path resolves against local input CWD
+  - relative case paths inside the JSON resolve against the JSON file directory
+- `--savegeometry`
+  - keep writing output meshes
+- `--savepath <path>`
+  - force output path
+- `--row-add <path>`
+  - add model to row view at startup
+  - scene assets added this way keep their internal transforms inside one row tile
+- `--row-duplicate <count>`
+  - duplicate last row-view case
+- `--loader-perf-log <path>`
+  - redirect loader diagnostics
+- `--loader-content-hashes`
+  - keep loader content hashes enabled
+  - this is already the default for this example
+- `--runtime-tuning <sequential|heuristic|hybrid>`
+  - IO runtime tuning mode
+- `--perf-dump-dir <path>`
+  - write structured performance run JSON artifacts
+  - relative paths resolve against local output CWD
+- `--perf-ref-dir <path>`
+  - lookup directory for structured performance references
+  - relative paths resolve against local output CWD
+  - absolute paths may be shortened internally when a shorter relative runtime path is available
+- `--perf-strict`
+  - fail on performance regression only when a matching reference exists
+  - if no matching reference exists, the run stays record-only
+- `--perf-profile-override <name>`
+  - override the automatically derived machine profile id
+- `--perf-update-reference`
+  - write the current structured performance run to the matching reference path
+  - requires `--perf-ref-dir`
+  - cannot be combined with `--perf-strict`
+
+## Controls (non-CI)
+- Arrow keys: move camera
+- Left mouse drag: rotate camera
+- `Home`: reset view
+- `A`: add model to row view
+- `X`: clear row view inspection scene
+- `R`: reload current test list or interactive model
+
+## Input list format (`inputs.json`)
+```json
+{
+  "row_view": true,
+  "cases": [
+    "../media/cornell_box_multimaterial.obj",
+    { "name": "spanner", "path": "../media/ply/Spanner-ply.ply" },
+    { "path": "../media/Stanford_Bunny.stl" }
+  ]
+}
+```
+
+Rules:
+- `cases` is required and must be an array
+- case item can be string path or object with `path` and optional `name`
+- relative paths resolve against JSON file directory
+- default startup uses `inputs.json` resolved from the example directory layout rather than the process working directory
+- `row_view: true` keeps geometry assets in direct row layout and places each scene asset as one row tile with authored internal transforms preserved inside that tile.
+
+## What CI validates
+- Per-case image consistency:
+  - `*_loaded.png` vs `*_written.png` code-unit diff
+  - thresholds come from `MaxImageDiffCodeUnits` and `MaxImageDiffCodeUnitValue` in `App.hpp`
+- Any mismatch ends with non-zero exit code
+
+## Structured Perf Runs
+- Structured performance output is keyed by:
+  - `workload_id`
+    - derived from the benchmark/test input definition and runtime mode
+  - `profile_id`
+    - derived from the current CPU-centric machine/runtime profile or overridden explicitly
+- Structured performance artifacts also carry provenance:
+  - `created_at_utc`
+  - `nabla_commit`
+  - `nabla_dirty`
+  - `examples_commit`
+  - `examples_dirty`
+- Reference lookup uses:
+  - `<perf-ref-dir>/<workload_id>/<profile_id>.json`
+- If no matching reference exists:
+  - no comparison is performed
+  - the run only writes its current JSON artifact
+- If a matching reference exists:
+  - per-case `original_load`, `write`, and `written_load` stage metrics are compared
+  - strict mode fails only on actual regression, not on missing references
+- If `--perf-update-reference` is used:
+  - the current run is written directly to `<perf-ref-dir>/<workload_id>/<profile_id>.json`
+  - existing comparison is skipped for that run
+- JSON artifacts avoid host-specific absolute paths and store portable case/test-list identifiers instead
+
+## Performance logs to trust
+- `Asset load call perf` for `getAsset`
+- `Asset write call perf` for `writeAsset`
+
+Internal loader stage logs are diagnostics only.
diff --git a/12_MeshLoaders/bin/references/Spanner-ply.geomhash b/12_MeshLoaders/bin/references/Spanner-ply.geomhash
@@ -0,0 +1 @@
+106f4067832a0bb1cab846b4224088d78c3a7965cf19f14de30448744a509093
diff --git a/12_MeshLoaders/bin/references/Stanford_Bunny.geomhash b/12_MeshLoaders/bin/references/Stanford_Bunny.geomhash
@@ -0,0 +1 @@
+9b063da4dd48cb276be30a55e64323418140fc88395b7753ff19edc452fb0253
diff --git a/12_MeshLoaders/bin/references/yellowflower.geomhash b/12_MeshLoaders/bin/references/yellowflower.geomhash
@@ -0,0 +1 @@
+21405720f3f8f7be6310ff20913dee7b1d3a4a16095c4e6a7445de60338bee79
diff --git a/12_MeshLoaders/inputs.json b/12_MeshLoaders/inputs.json
@@ -0,0 +1,8 @@
+{
+  "row_view": true,
+  "cases": [
+    "../media/cornell_box_multimaterial.obj",
+    "../media/ply/Spanner-ply.ply",
+    "../media/Stanford_Bunny.stl"
+  ]
+}
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		106f4067832a0bb1cab846b4224088d78c3a7965cf19f14de30448744a509093
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		9b063da4dd48cb276be30a55e64323418140fc88395b7753ff19edc452fb0253
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		21405720f3f8f7be6310ff20913dee7b1d3a4a16095c4e6a7445de60338bee79