Interfaces for encoded video sources

media/video/encoded_video_source.h

Index: media/video/encoded_video_source.h
diff --git a/media/video/encoded_video_source.h b/media/video/encoded_video_source.h
new file mode 100644
index 0000000000000000000000000000000000000000..883f87a582ca37530c8529bd2cc03f6a90aac28b
--- /dev/null
+++ b/media/video/encoded_video_source.h
@@ -0,0 +1,130 @@
+// Copyright 2013 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.
+
+#ifndef MEDIA_VIDEO_ENCODED_VIDEO_SOURCE_H_
+#define MEDIA_VIDEO_ENCODED_VIDEO_SOURCE_H_
+
+#include "base/memory/ref_counted.h"
+#include "media/base/encoded_bitstream_buffer.h"
+#include "media/video/video_encode_types.h"
+
+namespace media {
+
+// Class to represent an encoded video bitstream which originates from an
+// EncodedVideoSource. The interface is usually obtained through initialization
+// with OpenBitstream call to EncodedVideoSource. Each EncodedVideoBitstream
+// instance has only one client, but there can be multiple EncodedVideoBitstream
+// objects representing the same concrete bitstream from a EncodedVideoSource.
+//
+// Client can close the bitstream simply by discarding the scoped_refptr to the
+// object. Also, if client receives OnDestroyed callback from the bitstream, it
+// should consider bitstream instance invalid and can discard the pointer to it.
+class MEDIA_EXPORT EncodedVideoBitstream :
+    public base::RefCountedThreadSafe<EncodedVideoBitstream> {
+ public:
+  // Status codes to inform the client about the reasons for bitstream
+  // destruction.
+  enum StatusCode {

[Ami GONE FROM CHROMIUM, 2013/03/19 18:01:49]

this name is unfortunately general.
DestructionReason
?

[vmr, 2013/03/20 12:09:14]

SGTM. Done.

+    kRemovedOnRequest = 0,  // Bitstream was removed on client's request.
+    kEndOfStream,  // End of stream triggered from source.
+    kInvalidConfiguration,  // Client tried to initialize the bitstream with
+                            // unsupported or invalid configuration.
+    kSourceRemoved,  // Unexpected removal of source device, e.g. removal of
+                     // webcam from USB connector.
+    kHardwareError,  // Hardware has encountered internal error.
+  };
+
+  class MEDIA_EXPORT Client {
+   public:
+    // OnStreaming callback lets the client know that the bitstream has been
+    // successfully created and is streaming. Parameter modifiable lets the

[Ami GONE FROM CHROMIUM, 2013/03/19 18:01:49]

s/modifiable/is_mutable/

[vmr, 2013/03/20 12:09:14]

Done.

+    // client know, whether it is allowed to change the runtime configuration of

[Ami GONE FROM CHROMIUM, 2013/03/19 18:01:49]

s/,//

[vmr, 2013/03/20 12:09:14]

Done.

+    // the bitstream.

[Ami GONE FROM CHROMIUM, 2013/03/19 18:01:49]

If two clients A & B open the same stream, and A gets is_mutable=true and B gets
is_mutable=false, and then A destroys the bitstream, B is unfortunately unable
to modify the bitstream.  I wonder how much value there is to exposing the
modifability bit to the client here, as opposed to maintaining modifiability in
the browser process, using a "mutable" token per device which only one client
can own, and moving the token around as clients depart.

[vmr, 2013/03/20 12:09:14]

It's a corner case and could be handled just by rejecting TryConfigure in
implementation from clients that aren't supposed to modify the properties (until
they are :).

+    virtual void OnStreaming(

[Ami GONE FROM CHROMIUM, 2013/03/19 18:01:49]

I don't see this here (but it is present in the message).

[vmr, 2013/03/20 12:09:14]

Done.

+        scoped_refptr<EncodedVideoBitstream> bitstream, bool is_mutable) = 0;
+
+    // OnDestroyed tells the client to stop using the bitstream object and
+    // expecting bitstream buffers for the given stream. OnDestroyed will be
+    // called also in case of any unrecoverable failure in the device. After
+    // OnDestroyed is called for a bitstream it is guaranteed that that there
+    // will be no longer pending calls coming in to the client.
+    virtual void OnDestroyed(scoped_refptr<EncodedVideoBitstream> bitstream,
+                             StatusCode status) = 0;
+
+    // OnBufferReady delivers the captured bitstream buffer by buffer to the
+    // client.
+    virtual void OnBufferReady(
+        scoped_refptr<EncodedVideoBitstream> bitstream,
+        scoped_refptr<const EncodedBitstreamBuffer> buffer) = 0;
+
+    // OnConfigChanged informs about change in bitstream parameters that can
+    // change during runtime.
+    virtual void OnConfigChanged(
+        scoped_refptr<EncodedVideoBitstream> bitstream,
+        const RuntimeVideoEncodingParameters& params) = 0;
+  };
+
+  // Client can request change in runtime configuration by calling TryConfigure
+  // on a bitstream. Until OnConfigChanged callback is called the old
+  // configuration is valid and there may be incoming buffers with the old
+  // configuration. Regardless of whether this call succeeded or not,
+  // OnConfigChanged callback will be issued with the current parameters.
+  virtual void TryConfigure(
+      const RuntimeVideoEncodingParameters& params) = 0;
+
+  // RequestSpecialFrame allows the client to request special frames from the
+  // encoded video bitstream. The effect of the request is only visible in the
+  // bitstream buffers passed to client through the OnBitstreamReady callback.
+  // This request is served on best-effort basis and client is not given any
+  // guarantees of the realization or timing of the request. Flags parameters
+  // will be interpreted in format specific manner using enumerations.
+  virtual void RequestSpecialFrame(int flags) = 0;
+
+ protected:
+  virtual ~EncodedVideoBitstream() {};
+  friend class base::RefCountedThreadSafe<EncodedVideoBitstream>;
+};
+
+// Interface to represent any encoded video source. EncodedVideoSource tries
+// to capture the essentials of what a client of an encoder would expect from
+// the *output video bitstream*. Therefore EncodedVideoSource does not specify
+// where the input pictures come from or how the lifetime of the device is
+// managed. Interface is primarily focused around the concept of bitstream,
+// discovery the configuration space of such bitstreams from device with video
+// encoding capability, mechanisms to instantiate such a bitstream, manipulation
+// of the bitstream properties, reception of interesting bitstream events and
+// reception of the stream of buffers in the bitstream.
+//
+// Anything that provides encoded video bitstream to clients can be an
+// EncodedVideoSource. Typical examples of this can be video encoder (duh!) and
+// webcam that has encoding capability. In case of video encoder implementation
+// would inherit this interface and add at least instantiatiation and
+// destruction functionality for the encoder instance and some mechanism to feed
+// the input to it. In case of webcam implementation would again inherit this
+// same interface and add mechanisms to instantiate and close the webcam, but it
+// would not have to have a mechanism to feed the input since it has internal
+// video source.
+class MEDIA_EXPORT EncodedVideoSource {
+ public:
+  virtual ~EncodedVideoSource() {};
+
+  // GetCapabilities allows the discovery of the limitations encoded video
+  // bitstreams from this source have.
+  virtual VideoEncodingLimits GetLimits() = 0;
+
+  // OpenBitstream returns object for the stream being added. Client must
+  // consider the returned stream valid until OnBitstreamRemoved callback is
+  // called with the id. Client should check the parameters against limits
+  // reported by GetCapabilities before trying to issue a request to add an
+  // encoded bitstream. Returned EncodedVideoBitstream is only a proxy handle
+  // to the actual bitstream object.
+  virtual scoped_refptr<EncodedVideoBitstream> OpenBitstream(
+      EncodedVideoBitstream::Client* client,
+      const VideoEncodingParameters& params) = 0;
+};
+
+}  // namespace media
+
+#endif  // MEDIA_VIDEO_ENCODED_VIDEO_SOURCE_H_
+