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"
@@ skipping 25 matching lines @@
     // 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,
 
+    // 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.
+    //
+    // 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
   };
 
   VideoFrameMetadata();
   ~VideoFrameMetadata();
 
   bool HasKey(Key key) const;
 
   void Clear() { dictionary_.Clear(); }
 
@@ skipping 25 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_