Minor refactoring of support classes for video-device constraints.

content/renderer/media/media_stream_constraints_util_video_source.h

-// Copyright 2017 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 CONTENT_RENDERER_MEDIA_MEDIA_STREAM_CONSTRAINTS_UTIL_VIDEO_SOURCE_H_
-#define CONTENT_RENDERER_MEDIA_MEDIA_STREAM_CONSTRAINTS_UTIL_VIDEO_SOURCE_H_
-
-#include <iosfwd>
-#include <string>
-#include <vector>
-
-#include "content/common/content_export.h"
-#include "content/common/media/media_devices.mojom.h"
-#include "media/capture/video_capture_types.h"
-
-namespace blink {
-class WebString;
-class WebMediaConstraints;
-}
-
-namespace content {
-
-// Calculates and returns videoKind value for |format|.
-// See https://w3c.github.io/mediacapture-depth.
-blink::WebString CONTENT_EXPORT
-GetVideoKindForFormat(const media::VideoCaptureFormat& format);
-
-struct CONTENT_EXPORT VideoCaptureCapabilities {
-  VideoCaptureCapabilities();
-  VideoCaptureCapabilities(VideoCaptureCapabilities&& other);
-  ~VideoCaptureCapabilities();
-  VideoCaptureCapabilities& operator=(VideoCaptureCapabilities&& other);
-
-  // Each field is independent of each other.
-  std::vector<::mojom::VideoInputDeviceCapabilitiesPtr> device_capabilities;
-  std::vector<media::PowerLineFrequency> power_line_capabilities;
-};
-
-class CONTENT_EXPORT VideoCaptureSourceSettings {
- public:
-  VideoCaptureSourceSettings();
-  VideoCaptureSourceSettings(const VideoCaptureSourceSettings& other);
-  VideoCaptureSourceSettings(VideoCaptureSourceSettings&& other);
-  VideoCaptureSourceSettings(const std::string& device_id,
-                             const media::VideoCaptureFormat& format,
-                             ::mojom::FacingMode facing_mode,
-                             media::PowerLineFrequency power_line_frequency);
-  ~VideoCaptureSourceSettings();
-  VideoCaptureSourceSettings& operator=(
-      const VideoCaptureSourceSettings& other);
-  VideoCaptureSourceSettings& operator=(VideoCaptureSourceSettings&& other);
-
-  // Accessors for easier interaction with blink constraint classes.
-  blink::WebString GetFacingMode() const;
-  long GetPowerLineFrequency() const;
-  long GetWidth() const;
-  long GetHeight() const;
-  double GetFrameRate() const;
-  blink::WebString GetDeviceId() const;
-  blink::WebString GetVideoKind() const;
-
-  const media::VideoCaptureFormat& format() const { return format_; }
-  const std::string& device_id() const { return device_id_; }
-  ::mojom::FacingMode facing_mode() const { return facing_mode_; }
-  media::PowerLineFrequency power_line_frequency() const {
-    return power_line_frequency_;
-  }
-
- private:
-  std::string device_id_;
-  media::VideoCaptureFormat format_;
-  ::mojom::FacingMode facing_mode_;
-  media::PowerLineFrequency power_line_frequency_;
-};
-
-struct CONTENT_EXPORT VideoCaptureSourceSelectionResult {
-  VideoCaptureSourceSelectionResult();
-  VideoCaptureSourceSelectionResult(
-      const VideoCaptureSourceSelectionResult& other);
-  VideoCaptureSourceSelectionResult(VideoCaptureSourceSelectionResult&& other);
-  ~VideoCaptureSourceSelectionResult();
-  VideoCaptureSourceSelectionResult& operator=(
-      const VideoCaptureSourceSelectionResult& other);
-  VideoCaptureSourceSelectionResult& operator=(
-      VideoCaptureSourceSelectionResult&& other);
-
-  bool has_value() const { return failed_constraint_name == nullptr; }
-
-  VideoCaptureSourceSettings settings;
-  const char* failed_constraint_name;
-};
-
-// This function performs source and source-settings selection based on
-// the given |capabilities| and |constraints|.
-// Chromium performs constraint resolution in two steps. First, a source and its
-// settings are selected; then a track is created, connected to the source, and
-// finally the track settings are selected. This function implements an
-// algorithm for the first step. Sources are not a user-visible concept, so the
-// spec only specifies an algorithm for track settings.
-// This algorithm for sources is compatible with the spec algorithm for tracks,
-// as defined in https://w3c.github.io/mediacapture-main/#dfn-selectsettings,
-// but it is customized to account for differences between sources and tracks,
-// and to break ties when multiple source settings are equally good according to
-// the spec algorithm.
-// The main difference between a source and a track with regards to the spec
-// algorithm is that a candidate  source can support a range of values for some
-// constraints while a candidate track supports a single value. For example,
-// cropping allows a source with native resolution AxB to support the range of
-// resolutions from 1x1 to AxB.
-// Only candidates that satisfy the basic constraint set are valid. If no
-// candidate can satisfy the basic constraint set, this function returns
-// a result without a valid |settings| field and with the name of a failed
-// constraint in field |failed_constraint_name|. If at least one candidate that
-// satisfies the basic constraint set can be found, this function returns a
-// result with a valid |settings| field and a null |failed_constraint_name|.
-// If there are no candidates at all, this function returns a result with an
-// empty string in |failed_constraint_name| and without a valid |settings|
-// field.
-// The criteria to decide if a valid candidate is better than another one are as
-// follows:
-// 1. Given advanced constraint sets A[0],A[1]...,A[n], candidate C1 is better
-//    than candidate C2 if C1 supports the first advanced set for which C1's
-//    support is different than C2's support.
-//    Examples:
-//    * One advanced set, C1 supports it, and C2 does not. C1 is better.
-//    * Two sets, C1 supports both, C2 supports only the first. C1 is better.
-//    * Three sets, C1 supports the first and second set, C2 supports the first
-//      and third set. C1 is better.
-// 2. C1 is better than C2 if C1 has a smaller fitness distance than C2. The
-//    fitness distance depends on the ability of the candidate to support ideal
-//    values in the basic constraint set. This is the final criterion defined in
-//    the spec.
-// 3. C1 is better than C2 if C1 has a lower Chromium-specific custom distance
-//    from the basic constraint set. This custom distance is the sum of various
-//    constraint-specific custom distances.
-//    For example, if the constraint set specifies a resolution of exactly
-//    1000x1000 for a track, then a candidate with a resolution of 1200x1200
-//    is better than a candidate with a resolution of 2000x2000. Both settings
-//    satisfy the constraint set because cropping can be used to produce the
-//    track setting of 1000x1000, but 1200x1200 is considered better because it
-//    has lower resource usage. The same criteria applies for each advanced
-//    constraint set.
-// 4. C1 is better than C2 if its native settings have a smaller fitness
-//    distance. For example, if the ideal resolution is 1000x1000 and C1 has a
-//    native resolution of 1200x1200, while C2 has a native resolution of
-//    2000x2000, then C1 is better because it can support the ideal value with
-//    lower resource usage. Both C1 and C2 are better than a candidate C3 with
-//    a native resolution of 999x999, since C3 has a nonzero distance to the
-//    ideal value and thus has worse fitness according to step 2, even if C3's
-//    native fitness is better than C1's and C2's.
-// 5. C1 is better than C2 if its settings are closer to certain default
-//    settings that include the device ID, power-line frequency, resolution, and
-//    frame rate, in that order. Note that there is no default facing mode or
-//    aspect ratio.
-VideoCaptureSourceSelectionResult CONTENT_EXPORT
-SelectVideoCaptureSourceSettings(const VideoCaptureCapabilities& capabilities,
-                                 const blink::WebMediaConstraints& constraints);
-
-}  // namespace content
-
-#endif  // CONTENT_RENDERER_MEDIA_MEDIA_STREAM_CONSTRAINTS_UTIL_VIDEO_SOURCE_H_