Export equirectangular JPEGs through paint renderer

2026-06-05 21:22:06 +02:00
parent 875a0127d9
commit bd416f8473
11 changed files with 604 additions and 96 deletions
--- a/docs/modernization/build-inventory.md
+++ b/docs/modernization/build-inventory.md
@@ -296,12 +296,14 @@ powershell -ExecutionPolicy Bypass -File scripts\automation\apple-remote-build.p
  document/paint-renderer equirectangular PNG before falling back to the
  retained writer. Payload-complete layer and animation-frame PNG collections
  write pure document/paint-renderer equirectangular PNG sequences through the
-  app-core collection write/publish executor before retained fallback; JPEG/XMP
-  equirectangular export, Web handoff, incomplete-readback collection cases,
-  and video export remain on retained writer paths. Depth export now plans the
-  retained image/depth output paths in `pp_app_core` and logs a tested
-  `pp_paint_renderer` depth render plan plus the shared document-frame
-  renderer-readiness report before retained `Canvas::export_depth` execution.
+  app-core collection write/publish executor before retained fallback. JPEG
+  equirectangular export writes a pure document/paint-renderer JPEG with GPano
+  XMP metadata before retained fallback; Web handoff, incomplete-readback
+  collection cases, and video export remain on retained writer paths. Depth
+  export now plans the retained image/depth output paths in `pp_app_core` and
+  logs a tested `pp_paint_renderer` depth render plan plus the shared
+  document-frame renderer-readiness report before retained
+  `Canvas::export_depth` execution.
 - `pano_cli save-document-project` writes that pure document export to a PPI
  file and is covered by `pano_cli_save_document_project_roundtrip_smoke`,
  which inspects and loads the generated file.
@@ -1149,8 +1151,10 @@ powershell -ExecutionPolicy Bypass -File scripts\automation\apple-remote-build.p
  animation-frame collections write pure document/paint-renderer PNG sequences
  through the app-core collection write/publish executor, depth export plans
  image/depth targets and logs the paint-renderer render plan plus shared
-  renderer readiness before retained execution, and JPEG/XMP plus
-  Web/incomplete-readback collection cases remain on older retained paths. It
+  renderer readiness before retained execution, and JPEG equirectangular export
+  writes a pure document/paint-renderer JPEG with GPano XMP metadata before
+  retained fallback while Web/incomplete-readback collection cases remain on
+  older retained paths. It
  also bridges timelapse and animation MP4 export picker-selected paths while
  preserving desktop worker-thread timelapse behavior, mobile/Web save
  callbacks, `App::rec_export`, animation `Canvas::export_anim_mp4`, and
--- a/docs/modernization/capability-map.md
+++ b/docs/modernization/capability-map.md
@@ -24,8 +24,8 @@ and validation command.
 | Capability | Current Area | Target Owner | Required Tests |
 | --- | --- | --- | --- |
 | PNG/JPEG import | `Image`, `Canvas` import paths | `pp_assets`, `pp_document` | Fixture import, malformed file |
-| PNG/JPEG export | `Canvas`, `Image`, export dialogs | `pp_assets`, `pp_paint_renderer`, `pp_app_core` | Golden output tolerance, export start/target planning tests, live export-adapter document snapshot readiness through the shared paint-renderer export report, pure cube-face PNG writer, pure equirectangular PNG writer, pure layer/frame collection PNG writers, app-core collection write executor, JPEG/XMP parity still retained |
-| Equirectangular import/export | `Canvas`, shaders, RTT, export dialogs | `pp_paint_renderer`, `pp_app_core` | Tiny cube/equirect golden, app-core file target tests, live export-adapter renderer-upload/face-PNG readiness report, pure document-frame equirectangular PNG export and live PNG writer fallback, pure layer/frame equirectangular PNG collection export, JPEG/XMP retained until metadata parity is owned |
+| PNG/JPEG export | `Canvas`, `Image`, export dialogs | `pp_assets`, `pp_paint_renderer`, `pp_app_core` | Golden output tolerance, export start/target planning tests, live export-adapter document snapshot readiness through the shared paint-renderer export report, pure cube-face PNG writer, pure equirectangular PNG/JPEG+XMP writers, pure layer/frame collection PNG writers, app-core collection write executor, retained fallback coverage |
+| Equirectangular import/export | `Canvas`, shaders, RTT, export dialogs | `pp_paint_renderer`, `pp_app_core` | Tiny cube/equirect golden, app-core file target tests, live export-adapter renderer-upload/face-PNG readiness report, pure document-frame equirectangular PNG and JPEG+XMP export with live writer fallback, pure layer/frame equirectangular PNG collection export, exact GPU/golden parity |
 | Cube face export | `Canvas` fallback | `pp_paint_renderer`, `pp_app_core` | Pure six-face document frame composite, renderer texture-upload bridge, shared export-readiness report, app-core face filename planning and write/publish service execution, payload-complete canvas-snapshot renderer-upload and face-PNG automation, live document/renderer face-PNG writer with retained Canvas fallback, OpenGL command-plan coverage, six-face golden set |
 | Depth export | `Canvas`, grid tools | `pp_paint_renderer`, `pp_app_core` | Depth target/write planning, document-snapshot renderer-readiness logging, depth render-plan draw/readback counts, retained render/readback parity, and format/golden validation |

--- a/docs/modernization/debt.md
+++ b/docs/modernization/debt.md
--- a/docs/modernization/roadmap.md
+++ b/docs/modernization/roadmap.md
@@ -699,9 +699,11 @@ PNG equirectangular export now uses the same document/composite payload to
 generate an equirectangular PNG through `pp_paint_renderer` before the retained
 fallback. Payload-complete layer and animation-frame PNG collections now use
 pure `pp_paint_renderer` equirectangular PNG generation plus app-core
-collection write/publish execution before retained fallback. JPEG/XMP
-equirectangular export, Web handoff, video, and incomplete-readback collection
-cases still delegate to retained `Canvas` writers after readiness reporting.
+collection write/publish execution before retained fallback. Payload-complete
+desktop JPEG equirectangular export now uses the same projection through
+`pp_paint_renderer`, `pp_assets` JPEG encoding, and GPano XMP injection before
+retained fallback. Web handoff, video, and incomplete-readback collection cases
+still delegate to retained `Canvas` writers after readiness reporting.
 Depth export now also plans the retained image/depth file targets in
 `pp_app_core` and logs a `pp_paint_renderer` document depth render plan for the
 legacy 1024x1024 perspective render plus per-layer depth pass before falling
@@ -2557,9 +2559,11 @@ Results:
  collection write/publish executor before retained fallback. Depth export now
  prepares the same document/canvas snapshot, logs the shared renderer-upload
  readiness report, and records a tested paint-renderer depth render plan before
-  retained `Canvas` execution. JPEG/XMP, Web prepared-file handoff, video, and
-  incomplete-readback collection cases remain on their prior retained writer
-  paths. Actual broader writer replacement remains tracked under export debt.
+  retained `Canvas` execution. JPEG equirectangular export now writes a
+  pure `pp_paint_renderer`/`pp_assets` JPEG with GPano XMP metadata before
+  retained fallback. Web prepared-file handoff, video, and incomplete-readback
+  collection cases remain on their prior retained writer paths. Actual broader
+  writer replacement remains tracked under export debt.
 - Snapshot creation now rejects invalid embedded RGBA8 face payloads before
  document export or history can persist malformed state.
 - Package-smoke wrappers validate the Windows CMake app executable/runtime
--- a/src/assets/image_pixels.cpp
+++ b/src/assets/image_pixels.cpp
@@ -48,6 +48,37 @@ void append_png_bytes(void* context, void* data, int size)
    bytes->insert(bytes->end(), begin, begin + size);
 }

+void append_encoded_bytes(void* context, void* data, int size)
+{
+    append_png_bytes(context, data, size);
+}
+
+[[nodiscard]] bool has_jpeg_soi(std::span<const std::byte> bytes) noexcept
+{
+    return bytes.size() >= 2U
+        && bytes[0] == std::byte { 0xff }
+        && bytes[1] == std::byte { 0xd8 };
+}
+
+constexpr char gpano_xmp[] =
+    "http://ns.adobe.com/xap/1.0/\0"
+    R"(<?xpacket begin="" id="W5M0MpCehiHzreSzNTczkc9d"?>
+  <x:xmpmeta xmlns:x="adobe:ns:meta/" xmptk="SAMSUNG 360CAM">
+    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
+      <rdf:Description rdf:about="" xmlns:GPano="http://ns.google.com/photos/1.0/panorama/">
+        <GPano:ProjectionType>equirectangular</GPano:ProjectionType>
+        <GPano:UsePanoramaViewer>True</GPano:UsePanoramaViewer>
+        <GPano:CroppedAreaLeftPixels>0</GPano:CroppedAreaLeftPixels>
+        <GPano:CroppedAreaTopPixels>0</GPano:CroppedAreaTopPixels>
+        <GPano:PoseHeadingDegrees>0</GPano:PoseHeadingDegrees>
+        <GPano:PosePitchDegrees>0</GPano:PosePitchDegrees>
+        <GPano:PoseRollDegrees>0</GPano:PoseRollDegrees>
+        <GPano:StitchingSoftware>PanoPainter</GPano:StitchingSoftware>
+      </rdf:Description>
+    </rdf:RDF>
+  </x:xmpmeta>
+<?xpacket end="r"?>)";
+
 }

 pp::foundation::Result<Rgba8Image> decode_png_rgba8(std::span<const std::byte> bytes)
@@ -106,6 +137,64 @@ pp::foundation::Result<Rgba8Image> decode_png_rgba8(std::span<const std::byte> b
    return pp::foundation::Result<Rgba8Image>::success(std::move(image));
 }

+pp::foundation::Result<Rgba8Image> decode_jpeg_rgba8(std::span<const std::byte> bytes)
+{
+    if (!has_jpeg_soi(bytes)) {
+        return pp::foundation::Result<Rgba8Image>::failure(
+            pp::foundation::Status::invalid_argument("JPEG signature is invalid"));
+    }
+
+    if (bytes.size() > static_cast<std::size_t>(std::numeric_limits<int>::max())) {
+        return pp::foundation::Result<Rgba8Image>::failure(
+            pp::foundation::Status::out_of_range("JPEG payload is too large for the decoder"));
+    }
+
+    int width = 0;
+    int height = 0;
+    int source_components = 0;
+    auto* decoded = stbi_load_from_memory(
+        reinterpret_cast<const stbi_uc*>(bytes.data()),
+        static_cast<int>(bytes.size()),
+        &width,
+        &height,
+        &source_components,
+        4);
+    if (decoded == nullptr) {
+        return pp::foundation::Result<Rgba8Image>::failure(
+            pp::foundation::Status::invalid_argument("JPEG payload could not be decoded"));
+    }
+
+    const auto cleanup = [decoded]() noexcept {
+        stbi_image_free(decoded);
+    };
+
+    if (width <= 0 || height <= 0
+        || static_cast<std::uint32_t>(width) > max_image_dimension
+        || static_cast<std::uint32_t>(height) > max_image_dimension) {
+        cleanup();
+        return pp::foundation::Result<Rgba8Image>::failure(
+            pp::foundation::Status::out_of_range("decoded JPEG dimensions are outside the configured range"));
+    }
+
+    const auto byte_count = rgba_byte_size(
+        static_cast<std::uint32_t>(width),
+        static_cast<std::uint32_t>(height));
+    if (!byte_count) {
+        cleanup();
+        return pp::foundation::Result<Rgba8Image>::failure(byte_count.status());
+    }
+
+    Rgba8Image image {
+        .width = static_cast<std::uint32_t>(width),
+        .height = static_cast<std::uint32_t>(height),
+        .pixels = {},
+    };
+    image.pixels.assign(decoded, decoded + byte_count.value());
+    cleanup();
+
+    return pp::foundation::Result<Rgba8Image>::success(std::move(image));
+}
+
 pp::foundation::Result<std::vector<std::byte>> encode_png_rgba8(
    std::uint32_t width,
    std::uint32_t height,
@@ -156,4 +245,79 @@ pp::foundation::Result<std::vector<std::byte>> encode_png_rgba8(
    return pp::foundation::Result<std::vector<std::byte>>::success(std::move(encoded));
 }

+pp::foundation::Result<std::vector<std::byte>> encode_jpeg_rgba8(
+    std::uint32_t width,
+    std::uint32_t height,
+    std::span<const std::uint8_t> pixels,
+    int quality)
+{
+    if (width == 0 || height == 0) {
+        return pp::foundation::Result<std::vector<std::byte>>::failure(
+            pp::foundation::Status::invalid_argument("JPEG dimensions must be greater than zero"));
+    }
+
+    if (width > static_cast<std::uint32_t>(std::numeric_limits<int>::max())
+        || height > static_cast<std::uint32_t>(std::numeric_limits<int>::max())) {
+        return pp::foundation::Result<std::vector<std::byte>>::failure(
+            pp::foundation::Status::out_of_range("JPEG dimensions exceed encoder limits"));
+    }
+
+    if (quality < 1 || quality > 100) {
+        return pp::foundation::Result<std::vector<std::byte>>::failure(
+            pp::foundation::Status::out_of_range("JPEG quality must be within 1..100"));
+    }
+
+    const auto byte_count = rgba_byte_size(width, height);
+    if (!byte_count) {
+        return pp::foundation::Result<std::vector<std::byte>>::failure(byte_count.status());
+    }
+
+    if (pixels.size() != byte_count.value()) {
+        return pp::foundation::Result<std::vector<std::byte>>::failure(
+            pp::foundation::Status::invalid_argument("RGBA pixel payload size does not match dimensions"));
+    }
+
+    std::vector<std::byte> encoded;
+    const auto result = stbi_write_jpg_to_func(
+        append_encoded_bytes,
+        &encoded,
+        static_cast<int>(width),
+        static_cast<int>(height),
+        4,
+        pixels.data(),
+        quality);
+
+    if (result == 0 || encoded.empty()) {
+        return pp::foundation::Result<std::vector<std::byte>>::failure(
+            pp::foundation::Status::invalid_argument("RGBA pixels could not be encoded as JPEG"));
+    }
+
+    return pp::foundation::Result<std::vector<std::byte>>::success(std::move(encoded));
+}
+
+pp::foundation::Result<std::vector<std::byte>> inject_gpano_xmp_into_jpeg(std::span<const std::byte> jpeg)
+{
+    if (!has_jpeg_soi(jpeg)) {
+        return pp::foundation::Result<std::vector<std::byte>>::failure(
+            pp::foundation::Status::invalid_argument("JPEG signature is invalid"));
+    }
+
+    constexpr auto xmp_size = sizeof(gpano_xmp);
+    static_assert(xmp_size + 2U <= 0xffffU);
+    const auto segment_length = static_cast<std::uint16_t>(xmp_size + 2U);
+
+    std::vector<std::byte> encoded;
+    encoded.reserve(jpeg.size() + xmp_size + 4U);
+    encoded.insert(encoded.end(), jpeg.begin(), jpeg.begin() + 2);
+    encoded.push_back(std::byte { 0xff });
+    encoded.push_back(std::byte { 0xe1 });
+    encoded.push_back(static_cast<std::byte>((segment_length >> 8U) & 0xffU));
+    encoded.push_back(static_cast<std::byte>(segment_length & 0xffU));
+    const auto* xmp_begin = reinterpret_cast<const std::byte*>(gpano_xmp);
+    encoded.insert(encoded.end(), xmp_begin, xmp_begin + xmp_size);
+    encoded.insert(encoded.end(), jpeg.begin() + 2, jpeg.end());
+
+    return pp::foundation::Result<std::vector<std::byte>>::success(std::move(encoded));
+}
+
 }
--- a/src/assets/image_pixels.h
+++ b/src/assets/image_pixels.h
@@ -18,9 +18,21 @@ struct Rgba8Image {
 [[nodiscard]] pp::foundation::Result<Rgba8Image> decode_png_rgba8(
    std::span<const std::byte> bytes);

+[[nodiscard]] pp::foundation::Result<Rgba8Image> decode_jpeg_rgba8(
+    std::span<const std::byte> bytes);
+
 [[nodiscard]] pp::foundation::Result<std::vector<std::byte>> encode_png_rgba8(
    std::uint32_t width,
    std::uint32_t height,
    std::span<const std::uint8_t> pixels);

+[[nodiscard]] pp::foundation::Result<std::vector<std::byte>> encode_jpeg_rgba8(
+    std::uint32_t width,
+    std::uint32_t height,
+    std::span<const std::uint8_t> pixels,
+    int quality);
+
+[[nodiscard]] pp::foundation::Result<std::vector<std::byte>> inject_gpano_xmp_into_jpeg(
+    std::span<const std::byte> jpeg);
+
 }
--- a/src/legacy_document_export_services.cpp
+++ b/src/legacy_document_export_services.cpp
@@ -38,6 +38,40 @@ bool is_png_export_target(std::string_view path) noexcept
        && (extension[3] == 'g' || extension[3] == 'G');
 }

+bool ascii_iequals(std::string_view left, std::string_view right) noexcept
+{
+    if (left.size() != right.size()) {
+        return false;
+    }
+
+    for (std::size_t i = 0; i < left.size(); ++i) {
+        auto lhs = left[i];
+        if (lhs >= 'A' && lhs <= 'Z') {
+            lhs = static_cast<char>(lhs - 'A' + 'a');
+        }
+        auto rhs = right[i];
+        if (rhs >= 'A' && rhs <= 'Z') {
+            rhs = static_cast<char>(rhs - 'A' + 'a');
+        }
+        if (lhs != rhs) {
+            return false;
+        }
+    }
+
+    return true;
+}
+
+bool has_extension(std::string_view path, std::string_view extension) noexcept
+{
+    return path.size() >= extension.size()
+        && ascii_iequals(path.substr(path.size() - extension.size()), extension);
+}
+
+bool is_jpeg_export_target(std::string_view path) noexcept
+{
+    return has_extension(path, ".jpg") || has_extension(path, ".jpeg");
+}
+
 struct LegacyDocumentExportSnapshotReports {
    pp::app::DocumentCanvasSnapshotResult snapshot;
    pp::paint_renderer::DocumentFrameFacePngExportResult face_pngs;
@@ -270,32 +304,52 @@ pp::foundation::Status export_animation_frames_from_document_snapshot(
    return pp::app::execute_document_export_collection_write(target, payloads, services);
 }

-pp::foundation::Status export_equirectangular_png_from_document_snapshot(
+pp::foundation::Status export_equirectangular_from_document_snapshot(
    App& app,
    const pp::app::DocumentExportFileTarget& target,
    const LegacyDocumentExportSnapshotReports& reports)
 {
-    if (!is_png_export_target(target.path)) {
+    std::span<const std::byte> bytes;
+    pp::paint_renderer::DocumentFrameEquirectangularPngExportResult png_export;
+    pp::paint_renderer::DocumentFrameEquirectangularJpegExportResult jpeg_export;
+
+    if (is_png_export_target(target.path)) {
+        auto exported = pp::paint_renderer::export_document_frame_equirectangular_png(reports.face_pngs.composite);
+        if (!exported) {
+            return exported.status();
+        }
+
+        png_export = std::move(exported.value());
+        LOG(
+            "export-equirectangular document export PNG writer: %ux%u bytes=%llu facePayloads=%zu compositedLayerFaces=%zu",
+            png_export.equirectangular_extent.width,
+            png_export.equirectangular_extent.height,
+            static_cast<unsigned long long>(png_export.encoded_bytes),
+            png_export.face_payload_count,
+            png_export.composited_layer_face_count);
+        bytes = std::span<const std::byte>(png_export.png.data(), png_export.png.size());
+    } else if (is_jpeg_export_target(target.path)) {
+        auto exported = pp::paint_renderer::export_document_frame_equirectangular_jpeg(reports.face_pngs.composite);
+        if (!exported) {
+            return exported.status();
+        }
+
+        jpeg_export = std::move(exported.value());
+        LOG(
+            "export-equirectangular document export JPEG writer: %ux%u bytes=%llu facePayloads=%zu compositedLayerFaces=%zu xmp=%s",
+            jpeg_export.equirectangular_extent.width,
+            jpeg_export.equirectangular_extent.height,
+            static_cast<unsigned long long>(jpeg_export.encoded_bytes),
+            jpeg_export.face_payload_count,
+            jpeg_export.composited_layer_face_count,
+            jpeg_export.xmp_injected ? "true" : "false");
+        bytes = std::span<const std::byte>(jpeg_export.jpeg.data(), jpeg_export.jpeg.size());
+    } else {
        return pp::foundation::Status::invalid_argument(
-            "document snapshot equirectangular export currently supports PNG targets only");
+            "document snapshot equirectangular export currently supports PNG and JPEG targets only");
    }

-    auto exported = pp::paint_renderer::export_document_frame_equirectangular_png(reports.face_pngs.composite);
-    if (!exported) {
-        return exported.status();
-    }
-
-    auto exported_value = std::move(exported.value());
-    LOG(
-        "export-equirectangular document export PNG writer: %ux%u bytes=%llu facePayloads=%zu compositedLayerFaces=%zu",
-        exported_value.equirectangular_extent.width,
-        exported_value.equirectangular_extent.height,
-        static_cast<unsigned long long>(exported_value.encoded_bytes),
-        exported_value.face_payload_count,
-        exported_value.composited_layer_face_count);
-    const auto write_status = write_export_binary_file(
-        target.path,
-        std::span<const std::byte>(exported_value.png.data(), exported_value.png.size()));
+    const auto write_status = write_export_binary_file(target.path, bytes);
    if (!write_status.ok()) {
        return write_status;
    }
@@ -320,10 +374,10 @@ public:
    {
        auto* app = &app_;
 #if !__WEB__
-        if (is_png_export_target(target.path)) {
+        if (is_png_export_target(target.path) || is_jpeg_export_target(target.path)) {
            const auto prepared = prepare_legacy_document_export_snapshot(app_, "export-equirectangular");
            if (prepared) {
-                const auto exported = export_equirectangular_png_from_document_snapshot(app_, target, prepared.value());
+                const auto exported = export_equirectangular_from_document_snapshot(app_, target, prepared.value());
                if (exported.ok()) {
                    show_export_success_dialog(
                        app_,
--- a/src/paint_renderer/compositor.cpp
+++ b/src/paint_renderer/compositor.cpp
@@ -271,6 +271,75 @@ void append_rgba8_bytes(std::vector<std::uint8_t>& bytes, std::span<const pp::pa
    }
 }

+struct EquirectangularProjectionResult {
+    pp::renderer::Extent2D face_extent {};
+    pp::renderer::Extent2D equirectangular_extent {};
+    std::vector<pp::paint::Rgba> pixels;
+    std::size_t face_payload_count = 0;
+    std::size_t composited_layer_face_count = 0;
+};
+
+pp::foundation::Result<EquirectangularProjectionResult> project_document_frame_equirectangular(
+    const DocumentFrameCompositeResult& composite)
+{
+    const auto face_pixel_count = expected_pixel_count(composite.extent);
+    if (!face_pixel_count) {
+        return pp::foundation::Result<EquirectangularProjectionResult>::failure(face_pixel_count.status());
+    }
+
+    for (const auto& face : composite.faces) {
+        if (face.extent.width != composite.extent.width || face.extent.height != composite.extent.height
+            || face.pixels.size() != face_pixel_count.value()) {
+            return pp::foundation::Result<EquirectangularProjectionResult>::failure(
+                pp::foundation::Status::invalid_argument("document equirectangular export requires complete cube faces"));
+        }
+    }
+
+    const auto output_width = static_cast<std::uint64_t>(composite.extent.width) * 4U;
+    const auto output_height = static_cast<std::uint64_t>(composite.extent.height) * 2U;
+    if (output_width > std::numeric_limits<std::uint32_t>::max()
+        || output_height > std::numeric_limits<std::uint32_t>::max()) {
+        return pp::foundation::Result<EquirectangularProjectionResult>::failure(
+            pp::foundation::Status::out_of_range("document equirectangular extent exceeds uint32"));
+    }
+
+    EquirectangularProjectionResult result;
+    result.face_extent = composite.extent;
+    result.equirectangular_extent = pp::renderer::Extent2D {
+        .width = static_cast<std::uint32_t>(output_width),
+        .height = static_cast<std::uint32_t>(output_height),
+    };
+    result.face_payload_count = composite.face_payload_count;
+    result.composited_layer_face_count = composite.composited_layer_face_count;
+
+    const auto output_pixel_count = expected_pixel_count(result.equirectangular_extent);
+    if (!output_pixel_count) {
+        return pp::foundation::Result<EquirectangularProjectionResult>::failure(output_pixel_count.status());
+    }
+
+    constexpr auto pi = 3.14159265358979323846F;
+    constexpr auto two_pi = 6.28318530717958647692F;
+    result.pixels.assign(output_pixel_count.value(), pp::paint::Rgba {});
+    for (std::uint32_t y = 0; y < result.equirectangular_extent.height; ++y) {
+        const auto v = (static_cast<float>(y) + 0.5F) / static_cast<float>(result.equirectangular_extent.height);
+        const auto angle_y = (1.0F - v) * pi;
+        const auto sin_y = std::sin(angle_y);
+        const auto cos_y = std::cos(angle_y);
+        for (std::uint32_t x = 0; x < result.equirectangular_extent.width; ++x) {
+            const auto u = (static_cast<float>(x) + 0.5F) / static_cast<float>(result.equirectangular_extent.width);
+            const auto angle_x = (1.25F - u) * two_pi;
+            const auto sample = panopainter_cube_face_sample(
+                sin_y * std::cos(angle_x),
+                cos_y,
+                sin_y * std::sin(angle_x));
+            result.pixels[static_cast<std::size_t>(y) * result.equirectangular_extent.width + x] =
+                sample_face_nearest(composite.faces[sample.face_index], sample.s, sample.t);
+        }
+    }
+
+    return pp::foundation::Result<EquirectangularProjectionResult>::success(std::move(result));
+}
+
 }

 pp::foundation::Status composite_layer(
@@ -602,63 +671,19 @@ pp::foundation::Result<DocumentFrameFacePngExportResult> export_document_frame_f
 pp::foundation::Result<DocumentFrameEquirectangularPngExportResult>
 export_document_frame_equirectangular_png(const DocumentFrameCompositeResult& composite)
 {
-    const auto face_pixel_count = expected_pixel_count(composite.extent);
-    if (!face_pixel_count) {
-        return pp::foundation::Result<DocumentFrameEquirectangularPngExportResult>::failure(face_pixel_count.status());
-    }
-
-    for (const auto& face : composite.faces) {
-        if (face.extent.width != composite.extent.width || face.extent.height != composite.extent.height
-            || face.pixels.size() != face_pixel_count.value()) {
-            return pp::foundation::Result<DocumentFrameEquirectangularPngExportResult>::failure(
-                pp::foundation::Status::invalid_argument("document equirectangular export requires complete cube faces"));
-        }
-    }
-
-    const auto output_width = static_cast<std::uint64_t>(composite.extent.width) * 4U;
-    const auto output_height = static_cast<std::uint64_t>(composite.extent.height) * 2U;
-    if (output_width > std::numeric_limits<std::uint32_t>::max()
-        || output_height > std::numeric_limits<std::uint32_t>::max()) {
-        return pp::foundation::Result<DocumentFrameEquirectangularPngExportResult>::failure(
-            pp::foundation::Status::out_of_range("document equirectangular extent exceeds uint32"));
+    auto projection = project_document_frame_equirectangular(composite);
+    if (!projection) {
+        return pp::foundation::Result<DocumentFrameEquirectangularPngExportResult>::failure(projection.status());
    }

    DocumentFrameEquirectangularPngExportResult result;
-    result.face_extent = composite.extent;
-    result.equirectangular_extent = pp::renderer::Extent2D {
-        .width = static_cast<std::uint32_t>(output_width),
-        .height = static_cast<std::uint32_t>(output_height),
-    };
-    result.face_payload_count = composite.face_payload_count;
-    result.composited_layer_face_count = composite.composited_layer_face_count;
-
-    const auto output_pixel_count = expected_pixel_count(result.equirectangular_extent);
-    if (!output_pixel_count) {
-        return pp::foundation::Result<DocumentFrameEquirectangularPngExportResult>::failure(output_pixel_count.status());
-    }
-
-    constexpr auto pi = 3.14159265358979323846F;
-    constexpr auto two_pi = 6.28318530717958647692F;
-    std::vector<pp::paint::Rgba> output(output_pixel_count.value());
-    for (std::uint32_t y = 0; y < result.equirectangular_extent.height; ++y) {
-        const auto v = (static_cast<float>(y) + 0.5F) / static_cast<float>(result.equirectangular_extent.height);
-        const auto angle_y = (1.0F - v) * pi;
-        const auto sin_y = std::sin(angle_y);
-        const auto cos_y = std::cos(angle_y);
-        for (std::uint32_t x = 0; x < result.equirectangular_extent.width; ++x) {
-            const auto u = (static_cast<float>(x) + 0.5F) / static_cast<float>(result.equirectangular_extent.width);
-            const auto angle_x = (1.25F - u) * two_pi;
-            const auto sample = panopainter_cube_face_sample(
-                sin_y * std::cos(angle_x),
-                cos_y,
-                sin_y * std::sin(angle_x));
-            output[static_cast<std::size_t>(y) * result.equirectangular_extent.width + x] =
-                sample_face_nearest(composite.faces[sample.face_index], sample.s, sample.t);
-        }
-    }
+    result.face_extent = projection.value().face_extent;
+    result.equirectangular_extent = projection.value().equirectangular_extent;
+    result.face_payload_count = projection.value().face_payload_count;
+    result.composited_layer_face_count = projection.value().composited_layer_face_count;

    std::vector<std::uint8_t> rgba8;
-    append_rgba8_bytes(rgba8, output);
+    append_rgba8_bytes(rgba8, projection.value().pixels);
    auto encoded = pp::assets::encode_png_rgba8(
        result.equirectangular_extent.width,
        result.equirectangular_extent.height,
@@ -683,6 +708,53 @@ export_document_frame_equirectangular_png(DocumentFrameCompositeRequest request)
    return export_document_frame_equirectangular_png(composite.value());
 }

+pp::foundation::Result<DocumentFrameEquirectangularJpegExportResult>
+export_document_frame_equirectangular_jpeg(const DocumentFrameCompositeResult& composite, int quality)
+{
+    auto projection = project_document_frame_equirectangular(composite);
+    if (!projection) {
+        return pp::foundation::Result<DocumentFrameEquirectangularJpegExportResult>::failure(projection.status());
+    }
+
+    DocumentFrameEquirectangularJpegExportResult result;
+    result.face_extent = projection.value().face_extent;
+    result.equirectangular_extent = projection.value().equirectangular_extent;
+    result.face_payload_count = projection.value().face_payload_count;
+    result.composited_layer_face_count = projection.value().composited_layer_face_count;
+
+    std::vector<std::uint8_t> rgba8;
+    append_rgba8_bytes(rgba8, projection.value().pixels);
+    auto encoded = pp::assets::encode_jpeg_rgba8(
+        result.equirectangular_extent.width,
+        result.equirectangular_extent.height,
+        rgba8,
+        quality);
+    if (!encoded) {
+        return pp::foundation::Result<DocumentFrameEquirectangularJpegExportResult>::failure(encoded.status());
+    }
+
+    auto with_xmp = pp::assets::inject_gpano_xmp_into_jpeg(encoded.value());
+    if (!with_xmp) {
+        return pp::foundation::Result<DocumentFrameEquirectangularJpegExportResult>::failure(with_xmp.status());
+    }
+
+    result.encoded_bytes = static_cast<std::uint64_t>(with_xmp.value().size());
+    result.jpeg = std::move(with_xmp.value());
+    result.xmp_injected = true;
+    return pp::foundation::Result<DocumentFrameEquirectangularJpegExportResult>::success(std::move(result));
+}
+
+pp::foundation::Result<DocumentFrameEquirectangularJpegExportResult>
+export_document_frame_equirectangular_jpeg(DocumentFrameCompositeRequest request, int quality)
+{
+    auto composite = composite_document_frame(request);
+    if (!composite) {
+        return pp::foundation::Result<DocumentFrameEquirectangularJpegExportResult>::failure(composite.status());
+    }
+
+    return export_document_frame_equirectangular_jpeg(composite.value(), quality);
+}
+
 pp::foundation::Result<DocumentDepthExportRenderPlan> plan_document_depth_export_render(
    DocumentDepthExportRenderPlanRequest request) noexcept
 {
--- a/src/paint_renderer/compositor.h
+++ b/src/paint_renderer/compositor.h
@@ -156,6 +156,16 @@ struct DocumentFrameEquirectangularPngExportResult {
    std::size_t composited_layer_face_count = 0;
 };

+struct DocumentFrameEquirectangularJpegExportResult {
+    pp::renderer::Extent2D face_extent {};
+    pp::renderer::Extent2D equirectangular_extent {};
+    std::vector<std::byte> jpeg;
+    std::uint64_t encoded_bytes = 0;
+    std::size_t face_payload_count = 0;
+    std::size_t composited_layer_face_count = 0;
+    bool xmp_injected = false;
+};
+
 struct DocumentDepthExportRenderPlanRequest {
    const pp::document::CanvasDocument* document = nullptr;
    std::size_t frame_index = 0;
@@ -255,6 +265,16 @@ export_document_frame_equirectangular_png(const DocumentFrameCompositeResult& co
 [[nodiscard]] pp::foundation::Result<DocumentFrameEquirectangularPngExportResult>
 export_document_frame_equirectangular_png(DocumentFrameCompositeRequest request);

+[[nodiscard]] pp::foundation::Result<DocumentFrameEquirectangularJpegExportResult>
+export_document_frame_equirectangular_jpeg(
+    const DocumentFrameCompositeResult& composite,
+    int quality = 100);
+
+[[nodiscard]] pp::foundation::Result<DocumentFrameEquirectangularJpegExportResult>
+export_document_frame_equirectangular_jpeg(
+    DocumentFrameCompositeRequest request,
+    int quality = 100);
+
 [[nodiscard]] pp::foundation::Result<DocumentDepthExportRenderPlan> plan_document_depth_export_render(
    DocumentDepthExportRenderPlanRequest request) noexcept;

--- a/tests/assets/image_pixels_tests.cpp
+++ b/tests/assets/image_pixels_tests.cpp
@@ -5,10 +5,14 @@
 #include <cstddef>
 #include <cstdint>
 #include <span>
+#include <string_view>
 #include <vector>

 using pp::assets::decode_png_rgba8;
+using pp::assets::decode_jpeg_rgba8;
+using pp::assets::encode_jpeg_rgba8;
 using pp::assets::encode_png_rgba8;
+using pp::assets::inject_gpano_xmp_into_jpeg;
 using pp::foundation::StatusCode;

 namespace {
@@ -75,6 +79,66 @@ void encodes_rgba8_pixels_to_decodable_png(pp::tests::Harness& h)
    PP_EXPECT(h, decoded.value().pixels == pixels);
 }

+void encodes_rgba8_pixels_to_decodable_jpeg(pp::tests::Harness& h)
+{
+    const std::vector<std::uint8_t> pixels {
+        255, 0, 0, 255,
+        0, 255, 0, 255,
+        0, 0, 255, 255,
+        255, 255, 255, 255,
+    };
+
+    const auto encoded = encode_jpeg_rgba8(2, 2, pixels, 95);
+
+    PP_EXPECT(h, encoded.ok());
+    PP_EXPECT(h, encoded.value().size() > 4U);
+    PP_EXPECT(h, encoded.value()[0] == std::byte { 0xff });
+    PP_EXPECT(h, encoded.value()[1] == std::byte { 0xd8 });
+    const auto decoded = decode_jpeg_rgba8(encoded.value());
+    PP_EXPECT(h, decoded.ok());
+    PP_EXPECT(h, decoded.value().width == 2U);
+    PP_EXPECT(h, decoded.value().height == 2U);
+    PP_EXPECT(h, decoded.value().pixels.size() == pixels.size());
+}
+
+void injects_gpano_xmp_into_jpeg(pp::tests::Harness& h)
+{
+    const std::vector<std::uint8_t> pixels {
+        10, 20, 30, 255,
+        40, 50, 60, 255,
+    };
+    const auto encoded = encode_jpeg_rgba8(2, 1, pixels, 90);
+    PP_EXPECT(h, encoded);
+    if (!encoded) {
+        return;
+    }
+
+    const auto with_xmp = inject_gpano_xmp_into_jpeg(encoded.value());
+    PP_EXPECT(h, with_xmp);
+    if (!with_xmp) {
+        return;
+    }
+
+    PP_EXPECT(h, with_xmp.value().size() > encoded.value().size());
+    PP_EXPECT(h, with_xmp.value()[0] == std::byte { 0xff });
+    PP_EXPECT(h, with_xmp.value()[1] == std::byte { 0xd8 });
+    PP_EXPECT(h, with_xmp.value()[2] == std::byte { 0xff });
+    PP_EXPECT(h, with_xmp.value()[3] == std::byte { 0xe1 });
+
+    const std::string_view text(
+        reinterpret_cast<const char*>(with_xmp.value().data()),
+        with_xmp.value().size());
+    PP_EXPECT(h, text.find("GPano:ProjectionType") != std::string_view::npos);
+    PP_EXPECT(h, text.find("equirectangular") != std::string_view::npos);
+
+    const auto decoded = decode_jpeg_rgba8(with_xmp.value());
+    PP_EXPECT(h, decoded);
+    if (decoded) {
+        PP_EXPECT(h, decoded.value().width == 2U);
+        PP_EXPECT(h, decoded.value().height == 1U);
+    }
+}
+
 void rejects_invalid_png_encode_inputs(pp::tests::Harness& h)
 {
    const std::vector<std::uint8_t> pixels { 0, 0, 0, 0 };
@@ -88,6 +152,29 @@ void rejects_invalid_png_encode_inputs(pp::tests::Harness& h)
    PP_EXPECT(h, wrong_payload_size.status().code == StatusCode::invalid_argument);
 }

+void rejects_invalid_jpeg_inputs(pp::tests::Harness& h)
+{
+    const std::vector<std::uint8_t> pixels { 0, 0, 0, 255 };
+    const std::byte corrupt[] { std::byte { 0x00 }, std::byte { 0x01 } };
+
+    const auto no_size = encode_jpeg_rgba8(0, 1, pixels, 90);
+    const auto bad_quality = encode_jpeg_rgba8(1, 1, pixels, 0);
+    const auto wrong_payload_size = encode_jpeg_rgba8(2, 1, pixels, 90);
+    const auto corrupt_decode = decode_jpeg_rgba8(corrupt);
+    const auto corrupt_xmp = inject_gpano_xmp_into_jpeg(corrupt);
+
+    PP_EXPECT(h, !no_size.ok());
+    PP_EXPECT(h, no_size.status().code == StatusCode::invalid_argument);
+    PP_EXPECT(h, !bad_quality.ok());
+    PP_EXPECT(h, bad_quality.status().code == StatusCode::out_of_range);
+    PP_EXPECT(h, !wrong_payload_size.ok());
+    PP_EXPECT(h, wrong_payload_size.status().code == StatusCode::invalid_argument);
+    PP_EXPECT(h, !corrupt_decode.ok());
+    PP_EXPECT(h, corrupt_decode.status().code == StatusCode::invalid_argument);
+    PP_EXPECT(h, !corrupt_xmp.ok());
+    PP_EXPECT(h, corrupt_xmp.status().code == StatusCode::invalid_argument);
+}
+
 }

 int main()
@@ -96,6 +183,9 @@ int main()
    harness.run("decodes_png_to_rgba8_pixels", decodes_png_to_rgba8_pixels);
    harness.run("rejects_corrupt_png_payload", rejects_corrupt_png_payload);
    harness.run("encodes_rgba8_pixels_to_decodable_png", encodes_rgba8_pixels_to_decodable_png);
+    harness.run("encodes_rgba8_pixels_to_decodable_jpeg", encodes_rgba8_pixels_to_decodable_jpeg);
+    harness.run("injects_gpano_xmp_into_jpeg", injects_gpano_xmp_into_jpeg);
    harness.run("rejects_invalid_png_encode_inputs", rejects_invalid_png_encode_inputs);
+    harness.run("rejects_invalid_jpeg_inputs", rejects_invalid_jpeg_inputs);
    return harness.finish();
 }
--- a/tests/paint_renderer/compositor_tests.cpp
+++ b/tests/paint_renderer/compositor_tests.cpp
@@ -903,6 +903,71 @@ void exports_document_frame_as_equirectangular_png(pp::tests::Harness& h)
    PP_EXPECT(h, decoded.value().pixels[bottom + 2U] == 255U);
 }

+void exports_document_frame_as_equirectangular_jpeg_with_xmp(pp::tests::Harness& h)
+{
+    const AnimationFrame root_frames[] {
+        { .duration_ms = 100, .face_pixels = {} },
+    };
+    const AnimationFrame layer_frames[] {
+        {
+            .duration_ms = 100,
+            .face_pixels = solid_cube_faces(1, 4, 25, 125, 225, 255),
+        },
+    };
+    const DocumentLayerConfig layers[] {
+        {
+            .name = "Paint",
+            .frames = std::span<const AnimationFrame>(layer_frames, 1),
+        },
+    };
+    const auto document = CanvasDocument::create_from_snapshot(DocumentSnapshotConfig {
+        .width = 1,
+        .height = 4,
+        .layers = std::span<const DocumentLayerConfig>(layers, 1),
+        .frames = std::span<const AnimationFrame>(root_frames, 1),
+        .selection_masks = {},
+    });
+    PP_EXPECT(h, document);
+    if (!document) {
+        return;
+    }
+
+    const auto exported = pp::paint_renderer::export_document_frame_equirectangular_jpeg(
+        DocumentFrameCompositeRequest {
+            .document = &document.value(),
+            .frame_index = 0,
+        },
+        90);
+
+    PP_EXPECT(h, exported);
+    if (!exported) {
+        return;
+    }
+
+    PP_EXPECT(h, exported.value().face_extent.width == 1U);
+    PP_EXPECT(h, exported.value().face_extent.height == 4U);
+    PP_EXPECT(h, exported.value().equirectangular_extent.width == 4U);
+    PP_EXPECT(h, exported.value().equirectangular_extent.height == 8U);
+    PP_EXPECT(h, exported.value().face_payload_count == pp::document::cube_face_count);
+    PP_EXPECT(h, exported.value().encoded_bytes == exported.value().jpeg.size());
+    PP_EXPECT(h, exported.value().xmp_injected);
+
+    const std::string_view text(
+        reinterpret_cast<const char*>(exported.value().jpeg.data()),
+        exported.value().jpeg.size());
+    PP_EXPECT(h, text.find("GPano:ProjectionType") != std::string_view::npos);
+    PP_EXPECT(h, text.find("equirectangular") != std::string_view::npos);
+
+    const auto decoded = pp::assets::decode_jpeg_rgba8(exported.value().jpeg);
+    PP_EXPECT(h, decoded);
+    if (!decoded) {
+        return;
+    }
+
+    PP_EXPECT(h, decoded.value().width == 4U);
+    PP_EXPECT(h, decoded.value().height == 8U);
+}
+
 void exports_document_layers_as_equirectangular_pngs(pp::tests::Harness& h)
 {
    const AnimationFrame root_frames[] {
@@ -1121,6 +1186,8 @@ void document_frame_upload_rejects_invalid_requests(pp::tests::Harness& h)
        DocumentFrameCompositeRequest {});
    const auto no_document_equirect = pp::paint_renderer::export_document_frame_equirectangular_png(
        DocumentFrameCompositeRequest {});
+    const auto no_document_jpeg = pp::paint_renderer::export_document_frame_equirectangular_jpeg(
+        DocumentFrameCompositeRequest {});
    const auto no_document_layers = pp::paint_renderer::export_document_layers_equirectangular_pngs(
        pp::paint_renderer::DocumentLayerEquirectangularPngExportRequest {});
    const auto no_document_frames = pp::paint_renderer::export_document_animation_frames_equirectangular_pngs(
@@ -1165,6 +1232,12 @@ void document_frame_upload_rejects_invalid_requests(pp::tests::Harness& h)
            .frame_index = 0,
            .output_extent = Extent2D {},
        });
+    const auto bad_jpeg_quality = pp::paint_renderer::export_document_frame_equirectangular_jpeg(
+        DocumentFrameCompositeRequest {
+            .document = &document.value(),
+            .frame_index = 0,
+        },
+        0);

    PP_EXPECT(h, !no_document.ok());
    PP_EXPECT(h, no_document.status().code == StatusCode::invalid_argument);
@@ -1172,6 +1245,8 @@ void document_frame_upload_rejects_invalid_requests(pp::tests::Harness& h)
    PP_EXPECT(h, no_document_readiness.status().code == StatusCode::invalid_argument);
    PP_EXPECT(h, !no_document_equirect.ok());
    PP_EXPECT(h, no_document_equirect.status().code == StatusCode::invalid_argument);
+    PP_EXPECT(h, !no_document_jpeg.ok());
+    PP_EXPECT(h, no_document_jpeg.status().code == StatusCode::invalid_argument);
    PP_EXPECT(h, !no_document_layers.ok());
    PP_EXPECT(h, no_document_layers.status().code == StatusCode::invalid_argument);
    PP_EXPECT(h, !no_document_frames.ok());
@@ -1186,6 +1261,8 @@ void document_frame_upload_rejects_invalid_requests(pp::tests::Harness& h)
    PP_EXPECT(h, bad_frame_depth.status().code == StatusCode::out_of_range);
    PP_EXPECT(h, !bad_extent_depth.ok());
    PP_EXPECT(h, bad_extent_depth.status().code == StatusCode::invalid_argument);
+    PP_EXPECT(h, !bad_jpeg_quality.ok());
+    PP_EXPECT(h, bad_jpeg_quality.status().code == StatusCode::out_of_range);
    PP_EXPECT(h, device.commands().empty());
 }

@@ -1538,6 +1615,9 @@ int main()
    harness.run("exports_document_frame_faces_as_pngs", exports_document_frame_faces_as_pngs);
    harness.run("prepares_document_frame_export_readiness_report", prepares_document_frame_export_readiness_report);
    harness.run("exports_document_frame_as_equirectangular_png", exports_document_frame_as_equirectangular_png);
+    harness.run(
+        "exports_document_frame_as_equirectangular_jpeg_with_xmp",
+        exports_document_frame_as_equirectangular_jpeg_with_xmp);
    harness.run("exports_document_layers_as_equirectangular_pngs", exports_document_layers_as_equirectangular_pngs);
    harness.run(
        "exports_document_animation_frames_as_equirectangular_pngs",