mojo/services/media/common/interfaces/media_pipe.mojom

// Copyright 2015 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 mojo.media;

import "mojo/services/media/common/interfaces/media_common.mojom";

// MediaPacketRegion
//
// A small structure used to keep track of a portion of a shared buffer used by
// a MediaPacket to hold its payload.
struct MediaPacketRegion {
  uint64 offset;
  uint64 length;
};

// MediaPacket
//
// A structure which hold the definition of an atomic unit of media which may be
// sent across a media pipe.  MediaPackets consist of the metadata for the unit
// of media, as well as the set of offset/lengths in the pipe's shared buffer
// which define the payload of the packet itself.
struct MediaPacket {
  const int64 kNoTimestamp = 0x7fffffffffffffff;

  // Presentation Time Stamp.  Time time at which the media should be presented,
  // according to the media timeline.
  int64 pts = kNoTimestamp;

  // Bookkeeping to determine where this MediaPacket's payload exists in its
  // MediaPipe's shared buffer.
  // 
  // For simple cases, only the payload field is used.  It provides the offset
  // into the shared buffer for the payload, as well as its length.  In more
  // complicated cases (circular buffer, arbitrary scatter-gather), additional
  // regions may be described in the extra_payload array.  Logically, the
  // payload is the concatination of the payload region, followed by the extra
  // payload regions, from index 0 to index N-1.
  //
  // TODO(johngro): Depending on what happens with mojo struct marshalling,
  // consider merging payload and extra_payload into just a single array.  The
  // intention was to not need any extra allocations if there way only a single
  // payload region, but right now we always need to allocate an array, even if
  // it is zero length.  If this is not going to change, then we should just
  // merge these two fields.
  MediaPacketRegion payload;
  array<MediaPacketRegion> extra_payload;

  // TODO(johngro): do we need to describe the MediaType of this payload, or is
  // its type implicit based on the channel over which it is being pushed?

  // TODO(johngro): how do we attach per-packet media specific metadata to this
  // packet?
};

// MediaPipeState
//
// A small structure used by the user of a media pipe to fetch the shared buffer
// used by the media pipe to move bulk data.
//
// TODO(johngro): Right now, the only real purpose for this struture is to
// bundle the size of the buffer with the buffer handle itself.  When buffer
// handles can have their properties queried directly, it can go away.  See
// domokit/mojo issue #501
struct MediaPipeState {
  const uint64 kMaxPayloadLen = 0x3FFFFFFFFFFFFFFF;

  handle<shared_buffer> payload_buffer;

  // TODO(johngro) : Why do I have to send this?  Why can't I just query the
  // shared_buffer handle for its length?
  uint64 payload_buffer_len;
};

// MediaPipe
//
// An interface exposed by consumers of media which provides the means for
// producers to send media to consumers.  A pipe logically consists of a shared
// memory region, and an ordered queue of MediaPackets.  Users obtain access to
// the shared buffer via the GetState method.  They may then send packet to the
// other side of the pipe using the SendPacket method and be informed about when
// the media has been consumed via the SendPacket callback they provide.
// Finally, the pipeline may be flushed using the Flush method.
interface MediaPipe {
  // Request that a reference to the pipe's state be sent to the caller via
  // callback.
  GetState() => (MediaPipeState state);

  // Place a media packet into the pipeline to be consumed.  When the consumer
  // is finished with the packet, it will invoke the supplied callback to
  // indicate that the region of the shared buffer indicated by the MediaPacket
  // object is now available for new data.  MediaResults in the operation may
  // include...
  //
  // kOK:
  //   Media packet has been consumed without error.
  // kBadState:
  //   The media pipe is in a bad state (perhaps uninitialized) and payloads
  //   cannot be pushed to it.
  // kInvalidArgs:
  //   One or more of the payload regions does not appears to go outside the
  //   shared buffer bounds.
  // kFlushed:
  //   The packet was flushed at the request of the producer.  It was not
  //   completely consumed (but may have been partially consumed)
  SendPacket(MediaPacket packet) => (MediaResult result);

  // Flush the pipe, discarding all queued packets in order (from front to back)
  // as we go.  When the flush operation is complete, the provided callback will
  // be invoked to indicate that the consumer end of the pipe has finished
  // flushing and that the pipeline is now empty.  Possible values for the
  // MediaResult parameter of the callback include...
  //
  // kOK:
  //    Pipeline has been successfully flushed.
  // kBusy:
  //    A flush was already in progress, this flush request was ignored.
  // kBadState:
  //   The media pipe is in a bad state (perhaps uninitialized) and cannot be
  //   flushed
  Flush() => (MediaResult result);
};