/* -*- Mode: C++; tab-width: 20; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

include LayersSurfaces;
include protocol PGrallocBuffer;
include protocol PImageBridge;

namespace mozilla {
namespace layers {


/**
 * The PImageBridge protocol is used to allow isolated threads or processes to push
 * frames directly to the compositor thread/process without relying on the main
 * thread which might be too busy dealing with content script.
 *
 * PImageContainer is the sub protocol of PImageBridge that takes place on the 
 * ImageContainer level. There is basically one pair ImageContainerChild/Parent
 * for each ImageContainer that uses the protocol. ImageContainerChild (content 
 * side) is responsible for sending images to the ImageContainerParent (compositor
 * side) by using SendPublishImage. Once received on the content side, shared 
 * images are stored in a global map (see ImageContainerParent.cpp) accessible to
 * the image layers. Once a shared image is not usefull to the compositor anymore,
 * it is sent back to the child side (ReturnImage).
 */
sync protocol PImageContainer
{
  manager PImageBridge;
  manages PGrallocBuffer;

child:
  // Give back the child thread/process ownership to a SharedImage
  async ReturnImage(SharedImage image);

parent:
  sync PGrallocBuffer(gfxIntSize size, gfxContentType content)
    returns (MaybeMagicGrallocBufferHandle handle);

  // Send a SharedImage to the compositor giving to the compositor ownership 
  // of the image.
  async PublishImage(SharedImage image);

  // Tells the parent side to dispose of its shared images (most likely because the
  // video element is still alive but will not be displayed for a moment).
  async Flush();
  
  // After receiving this message, the ImageContainerParent will not return images
  // back to the child side (to avoid a race between ReturnImage and __delete__) 
  sync Stop();

  sync __delete__();

};


} // namespace
} // namespace