media/base/video_frame_metadata.h

   1 // Copyright 2015 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef MEDIA_BASE_VIDEO_FRAME_METADATA_H_
   6 #define MEDIA_BASE_VIDEO_FRAME_METADATA_H_
   7
   8 #include "base/compiler_specific.h"
   9 #include "base/time/time.h"
  10 #include "base/values.h"
  11 #include "media/base/media_export.h"
  12
  13 namespace media {
  14
  15 class MEDIA_EXPORT VideoFrameMetadata {
  16  public:
  17   enum Key {
  18     // Sources of VideoFrames use this marker to indicate that the associated
  19     // VideoFrame can be overlayed, case in which its contents do not need to be
  20     // further composited but displayed directly. Use Get/SetBoolean() for
  21     // this Key.
  22     ALLOW_OVERLAY,
  23
  24     // Video capture begin/end timestamps.  Consumers can use these values for
  25     // dynamic optimizations, logging stats, etc.  Use Get/SetTimeTicks() for
  26     // these keys.
  27     CAPTURE_BEGIN_TIME,
  28     CAPTURE_END_TIME,
  29
  30     // Some VideoFrames have an indication of the color space used.  Use
  31     // GetInteger()/SetInteger() and ColorSpace enumeration.
  32     COLOR_SPACE,
  33
  34     // Indicates if the current frame is the End of its current Stream. Use
  35     // Get/SetBoolean() for this Key.
  36     END_OF_STREAM,
  37
  38     // The estimated duration of this frame (i.e., the amount of time between
  39     // the media timestamp of this frame and the next).  Note that this is not
  40     // the same information provided by FRAME_RATE as the FRAME_DURATION can
  41     // vary unpredictably for every frame.  Consumers can use this to optimize
  42     // playback scheduling, make encoding quality decisions, and/or compute
  43     // frame-level resource utilization stats.  Use Get/SetTimeDelta() for this
  44     // key.
  45     FRAME_DURATION,
  46
  47     // Represents either the fixed frame rate, or the maximum frame rate to
  48     // expect from a variable-rate source.  This value generally remains the
  49     // same for all frames in the same session.  Use Get/SetDouble() for this
  50     // key.
  51     FRAME_RATE,
  52
  53     // This field represents the local time at which either: 1) the frame was
  54     // generated, if it was done so locally; or 2) the targeted play-out time
  55     // of the frame, if it was generated from a remote source. This value is NOT
  56     // a high-resolution timestamp, and so it should not be used as a
  57     // presentation time; but, instead, it should be used for buffering playback
  58     // and for A/V synchronization purposes.
  59     // Use Get/SetTimeTicks() for this key.
  60     REFERENCE_TIME,
  61
  62     // A feedback signal that indicates the fraction of the tolerable maximum
  63     // amount of resources that were utilized to process this frame.  A producer
  64     // can check this value after-the-fact, usually via a VideoFrame destruction
  65     // observer, to determine whether the consumer can handle more or less data
  66     // volume, and achieve the right quality versus performance trade-off.
  67     //
  68     // Use Get/SetDouble() for this key.  Values are interpreted as follows:
  69     // Less than 0.0 is meaningless and should be ignored.  1.0 indicates a
  70     // maximum sustainable utilization.  Greater than 1.0 indicates the consumer
  71     // is likely to stall or drop frames if the data volume is not reduced.
  72     //
  73     // Example: In a system that encodes and transmits video frames over the
  74     // network, this value can be used to indicate whether sufficient CPU
  75     // is available for encoding and/or sufficient bandwidth is available for
  76     // transmission over the network.  The maximum of the two utilization
  77     // measurements would be used as feedback.
  78     RESOURCE_UTILIZATION,
  79
  80     NUM_KEYS
  81   };
  82
  83   VideoFrameMetadata();
  84   ~VideoFrameMetadata();
  85
  86   bool HasKey(Key key) const;
  87
  88   void Clear() { dictionary_.Clear(); }
  89
  90   // Setters.  Overwrites existing value, if present.
  91   void SetBoolean(Key key, bool value);
  92   void SetInteger(Key key, int value);
  93   void SetDouble(Key key, double value);
  94   void SetString(Key key, const std::string& value);
  95   void SetTimeDelta(Key key, const base::TimeDelta& value);
  96   void SetTimeTicks(Key key, const base::TimeTicks& value);
  97   void SetValue(Key key, scoped_ptr<base::Value> value);
  98
  99   // Getters.  Returns true if |key| is present, and its value has been set.
 100   bool GetBoolean(Key key, bool* value) const WARN_UNUSED_RESULT;
 101   bool GetInteger(Key key, int* value) const WARN_UNUSED_RESULT;
 102   bool GetDouble(Key key, double* value) const WARN_UNUSED_RESULT;
 103   bool GetString(Key key, std::string* value) const WARN_UNUSED_RESULT;
 104   bool GetTimeDelta(Key key, base::TimeDelta* value) const WARN_UNUSED_RESULT;
 105   bool GetTimeTicks(Key key, base::TimeTicks* value) const WARN_UNUSED_RESULT;
 106
 107   // Returns null if |key| was not present.
 108   const base::Value* GetValue(Key key) const WARN_UNUSED_RESULT;
 109
 110   // Convenience method that returns true if |key| exists and is set to true.
 111   bool IsTrue(Key key) const WARN_UNUSED_RESULT;
 112
 113   // For serialization.
 114   void MergeInternalValuesInto(base::DictionaryValue* out) const;
 115   void MergeInternalValuesFrom(const base::DictionaryValue& in);
 116
 117  private:
 118   const base::BinaryValue* GetBinaryValue(Key key) const;
 119
 120   base::DictionaryValue dictionary_;
 121
 122   DISALLOW_COPY_AND_ASSIGN(VideoFrameMetadata);
 123 };
 124
 125 }  // namespace media
 126
 127 #endif  // MEDIA_BASE_VIDEO_FRAME_METADATA_H_