chore: checkpoint web Blender migration source, tools and docs

Accumulated uncommitted work: GHOST Web backend, WebGL/GPU web layer, web workflow engine and protocol, tooling, docs and task records. Large generated evidence, user-testing archives, build snapshots and imported test assets remain untracked. Co-Authored-By: Claude Code <noreply@anthropic.com>
2026-11-10 11:18:01 +08:00
parent 122142c26c
commit f3e21c6b98
6887 changed files with 257154 additions and 12294 deletions
--- a/blender-5.2.0/source/blender/blenkernel/intern/cachefile.cc
+++ b/blender-5.2.0/source/blender/blenkernel/intern/cachefile.cc
@@ -8,6 +8,8 @@

 #include <cstring>
 #include <optional>
+#include <map>
+#include <string>

 #include "DNA_cachefile_types.h"
 #include "DNA_object_types.h"
@@ -19,6 +21,7 @@
 #include "BLI_mutex.hh"
 #include "BLI_path_utils.hh"
 #include "BLI_string.h"
+#include "BLI_string_utf8.h"
 #include "BLI_utildefines.h"

 #include "BLT_translation.hh"
@@ -49,6 +52,10 @@

 namespace blender {

+struct CacheFileReaderDiagnostics {
+  std::map<std::pair<const Object *, std::string>, std::string> errors;
+};
+
 static void cachefile_handle_free(CacheFile *cache_file);

 static void cache_file_init_data(ID *id)
@@ -70,7 +77,10 @@ static void cache_file_copy_data(Main * /*bmain*/,
  const CacheFile *cache_file_src = id_cast<const CacheFile *>(id_src);

  cache_file_dst->handle = nullptr;
+  cache_file_dst->handle_status = CACHEFILE_HANDLE_STATUS_NONE;
+  cache_file_dst->handle_error[0] = '\0';
  cache_file_dst->handle_readers = nullptr;
+  cache_file_dst->reader_diagnostics = nullptr;
  BLI_duplicatelist(&cache_file_dst->object_paths, &cache_file_src->object_paths);
  BLI_duplicatelist(&cache_file_dst->layers, &cache_file_src->layers);
 }
@@ -98,7 +108,10 @@ static void cache_file_blend_write(BlendWriter *writer, ID *id, const void *id_a
  cache_file->object_paths.clear_no_delete();
  cache_file->handle = nullptr;
  memset(cache_file->handle_filepath, 0, sizeof(cache_file->handle_filepath));
+  cache_file->handle_status = CACHEFILE_HANDLE_STATUS_NONE;
+  memset(cache_file->handle_error, 0, sizeof(cache_file->handle_error));
  cache_file->handle_readers = nullptr;
+  cache_file->reader_diagnostics = nullptr;

  writer->write_id_struct(id_address, cache_file);
  BKE_id_blend_write(writer, &cache_file->id);
@@ -115,7 +128,10 @@ static void cache_file_blend_read_data(BlendDataReader *reader, ID *id)
  cache_file->object_paths.clear_no_delete();
  cache_file->handle = nullptr;
  cache_file->handle_filepath[0] = '\0';
+  cache_file->handle_status = CACHEFILE_HANDLE_STATUS_NONE;
+  cache_file->handle_error[0] = '\0';
  cache_file->handle_readers = nullptr;
+  cache_file->reader_diagnostics = nullptr;

  /* relink layers */
  BLO_read_struct_list(reader, CacheFileLayer, &cache_file->layers);
@@ -170,19 +186,20 @@ void BKE_cachefile_reader_open(CacheFile *cache_file,
    return;
  }

+  std::string reader_error;
  switch (cache_file->type) {
    case CACHEFILE_TYPE_ALEMBIC:
 #  ifdef WITH_ALEMBIC
      /* Open Alembic cache reader. */
      *reader = CacheReader_open_alembic_object(
-          cache_file->handle, *reader, object, object_path, cache_file->is_sequence);
+          cache_file->handle, *reader, object, object_path, cache_file->is_sequence, &reader_error);
 #  endif
      break;
    case CACHEFILE_TYPE_USD:
 #  ifdef WITH_USD
      /* Open USD cache reader. */
      *reader = io::usd::CacheReader_open_usd_object(
-          cache_file->handle, *reader, object, object_path);
+          cache_file->handle, *reader, object, object_path, &reader_error);
 #  endif
      break;
    case CACHE_FILE_TYPE_INVALID:
@@ -191,6 +208,20 @@ void BKE_cachefile_reader_open(CacheFile *cache_file,

  /* Multiple modifiers and constraints can call this function concurrently. */
  std::lock_guard lock(cache_mutex);
+  const auto key = std::make_pair(static_cast<const Object *>(DEG_get_original(object)),
+                                  std::string(object_path));
+  if (!reader_error.empty()) {
+    if (!cache_file->reader_diagnostics) {
+      cache_file->reader_diagnostics = MEM_new<CacheFileReaderDiagnostics>(
+          "CacheFile.reader_diagnostics");
+    }
+    char diagnostic[3072];
+    BLI_strncpy_utf8(diagnostic, reader_error.c_str(), sizeof(diagnostic));
+    cache_file->reader_diagnostics->errors[key] = diagnostic;
+  }
+  else if (cache_file->reader_diagnostics) {
+    cache_file->reader_diagnostics->errors.erase(key);
+  }
  if (*reader) {
    /* Register in set so we can free it when the cache file changes. */
    if (cache_file->handle_readers == nullptr) {
@@ -207,6 +238,25 @@ void BKE_cachefile_reader_open(CacheFile *cache_file,
 #endif
 }

+std::string BKE_cachefile_reader_error(const CacheFile *cache_file,
+                                     const Object *object,
+                                     const char *object_path)
+{
+#if defined(WITH_ALEMBIC) || defined(WITH_USD)
+  std::lock_guard lock(cache_mutex);
+  if (cache_file->reader_diagnostics) {
+    const auto key = std::make_pair(static_cast<const Object *>(DEG_get_original(object)),
+                                    std::string(object_path));
+    const auto &errors = cache_file->reader_diagnostics->errors;
+    const auto found = errors.find(key);
+    if (found != errors.end()) return found->second;
+  }
+#else
+  UNUSED_VARS(cache_file, object, object_path);
+#endif
+  return {};
+}
+
 void BKE_cachefile_reader_free(CacheFile *cache_file, CacheReader **reader)
 {
 #if defined(WITH_ALEMBIC) || defined(WITH_USD)
@@ -252,6 +302,10 @@ static void cachefile_handle_free(CacheFile *cache_file)
   * we free the handle itself. */
  {
    std::lock_guard lock(cache_mutex);
+    if (cache_file->reader_diagnostics) {
+      MEM_delete(cache_file->reader_diagnostics);
+      cache_file->reader_diagnostics = nullptr;
+    }
    if (cache_file->handle_readers) {
      for (CacheReader **reader : *cache_file->handle_readers) {
        if (*reader != nullptr) {
@@ -341,26 +395,81 @@ void BKE_cachefile_eval(Main *bmain, Depsgraph *depsgraph, CacheFile *cache_file

  cachefile_handle_free(cache_file);
  cache_file->object_paths.free_no_destruct();
+  cache_file->handle_status = CACHEFILE_HANDLE_STATUS_NONE;
+  cache_file->handle_error[0] = '\0';
+
+  if (filepath[0] == '\0') {
+    cache_file->handle_status = CACHEFILE_HANDLE_STATUS_EMPTY_PATH;
+    STRNCPY(cache_file->handle_error, "CACHEFILE_EMPTY_PATH");
+  }

 #ifdef WITH_ALEMBIC
  if (BLI_path_extension_check_glob(filepath, "*.abc")) {
    cache_file->type = CACHEFILE_TYPE_ALEMBIC;
+    std::string archive_error;
    cache_file->handle = ABC_create_handle(
        bmain,
        filepath,
        static_cast<const CacheFileLayer *>(cache_file->layers.first),
-        &cache_file->object_paths);
+        &cache_file->object_paths,
+        &archive_error);
    STRNCPY(cache_file->handle_filepath, filepath);
+    cache_file->handle_status = cache_file->handle ? CACHEFILE_HANDLE_STATUS_OPEN :
+                                                     CACHEFILE_HANDLE_STATUS_ALEMBIC_OPEN_FAILED;
+    if (!archive_error.empty()) {
+      BLI_strncpy_utf8(cache_file->handle_error, archive_error.c_str(),
+                       sizeof(cache_file->handle_error));
+    }
+    else if (!cache_file->handle) {
+      STRNCPY(cache_file->handle_error, "ALEMBIC_ARCHIVE_OPEN_FAILED");
+    }
+  }
+#else
+  /* Keep the diagnostic explicit when the format is recognised but the
+   * native reader is unavailable in this build. */
+  if (BLI_path_extension_check_glob(filepath, "*.abc")) {
+    cache_file->type = CACHEFILE_TYPE_ALEMBIC;
+    STRNCPY(cache_file->handle_filepath, filepath);
+    cache_file->handle_status = CACHEFILE_HANDLE_STATUS_BACKEND_UNAVAILABLE;
+    STRNCPY(cache_file->handle_error, "ALEMBIC_BACKEND_UNAVAILABLE");
  }
 #endif
 #ifdef WITH_USD
  if (BLI_path_extension_check_glob(filepath, "*.usd;*.usda;*.usdc;*.usdz")) {
    cache_file->type = CACHEFILE_TYPE_USD;
-    cache_file->handle = io::usd::USD_create_handle(bmain, filepath, &cache_file->object_paths);
+    std::string archive_error;
+    cache_file->handle = io::usd::USD_create_handle(
+        bmain, filepath, &cache_file->object_paths, &archive_error);
    STRNCPY(cache_file->handle_filepath, filepath);
+    cache_file->handle_status = cache_file->handle ? CACHEFILE_HANDLE_STATUS_OPEN :
+                                                     CACHEFILE_HANDLE_STATUS_USD_OPEN_FAILED;
+    if (!archive_error.empty()) {
+      BLI_strncpy_utf8(cache_file->handle_error, archive_error.c_str(),
+                       sizeof(cache_file->handle_error));
+    }
+    else if (!cache_file->handle) {
+      STRNCPY(cache_file->handle_error, "USD_STAGE_OPEN_FAILED");
+    }
+  }
+#else
+  if (BLI_path_extension_check_glob(filepath, "*.usd;*.usda;*.usdc;*.usdz")) {
+    cache_file->type = CACHEFILE_TYPE_USD;
+    STRNCPY(cache_file->handle_filepath, filepath);
+    cache_file->handle_status = CACHEFILE_HANDLE_STATUS_BACKEND_UNAVAILABLE;
+    STRNCPY(cache_file->handle_error, "USD_BACKEND_UNAVAILABLE");
  }
 #endif

+  if (cache_file->handle_status == CACHEFILE_HANDLE_STATUS_NONE && filepath[0] != '\0') {
+    cache_file->handle_status = CACHEFILE_HANDLE_STATUS_UNSUPPORTED_FORMAT;
+    STRNCPY(cache_file->handle_error, "CACHEFILE_UNSUPPORTED_ARCHIVE_FORMAT");
+  }
+
+  if (!cache_file->handle) {
+    /* Path enumeration may have failed part-way through a damaged archive. */
+    cache_file->object_paths.free_no_destruct();
+  }
+
  if (DEG_is_active(depsgraph)) {
    /* Flush object paths back to original data-block for UI. */
    CacheFile *cache_file_orig = DEG_get_original(cache_file);