blob: 4ba35f0b9d73c2240c44c8b7af4e3d2085129488 [file] [log] [blame]
// 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.
#include <memory>
#include <string>
#include "base/compiler_specific.h"
#include "base/macros.h"
#include "base/time/time.h"
#include "base/unguessable_token.h"
#include "base/values.h"
#include "build/build_config.h"
#include "media/base/media_export.h"
#include "media/base/video_rotation.h"
namespace gfx {
class Rect;
namespace media {
class MEDIA_EXPORT VideoFrameMetadata {
enum Key {
// Sources of VideoFrames use this marker to indicate that the associated
// VideoFrame can be overlayed, case in which its contents do not need to be
// further composited but displayed directly. Use Get/SetBoolean() for
// this Key.
// Video capture begin/end timestamps. Consumers can use these values for
// dynamic optimizations, logging stats, etc. Use Get/SetTimeTicks() for
// these keys.
// A counter that is increased by the producer of video frames each time
// it pushes out a new frame. By looking for gaps in this counter, clients
// can determine whether or not any frames have been dropped on the way from
// the producer between two consecutively received frames. Note that the
// counter may start at arbitrary values, so the absolute value of it has no
// meaning.
// A base::ListValue containing 4 integers representing x, y, width, height
// of the rectangular region of the frame that has changed since the frame
// with the directly preceding CAPTURE_COUNTER. If that frame was not
// received, typically because it was dropped during transport from the
// producer, clients must assume that the entire frame has changed.
// The rectangle is relative to the full frame data, i.e. [0, 0,
// coded_size().width(), coded_size().height()]. It does not have to be
// fully contained within visible_rect().
// Indicates that this frame must be copied to a new texture before use,
// rather than being used directly. Specifically this is required for
// WebView because of limitations about sharing surface textures between GL
// contexts.
// Indicates if the current frame is the End of its current Stream. Use
// Get/SetBoolean() for this Key.
// 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.
// 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.
// This is a boolean that signals that the video capture engine detects
// interactive content. One possible optimization that this signal can help
// with is remote content: adjusting end-to-end latency down to help the
// user better coordinate their actions.
// Use Get/SetBoolean for this key.
// This field represents the local time at which either: 1) the frame was
// generated, if it was done so locally; or 2) the targeted play-out time
// of the frame, if it was generated from a remote source. This value is NOT
// a high-resolution timestamp, and so it should not be used as a
// presentation time; but, instead, it should be used for buffering playback
// and for A/V synchronization purposes.
// Use Get/SetTimeTicks() for this key.
// 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.
// Sources of VideoFrames use this marker to indicate that an instance of
// VideoFrameExternalResources produced from the associated video frame
// should use read lock fences.
// Indicates that the frame is rotated.
// Android only: if set, then this frame is not suitable for overlay, even
// if ALLOW_OVERLAY is set. However, it allows us to process the overlay
// to see if it would have been promoted, if it were backed by a SurfaceView
// instead. This lets us figure out when SurfaceViews are appropriate.
// Android only: if set, then this frame's resource would like to be
// notified about its promotability to an overlay.
// This video frame comes from protected content.
// This video frame is protected by hardware. This option is valid only if
// PROTECTED_VIDEO is also set to true.
// An UnguessableToken that identifies VideoOverlayFactory that created
// this VideoFrame. It's used by Cast to help with video hole punch.
// Use Get/SetUnguessableToken() for this key.
// Whether this frame was decoded in a power efficient way.
// CompositorFrameMetadata variables associated with this frame. Used for
// remote debugging.
// Use Get/SetDouble() for these keys.
// TODO( Use a customized dictionary value instead of
// using these keys directly.
// If present, this field represents the local time at which the VideoFrame
// was decoded from whichever format it was encoded in.
// Use Get/SetTimeTicks() for this key.
bool HasKey(Key key) const;
void Clear() { dictionary_.Clear(); }
// Setters. Overwrites existing value, if present.
void SetBoolean(Key key, bool value);
void SetInteger(Key key, int value);
void SetDouble(Key key, double value);
void SetRotation(Key key, VideoRotation value);
void SetString(Key key, const std::string& value);
void SetTimeDelta(Key key, const base::TimeDelta& value);
void SetTimeTicks(Key key, const base::TimeTicks& value);
void SetUnguessableToken(Key key, const base::UnguessableToken& value);
void SetRect(Key key, const gfx::Rect& value);
void SetValue(Key key, std::unique_ptr<base::Value> value);
// Getters. Returns true if |key| is present, and its value has been set.
bool GetBoolean(Key key, bool* value) const WARN_UNUSED_RESULT;
bool GetInteger(Key key, int* value) const WARN_UNUSED_RESULT;
bool GetDouble(Key key, double* value) const WARN_UNUSED_RESULT;
bool GetRotation(Key key, VideoRotation* value) const WARN_UNUSED_RESULT;
bool GetString(Key key, std::string* value) const WARN_UNUSED_RESULT;
bool GetTimeDelta(Key key, base::TimeDelta* value) const WARN_UNUSED_RESULT;
bool GetTimeTicks(Key key, base::TimeTicks* value) const WARN_UNUSED_RESULT;
bool GetUnguessableToken(Key key, base::UnguessableToken* value) const
bool GetRect(Key key, gfx::Rect* value) const WARN_UNUSED_RESULT;
// Returns null if |key| was not present or value was not a ListValue.
const base::ListValue* GetList(Key key) const WARN_UNUSED_RESULT;
// Returns null if |key| was not present.
const base::Value* GetValue(Key key) const WARN_UNUSED_RESULT;
// Convenience method that returns true if |key| exists and is set to true.
bool IsTrue(Key key) const WARN_UNUSED_RESULT;
// For serialization.
std::unique_ptr<base::DictionaryValue> CopyInternalValues() const;
void MergeInternalValuesFrom(const base::Value& in);
const base::Value& GetInternalValues() const { return dictionary_; }
// Merges internal values from |metadata_source|.
void MergeMetadataFrom(const VideoFrameMetadata* metadata_source);
const base::Value* GetBinaryValue(Key key) const;
base::DictionaryValue dictionary_;
} // namespace media