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

module video_capture.mojom;

import "media/capture/mojom/video_capture_buffer.mojom";
import "media/capture/mojom/video_capture_types.mojom";
import "media/mojo/mojom/media_types.mojom";

// Describes a new frame that is ready for consumption in the buffer with id
// |buffer_id| and allows it to read the data from the buffer. The producer
// guarantees that the buffer and its contents stay alive and unchanged until
// VideoFrameAccessHandler.OnFinishedConsumingBuffer() is called.
struct ReadyFrameInBuffer {
  int32 buffer_id;
  int32 frame_feedback_id;
  media.mojom.VideoFrameInfo frame_info;
};

// Callback interface to be used when a buffer (ReadyFrameInBuffer) is no longer
// being consumed on the receiver side. The VideoFrameAccessHandler may outlive
// the VideoFrameHandler.
interface VideoFrameAccessHandler {
  // Informs the producer that the buffer associated with |buffer_id| is no
  // longer being accessed by any consumer, allowing the buffer to be reused.
  OnFinishedConsumingBuffer(int32 buffer_id);
};

// Callback interface for receiving data and messages from a
// video_capture.mojom.Device or
// video_capture.mojom.PushVideoStreamSubscription.
interface VideoFrameHandler {
  // Called to indicate that the producer has detected a change of
  // configuration in an underlying source.
  // This allows configurationchange events to fired as needed.
  OnCaptureConfigurationChanged();

  // Indicates that the producer is going to subsequently use the provided
  // buffer as one of possibly many for frame delivery via
  // OnFrameReadyInBuffer(). Note, that a call to this method does not mean that
  // the caller allows the handler to read from or write to the buffer just yet.
  // Temporary permission to read will be given with subsequent calls to
  // OnFrameReadyInBuffer().
  OnNewBuffer(int32 buffer_id, media.mojom.VideoBufferHandle buffer_handle);

  // Frames delivered by subsequent OnFrameReadyInBuffer() calls have their
  // access permissions managed by this |frame_access_handler|. The producer
  // guarantees that the buffer stays alive until
  // VideoFrameAccessHandler.OnFinishedConsumingBuffer() is called and the
  // consumer guarantees to call this method when finished consuming the buffer.
  OnFrameAccessHandlerReady(
      pending_remote<VideoFrameAccessHandler> frame_access_handler);

  // Indicates that a new frame is ready for consumption. The producer
  // guarantees that the buffer and its contents stay alive and unchanged until
  // VideoFrameHandler releases the buffer using |frame_access_handler|'s
  // OnFinishedConsumingBuffer().
  OnFrameReadyInBuffer(ReadyFrameInBuffer buffer);

  // Indicates that the producer is no longer going to use the buffer with id
  // |buffer_id| for frame delivery. This may be called even while the handler
  // still holds access to the buffer (not having called
  // OnFinishedConsumingBuffer() for this buffer yet). In that case, it means
  // that the caller is asking the VideoFrameHandler to release the access and
  // buffer handle at its earliest convenience. After this call, a producer may
  // immediately reuse the retired |buffer_id| with a new buffer via a call to
  // OnNewBuffer().
  OnBufferRetired(int32 buffer_id);

  // Indicates that an error occurred on the producer side.
  OnError(media.mojom.VideoCaptureError error);

  OnFrameDropped(media.mojom.VideoCaptureFrameDropReason reason);

  // Called to indicate that a new |capture_version| has been set,
  // and that all frames which will subsequently be delivered using
  // OnFrameCaptured(), will have a capture-target-version that is
  // greater-than-or-equal-to this one.
  //
  // This allows the Promise which cropTo() or restrictTo() returned to be
  // resolved promptly, even if frames are not being produced over the track
  // at the moment, which can happen if the track is cropped to an invisible
  // target, or is paused, or is muted.
  OnNewCaptureVersion(media.mojom.CaptureVersion capture_version);

  // Called when a frame is *not* delivered because Region Capture was applied,
  // but the cropped-to region consists of zero pixels. This is needed because
  // the blue border that is normally drawn around the cropped-to region should
  // be updated.
  // Note that this is specific to Region Capture. With Element Capture,
  // we always draw the blue border around the entire tab's viewport.
  OnFrameWithEmptyRegionCapture();

  OnLog(string message);

  // Indicates that the producer side has started successfully. The producer
  // guarantees that this is called before any call to OnFrameReadyInBuffer().
  OnStarted();

  OnStartedUsingGpuDecode();

  // Indicates that the producer side has stopped and is not going to make any
  // further calls to this VideoFrameHandler.
  OnStopped();
};