// Copyright 2019 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

module paint_preview.mojom;

import "components/paint_preview/common/mojom/paint_preview_types.mojom";
import "mojo/public/mojom/base/big_buffer.mojom";
import "mojo/public/mojom/base/file.mojom";
import "mojo/public/mojom/base/time.mojom";
import "mojo/public/mojom/base/unguessable_token.mojom";
import "ui/gfx/geometry/mojom/geometry.mojom";
import "url/mojom/url.mojom";

// Status codes for the PaintPreviewRecorder.
enum PaintPreviewStatus {
  // Everything worked as intended.
  kOk,

  // The service was already performing a capture of the frame.
  kAlreadyCapturing,

  // Capturing the SkPicture for the frame failed or the file provided was bad.
  kCaptureFailed,

  // The GUID provided for the document collides with another in progress
  // capture.
  kGuidCollision,

  // Failed to create the file for serialization of the SkPicture.
  kFileCreationError,

  // Indicates that the capture was at least partially complete but there was an
  // error.
  kPartialSuccess,

  // Indicates that the capture failed entirely.
  kFailed,
};

// The collection of parameters needed for a recording of a render frame.
struct PaintPreviewCaptureParams {
  // The strategy for where to store the serialized SkPictures resulting from
  // this capture.
  RecordingPersistence persistence;

  // GUID for the Paint Preview (used to associate subframes to main frame).
  mojo_base.mojom.UnguessableToken guid;

  // Params that control the geometry/placement of the capture.
  GeometryMetadataParams geometry_metadata_params;

  // Used to identify if the capture request is for the main frame.
  bool is_main_frame;

  // Indicates whether links should be captured and added to the response.
  bool capture_links;

  // File to write the SkPicture to (write-only). A separate file should be
  // created for each RenderFrame. See |SerializedRecording| for details on
  // contents.
  //
  // null if not |RecordingPersistence::FileSystem|.
  mojo_base.mojom.File? file;

  // The maximum allowed size of a capture that can be produced. A value of
  // 0 means the size is unrestricted.
  uint64 max_capture_size;

  // Limit on the maximum size of a decoded image that can be serialized.
  // Any images with a decoded size exceeding this value will be discarded.
  uint64 max_decoded_image_size_bytes;

  // This flag will skip GPU accelerated content where applicable when
  // capturing. This reduces hangs, capture time and may also reduce OOM
  // crashes, but results in a lower fideltiy capture (i.e. the contents
  // captured may not accurately reflect the content visible to the user at
  // time of capture). See PaintPreviewBaseService::CaptureParams for a
  // description of the effects of this flag.
  bool skip_accelerated_content;
};

struct LinkData {
  // URL of the link.
  url.mojom.Url url;

  // Rect for the link.
  gfx.mojom.Rect rect;
};

struct PaintPreviewCaptureResponse {
  // Embedding token of the frame. Will be nullopt for the main frame.
  mojo_base.mojom.UnguessableToken? embedding_token;

  // Map between subframe content IDs and the RenderFrameProxy Routing ID.
  map<uint32, mojo_base.mojom.UnguessableToken> content_id_to_embedding_token;

  // A list of links within the frame.
  array<LinkData> links;

  // The time spent capturing in Blink.
  mojo_base.mojom.TimeDelta blink_recording_time;

  // The size of the resulting serialized capture.
  uint64 serialized_size;

  // Metadata about the geometry/placement of the capture.
  GeometryMetadataResponse geometry_metadata;

  // The serialized skia picture. See |SerializedRecording| for details on
  // contents.
  //
  // null if not |RecordingPersistence::MemoryBuffer|.
  mojo_base.mojom.BigBuffer? skp;
};

struct GeometryMetadataParams {
  // Clip rect for the capture. An empty |clip_rect| will be treated as
  // unclipped and will default to the frame (document) size. Values for
  // width/height larger than the document size will be clamped to the
  // size of the document.
  gfx.mojom.Rect clip_rect;

  // If not `kNone`, overrides `clip_rect`'s x coordinate with a
  // renderer-computed value.
  ClipCoordOverride clip_x_coord_override = kNone;
  // If not `kNone`, overrides `clip_rect`'s y coordinate with a
  // renderer-computed value.
  ClipCoordOverride clip_y_coord_override = kNone;

  // Set to true if the clip rect is only a hint as to size.
  bool clip_rect_is_hint;
};

struct GeometryMetadataResponse {
  // Scroll offsets of the viewport relative to the captured region of the
  // frame at capture time.
  gfx.mojom.Point scroll_offsets;

  // Offset of the captured content relative to the top-left corner of the
  // captured frame.
  gfx.mojom.Point frame_offsets;
};

// Service for capturing a paint preview of a RenderFrame's contents. This
// includes both the visual contents (as an SkPicture) and hyperlinks
// for the frame.
interface PaintPreviewRecorder {
  // Captures a paint preview of the RenderFrame that receives the request.
  //
  // This interface is used for both the main frame and sub frames.
  // Out-of-process subframes are handled by making requests back to the browser
  // via the RenderFrameProxy. The browser handles dispatching these requests to
  // the correct RenderFrame and aggregating all the outputs.
  //
  // Returns a valid instance of PaintPreviewCaptureResponse, or a status code
  // on error.
  CapturePaintPreview(PaintPreviewCaptureParams params) =>
    result<PaintPreviewCaptureResponse, PaintPreviewStatus>;

  // Computes the geometry that would be used for a capture with the given
  // geometry params. Returns null if the geometry couldn't be calculated.
  GetGeometryMetadata(GeometryMetadataParams params) =>
    (GeometryMetadataResponse? response);
};