Add renderer frame capture contract

tests/renderer_api/renderer_api_tests.cpp

@@ -9,6 +9,7 @@
 using pp::foundation::StatusCode;
 using pp::renderer::ClearColor;
 using pp::renderer::Extent2D;
+using pp::renderer::frame_capture_byte_size;
 using pp::renderer::ICommandContext;
 using pp::renderer::IMesh;
 using pp::renderer::IRenderDevice;
@@ -167,6 +168,21 @@ public:
         return pp::foundation::Status::success();
     }
 
+    [[nodiscard]] pp::foundation::Status capture_frame(
+        IRenderTarget& target,
+        pp::renderer::IReadbackBuffer& destination) noexcept override
+    {
+        const auto bytes = frame_capture_byte_size(target.color_desc());
+        if (!bytes) {
+            return bytes.status();
+        }
+        if (destination.size_bytes() < bytes.value()) {
+            return pp::foundation::Status::out_of_range("frame capture buffer is too small");
+        }
+        last_capture_bytes = bytes.value();
+        return pp::foundation::Status::success();
+    }
+
     void end_render_pass() noexcept override
     {
         in_render_pass = false;
@@ -175,6 +191,7 @@ public:
     bool in_render_pass = false;
     const char* shader_name = nullptr;
     std::uint64_t last_readback_bytes = 0;
+    std::uint64_t last_capture_bytes = 0;
 };
 
 class FakeRenderDevice final : public IRenderDevice {
@@ -281,6 +298,28 @@ void computes_readback_byte_sizes(pp::tests::Harness& h)
     PP_EXPECT(h, overrun.status().code == StatusCode::out_of_range);
 }
 
+void computes_frame_capture_byte_sizes(pp::tests::Harness& h)
+{
+    const TextureDesc target_desc {
+        .extent = Extent2D { .width = 16, .height = 8 },
+        .format = TextureFormat::rgba8,
+        .render_target = true,
+    };
+    const TextureDesc texture_desc {
+        .extent = Extent2D { .width = 16, .height = 8 },
+        .format = TextureFormat::rgba8,
+        .render_target = false,
+    };
+
+    const auto capture = frame_capture_byte_size(target_desc);
+    const auto non_target = frame_capture_byte_size(texture_desc);
+
+    PP_EXPECT(h, capture.ok());
+    PP_EXPECT(h, capture.value() == 512U);
+    PP_EXPECT(h, !non_target.ok());
+    PP_EXPECT(h, non_target.status().code == StatusCode::invalid_argument);
+}
+
 void validates_viewports_and_mesh_descriptors(pp::tests::Harness& h)
 {
     const Extent2D target { .width = 64, .height = 32 };
@@ -448,8 +487,10 @@ void renderer_interfaces_support_backend_neutral_dispatch(pp::tests::Harness& h)
                      ReadbackRegion { .x = 2, .y = 3, .width = 4, .height = 5 },
                      readback_buffer)
                      .ok());
+    PP_EXPECT(h, context.capture_frame(target, readback_buffer).ok());
     PP_EXPECT(h, device.context.shader_name == std::string_view("fake-shader"));
     PP_EXPECT(h, device.context.last_readback_bytes == 80U);
+    PP_EXPECT(h, device.context.last_capture_bytes == 8192U);
 }
 
 void recording_renderer_records_valid_command_sequences(pp::tests::Harness& h)
@@ -512,6 +553,15 @@ void recording_renderer_records_valid_command_sequences(pp::tests::Harness& h)
     PP_EXPECT(h, commands_after_readback[7].readback_bytes == 96U);
     PP_EXPECT(h, recorded_render_command_kind_name(commands_after_readback[7].kind) == std::string_view("read_texture"));
 
+    PP_EXPECT(h, context.capture_frame(target, readback_buffer).ok());
+    const auto commands_after_capture = device.commands();
+    PP_EXPECT(h, commands_after_capture.size() == 9U);
+    PP_EXPECT(h, commands_after_capture[8].kind == RecordedRenderCommandKind::capture_frame);
+    PP_EXPECT(h, commands_after_capture[8].target_desc.extent.width == 64U);
+    PP_EXPECT(h, commands_after_capture[8].target_desc.extent.height == 32U);
+    PP_EXPECT(h, commands_after_capture[8].capture_bytes == 8192U);
+    PP_EXPECT(h, recorded_render_command_kind_name(commands_after_capture[8].kind) == std::string_view("capture_frame"));
+
     device.clear();
     PP_EXPECT(h, device.commands().empty());
 }
@@ -558,6 +608,10 @@ void recording_renderer_rejects_invalid_command_order_and_targets(pp::tests::Har
     PP_EXPECT(h, !read_during_render_pass.ok());
     PP_EXPECT(h, read_during_render_pass.code == StatusCode::invalid_argument);
 
+    const auto capture_during_render_pass = context.capture_frame(target, full_readback_buffer);
+    PP_EXPECT(h, !capture_during_render_pass.ok());
+    PP_EXPECT(h, capture_during_render_pass.code == StatusCode::invalid_argument);
+
     const auto nested_begin = context.begin_render_pass(target, ClearColor {});
     PP_EXPECT(h, !nested_begin.ok());
     PP_EXPECT(h, nested_begin.code == StatusCode::invalid_argument);
@@ -596,6 +650,14 @@ void recording_renderer_rejects_invalid_command_order_and_targets(pp::tests::Har
         small_readback_buffer);
     PP_EXPECT(h, !read_into_small_buffer.ok());
     PP_EXPECT(h, read_into_small_buffer.code == StatusCode::out_of_range);
+
+    const auto capture_into_small_buffer = context.capture_frame(target, small_readback_buffer);
+    PP_EXPECT(h, !capture_into_small_buffer.ok());
+    PP_EXPECT(h, capture_into_small_buffer.code == StatusCode::out_of_range);
+
+    const auto capture_non_target = context.capture_frame(non_render_target, full_readback_buffer);
+    PP_EXPECT(h, !capture_non_target.ok());
+    PP_EXPECT(h, capture_non_target.code == StatusCode::invalid_argument);
 }
 
 }
@@ -607,6 +669,7 @@ int main()
     harness.run("rejects_invalid_or_excessive_extents", rejects_invalid_or_excessive_extents);
     harness.run("validates_readback_bounds", validates_readback_bounds);
     harness.run("computes_readback_byte_sizes", computes_readback_byte_sizes);
+    harness.run("computes_frame_capture_byte_sizes", computes_frame_capture_byte_sizes);
     harness.run("validates_viewports_and_mesh_descriptors", validates_viewports_and_mesh_descriptors);
     harness.run("validates_shader_program_descriptors", validates_shader_program_descriptors);
     harness.run("validates_panopainter_shader_catalog", validates_panopainter_shader_catalog);