Interfaces for encoded video sources

media/video/video_encode_types.h

Index: media/video/video_encode_types.h
diff --git a/media/video/video_encode_types.h b/media/video/video_encode_types.h
new file mode 100644
index 0000000000000000000000000000000000000000..18cf42ae59ad9e74df2cf0f76fa5abf008b2d596
--- /dev/null
+++ b/media/video/video_encode_types.h
@@ -0,0 +1,104 @@
+// Copyright (c) 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_VIDEO_ENCODE_TYPES_H_
+#define MEDIA_VIDEO_VIDEO_ENCODE_TYPES_H_
+
+#include <ostream>
+#include <vector>
+
+#include "base/time.h"
+#include "media/base/media_export.h"
+#include "media/base/video_decoder_config.h"
+#include "ui/gfx/size.h"
+
+namespace media {
+
+// Flags to request special frames for VP8.
+enum VP8SpecialFrameFlags {
+  kVP8KeyFrame = 1,   // Key frame (implies also golden and altref refresh).
+  kVP8GoldenFrame = 1 << 1,   // Golden frame refresh without key frame.
+  kVP8AltrefFrame = 1 << 2,   // Altref frame refresh without key frame.
+};

[Ami GONE FROM CHROMIUM, 2013/03/18 22:53:45]

These values are not orthogonal and therefore are not truly flags.  What does a
value of 5 mean?
If you want orthogonal values, make each of the values imply a single bit of
information.
If you only need to support key+golden+altref, golden, and altref, make it a
non-flag enum of those things.

[Ville-Mikko Rautio, 2013/03/19 16:45:43]

Done.

+
+// Data to represent limitations for a encoded video source.
+struct MEDIA_EXPORT VideoEncodingLimits {
+  struct MEDIA_EXPORT EncoderConfig {
+    // Range to represent limitations in encoder controls.
+    struct Range {
+      int min;
+      int max;
+      int step;
+    };
+
+    EncoderConfig();
+    ~EncoderConfig();
+
+    VideoCodec codec;

[Ami GONE FROM CHROMIUM, 2013/03/18 22:53:45]

Multi-profile codecs are going to need the profile here.
(if you're only supporting vp8, then no need for this field; if you're
contemplating support for other things, put in the right hooks now).

[Ville-Mikko Rautio, 2013/03/19 16:45:43]

Done.

+    gfx::Size resolution;
+    std::vector<int> frames_per_second;  // Maximum fps choices for stream.

[Ami GONE FROM CHROMIUM, 2013/03/18 22:53:45]

s/for stream//

[Ville-Mikko Rautio, 2013/03/19 16:45:43]

Done.

+    Range stream_count;
+    Range temporal_layer_count;
+    Range average_bitrate;
+    Range qp;
+  };
+
+  VideoEncodingLimits();
+  ~VideoEncodingLimits();
+
+  std::vector<EncoderConfig> configs;  // A set of supported configs.
+};
+
+struct MEDIA_EXPORT TemporalLayerParameters {
+  bool enabled;  // Flag telling whether temporal layer is enabled. If a layer
+                 // is not enabled, any of the layers depending on it will be
+                 // also disabled regardless of their parameters.

[Ami GONE FROM CHROMIUM, 2013/03/18 22:53:45]

Does that mean that to tell if a layer is disabled one must check its transitive
dependencies?  That seems like a bad time.

[Ville-Mikko Rautio, 2013/03/19 16:45:43]

It says that a layer is disabled, all the direct and transitive dependencies are
automatically disabled as well.

Temporal layers are generally encoded in a way that temporal layers with higher
ids are depending on ones with lower ids. And what I am trying to say, is that
if client in case with three temporal layers (0, 1 and 2) disables layer 1 (by
setting enabled to false for it), it will automatically disable layer 2 as well.

+  int target_bitrate;  // Target bitrate for the layer.

[Ami GONE FROM CHROMIUM, 2013/03/18 22:53:45]

specify units: "in bytes/second" (if that's the case).

[Ville-Mikko Rautio, 2013/03/19 16:45:43]

Done.

+};
+
+// Video encoder controls that can be configured during streaming for each
+// stream.
+struct MEDIA_EXPORT RuntimeVideoEncodingParameters {
+  RuntimeVideoEncodingParameters();
+  ~RuntimeVideoEncodingParameters();
+
+  int frames_per_second;
+  int max_bitrate;
+  int max_qp;
+  // Runtime parameters for each temporal layer. One element for each layer,
+  // first one for the base layer, second for first temporal enhancement layer
+  // and so on.
+  std::vector<TemporalLayerParameters> temporal_layer_params;
+};

[Ami GONE FROM CHROMIUM, 2013/03/18 22:53:45]

Shouldn't there be a way to indicate that the client doesn't care about given
field?  IOW I want a certain FPS at a certain bitrate and am willing to let the
decoder decide the QP/temporal layer params to achieve my desires.

[Ville-Mikko Rautio, 2013/03/19 16:45:43]

Done.

+
+// Video encoder parameters to be configured during initialization time for each
+// stream.
+struct MEDIA_EXPORT VideoEncodingParameters {
+  VideoCodec codec;

[Ami GONE FROM CHROMIUM, 2013/03/18 22:53:45]

ditto profile

[Ville-Mikko Rautio, 2013/03/19 16:45:43]

Done.

+  gfx::Size resolution;
+  int temporal_layer_count;

[Ami GONE FROM CHROMIUM, 2013/03/18 22:53:45]

this is redundant to runtime_params.temporal_layer_params.size() and should be
dropped.

[Ville-Mikko Rautio, 2013/03/19 16:45:43]

Done.

+  RuntimeVideoEncodingParameters runtime_params;
+};
+
+struct MEDIA_EXPORT BufferEncodingMetadata {
+  base::Time timestamp;
+  int frame_type_flags;
+  int temporal_layer_id;
+  bool layer_sync;  // Tells if the frame is temporal layer sync point.
+  bool droppable;   // Tells whether the encoded buffer can be dropped without
+                    // affecting the decoding of subsequent frames.
+};
+
+}  // namespace media
+
+// Pretty print operators to log structures found in the header conveniently.

[Ami GONE FROM CHROMIUM, 2013/03/18 22:53:45]

ditto convert to ToDebugString()s on the respective types.

[Ville-Mikko Rautio, 2013/03/19 16:45:43]

Done.

+std::ostream& operator<<(
+    std::ostream& output,
+    const media::VideoEncodingLimits::EncoderConfig::Range& r);
+std::ostream& operator<<(
+    std::ostream& output,
+    const media::VideoEncodingLimits::EncoderConfig& c);
+std::ostream& operator<<(std::ostream& output,
+                         const media::VideoEncodingLimits& l);
+
+#endif  // MEDIA_VIDEO_VIDEO_ENCODE_TYPES_H_