RESOURCE_UTILIZATION in VideoFrameMetadata, a consumer feedback signal.

media/base/video_frame_metadata.h

Index: media/base/video_frame_metadata.h
diff --git a/media/base/video_frame_metadata.h b/media/base/video_frame_metadata.h
index 526383b42305d5d3c7961992e65a761eaab3ccf2..74830205ec41eab9a0e7f7ec5648aa8dcd214291 100644
--- a/media/base/video_frame_metadata.h
+++ b/media/base/video_frame_metadata.h
@@ -21,6 +21,10 @@ class MEDIA_EXPORT VideoFrameMetadata {
     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
@@ -36,9 +40,24 @@ class MEDIA_EXPORT VideoFrameMetadata {
     // key.
     FRAME_RATE,
 
-    // Some VideoFrames have an indication of the color space used.  Use
-    // GetInteger()/SetInteger() and VideoFrame::ColorSpace enumeration.
-    COLOR_SPACE,
+    // A feedback signal that indicates the fraction of the tolerable maximum
+    // amount of resources that were utilized to process this frame.  A producer
+    // can check this value after-the-fact, usually via a VideoFrame destruction
+    // observer, to determine whether the consumer can handle more or less data
+    // volume, and 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.  1.0 indicates a
+    // maximum sustainable utilization.  Greater than 1.0 indicates the consumer
+    // is likely to stall or drop frames if the data volume is not reduced
+    // immediately.

[hubbe, 2015/06/04 22:08:53]

I would remove the word "immediately" here.

[miu, 2015/06/06 00:29:22]

Done.

+    //
+    // Example: In a system that encodes and transmits video frames over the
+    // network, this value can be used to indicate whether sufficient CPU
+    // is available for encoding and/or sufficient bandwidth is available for
+    // transmission over the network.  The maximum of the two utilization
+    // measurements would be used as feedback.
+    RESOURCE_UTILIZATION,
 
     NUM_KEYS
   };