ernie-renderer 0.2.0.dev82__tar.gz → 0.2.0.dev117__tar.gz

{ernie_renderer-0.2.0.dev82 → ernie_renderer-0.2.0.dev117}/.github/workflows/ci.yml

@@ -77,6 +77,14 @@ jobs:
         with:
           python-version: "3.12"
       - run: python -m pip install nanobind ninja
+      # The viewer's window: GLFW builds against X11's and Wayland's headers, and opens them at
+      # run time.
+      - name: Install window system headers
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libx11-dev libxrandr-dev libxinerama-dev libxcursor-dev \
+            libxi-dev libwayland-dev libxkbcommon-dev
       # MSVC on the path for the Ninja generator.
       - uses: ilammy/msvc-dev-cmd@0b201ec74fa43914dc39ae48a89fd1d8cb592756 # v1.13.0
         if: runner.os == 'Windows'
@@ -357,7 +365,8 @@ jobs:
           CMakeLists.txt
       - name: Build tools
         run: |
-          dnf install -y -q rpm-build
+          dnf install -y -q rpm-build libX11-devel libXrandr-devel libXinerama-devel \
+            libXcursor-devel libXi-devel wayland-devel libxkbcommon-devel
           command -v ninja >/dev/null || pipx install -q ninja
       # One build; each format installs the library where its distributions look for it, as the
       # build image (RHEL's lib64) is not where Debian and Ubuntu look. The program relinks for

{ernie_renderer-0.2.0.dev82 → ernie_renderer-0.2.0.dev117}/CMakeLists.txt

@@ -15,7 +15,7 @@ project(
 )
 
 # Pre-release suffix such as .dev12, written by CI.
-set(ERNIE_VERSION_SUFFIX ".dev82" CACHE STRING "Pre-release suffix of Ernie's version")
+set(ERNIE_VERSION_SUFFIX ".dev117" CACHE STRING "Pre-release suffix of Ernie's version")
 set(ERNIE_VERSION "${PROJECT_VERSION}${ERNIE_VERSION_SUFFIX}")
 
 option(ERNIE_BUILD_TESTS "Build Ernie's tests" OFF)

{ernie_renderer-0.2.0.dev82 → ernie_renderer-0.2.0.dev117}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ernie-renderer
-Version: 0.2.0.dev82
+Version: 0.2.0.dev117
 Summary: Efficient Renderer for Natural and Interplanetary Environments: a physically based, spectral Vulkan ray tracer
 Author: Alex Maietta
 License-Expression: BSD-3-Clause

{ernie_renderer-0.2.0.dev82 → ernie_renderer-0.2.0.dev117}/benchmarks/CMakeLists.txt

@@ -1,5 +1,12 @@
 # SPDX-License-Identifier: BSD-3-Clause
-add_executable(ernie_benchmarks main.cpp device/pose_step.cpp scene/extents.cpp scene/storage.cpp)
+add_executable(
+    ernie_benchmarks
+    main.cpp
+    device/pose_step.cpp
+    render/transform_graph.cpp
+    scene/extents.cpp
+    scene/storage.cpp
+)
 target_link_libraries(
     ernie_benchmarks
     PRIVATE ernie_static ernie_volk ernie_vma ernie_build_options

ernie_renderer-0.2.0.dev117/benchmarks/render/transform_graph.cpp

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: BSD-3-Clause
+/// @file transform_graph.cpp
+/// @brief The transform graph at 10,000 environments of a body each: every body's transform
+/// authored on the host, and the whole world removed in one update.
+#include "ernie/render/transform_graph.h"
+#include "benchmarks/bench.h"
+#include "ernie/scene/xform.h"
+
+#include <cstdio>
+#include <memory>
+#include <string>
+
+namespace ernie::bench {
+namespace {
+
+constexpr int kEnvironments = 10'000;
+
+/// A world of environments, each a body, and its transform graph.
+struct World {
+    std::unique_ptr<DeviceContext> context;
+    std::unique_ptr<ShaderCompiler> compiler;
+    std::unique_ptr<Arenas> arenas;
+    std::unique_ptr<Scene> scene;
+    std::unique_ptr<TransformGraph> graph;
+
+    /// @return Whether there is a device to run on.
+    bool Open() {
+        try {
+            context = std::make_unique<DeviceContext>();
+        } catch (const DeviceError& error) {
+            std::printf("skipped: %s\n", error.what());
+            return false;
+        }
+        compiler = std::make_unique<ShaderCompiler>();
+        arenas = std::make_unique<Arenas>(*context, MemoryUse::Device, "transforms", 1 << 22);
+        return true;
+    }
+
+    void Build() {
+        graph.reset();
+        scene = std::make_unique<Scene>();
+        scene->Define("/World", "Xform");
+        for (int i = 0; i < kEnvironments; ++i) {
+            const std::string env = "/World/Env_" + std::to_string(i);
+            scene->Define(env, "Xform");
+            SetXform(*scene, env, {.translate = glm::dvec3(i, 0, 0)});
+            scene->Define(env + "/Body", "Xform");
+            SetXform(*scene, env + "/Body", {.translate = glm::dvec3(0), .scale = glm::dvec3(1)});
+        }
+        graph = std::make_unique<TransformGraph>(*context, *arenas, *scene, *compiler);
+        graph->Update().Wait();
+    }
+};
+
+const bool kHostEdits = Register("render.transform_graph.edit_10k_bodies", [] {
+    World world;
+    if (!world.Open()) {
+        return Timing{0.0, 5.0};
+    }
+    world.Build();
+    double height = 0.0;
+    const auto edit = [&] {
+        height += 1.0;
+        for (int i = 0; i < kEnvironments; ++i) {
+            world.scene->Set(*world.scene->Find("/World/Env_" + std::to_string(i) + "/Body"),
+                             "xformOp:translate", glm::dvec3(0, 0, height));
+        }
+    };
+    return Timing{Fastest(edit, [&] { world.graph->Update().Wait(); }), 5.0};
+});
+
+const bool kRemoveWorld = Register("render.transform_graph.remove_20k_prims", [] {
+    World world;
+    if (!world.Open()) {
+        return Timing{0.0, 10.0};
+    }
+    const auto remove = [&] {
+        world.scene->Remove("/World");
+        world.graph->Update().Wait();
+    };
+    return Timing{Fastest([&] { world.Build(); }, remove, 3), 10.0};
+});
+
+}  // namespace
+}  // namespace ernie::bench

ernie_renderer-0.2.0.dev117/cmake/third_party/dear_imgui.cmake

@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: BSD-3-Clause
+set(ERNIE_DEP_VERSION_dear_imgui
+    v1.92.9b-docking
+    CACHE STRING
+    "Tag of Dear ImGui to fetch: a docking-branch tag, for dockable panels"
+)
+mark_as_advanced(ERNIE_DEP_VERSION_dear_imgui)
+
+# Dear ImGui (MIT) has no CMake project; its sources are compiled here.
+ernie_fetch(
+    dear_imgui
+    URL https://github.com/ocornut/imgui/archive/refs/tags/${ERNIE_DEP_VERSION_dear_imgui}.tar.gz
+)
+add_library(
+    ernie_imgui
+    STATIC
+    "${dear_imgui_SOURCE_DIR}/imgui.cpp"
+    "${dear_imgui_SOURCE_DIR}/imgui_demo.cpp"
+    "${dear_imgui_SOURCE_DIR}/imgui_draw.cpp"
+    "${dear_imgui_SOURCE_DIR}/imgui_tables.cpp"
+    "${dear_imgui_SOURCE_DIR}/imgui_widgets.cpp"
+    # Vulkan functions come from volk, as in the device layer.
+    "${dear_imgui_SOURCE_DIR}/backends/imgui_impl_vulkan.cpp"
+)
+target_include_directories(
+    ernie_imgui
+    SYSTEM
+    PUBLIC "${dear_imgui_SOURCE_DIR}" "${dear_imgui_SOURCE_DIR}/backends"
+)
+target_compile_definitions(ernie_imgui PUBLIC IMGUI_IMPL_VULKAN_USE_VOLK)
+target_link_libraries(ernie_imgui PUBLIC ernie_volk)
+ernie_quiet_third_party(ernie_imgui)
+
+if(TARGET ernie_glfw)
+    add_library(ernie_imgui_glfw STATIC "${dear_imgui_SOURCE_DIR}/backends/imgui_impl_glfw.cpp")
+    # No OpenGL header from glfw3.h: the viewer draws with Vulkan.
+    target_compile_definitions(ernie_imgui_glfw PRIVATE GLFW_INCLUDE_NONE)
+    target_link_libraries(ernie_imgui_glfw PUBLIC ernie_imgui ernie_glfw)
+    ernie_quiet_third_party(ernie_imgui_glfw)
+endif()

ernie_renderer-0.2.0.dev117/cmake/third_party/glfw.cmake

@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: BSD-3-Clause
+set(ERNIE_DEP_VERSION_glfw 3.4 CACHE STRING "Tag of GLFW to fetch")
+mark_as_advanced(ERNIE_DEP_VERSION_glfw)
+option(
+    ERNIE_USE_SYSTEM_GLFW
+    "Use an installed GLFW 3.4 instead of building one in, which loads its window systems at run time"
+    OFF
+)
+
+# The viewer's window. `ernie_glfw` is defined only when a window system can be built for; without
+# one the viewer still draws offscreen.
+if(ERNIE_USE_SYSTEM_GLFW)
+    find_package(glfw3 3.4 REQUIRED)
+    add_library(ernie_glfw INTERFACE)
+    target_link_libraries(ernie_glfw INTERFACE glfw)
+    return()
+endif()
+
+if(CMAKE_SYSTEM_NAME STREQUAL "Linux")
+    # GLFW opens X11 and Wayland at run time, but needs their headers to build.
+    find_package(X11 QUIET)
+    find_package(PkgConfig QUIET)
+    if(PkgConfig_FOUND)
+        pkg_check_modules(ernie_wayland QUIET wayland-client wayland-cursor wayland-egl xkbcommon)
+    endif()
+    find_program(ernie_wayland_scanner wayland-scanner)
+    set(ernie_x11 OFF)
+    if(
+        X11_FOUND
+        AND X11_Xrandr_INCLUDE_PATH
+        AND X11_Xinerama_INCLUDE_PATH
+        AND X11_Xkb_INCLUDE_PATH
+        AND X11_Xcursor_INCLUDE_PATH
+        AND X11_Xi_INCLUDE_PATH
+    )
+        set(ernie_x11 ON)
+    endif()
+    set(ernie_wayland OFF)
+    if(ernie_wayland_FOUND AND ernie_wayland_scanner)
+        set(ernie_wayland ON)
+    endif()
+    if(NOT ernie_x11 AND NOT ernie_wayland)
+        message(
+            STATUS
+            "No X11 or Wayland development headers: the viewer is built without a window"
+        )
+        return()
+    endif()
+    set(GLFW_BUILD_X11 ${ernie_x11} CACHE BOOL "" FORCE)
+    set(GLFW_BUILD_WAYLAND ${ernie_wayland} CACHE BOOL "" FORCE)
+endif()
+
+set(GLFW_BUILD_DOCS OFF CACHE BOOL "" FORCE)
+set(GLFW_BUILD_TESTS OFF CACHE BOOL "" FORCE)
+set(GLFW_BUILD_EXAMPLES OFF CACHE BOOL "" FORCE)
+set(GLFW_INSTALL OFF CACHE BOOL "" FORCE)
+set(ernie_saved_shared_libs ${BUILD_SHARED_LIBS})
+set(BUILD_SHARED_LIBS OFF)
+ernie_fetch(
+    glfw
+    URL https://github.com/glfw/glfw/archive/refs/tags/${ERNIE_DEP_VERSION_glfw}.tar.gz
+)
+set(BUILD_SHARED_LIBS ${ernie_saved_shared_libs})
+ernie_quiet_third_party(glfw)
+
+add_library(ernie_glfw INTERFACE)
+target_link_libraries(ernie_glfw INTERFACE glfw)

ernie_renderer-0.2.0.dev117/ernie/app/CMakeLists.txt

@@ -0,0 +1,32 @@
+# SPDX-License-Identifier: BSD-3-Clause
+include("${PROJECT_SOURCE_DIR}/cmake/third_party/glfw.cmake")
+include("${PROJECT_SOURCE_DIR}/cmake/third_party/dear_imgui.cmake")
+
+# The viewer: its window, panels and frame loop, a library so tests drive it without a window.
+add_library(ernie_viewer STATIC imgui_backend.cpp ui.cpp viewer.cpp)
+target_link_libraries(
+    ernie_viewer
+    PUBLIC ernie_static ernie_imgui ernie_volk ernie_vma
+    PRIVATE ernie_build_options
+)
+if(TARGET ernie_glfw)
+    target_link_libraries(ernie_viewer PRIVATE ernie_imgui_glfw)
+    target_compile_definitions(ernie_viewer PUBLIC ERNIE_VIEWER_WINDOW=1)
+endif()
+
+add_executable(ernie_app main.cpp)
+set_target_properties(ernie_app PROPERTIES OUTPUT_NAME ernie)
+target_link_libraries(ernie_app PRIVATE ernie_viewer ernie_build_options)
+install(TARGETS ernie_app RUNTIME DESTINATION "${CMAKE_INSTALL_BINDIR}" COMPONENT app)
+
+# The licences of what the program carries.
+set(ernie_app_notices "dear_imgui|${dear_imgui_SOURCE_DIR}/LICENSE.txt")
+if(glfw_SOURCE_DIR)
+    list(APPEND ernie_app_notices "glfw|${glfw_SOURCE_DIR}/LICENSE.md")
+endif()
+foreach(notice ${ernie_app_notices})
+    string(REPLACE "|" ";" parts "${notice}")
+    list(GET parts 0 name)
+    list(GET parts 1 file)
+    install(FILES "${file}" DESTINATION "${CMAKE_INSTALL_DOCDIR}/third_party/${name}" COMPONENT app)
+endforeach()

ernie_renderer-0.2.0.dev117/ernie/app/imgui_backend.cpp

@@ -0,0 +1,141 @@
+// SPDX-License-Identifier: BSD-3-Clause
+/// @file imgui_backend.cpp
+/// @brief Creating the ImGui context, setting up its Vulkan backend and recording its draws.
+#include "ernie/app/imgui_backend.h"
+
+#include "ernie/util/profiler.h"
+
+#include <imgui.h>
+#include <imgui_impl_vulkan.h>
+
+namespace ernie::app {
+namespace {
+
+void Transition(VkCommandBuffer commands, VkImage image, VkImageLayout from, VkImageLayout to,
+                VkPipelineStageFlags2 srcStage, VkAccessFlags2 srcAccess,
+                VkPipelineStageFlags2 dstStage, VkAccessFlags2 dstAccess) {
+    const VkImageMemoryBarrier2 barrier{
+        .sType = VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER_2,
+        .srcStageMask = srcStage,
+        .srcAccessMask = srcAccess,
+        .dstStageMask = dstStage,
+        .dstAccessMask = dstAccess,
+        .oldLayout = from,
+        .newLayout = to,
+        .srcQueueFamilyIndex = VK_QUEUE_FAMILY_IGNORED,
+        .dstQueueFamilyIndex = VK_QUEUE_FAMILY_IGNORED,
+        .image = image,
+        .subresourceRange = {VK_IMAGE_ASPECT_COLOR_BIT, 0, 1, 0, 1}};
+    const VkDependencyInfo dependency{.sType = VK_STRUCTURE_TYPE_DEPENDENCY_INFO,
+                                      .imageMemoryBarrierCount = 1,
+                                      .pImageMemoryBarriers = &barrier};
+    vkCmdPipelineBarrier2(commands, &dependency);
+}
+
+}  // namespace
+
+ImGuiSession::ImGuiSession(const Theme& theme) {
+    ERNIE_ZONE("Set up ImGui");
+    IMGUI_CHECKVERSION();
+    context_ = ImGui::CreateContext();
+    ImGuiIO& io = ImGui::GetIO();
+    // Layouts are the viewer's to save; nothing is written behind its back.
+    io.IniFilename = nullptr;
+    io.LogFilename = nullptr;
+    io.ConfigFlags |= ImGuiConfigFlags_DockingEnable | ImGuiConfigFlags_NavEnableKeyboard;
+    io.Fonts->AddFontDefaultVector();
+    ApplyTheme(theme);
+}
+
+ImGuiSession::~ImGuiSession() {
+    ImGui::DestroyContext(context_);
+}
+
+ImGuiRenderer::ImGuiRenderer(DeviceContext& context, VkFormat format, std::uint32_t imageCount)
+    : context_(context) {
+    ERNIE_ZONE("Set up ImGui's Vulkan backend");
+    ImGui_ImplVulkan_InitInfo info{};
+    info.ApiVersion = VK_API_VERSION_1_3;
+    info.Instance = context.Instance();
+    info.PhysicalDevice = context.Physical();
+    info.Device = context.Device();
+    info.QueueFamily = context.Main().Family();
+    // Used only by texture uploads, which borrow the queue (`UpdateTextures`).
+    info.Queue = context.Main().Handle();
+    info.DescriptorPoolSize = 64;
+    info.MinImageCount = imageCount;
+    info.ImageCount = imageCount;
+    info.UseDynamicRendering = true;
+    info.PipelineInfoMain.MSAASamples = VK_SAMPLE_COUNT_1_BIT;
+    info.PipelineInfoMain.PipelineRenderingCreateInfo = {
+        .sType = VK_STRUCTURE_TYPE_PIPELINE_RENDERING_CREATE_INFO,
+        .colorAttachmentCount = 1,
+        .pColorAttachmentFormats = &format};
+    info.PipelineCache = context.PipelineCache();
+    info.CheckVkResultFn = [](VkResult result) { CheckVk(result, "ImGui's Vulkan backend"); };
+    if (!ImGui_ImplVulkan_Init(&info)) {
+        throw DeviceError(DeviceErrorKind::Failed, "Could not set up ImGui's Vulkan backend");
+    }
+}
+
+ImGuiRenderer::~ImGuiRenderer() {
+    Quietly([this] { context_.Main().Last().Wait(); });
+    ImGui_ImplVulkan_Shutdown();
+}
+
+void ImGuiRenderer::NewFrame() {
+    ImGui_ImplVulkan_NewFrame();
+}
+
+ImTextureID ImGuiRenderer::AddTexture(VkImageView view, VkSampler sampler) {
+    return reinterpret_cast<ImTextureID>(
+        ImGui_ImplVulkan_AddTexture(sampler, view, VK_IMAGE_LAYOUT_GENERAL));
+}
+
+void ImGuiRenderer::RemoveTexture(ImTextureID texture) {
+    ImGui_ImplVulkan_RemoveTexture(reinterpret_cast<VkDescriptorSet>(texture));
+}
+
+void ImGuiRenderer::UpdateTextures(ImDrawData& data) {
+    if (data.Textures == nullptr) {
+        return;
+    }
+    for (ImTextureData* texture : *data.Textures) {
+        if (texture->Status != ImTextureStatus_OK) {
+            // The font atlas, on the first frame and when it grows; the backend submits the
+            // upload and waits for it itself.
+            ERNIE_ZONE("Upload a UI texture");
+            context_.Main().Borrow([&](VkQueue) { ImGui_ImplVulkan_UpdateTexture(texture); });
+        }
+    }
+}
+
+void ImGuiRenderer::Record(VkCommandBuffer commands, ImDrawData& data, const FrameTarget& target,
+                           const glm::vec4& clear) {
+    // Whatever the image held is replaced; earlier work on it, a previous frame's, finishes first.
+    Transition(commands, target.image, VK_IMAGE_LAYOUT_UNDEFINED,
+               VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT,
+               VK_ACCESS_2_MEMORY_WRITE_BIT, VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT,
+               VK_ACCESS_2_COLOR_ATTACHMENT_WRITE_BIT | VK_ACCESS_2_COLOR_ATTACHMENT_READ_BIT);
+    const VkRenderingAttachmentInfo attachment{
+        .sType = VK_STRUCTURE_TYPE_RENDERING_ATTACHMENT_INFO,
+        .imageView = target.view,
+        .imageLayout = VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL,
+        .loadOp = VK_ATTACHMENT_LOAD_OP_CLEAR,
+        .storeOp = VK_ATTACHMENT_STORE_OP_STORE,
+        .clearValue = {.color = {.float32 = {clear.r, clear.g, clear.b, clear.a}}}};
+    const VkRenderingInfo rendering{.sType = VK_STRUCTURE_TYPE_RENDERING_INFO,
+                                    .renderArea = {{0, 0}, {target.extent.x, target.extent.y}},
+                                    .layerCount = 1,
+                                    .colorAttachmentCount = 1,
+                                    .pColorAttachments = &attachment};
+    vkCmdBeginRendering(commands, &rendering);
+    ImGui_ImplVulkan_RenderDrawData(&data, commands);
+    vkCmdEndRendering(commands);
+    Transition(commands, target.image, VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL, target.finalLayout,
+               VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT,
+               VK_ACCESS_2_COLOR_ATTACHMENT_WRITE_BIT, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT,
+               kAnyAccess);
+}
+
+}  // namespace ernie::app

ernie_renderer-0.2.0.dev117/ernie/app/imgui_backend.h

@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: BSD-3-Clause
+/// @file imgui_backend.h
+/// @brief Dear ImGui's plumbing: its context as the viewer sets it up, and its Vulkan backend.
+#pragma once
+
+#include "ernie/app/ui.h"
+#include "ernie/device/context.h"
+
+#include <glm/vec4.hpp>
+
+struct ImDrawData;
+struct ImGuiContext;
+
+namespace ernie::app {
+
+struct Theme;
+
+/// @brief Makes and destroys an ImGui context with docking and keyboard navigation, the theme
+/// applied and no settings file, current while it lives. One at a time.
+class ImGuiSession {
+  public:
+    explicit ImGuiSession(const Theme& theme);
+    ~ImGuiSession();
+    ImGuiSession(const ImGuiSession&) = delete;
+    ImGuiSession& operator=(const ImGuiSession&) = delete;
+
+  private:
+    ImGuiContext* context_;
+};
+
+/// @brief ImGui's Vulkan backend on a device context's main queue, drawing into images of one
+/// format with dynamic rendering. Needs a current ImGui context for its whole life.
+class ImGuiRenderer {
+  public:
+    ImGuiRenderer(DeviceContext& context, VkFormat format, std::uint32_t imageCount);
+    ~ImGuiRenderer();
+    ImGuiRenderer(const ImGuiRenderer&) = delete;
+    ImGuiRenderer& operator=(const ImGuiRenderer&) = delete;
+
+    /// @brief Starts the backend's part of a UI frame.
+    void NewFrame();
+    /// @brief Uploads the textures ImGui asks for, such as its font atlas. The backend submits and
+    /// waits for these copies itself, so this runs before recording the frame.
+    void UpdateTextures(ImDrawData& data);
+    /// @brief Records clearing the target to `clear`, drawing the UI over it, and leaving it in
+    /// its final layout.
+    void Record(VkCommandBuffer commands, ImDrawData& data, const FrameTarget& target,
+                const glm::vec4& clear);
+    /// @return A texture the UI draws an image with in place, sampled in the general layout.
+    ImTextureID AddTexture(VkImageView view, VkSampler sampler);
+    /// @brief Forgets a texture `AddTexture` made, once no frame in flight draws with it.
+    void RemoveTexture(ImTextureID texture);
+
+  private:
+    DeviceContext& context_;
+};
+
+}  // namespace ernie::app

{ernie_renderer-0.2.0.dev82 → ernie_renderer-0.2.0.dev117}/ernie/app/main.cpp

@@ -1,14 +1,18 @@
 // SPDX-License-Identifier: BSD-3-Clause
 /// @file main.cpp
-/// @brief The ernie program.
+/// @brief The ernie program: the viewer, and the schema and scene tools.
+#include "ernie/app/viewer.h"
 #include "ernie/device/device.h"
 #include "ernie/scene/reference.h"
 #include "ernie/util/file.h"
 #include "ernie/util/version.h"
 
+#include <algorithm>
 #include <cstdio>
 #include <exception>
 #include <filesystem>
+#include <stdexcept>
+#include <string>
 #include <string_view>
 #include <vector>
 
@@ -17,9 +21,11 @@ namespace {
 namespace fs = std::filesystem;
 
 void PrintUsage() {
-    std::puts("Usage: ernie [--version] [--devices] [--help]\n"
-              "       ernie schema [--json-schema FILE] [--markdown DIR] [--usda DIR]\n"
-              "       ernie validate SCENE.json...");
+    std::printf("Usage: %.*s\n"
+                "       ernie --version | --devices | --help\n"
+                "       ernie schema [--json-schema FILE] [--markdown DIR] [--usda DIR]\n"
+                "       ernie validate SCENE.json...\n",
+                static_cast<int>(ernie::app::ViewUsage().size()), ernie::app::ViewUsage().data());
 }
 
 int PrintDevices() {
@@ -31,13 +37,6 @@ int PrintDevices() {
     return 0;
 }
 
-void Write(const fs::path& path, std::string_view text) {
-    if (path.has_parent_path()) {
-        fs::create_directories(path.parent_path());
-    }
-    ernie::WriteTextFile(path, text);
-}
-
 /// Writes the views of the schema registry that `arguments` ask for.
 int Schema(const std::vector<std::string_view>& arguments) {
     if (arguments.empty() || arguments.size() % 2 != 0) {
@@ -47,15 +46,16 @@ int Schema(const std::vector<std::string_view>& arguments) {
     for (std::size_t i = 0; i < arguments.size(); i += 2) {
         const fs::path out(arguments[i + 1]);
         if (arguments[i] == "--json-schema") {
-            Write(out, ernie::SceneJsonSchema());
+            ernie::WriteTextFile(out, ernie::SceneJsonSchema());
         } else if (arguments[i] == "--markdown") {
             for (const ernie::SchemaFamily& family : ernie::SchemaFamilies()) {
-                Write(out / (std::string(family.name) + ".md"), ernie::ReferencePage(family));
+                ernie::WriteTextFile(out / (std::string(family.name) + ".md"),
+                                     ernie::ReferencePage(family));
             }
         } else if (arguments[i] == "--usda") {
             const ernie::UsdSchemaPlugin plugin = ernie::ErnieUsdSchemaPlugin();
-            Write(out / "generatedSchema.usda", plugin.generatedSchema);
-            Write(out / "plugInfo.json", plugin.plugInfo);
+            ernie::WriteTextFile(out / "generatedSchema.usda", plugin.generatedSchema);
+            ernie::WriteTextFile(out / "plugInfo.json", plugin.plugInfo);
         } else {
             PrintUsage();
             return 2;
@@ -82,28 +82,46 @@ int Validate(const std::vector<std::string_view>& files) {
     return status;
 }
 
+/// Opens the viewer; only `ernie`, `ernie view` and a scene file or viewer options get here.
+int View(const std::vector<std::string_view>& arguments) {
+    ernie::app::ViewCommand command;
+    try {
+        command = ernie::app::ParseViewCommand(arguments);
+    } catch (const std::invalid_argument& error) {
+        std::fprintf(stderr, "ernie: %s\n", error.what());
+        PrintUsage();
+        return 2;
+    }
+    return ernie::app::RunView(command);
+}
+
 }  // namespace
 
 int main(int argc, char** argv) {
-    const std::string_view option = argc > 1 ? argv[1] : "--help";
-    const std::vector<std::string_view> rest(argv + std::min(argc, 2), argv + argc);
+    const std::vector<std::string_view> arguments(argv + std::min(argc, 1), argv + argc);
+    const std::string_view command = arguments.empty() ? "" : arguments.front();
+    const std::vector<std::string_view> rest(arguments.begin() + (arguments.empty() ? 0 : 1),
+                                             arguments.end());
     try {
-        if (option == "--version") {
+        if (command == "--version") {
             std::printf("ernie %.*s\n", static_cast<int>(ernie::Version().size()),
                         ernie::Version().data());
             return 0;
         }
-        if (option == "--devices") {
+        if (command == "--help") {
+            PrintUsage();
+            return 0;
+        }
+        if (command == "--devices") {
             return PrintDevices();
         }
-        if (option == "schema") {
+        if (command == "schema") {
             return Schema(rest);
         }
-        if (option == "validate") {
+        if (command == "validate") {
             return Validate(rest);
         }
-        PrintUsage();
-        return option == "--help" ? 0 : 2;
+        return View(command == "view" ? rest : arguments);
     } catch (const std::exception& error) {
         std::fprintf(stderr, "ernie: %s\n", error.what());
         return 1;