// Copyright 2017 The Chromium Authors. All rights reserved.
// 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_perception/mojom/video_capture_buffer.mojom";
import "media_perception/mojom/video_capture_types.mojom";
import "media_perception/mojom/producer.mojom";
import "media_perception/mojom/video_frame_handler.mojom";
import "media_perception/mojom/geometry.mojom";
import "media_perception/mojom/buffer_types.mojom";

// Interface for a producer to feed video frames into a virtual
// device. These frames will appear to the consumer of the device
// as if they were produced by a real device.
//
// The buffers used for transporting video frames are managed by
// this interface, and are obtained from a finite size buffer pool.
// When the producer wants to push a frame, it will first request a buffer
// via |RequestFrameBuffer|, and a buffer ID will be provided in the
// response. In the process of assigning a buffer to the producer, a new
// buffer might be created and/or an old buffer might be retired.
//
// To avoid the remapping of buffers in producer after each buffer
// request, a separate interface |Producer| is used for notifying the
// producer with the buffer information changes. It is producer's
// responsibility for caching the buffer information.
interface SharedMemoryVirtualDevice {
  // This is used by the producer for requesting a buffer to store frame
  // data. The frame can subsequently be pushed via |OnFrameReadyInBuffer|.
  // An invalid buffer ID |Constants.kInvalidBufferId| will be returned
  // if no buffer is available.
  //
  // Note: A new buffer might be created and/or an old buffer might be
  // retired as a side-effect of the request. In that case,
  // |Producer.OnNewBufferHandle| and/or |Producer.OnBufferRetired|
  // will be invoked.
  RequestFrameBuffer(gfx.mojom.Size dimension,
                     media.mojom.VideoCapturePixelFormat pixel_format,
                     media.mojom.PlaneStrides? strides)
      => (int32 buffer_id);

  // Called to indicate that a video frame is ready in the given buffer
  // |buffer_id|.
  OnFrameReadyInBuffer(int32 buffer_id,
                       media.mojom.VideoFrameInfo frame_info);
};

// Similar to SharedMemoryVirtualDevice but uses MailboxHolders instead of
// shared memory for transporting frames. The MailboxHolders are to be
// provided by the caller.
interface TextureVirtualDevice {
  // Registers a new set of mailbox holders for subsequent transport of
  // frames.
  OnNewMailboxHolderBufferHandle(
      int32 buffer_id, media.mojom.MailboxBufferHandleSet mailbox_handles);
  // Frames delivered by subsequent OnFrameReadyInBuffer() calls have their
  // access permissions managed by |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);
  // The invoker must guarantee that the textures with |buffer_id| stay valid
  // until VideoFrameAccessHandler.OnFinishedConsumingBuffer() is called.
  // In |frame_info|, |visible_rect| must be equivalent to the full |coded_size|
  // of the frame, i.e. using |visible_rect| to crop to subregions of the frame
  // is not supported.
  OnFrameReadyInBuffer(int32 buffer_id,
                       media.mojom.VideoFrameInfo frame_info);
  // Unregisters a set of mailbox holders previously registered via
  // OnNewMailboxHolderBufferHandle(). Note, that this should not be called
  // while the corresponding buffer is still in use via OnFrameReadyInBuffer().
  OnBufferRetired(int32 buffer_id);
};

// Virtual capture device with video frames backed by GpuMemoryBuffer.
interface GpuMemoryBufferVirtualDevice {
  // Registers a GpuMemoryBufferHandle for subsequent transport of frames.
  OnNewGpuMemoryBufferHandle(
      int32 buffer_id, gfx.mojom.GpuMemoryBufferHandle gmb_handle);

  // Frames delivered by subsequent OnFrameReadyInBuffer() calls have their
  // access permissions managed by |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);

  // The invoker must guarantee that the GpuMemoryBufferHandle with |buffer_id|
  // stay valid until VideoFrameAccessHandler.OnFinishedConsumingBuffer() is
  // called. In |frame_info|, |visible_rect| must be equivalent to the full
  // |coded_size| of the frame, i.e. using |visible_rect| to crop to subregions
  // of the frame is not supported.
  OnFrameReadyInBuffer(int32 buffer_id,
                       media.mojom.VideoFrameInfo frame_info);

  // Unregisters a GpuMemoryBufferHandle previously registered via
  // OnNewGpuMemoryBufferHandle(). Note, that this should not be called while
  // the corresponding buffer is still in use via OnFrameReadyInBuffer().
  OnBufferRetired(int32 buffer_id);
};