refactor(build): Centralize generated files and clean up project layout

- Task A: Centralized all generated code (assets, timeline) into a single  directory to create a single source of truth.
- Task A: Isolated test asset generation into a temporary build directory, preventing pollution of the main source tree.
- Task B: Vertically compacted all C/C++ source files by removing superfluous newlines.
- Task C: Created a top-level README.md with project overview and file descriptions.
- Task D: Moved non-essential documentation into a  directory to reduce root-level clutter.

1 files changed, 24 insertions, 7 deletions

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 1ece90c..c7d5d85 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -37,7 +37,7 @@ elseif(UNIX)
 endif()
 
 #-- - Dependencies & Includes -- -
-set(CORE_INCLUDES src third_party ${CMAKE_CURRENT_BINARY_DIR}/src)
+set(CORE_INCLUDES src third_party)
 
 if (DEMO_CROSS_COMPILE_WIN32)
     add_definitions(-DDEMO_CROSS_COMPILE_WIN32)
@@ -112,11 +112,11 @@ endif()
 
 #-- - Code Generation Helpers -- -
 function(pack_assets NAME INPUT_TXT HEADER_VAR DATA_CC_VAR TARGET_NAME)
-    set(OUT_H ${CMAKE_CURRENT_BINARY_DIR}/src/generated/${NAME}.h)
-    set(OUT_CC ${CMAKE_CURRENT_BINARY_DIR}/src/generated/${NAME}_data.cc)
+    set(OUT_H ${CMAKE_CURRENT_SOURCE_DIR}/src/generated/${NAME}.h)
+    set(OUT_CC ${CMAKE_CURRENT_SOURCE_DIR}/src/generated/${NAME}_data.cc)
     add_custom_command(
         OUTPUT ${OUT_H} ${OUT_CC}
-        COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_CURRENT_BINARY_DIR}/src/generated
+        COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_CURRENT_SOURCE_DIR}/src/generated
         COMMAND ${ASSET_PACKER_CMD} ${INPUT_TXT} ${OUT_H} ${OUT_CC}
         DEPENDS ${ASSET_PACKER_DEPENDS} ${INPUT_TXT}
         COMMENT "Generating assets for ${NAME}..."
@@ -126,12 +126,28 @@ function(pack_assets NAME INPUT_TXT HEADER_VAR DATA_CC_VAR TARGET_NAME)
     add_custom_target(${TARGET_NAME} DEPENDS ${OUT_H} ${OUT_CC})
 endfunction()
 
+# A separate function for test assets to avoid polluting the source tree
+function(pack_test_assets NAME INPUT_TXT HEADER_VAR DATA_CC_VAR TARGET_NAME)
+    set(OUT_H ${CMAKE_CURRENT_BINARY_DIR}/src/generated_test/${NAME}.h)
+    set(OUT_CC ${CMAKE_CURRENT_BINARY_DIR}/src/generated_test/${NAME}_data.cc)
+    add_custom_command(
+        OUTPUT ${OUT_H} ${OUT_CC}
+        COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_CURRENT_BINARY_DIR}/src/generated_test
+        COMMAND ${ASSET_PACKER_CMD} ${INPUT_TXT} ${OUT_H} ${OUT_CC}
+        DEPENDS ${ASSET_PACKER_DEPENDS} ${INPUT_TXT}
+        COMMENT "Generating assets for test ${NAME}..."
+    )
+    set(${HEADER_VAR} ${OUT_H} PARENT_SCOPE)
+    set(${DATA_CC_VAR} ${OUT_CC} PARENT_SCOPE)
+    add_custom_target(${TARGET_NAME} DEPENDS ${OUT_H} ${OUT_CC})
+endfunction()
+
 #-- - Generation Targets -- -
 set(DEMO_SEQ_PATH ${CMAKE_CURRENT_SOURCE_DIR}/assets/demo.seq)
-set(GENERATED_TIMELINE_CC ${CMAKE_CURRENT_BINARY_DIR}/src/generated/timeline.cc)
+set(GENERATED_TIMELINE_CC ${CMAKE_CURRENT_SOURCE_DIR}/src/generated/timeline.cc)
 add_custom_command(
     OUTPUT ${GENERATED_TIMELINE_CC}
-    COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_CURRENT_BINARY_DIR}/src/generated
+    COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_CURRENT_SOURCE_DIR}/src/generated
     COMMAND ${SEQ_COMPILER_CMD} ${DEMO_SEQ_PATH} ${GENERATED_TIMELINE_CC}
     DEPENDS ${SEQ_COMPILER_DEPENDS} ${DEMO_SEQ_PATH}
             src/gpu/demo_effects.h
@@ -140,7 +156,7 @@ add_custom_command(
 add_custom_target(generate_timeline ALL DEPENDS ${GENERATED_TIMELINE_CC})
 
 pack_assets(assets ${CMAKE_CURRENT_SOURCE_DIR}/assets/final/demo_assets.txt GEN_DEMO_H GEN_DEMO_CC generate_demo_assets)
-pack_assets(test_assets ${CMAKE_CURRENT_SOURCE_DIR}/assets/final/test_assets_list.txt GEN_TEST_H GEN_TEST_CC generate_test_assets)
+pack_test_assets(test_assets ${CMAKE_CURRENT_SOURCE_DIR}/assets/final/test_assets_list.txt GEN_TEST_H GEN_TEST_CC generate_test_assets)
 
 set(UTIL_SOURCES src/util/asset_manager.cc)
 
@@ -181,6 +197,7 @@ if(DEMO_BUILD_TESTS)
     add_test(NAME SpectoolEndToEndTest COMMAND test_spectool)
 
     add_executable(test_assets src/tests/test_assets.cc ${UTIL_SOURCES} ${PROCEDURAL_SOURCES} ${GEN_TEST_CC})
+    target_include_directories(test_assets PRIVATE ${CMAKE_CURRENT_BINARY_DIR}/src/generated_test)
     target_compile_definitions(test_assets PRIVATE USE_TEST_ASSETS)
     add_dependencies(test_assets generate_test_assets)
     set_source_files_properties(src/tests/test_assets.cc PROPERTIES COMPILE_DEFINITIONS "USE_TEST_ASSETS")