RESOURCE_UTILIZATION in VideoFrameMetadata, a consumer feedback signal.

media/base/video_frame_metadata.h

 // 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.
 
 #ifndef MEDIA_BASE_VIDEO_FRAME_METADATA_H_
 #define MEDIA_BASE_VIDEO_FRAME_METADATA_H_
 
 #include "base/compiler_specific.h"
 #include "base/time/time.h"
 #include "base/values.h"
 #include "media/base/media_export.h"
 
 namespace media {
 
 class MEDIA_EXPORT VideoFrameMetadata {
  public:
   enum Key {
     // Video capture begin/end timestamps.  Consumers can use these values for
     // dynamic optimizations, logging stats, etc.  Use Get/SetTimeTicks() for
     // these keys.
     CAPTURE_BEGIN_TIME,
     CAPTURE_END_TIME,
 
+    // Some VideoFrames have an indication of the color space used.  Use
+    // GetInteger()/SetInteger() and VideoFrame::ColorSpace enumeration.
+    COLOR_SPACE,
+
     // The estimated duration of this frame (i.e., the amount of time between
     // the media timestamp of this frame and the next).  Note that this is not
     // the same information provided by FRAME_RATE as the FRAME_DURATION can
     // vary unpredictably for every frame.  Consumers can use this to optimize
     // playback scheduling, make encoding quality decisions, and/or compute
     // frame-level resource utilization stats.  Use Get/SetTimeDelta() for this
     // key.
     FRAME_DURATION,
 
     // Represents either the fixed frame rate, or the maximum frame rate to
     // expect from a variable-rate source.  This value generally remains the
     // same for all frames in the same session.  Use Get/SetDouble() for this
     // key.
     FRAME_RATE,
 
-    // Some VideoFrames have an indication of the color space used.  Use
-    // GetInteger()/SetInteger() and VideoFrame::ColorSpace enumeration.
-    COLOR_SPACE,
+    // A measure of stress, usually related to resource bottlenecks, being
+    // experienced by the consumers of the video frame.  A producer can check
+    // this value after-the-fact, usually via a VideoFrame done callback, to
+    // determine whether the consumer can handle more/less data volume.  In all,
+    // this is a feedback mechanism used to achieve the right quality versus
+    // performance trade-off.
+    //
+    // Use Get/SetDouble() for this key.  Values are interpreted as follows:
+    // Less than 0.0 is meaningless and should be ignored.  0.0 indicates zero
+    // stress.  1.0 indicates a maximum sustainable stress level.  Greater than
+    // 1.0 indicates the processing pipeline is likely to stall or drop frames
+    // if the data volume is not reduced immediately.
+    //
+    // Example: In a system that encodes and transmits video frames over the
+    // network, the stress level can be used to indicate whether sufficient CPU
+    // is available for encoding and/or sufficient bandwidth is available for
+    // transmission over the network.
+    STRESS_LEVEL,

[hubbe, 2015/06/02 00:23:22]

I don't particularly like this name.
How about RESOURCE_UTILIZATION_FRACTION?
DOWNSTREAM_BOTTLENECK_PERCENTAGE?
MAX_PIXELS_PER_SECOND_FRACTION?
PPS_PERCENTAGE?
RESOLUTION_DIVIDER?

Ok, so some of these ideas are bad, I just wanted to provide some ideas.
My preferred suggest would probably be "RESOURCE_UTILIZATION".

[miu, 2015/06/02 03:07:34]

Done.  This is actually what I had in my working prototype, so sgtm.

 
     NUM_KEYS
   };
 
   VideoFrameMetadata();
   ~VideoFrameMetadata();
 
   bool HasKey(Key key) const;
 
   void Clear() { dictionary_.Clear(); }
@@ skipping 26 matching lines @@
   const base::BinaryValue* GetBinaryValue(Key key) const;
 
   base::DictionaryValue dictionary_;
 
   DISALLOW_COPY_AND_ASSIGN(VideoFrameMetadata);
 };
 
 }  // namespace media
 
 #endif  // MEDIA_BASE_VIDEO_FRAME_METADATA_H_