Probe and expose runtime renderer availability

Add runtime backend probing and reporting: introduce BackendRuntimeInfo and APIs to probe, cache and clear backend availability (refresh_runtime_backend_info, runtime_backend_info, backend_kind_is_available, backend_unavailable_reason). Wire renderer-side probe hooks for Vulkan/Metal/OpenGL and add a safe GLFW init/is_initialized guard so probing can initialize and terminate GLFW as needed. Update CLI (--list-backends), preferences UI and test-engine JSON to show runtime availability and unavailability reasons and disable/ignore unavailable backends. Improve backend resolution to prefer runtime-available builds and emit clearer diagnostics when no backend is usable. Also include robustness fixes to screen-capture code (handle negative coords/full-capture fallback and try front/back read buffers for GL) and small tooling updates to regression scripts to account for runtime availability and window-relative click coordinates.

Author: ssh4net

src/doc/imiv_dev.rst

@@ -116,27 +116,28 @@ The startup sequence in `src/imiv/imiv_app.cpp` is:
 
 1. `imiv_main.cpp` parses CLI arguments into `AppConfig`.
 2. `run()` loads persistent app state with `load_persistent_state()`.
-3. `run()` resolves the requested backend with
+3. `run()` initializes GLFW and refreshes runtime backend availability.
+4. `run()` resolves the requested backend with
    `requested_backend_for_launch()` and `resolve_backend_request()`.
-4. GLFW is initialized and the main window is created.
-5. The Dear ImGui context is created and configured:
+5. The main window is created for the resolved backend.
+6. The Dear ImGui context is created and configured:
 
    * `ImGuiConfigFlags_NavEnableKeyboard`
    * `ImGuiConfigFlags_DockingEnable`
    * `ImGuiConfigFlags_ViewportsEnable`
 
-6. Fonts and the base application style are loaded.
-7. Dear ImGui layout data is loaded from disk with
+7. Fonts and the base application style are loaded.
+8. Dear ImGui layout data is loaded from disk with
    `ImGui::LoadIniSettingsFromDisk()`.
-8. The selected renderer backend is initialized:
+9. The selected renderer backend is initialized:
 
    * instance/device setup;
    * swapchain or drawable setup;
    * backend-specific Dear ImGui renderer bootstrap.
 
-9. Optional OCIO preview support is preflighted for the active backend.
-10. Startup images are loaded with `load_viewer_image()`.
-11. Drag and drop and optional Dear ImGui Test Engine hooks are installed.
+10. Optional OCIO preview support is preflighted for the active backend.
+11. Startup images are loaded with `load_viewer_image()`.
+12. Drag and drop and optional Dear ImGui Test Engine hooks are installed.
 
 Main loop
 ---------

src/doc/imiv_user.rst

@@ -53,7 +53,8 @@ image list. For example::
          --view "ACES 2.0 - SDR 100 nits (Rec.709)" \
          --image-color-space ACEScg image.exr
 
-To see which renderer backends were compiled into the current binary::
+To see which renderer backends were compiled into the current binary and which
+of those are currently usable on this machine::
 
     imiv --list-backends
 
@@ -80,13 +81,15 @@ Use :program:`imiv --help` to print the option summary for the current build.
 
     The command-line request takes precedence over the saved backend
     preference. If the requested backend was not compiled into the current
-    binary, :program:`imiv` falls back to the resolved default backend and
-    prints a message.
+    binary, or was compiled but is not currently available at runtime,
+    :program:`imiv` falls back to the resolved default backend and prints a
+    message.
 
 .. option:: --list-backends
 
     Print the backend support compiled into the current :program:`imiv`
-    binary, then exit.
+    binary, including runtime availability and any unavailability reason, then
+    exit.
 
 .. option:: --display NAME
 

src/imiv/imiv_app.cpp

@@ -192,19 +192,6 @@ run(const AppConfig& config)
     }
     const BackendKind requested_backend = requested_backend_for_launch(
         run_config, ui_state);
-    const BackendKind active_backend = resolve_backend_request(
-        requested_backend);
-    if (active_backend == BackendKind::Auto) {
-        print(stderr, "imiv: no renderer backend is compiled into this build\n");
-        return EXIT_FAILURE;
-    }
-    if (requested_backend != BackendKind::Auto
-        && requested_backend != active_backend) {
-        print("imiv: requested backend '{}' is not compiled into this build; "
-              "using '{}'\n",
-              backend_cli_name(requested_backend),
-              backend_runtime_name(active_backend));
-    }
 
     const bool verbose_logging = run_config.verbose;
     const bool verbose_validation_output
@@ -230,6 +217,50 @@ run(const AppConfig& config)
         return EXIT_FAILURE;
     }
 
+    refresh_runtime_backend_info(verbose_logging, startup_error);
+
+    const BackendKind active_backend = resolve_backend_request(
+        requested_backend);
+    if (active_backend == BackendKind::Auto) {
+        if (compiled_backend_count() == 0) {
+            print(stderr,
+                  "imiv: no renderer backend is compiled into this build\n");
+        } else {
+            print(stderr,
+                  "imiv: no compiled renderer backend is currently available\n");
+            for (const BackendRuntimeInfo& info : runtime_backend_info()) {
+                if (!info.build_info.compiled || info.available)
+                    continue;
+                print(stderr, "imiv:   {} unavailable: {}\n",
+                      info.build_info.display_name,
+                      info.unavailable_reason.empty()
+                          ? "backend is unavailable"
+                          : info.unavailable_reason);
+            }
+        }
+        platform_glfw_terminate();
+        return EXIT_FAILURE;
+    }
+    if (requested_backend != BackendKind::Auto
+        && requested_backend != active_backend) {
+        if (!backend_kind_is_compiled(requested_backend)) {
+            print("imiv: requested backend '{}' is not compiled into this "
+                  "build; using '{}'\n",
+                  backend_cli_name(requested_backend),
+                  backend_runtime_name(active_backend));
+        } else {
+            const std::string_view unavailable_reason
+                = backend_unavailable_reason(requested_backend);
+            print("imiv: requested backend '{}' is unavailable at runtime{}; "
+                  "using '{}'\n",
+                  backend_cli_name(requested_backend),
+                  unavailable_reason.empty()
+                      ? ""
+                      : Strutil::fmt::format(" ({})", unavailable_reason),
+                  backend_runtime_name(active_backend));
+        }
+    }
+
     const std::string window_title = build_main_window_title(active_backend);
     GLFWwindow* window = platform_glfw_create_main_window(
         active_backend, 1600, 900, window_title.c_str(), startup_error);
@@ -371,13 +402,18 @@ run(const AppConfig& config)
     if (run_config.verbose) {
         print("imiv: bootstrap initialized (backend: {})\n",
               backend_runtime_name(active_backend));
-        for (const BackendInfo& info : compiled_backend_info()) {
-            print("imiv: backend {} ({}) compiled={} build_default={} "
-                  "platform_default={}\n",
-                  info.display_name, info.cli_name,
-                  info.compiled ? "yes" : "no",
-                  info.active_build ? "yes" : "no",
-                  info.platform_default ? "yes" : "no");
+        for (const BackendRuntimeInfo& info : runtime_backend_info()) {
+            print("imiv: backend {} ({}) compiled={} available={} "
+                  "build_default={} platform_default={}{}\n",
+                  info.build_info.display_name, info.build_info.cli_name,
+                  info.build_info.compiled ? "yes" : "no",
+                  info.available ? "yes" : "no",
+                  info.build_info.active_build ? "yes" : "no",
+                  info.build_info.platform_default ? "yes" : "no",
+                  (!info.available && !info.unavailable_reason.empty())
+                      ? Strutil::fmt::format(" reason='{}'",
+                                             info.unavailable_reason)
+                      : std::string());
         }
         print("imiv: startup queue has {} image path(s)\n",
               run_config.input_paths.size());

src/imiv/imiv_aux_windows.cpp

@@ -279,24 +279,31 @@ draw_preferences_window(PlaceholderUiState& ui, bool& show_window,
         ImVec2 backend_row_min(0.0f, 0.0f);
         ImVec2 backend_row_max(0.0f, 0.0f);
         int backend_button_index = 0;
-        for (const BackendInfo& info : compiled_backend_info()) {
-            const bool selected = requested_backend == info.kind;
+        for (const BackendRuntimeInfo& info : runtime_backend_info()) {
+            const bool selected = requested_backend == info.build_info.kind;
             if (backend_button_index > 0)
                 ImGui::SameLine(0.0f, spacing);
-            ImGui::PushID(static_cast<int>(info.kind));
-            if (!info.compiled)
+            ImGui::PushID(static_cast<int>(info.build_info.kind));
+            const bool enabled = info.build_info.compiled && info.available;
+            if (!enabled)
                 ImGui::BeginDisabled();
             push_preview_active_button_style(selected);
-            if (ImGui::Button(backend_display_name(info.kind),
+            if (ImGui::Button(backend_display_name(info.build_info.kind),
                               ImVec2(button_width, 0.0f))
-                && info.compiled) {
-                ui.renderer_backend = static_cast<int>(info.kind);
+                && enabled) {
+                ui.renderer_backend = static_cast<int>(info.build_info.kind);
+            }
+            {
+                const std::string test_label = std::string("pref-backend:")
+                                               + backend_cli_name(
+                                                   info.build_info.kind);
+                register_test_engine_item_label(test_label.c_str());
             }
             pop_preview_active_button_style(selected);
-            if (!info.compiled)
+            if (!enabled)
                 ImGui::EndDisabled();
             register_layout_dump_synthetic_item("button",
-                                                backend_display_name(info.kind));
+                                                backend_display_name(info.build_info.kind));
             const ImVec2 item_min = ImGui::GetItemRectMin();
             const ImVec2 item_max = ImGui::GetItemRectMax();
             if (!have_backend_row_rect) {
@@ -324,8 +331,14 @@ draw_preferences_window(PlaceholderUiState& ui, bool& show_window,
         const bool requested_backend_compiled
             = requested_backend == BackendKind::Auto
               || backend_kind_is_compiled(requested_backend);
+        const bool requested_backend_available
+            = requested_backend == BackendKind::Auto
+              || backend_kind_is_available(requested_backend);
         const bool invalid_requested_backend = requested_backend != BackendKind::Auto
                                               && !requested_backend_compiled;
+        const bool unavailable_requested_backend
+            = requested_backend != BackendKind::Auto
+              && requested_backend_compiled && !requested_backend_available;
         if (requested_backend == BackendKind::Auto)
             ImGui::TextUnformatted("Stored preference: Auto");
         else
@@ -336,6 +349,7 @@ draw_preferences_window(PlaceholderUiState& ui, bool& show_window,
             ImGui::BeginDisabled();
         if (ImGui::SmallButton("Reset to Auto"))
             ui.renderer_backend = static_cast<int>(BackendKind::Auto);
+        register_test_engine_item_label("pref-backend:auto");
         register_layout_dump_synthetic_item("button", "Reset to Auto");
         if (requested_backend == BackendKind::Auto)
             ImGui::EndDisabled();
@@ -348,12 +362,35 @@ draw_preferences_window(PlaceholderUiState& ui, bool& show_window,
         if (invalid_requested_backend) {
             ImGui::TextUnformatted(
                 "Requested backend is not built in this binary and will be ignored when Preferences closes.");
+        } else if (unavailable_requested_backend) {
+            const std::string_view unavailable_reason = backend_unavailable_reason(
+                requested_backend);
+            if (unavailable_reason.empty()) {
+                ImGui::TextUnformatted(
+                    "Requested backend is unavailable at runtime and will be ignored when Preferences closes.");
+            } else {
+                ImGui::TextWrapped(
+                    "Requested backend is unavailable at runtime (%s) and will be ignored when Preferences closes.",
+                    std::string(unavailable_reason).c_str());
+            }
         } else if (next_launch_backend != active_backend) {
             ImGui::TextUnformatted("Backend change requires restart.");
         }
         if (requested_backend == BackendKind::Auto) {
             ImGui::TextUnformatted("Auto selects the first available backend.");
         }
+        for (const BackendRuntimeInfo& info : runtime_backend_info()) {
+            if (!info.build_info.compiled || info.available)
+                continue;
+            if (info.unavailable_reason.empty()) {
+                ImGui::Text("%s unavailable",
+                            info.build_info.display_name);
+            } else {
+                ImGui::TextWrapped("%s unavailable: %s",
+                                   info.build_info.display_name,
+                                   info.unavailable_reason.c_str());
+            }
+        }
 
         ImGui::Spacing();
         ImGui::TextUnformatted("Image Cache max memory (requires restart)");
@@ -449,7 +486,8 @@ draw_preferences_window(PlaceholderUiState& ui, bool& show_window,
     ImGui::PopStyleVar();
     const BackendKind close_backend = sanitize_backend_kind(ui.renderer_backend);
     if (!show_window && close_backend != BackendKind::Auto
-        && !backend_kind_is_compiled(close_backend)) {
+        && (!backend_kind_is_compiled(close_backend)
+            || !backend_kind_is_available(close_backend))) {
         ui.renderer_backend = static_cast<int>(BackendKind::Auto);
     }
 }