omar/panopainter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Share document export readiness reporting

Browse Source
This commit is contained in:
omigamedev
2026-06-05 20:19:46 +02:00
parent 2d33f9d928
commit ebc84373e6
9 changed files with 181 additions and 87 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
docs/modernization/build-inventory.md
View File

@@ -252,9 +252,10 @@ powershell -ExecutionPolicy Bypass -File scripts\automation\apple-remote-build.p
rectangles into full renderer-sized RGBA buffers with layer visibility,
opacity, and blend mode applied in document order, then uploading those six
faces through the renderer-neutral `IRenderDevice` texture API using the
recording backend. It also covers the shared recorded-upload report helper
consumed by CLI and live export-readiness bridges, plus a pure six-face PNG
export helper that encodes composited document-frame faces through `pp_assets`.
recording backend. It also covers the shared
`prepare_document_frame_export_readiness` report consumed by CLI and live
export-readiness bridges, including the recorded upload command summary and
pure six-face PNG export bytes encoded through `pp_assets`.
- `pano_cli simulate-document-export` exposes the same pure document-to-PPI
export, asset-level decode, and document reimport path through JSON
automation and is covered by `pano_cli_simulate_document_export_smoke`.
@@ -271,17 +272,15 @@ powershell -ExecutionPolicy Bypass -File scripts\automation\apple-remote-build.p
payload-complete or metadata-only snapshots, the same app-core boundary now
exports through the pure `pp_document` PPI writer and reports generated byte
counts plus decoded dirty-face counts in `ppiExport` JSON. Payload-complete
snapshots also feed the active frame through the `pp_paint_renderer`
document-frame compositor and renderer-neutral recorded-upload report helper,
reporting texture, transition, command, byte, and active-frame payload counts
in `rendererUpload` JSON. The same payload-complete path also reports
`facePngExport` readiness, face count, byte count, and payload count from the
pure face-PNG export helper. It is covered by
snapshots also feed the active frame through the shared `pp_paint_renderer`
export-readiness report, reporting texture, transition, command, byte, and
active-frame payload counts in `rendererUpload` JSON plus `facePngExport`
readiness, face count, byte count, and payload count. It is covered by
`pano_cli_plan_canvas_document_snapshot_smoke` plus the payload-bearing
snapshot smoke.
- Live equirectangular, layer, animation-frame, and cube-face export adapters
now prepare and log the same payload-bearing canvas document snapshot plus
shared renderer-neutral active-frame upload and face-PNG export reports.
shared paint-renderer export-readiness report.
Cube-face export writes the pure document/renderer PNG bytes through the
app-core write/publish executor to the planned retained face filename set and
falls back to `Canvas::export_cube_faces` if snapshot capture, PNG generation,
@@ -1125,7 +1124,7 @@ powershell -ExecutionPolicy Bypass -File scripts\automation\apple-remote-build.p
exports, Web prepared-file handoff, and legacy `Canvas` export execution while
retained renderer/document/platform ownership is tracked by `DEBT-0043`.
Equirectangular, layer, animation-frame, and cube-face execution now prepare
the document snapshot plus renderer-upload readiness report before those
the document snapshot plus shared paint-renderer export-readiness report before those
retained calls; cube-face export writes pure face-PNG bytes to the app-core
planned legacy work-directory face paths through the app-core write/publish
executor before falling back to the retained writer, and depth export remains

8
docs/modernization/capability-map.md
View File

@@ -11,7 +11,7 @@ and validation command.
| Capability | Current Area | Target Owner | Required Tests |
| --- | --- | --- | --- |
| PPI open/save | `Canvas`, serializer, dialogs | `pp_document`, `pp_assets`, `pano_cli` | Round-trip tiny project, old-version fixture, corrupt/truncated fixture, live-canvas-to-`pp_document` snapshot projection with captured RGBA8 payloads, pending renderer-readback counts, save-readiness reporting before retained live saves, pure PPI export from payload-complete snapshots, and renderer-neutral active-frame upload from the same snapshot |
| PPI open/save | `Canvas`, serializer, dialogs | `pp_document`, `pp_assets`, `pano_cli` | Round-trip tiny project, old-version fixture, corrupt/truncated fixture, live-canvas-to-`pp_document` snapshot projection with captured RGBA8 payloads, pending renderer-readback counts, save-readiness reporting before retained live saves, pure PPI export from payload-complete snapshots, and shared paint-renderer export-readiness reporting from the same snapshot |
| Open-document routing | `App::open_document` | `pp_app_core`, `pano_cli`, `pp_panopainter_ui`, `pp_document`, `pp_assets` | Project/ABR/PPBR route tests, malformed path tests, open-action plan tests, CLI route/action smoke, app open smoke |
| Document session decisions | `App::open_document`, `App::request_close`, save hotkeys, file menu, dialogs | `pp_app_core`, `pano_cli`, `pp_panopainter_ui` | Clean/dirty/prompt-open/save/save-as/save-version/save-before-workflow/name/new-document resolution/overwrite/version-target decision tests, CLI session, new-document, document-file, and document-version smoke, app close/open/save/new/browse smoke |
| Version metadata | `scripts/pre-build.py`, `version.*` | build system, `pp_foundation` | Generated header smoke test, missing-tag behavior |
@@ -24,9 +24,9 @@ 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 |
| 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 readiness |
| Cube face export | `Canvas` fallback | `pp_paint_renderer`, `pp_app_core` | Pure six-face document frame composite, renderer texture-upload bridge, pure face-PNG export helper, 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 |
| 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 |
| 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 |
| 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` | Float/readback validation |
## Brush And Painting

11
docs/modernization/debt.md
View File

File diff suppressed because one or more lines are too long

32
docs/modernization/roadmap.md
View File

@@ -676,19 +676,17 @@ delegating to retained `Canvas::project_save`; the app-core snapshot boundary
also has a tested pure PPI export helper, and
`pano_cli plan-canvas-document-snapshot` runs that helper for payload-complete
snapshots and reports generated byte/dirty-face summaries. The same automation
now feeds payload-complete snapshots through the `pp_paint_renderer`
document-frame compositor and renderer-neutral recording upload path, reporting
texture, transition, byte, payload, and command counts through the shared
`record_document_frame_upload` report helper. Payload-complete snapshot
automation also encodes the active document frame's six composited faces to PNG
bytes through `pp_paint_renderer::export_document_frame_face_pngs`, giving the
cube-face export path a pure renderer/document writer primitive before live
writer replacement. Live save writer replacement, export adoption, and
renderer-owned readback remain under
now feeds payload-complete snapshots through the shared
`pp_paint_renderer::prepare_document_frame_export_readiness` report, which
records renderer-neutral six-face texture upload commands and encodes the
active document frame's six composited faces to PNG bytes. This gives CLI
automation and live export adapters the same document/canvas-to-renderer
readiness boundary before broader writer replacement. Live save writer
replacement, export adoption, and renderer-owned readback remain under
`DEBT-0010`/`DEBT-0013`/`DEBT-0036`.
Live equirectangular, layer, animation-frame, and cube-face export adapters now
prepare the same payload-bearing document snapshot and renderer-neutral upload
report helper plus pure face-PNG export report. Cube-face export writes those
prepare the same payload-bearing document snapshot and shared renderer export
readiness report. Cube-face export writes those
document/renderer-owned PNG bytes through a tested app-core write/publish
executor using the app-core-planned legacy face filenames when available and
falls back to retained `Canvas::export_cube_faces` on snapshot/write failure;
@@ -2523,13 +2521,11 @@ Results:
`pano_cli plan-canvas-document-snapshot` reports `ppiExport` readiness,
byte count, and dirty-face count for agent automation.
- Payload-complete canvas snapshot automation also crosses the renderer
boundary now: `pano_cli plan-canvas-document-snapshot` records the same
snapshot through the pure document-frame compositor and renderer-neutral
texture upload stream through `pp_paint_renderer::record_document_frame_upload`,
and encodes the composited active-frame cube faces as PNG bytes through
`pp_paint_renderer::export_document_frame_face_pngs`, so agents can validate
document/canvas payloads moving into renderer commands and image bytes before
live canvas export/save writer replacement.
boundary now: `pano_cli plan-canvas-document-snapshot` feeds the same snapshot
through `pp_paint_renderer::prepare_document_frame_export_readiness`, which
records the renderer-neutral active-frame texture upload stream and encodes
the composited active-frame cube faces as PNG bytes, so agents validate the
same document/canvas-to-renderer readiness report consumed by live export.
- Live image/collection/cube export adapters now prepare and log the same
document/canvas plus shared renderer-upload and face-PNG export readiness
reports. Cube-face export now writes the pure document/renderer PNG bytes to

40
src/legacy_document_export_services.cpp
View File

@@ -104,18 +104,20 @@ pp::foundation::Result<LegacyDocumentExportSnapshotReports> prepare_legacy_docum
return pp::foundation::Result<LegacyDocumentExportSnapshotReports>::success(std::move(reports));
}
const auto recorded_upload = pp::paint_renderer::record_document_frame_upload(
pp::paint_renderer::DocumentFrameUploadRequest {
auto readiness = pp::paint_renderer::prepare_document_frame_export_readiness(
pp::paint_renderer::DocumentFrameCompositeRequest {
.document = &reports.snapshot.document,
.frame_index = reports.snapshot.document.active_frame_index(),
.clear_color = {},
});
if (!recorded_upload) {
LOG("%s document export renderer upload failed: %s", context, recorded_upload.status().message);
return pp::foundation::Result<LegacyDocumentExportSnapshotReports>::failure(recorded_upload.status());
if (!readiness) {
LOG("%s document export renderer readiness failed: %s", context, readiness.status().message);
return pp::foundation::Result<LegacyDocumentExportSnapshotReports>::failure(readiness.status());
}
const auto& uploaded = recorded_upload.value().upload;
auto readiness_value = std::move(readiness.value());
const auto& recorded_upload = readiness_value.recorded_upload;
const auto& uploaded = recorded_upload.upload;
LOG(
"%s document export renderer upload: textures=%zu bytes=%llu transitions=%zu facePayloads=%zu commands=%zu uploadCommands=%zu transitionCommands=%zu",
context,
@@ -123,28 +125,18 @@ pp::foundation::Result<LegacyDocumentExportSnapshotReports> prepare_legacy_docum
static_cast<unsigned long long>(uploaded.uploaded_bytes),
uploaded.transition_count,
uploaded.composite.face_payload_count,
recorded_upload.value().command_count,
recorded_upload.value().upload_command_count,
recorded_upload.value().transition_command_count);
const auto face_pngs = pp::paint_renderer::export_document_frame_face_pngs(
pp::paint_renderer::DocumentFrameCompositeRequest {
.document = &reports.snapshot.document,
.frame_index = reports.snapshot.document.active_frame_index(),
.clear_color = {},
});
if (!face_pngs) {
LOG("%s document export face PNG export failed: %s", context, face_pngs.status().message);
return pp::foundation::Result<LegacyDocumentExportSnapshotReports>::failure(face_pngs.status());
}
recorded_upload.command_count,
recorded_upload.upload_command_count,
recorded_upload.transition_command_count);
LOG(
"%s document export face PNG export: faces=%zu bytes=%llu facePayloads=%zu compositedLayerFaces=%zu",
context,
face_pngs.value().face_count,
static_cast<unsigned long long>(face_pngs.value().encoded_bytes),
face_pngs.value().composite.face_payload_count,
face_pngs.value().composite.composited_layer_face_count);
reports.face_pngs = std::move(face_pngs.value());
readiness_value.face_pngs.face_count,
static_cast<unsigned long long>(readiness_value.face_pngs.encoded_bytes),
readiness_value.face_pngs.composite.face_payload_count,
readiness_value.face_pngs.composite.composited_layer_face_count);
reports.face_pngs = std::move(readiness_value.face_pngs);
return pp::foundation::Result<LegacyDocumentExportSnapshotReports>::success(std::move(reports));
}

23
src/paint_renderer/compositor.cpp
View File

@@ -481,6 +481,29 @@ pp::foundation::Result<DocumentFrameFacePngExportResult> export_document_frame_f
return pp::foundation::Result<DocumentFrameFacePngExportResult>::success(std::move(result));
}
pp::foundation::Result<DocumentFrameExportReadinessResult> prepare_document_frame_export_readiness(
DocumentFrameCompositeRequest request)
{
auto recorded_upload = record_document_frame_upload(DocumentFrameUploadRequest {
.document = request.document,
.frame_index = request.frame_index,
.clear_color = request.clear_color,
});
if (!recorded_upload) {
return pp::foundation::Result<DocumentFrameExportReadinessResult>::failure(recorded_upload.status());
}
auto face_pngs = export_document_frame_face_pngs(request);
if (!face_pngs) {
return pp::foundation::Result<DocumentFrameExportReadinessResult>::failure(face_pngs.status());
}
DocumentFrameExportReadinessResult result;
result.recorded_upload = std::move(recorded_upload.value());
result.face_pngs = std::move(face_pngs.value());
return pp::foundation::Result<DocumentFrameExportReadinessResult>::success(std::move(result));
}
bool stroke_composite_requires_feedback(
pp::paint::BlendMode layer_blend_mode,
pp::paint::StrokeBlendMode stroke_blend_mode,

8
src/paint_renderer/compositor.h
View File

@@ -146,6 +146,11 @@ struct DocumentFrameFacePngExportResult {
std::uint64_t encoded_bytes = 0;
};
struct DocumentFrameExportReadinessResult {
RecordedDocumentFrameUploadResult recorded_upload {};
DocumentFrameFacePngExportResult face_pngs {};
};
[[nodiscard]] pp::foundation::Status composite_layer(
std::span<pp::paint::Rgba> destination,
pp::renderer::Extent2D extent,
@@ -167,6 +172,9 @@ struct DocumentFrameFacePngExportResult {
[[nodiscard]] pp::foundation::Result<DocumentFrameFacePngExportResult> export_document_frame_face_pngs(
DocumentFrameCompositeRequest request);
[[nodiscard]] pp::foundation::Result<DocumentFrameExportReadinessResult> prepare_document_frame_export_readiness(
DocumentFrameCompositeRequest request);
[[nodiscard]] bool stroke_composite_requires_feedback(
pp::paint::BlendMode layer_blend_mode,
pp::paint::StrokeBlendMode stroke_blend_mode,

81
tests/paint_renderer/compositor_tests.cpp
View File

@@ -665,12 +665,83 @@ void exports_document_frame_faces_as_pngs(pp::tests::Harness& h)
}
}
void prepares_document_frame_export_readiness_report(pp::tests::Harness& h)
{
const AnimationFrame root_frames[] {
{ .duration_ms = 100, .face_pixels = {} },
};
const AnimationFrame layer_frames[] {
{
.duration_ms = 100,
.face_pixels = {
LayerFacePixels {
.face_index = 2,
.x = 0,
.y = 0,
.width = 1,
.height = 1,
.rgba8 = { 255, 128, 0, 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 = 1,
.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 readiness = pp::paint_renderer::prepare_document_frame_export_readiness(
DocumentFrameCompositeRequest {
.document = &document.value(),
.frame_index = 0,
.clear_color = {},
});
PP_EXPECT(h, readiness);
if (!readiness) {
return;
}
PP_EXPECT(h, readiness.value().recorded_upload.upload.texture_count == pp::document::cube_face_count);
PP_EXPECT(h, readiness.value().recorded_upload.upload.uploaded_bytes == 24U);
PP_EXPECT(h, readiness.value().recorded_upload.command_count == 12U);
PP_EXPECT(h, readiness.value().recorded_upload.upload_command_count == pp::document::cube_face_count);
PP_EXPECT(h, readiness.value().recorded_upload.transition_command_count == pp::document::cube_face_count);
PP_EXPECT(h, readiness.value().face_pngs.face_count == pp::document::cube_face_count);
PP_EXPECT(h, readiness.value().face_pngs.encoded_bytes > 0U);
PP_EXPECT(h, readiness.value().face_pngs.composite.face_payload_count == 1U);
const auto decoded = pp::assets::decode_png_rgba8(readiness.value().face_pngs.face_pngs[2]);
PP_EXPECT(h, decoded);
if (decoded) {
PP_EXPECT(h, decoded.value().pixels[0] == 255U);
PP_EXPECT(h, decoded.value().pixels[1] == 128U);
PP_EXPECT(h, decoded.value().pixels[2] == 0U);
PP_EXPECT(h, decoded.value().pixels[3] == 255U);
}
}
void document_frame_upload_rejects_invalid_requests(pp::tests::Harness& h)
{
RecordingRenderDevice device;
const auto no_document = pp::paint_renderer::upload_document_frame_faces(
device,
pp::paint_renderer::DocumentFrameUploadRequest {});
const auto no_document_readiness = pp::paint_renderer::prepare_document_frame_export_readiness(
DocumentFrameCompositeRequest {});
const AnimationFrame root_frames[] {
{ .duration_ms = 100, .face_pixels = {} },
@@ -693,11 +764,20 @@ void document_frame_upload_rejects_invalid_requests(pp::tests::Harness& h)
.document = &document.value(),
.frame_index = 1,
});
const auto bad_frame_readiness = pp::paint_renderer::prepare_document_frame_export_readiness(
DocumentFrameCompositeRequest {
.document = &document.value(),
.frame_index = 1,
});
PP_EXPECT(h, !no_document.ok());
PP_EXPECT(h, no_document.status().code == StatusCode::invalid_argument);
PP_EXPECT(h, !no_document_readiness.ok());
PP_EXPECT(h, no_document_readiness.status().code == StatusCode::invalid_argument);
PP_EXPECT(h, !bad_frame.ok());
PP_EXPECT(h, bad_frame.status().code == StatusCode::out_of_range);
PP_EXPECT(h, !bad_frame_readiness.ok());
PP_EXPECT(h, bad_frame_readiness.status().code == StatusCode::out_of_range);
PP_EXPECT(h, device.commands().empty());
}
@@ -1048,6 +1128,7 @@ int main()
harness.run("uploads_document_frame_faces_to_renderer_api", uploads_document_frame_faces_to_renderer_api);
harness.run("records_document_frame_upload_report", records_document_frame_upload_report);
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("document_frame_upload_rejects_invalid_requests", document_frame_upload_rejects_invalid_requests);
harness.run("detects_feedback_requirements", detects_feedback_requirements);
harness.run("plans_stroke_composite_paths", plans_stroke_composite_paths);

44
tools/pano_cli/main.cpp
View File

@@ -6028,42 +6028,32 @@ int plan_canvas_document_snapshot(int argc, char** argv)
ppi_export_bytes = exported.value().bytes.size();
ppi_export_dirty_faces = decoded.value().project.body.summary.dirty_face_count;
const auto recorded_upload = pp::paint_renderer::record_document_frame_upload(
pp::paint_renderer::DocumentFrameUploadRequest {
.document = &document,
.frame_index = document.active_frame_index(),
.clear_color = {},
});
if (!recorded_upload) {
print_error("plan-canvas-document-snapshot", recorded_upload.status().message);
return 2;
}
renderer_upload_ready = true;
renderer_texture_count = recorded_upload.value().upload.texture_count;
renderer_transition_count = recorded_upload.value().upload.transition_count;
renderer_uploaded_bytes = recorded_upload.value().upload.uploaded_bytes;
renderer_face_payloads = recorded_upload.value().upload.composite.face_payload_count;
renderer_composited_layer_faces = recorded_upload.value().upload.composite.composited_layer_face_count;
renderer_command_count = recorded_upload.value().command_count;
renderer_upload_command_count = recorded_upload.value().upload_command_count;
renderer_transition_command_count = recorded_upload.value().transition_command_count;
const auto face_pngs = pp::paint_renderer::export_document_frame_face_pngs(
const auto readiness = pp::paint_renderer::prepare_document_frame_export_readiness(
pp::paint_renderer::DocumentFrameCompositeRequest {
.document = &document,
.frame_index = document.active_frame_index(),
.clear_color = {},
});
if (!face_pngs) {
print_error("plan-canvas-document-snapshot", face_pngs.status().message);
if (!readiness) {
print_error("plan-canvas-document-snapshot", readiness.status().message);
return 2;
}
renderer_upload_ready = true;
renderer_texture_count = readiness.value().recorded_upload.upload.texture_count;
renderer_transition_count = readiness.value().recorded_upload.upload.transition_count;
renderer_uploaded_bytes = readiness.value().recorded_upload.upload.uploaded_bytes;
renderer_face_payloads = readiness.value().recorded_upload.upload.composite.face_payload_count;
renderer_composited_layer_faces =
readiness.value().recorded_upload.upload.composite.composited_layer_face_count;
renderer_command_count = readiness.value().recorded_upload.command_count;
renderer_upload_command_count = readiness.value().recorded_upload.upload_command_count;
renderer_transition_command_count = readiness.value().recorded_upload.transition_command_count;
face_png_export_ready = true;
face_png_export_faces = face_pngs.value().face_count;
face_png_export_bytes = face_pngs.value().encoded_bytes;
face_png_export_payloads = face_pngs.value().composite.face_payload_count;
face_png_export_faces = readiness.value().face_pngs.face_count;
face_png_export_bytes = readiness.value().face_pngs.encoded_bytes;
face_png_export_payloads = readiness.value().face_pngs.composite.face_payload_count;
}
std::cout << "{\"ok\":true,\"command\":\"plan-canvas-document-snapshot\""