Merge ScreenCapturerWinDirectx::frames_ and contexts_

webrtc/modules/desktop_capture/win/dxgi_duplicator_controller.h

 /*
  *  Copyright (c) 2016 The WebRTC project authors. All Rights Reserved.
  *
  *  Use of this source code is governed by a BSD-style license
  *  that can be found in the LICENSE file in the root of the source
  *  tree. An additional intellectual property rights grant can be found
  *  in the file PATENTS.  All contributing project authors may
  *  be found in the AUTHORS file in the root of the source tree.
  */
 
 #ifndef WEBRTC_MODULES_DESKTOP_CAPTURE_WIN_DXGI_DUPLICATOR_CONTROLLER_H_
 #define WEBRTC_MODULES_DESKTOP_CAPTURE_WIN_DXGI_DUPLICATOR_CONTROLLER_H_
 
 #include <D3DCommon.h>
 
 #include <memory>
 #include <vector>
 
 #include "webrtc/base/criticalsection.h"
 #include "webrtc/modules/desktop_capture/desktop_geometry.h"
 #include "webrtc/modules/desktop_capture/desktop_region.h"
 #include "webrtc/modules/desktop_capture/resolution_change_detector.h"
 #include "webrtc/modules/desktop_capture/shared_desktop_frame.h"
 #include "webrtc/modules/desktop_capture/win/d3d_device.h"
 #include "webrtc/modules/desktop_capture/win/dxgi_adapter_duplicator.h"
 
 namespace webrtc {
 
+class DxgiFrame;
+
 // A controller for all the objects we need to call Windows DirectX capture APIs
 // It's a singleton because only one IDXGIOutputDuplication instance per monitor
 // is allowed per application.
 //
 // Consumers should create a DxgiDuplicatorController::Context and keep it
 // throughout their lifetime, and pass it when calling Duplicate(). Consumers
 // can also call IsSupported() to determine whether the system supports DXGI
 // duplicator or not. If a previous IsSupported() function call returns true,
 // but a later Duplicate() returns false, this usually means the display mode is
 // changing. Consumers should retry after a while. (Typically 50 milliseconds,
 // but according to hardware performance, this time may vary.)
 class DxgiDuplicatorController {
  public:
-  // A context to store the status of a single consumer of
-  // DxgiDuplicatorController.
-  class Context {
-   public:
-    Context();
-    // Unregister this Context instance from all Dxgi duplicators during
-    // destructing.
-    ~Context();
-
-    // Reset current Context, so it will be reinitialized next time.
-    void Reset();
-
-   private:
-    friend class DxgiDuplicatorController;
-
-    // A Context will have an exactly same |identity_| as
-    // DxgiDuplicatorController, to ensure it has been correctly setted up after
-    // each DxgiDuplicatorController::Initialize().
-    int identity_ = 0;
-
-    // Child DxgiAdapterDuplicator::Context belongs to this Context.
-    std::vector<DxgiAdapterDuplicator::Context> contexts_;
-  };
-
   // A collection of D3d information we are interested on, which may impact
   // capturer performance or reliability.
   struct D3dInfo {
     // Each video adapter has its own D3D_FEATURE_LEVEL, so this structure
     // contains the minimum and maximium D3D_FEATURE_LEVELs current system
     // supports.
     // Both fields can be 0, which is the default value to indicate no valid
     // D3D_FEATURE_LEVEL has been retrieved from underlying OS APIs.
     D3D_FEATURE_LEVEL min_feature_level;
     D3D_FEATURE_LEVEL max_feature_level;
 
     // TODO(zijiehe): Add more fields, such as manufacturer name, mode, driver
     // version.
   };
 
+  enum class Result {
+    SUCCEEDED,
+    FRAME_PREPARE_FAILED,
+    INITIALIZATION_FAILED,
+    DUPLICATION_FAILED,
+    INVALID_MONITOR_ID,
+  };
+
   // Returns the singleton instance of DxgiDuplicatorController.
   static DxgiDuplicatorController* Instance();
 
   // Destructs current instance. We need to make sure COM components and their
-  // containers are destructed in correct order.
+  // containers are destructed in correct order. This function calls
+  // Deinitialize() to do the real work.
   ~DxgiDuplicatorController();
 
-  // All the following functions implicitly call Initialize() function if
-  // current instance has not been initialized.
+  // All the following public functions implicitly call Initialize() function.
 
   // Detects whether the system supports DXGI based capturer.
   bool IsSupported();
 
-  // Calls Deinitialize() function with lock. Consumers can call this function
-  // to force the DxgiDuplicatorController to be reinitialized to avoid an
-  // expected failure in next Duplicate() call.
-  void Reset();
-
   // Returns a copy of D3dInfo composed by last Initialize() function call.
   bool RetrieveD3dInfo(D3dInfo* info);
 
-  // Captures current screen and writes into target. Since we are using double
-  // buffering, |last_frame|.updated_region() is used to represent the not
-  // updated regions in current |target| frame, which should also be copied this
-  // time.
+  // Captures current screen and writes into |frame|.
   // TODO(zijiehe): Windows cannot guarantee the frames returned by each
   // IDXGIOutputDuplication are synchronized. But we are using a totally
   // different threading model than the way Windows suggested, it's hard to
   // synchronize them manually. We should find a way to do it.
-  bool Duplicate(Context* context, SharedDesktopFrame* target);
+  Result Duplicate(DxgiFrame* frame);
 
   // Captures one monitor and writes into target. |monitor_id| should >= 0. If
   // |monitor_id| is greater than the total screen count of all the Duplicators,
   // this function returns false.
-  bool DuplicateMonitor(Context* context,
-                        int monitor_id,
-                        SharedDesktopFrame* target);
+  Result DuplicateMonitor(DxgiFrame* frame, int monitor_id);
 
   // Returns dpi of current system. Returns an empty DesktopVector if system
   // does not support DXGI based capturer.
   DesktopVector dpi();
 
-  // Returns entire desktop size. Returns an empty DesktopRect if system does
-  // not support DXGI based capturer.
-  DesktopRect desktop_rect();
-
-  // Returns a DesktopSize to cover entire desktop_rect. This may be different
-  // than desktop_rect().size(), since top-left screen does not need to start
-  // from (0, 0).
-  DesktopSize desktop_size();
-
-  // Returns the size of one screen. |monitor_id| should be >= 0. If system does
-  // not support DXGI based capturer, or |monitor_id| is greater than the total
-  // screen count of all the Duplicators, this function returns an empty
-  // DesktopRect.
-  DesktopRect ScreenRect(int id);
-
   // Returns the count of screens on the system. These screens can be retrieved
   // by an integer in the range of [0, ScreenCount()). If system does not
   // support DXGI based capturer, this function returns 0.
   int ScreenCount();
 
  private:
+  // A context to store the status of a single consumer of
+  // DxgiDuplicatorController.
+  class Context {

[Sergey Ulanov, 2017/04/18 18:10:16]

This class is instantiated only in DxgiFrame. I'm not sure we want to keep it
here as a separate class. Maybe just add controller_id_ and contexts_ fields
directly in DxgiFrame? Or if you keep it it as a separate class then it's
probably better to move it to dxgi_frame.h
Otherwise it's not clear how to this class is used. The comment above also seems
outdated now.

[Hzj_jie, 2017/04/18 22:17:53]

Good point. Moving it into DxgiFrame is a good choice, though it's a little bit
strange that we do not have a DxgiDuplicatorController::Context. So meanwhile, I
added a using to forward the declaration to DxgiDuplicatorController.

Merging it with DxgiFrame is surely doable, but the change introduces two
"Setup" stages of DxgiFrame, i.e. DxgiFrame::Prepare() for SharedDesktopFrame,
and DxgiDuplicatorController::Setup(DxgiFrame*) for sub contexts. Merging these
two "Setup" stages is not so easy: the Prepare() is intentionally to be moved to
DxgiFrame to reduce the complexity of DxgiDuplicatorController. Setup() cannot
be moved to DxgiFrame, because it needs |duplicators_|.

+   public:
+    Context();
+    // Unregister this Context instance from all Dxgi duplicators during
+    // destructing.
+    ~Context();
+
+    // Reset current Context, so it will be reinitialized next time.
+    void Reset();
+
+   private:
+    friend class DxgiDuplicatorController;
+
+    // A Context will have an exactly same |identity_| as
+    // DxgiDuplicatorController, to ensure it has been correctly setted up after
+    // each DxgiDuplicatorController::Initialize().
+    int identity_ = 0;
+
+    // Child DxgiAdapterDuplicator::Context belongs to this Context.
+    std::vector<DxgiAdapterDuplicator::Context> contexts_;
+  };
+
   // Context calls private Unregister(Context*) function during
   // destructing.
   friend class Context;
+  // DxgiFrame uses Context.
+  friend class DxgiFrame;
 
   // A private constructor to ensure consumers to use
   // DxgiDuplicatorController::Instance().
   DxgiDuplicatorController();
 
+  // Does the real duplication work. Setting |monitor_id| < 0 to capture entire
+  // screen. This function calls Initialize(). And if the duplication failed,
+  // this function calls Deinitialize() to ensure the Dxgi components can be
+  // reinitialized next time.
+  Result DoDuplicate(DxgiFrame* frame, int monitor_id);
+
   // Unregisters Context from this instance and all DxgiAdapterDuplicator(s)
   // it owns.
   void Unregister(const Context* const context);
 
-  // All functions below should be called in |lock_| locked scope.
+  // All functions below should be called in |lock_| locked scope and should be
+  // after a successful Initialize().
 
-  // If current instance has not been initialized, executes DoInitialize
+  // If current instance has not been initialized, executes DoInitialize()
   // function, and returns initialize result. Otherwise directly returns true.
+  // This function may calls Deinitialize() if initialization failed.
   bool Initialize();
 
+  // Does the real initialization work, this function should only be called in
+  // Initialize().
   bool DoInitialize();
 
   // Clears all COM components referred by this instance. So next Duplicate()
   // call will eventually initialize this instance again.
   void Deinitialize();
 
   // A helper function to check whether a Context has been expired.
   bool ContextExpired(const Context* const context) const;
 
   // Updates Context if needed.
   void Setup(Context* context);
 
-  // Does the real duplication work. |monitor_id < 0| to capture entire screen.
-  bool DoDuplicate(Context* context,
-                   int monitor_id,
-                   SharedDesktopFrame* target);
-
   bool DoDuplicateUnlocked(Context* context,
                            int monitor_id,
                            SharedDesktopFrame* target);
 
   // Captures all monitors.
   bool DoDuplicateAll(Context* context, SharedDesktopFrame* target);
 
   // Captures one monitor.
   bool DoDuplicateOne(Context* context,
                       int monitor_id,
                       SharedDesktopFrame* target);
 
   // The minimum GetNumFramesCaptured() returned by |duplicators_|.
   int64_t GetNumFramesCaptured() const;
 
-  int ScreenCountUnlocked();
+  // Returns a DesktopSize to cover entire desktop_rect. This may be different
+  // than desktop_rect().size(), since top-left of the screen does not need to
+  // be started from (0, 0).
+  DesktopSize desktop_size() const;
+
+  // Returns the size of one screen. |id| should be >= 0. If system does not
+  // support DXGI based capturer, or |id| is greater than the total screen count
+  // of all the Duplicators, this function returns an empty DesktopRect.
+  DesktopRect ScreenRect(int id) const;
+
+  int ScreenCountUnlocked() const;
+
+  // Returns the desktop size of the selected screen |monitor_id|. Setting
+  // |monitor_id| < 0 to return the entire screen size.
+  DesktopSize SelectedDesktopSize(int monitor_id) const;
 
   // Retries DoDuplicateAll() for several times until GetNumFramesCaptured() is
   // large enough. Returns false if DoDuplicateAll() returns false, or
   // GetNumFramesCaptured() has never reached the requirement.
   // According to http://crbug.com/682112, dxgi capturer returns a black frame
   // during first several capture attempts.
   bool EnsureFrameCaptured(Context* context, SharedDesktopFrame* target);
 
   // This lock must be locked whenever accessing any of the following objects.
   rtc::CriticalSection lock_;
 
-  // A self-incremented integer to compare with the one in Context, to
-  // ensure a Context has been initialized after DxgiDuplicatorController.
+  // A self-incremented integer to compare with the one in Context. It ensures
+  // a Context instance is always initialized after DxgiDuplicatorController.
   int identity_ = 0;
   DesktopRect desktop_rect_;
   DesktopVector dpi_;
   std::vector<DxgiAdapterDuplicator> duplicators_;
   D3dInfo d3d_info_;
   ResolutionChangeDetector resolution_change_detector_;
 };
 
 }  // namespace webrtc
 
 #endif  // WEBRTC_MODULES_DESKTOP_CAPTURE_WIN_DXGI_DUPLICATOR_CONTROLLER_H_