feat: Port more Windows API utils

src/windows/include/displaydevice/windows/types.h

@@ -4,7 +4,10 @@
 #include <windows.h>
 
 // system includes
+#include <map>
+#include <optional>
 #include <string>
+#include <unordered_map>
 #include <vector>
 
 namespace display_device {
@@ -34,6 +37,21 @@ namespace display_device {
     std::string m_device_id; /**< A device id (made up by us) that is identifies the device. */
   };
 
+  /**
+   * @brief Contains information about sources with identical adapter ids from matching paths.
+   */
+  struct PathSourceIndexData {
+    std::unordered_map<UINT32, std::size_t> m_source_id_to_path_index; /**< Maps source ids to its index in the path list. */
+    LUID m_adapter_id {}; /**< Adapter id shared by all source ids. */
+    std::optional<UINT32> m_active_source; /**< Currently active source id. */
+  };
+
+  /**
+   * @brief Ordered map of [DEVICE_ID -> PathSourceIndexData].
+   * @see PathSourceIndexData
+   */
+  using PathSourceIndexDataMap = std::map<std::string, PathSourceIndexData>;
+
   /**
    * @brief A LIST[LIST[DEVICE_ID]] structure which represents an active topology.
    *

src/windows/include/displaydevice/windows/winapilayerinterface.h

@@ -1,10 +1,5 @@
 #pragma once
 
-// system includes
-#include <optional>
-#include <string>
-#include <vector>
-
 // local includes
 #include "types.h"
 
@@ -59,8 +54,8 @@ namespace display_device {
      * (probably because it uses the EDID for the id generation and the current
      * virtual displays have incomplete EDID information). The "ContainerID"
      * also does not change if the physical device is plugged into a different
-     * port and seems to be very stable, however because of virtual displays
-     * other solution was used.
+     * port (which does not satisfy the "device id for the path" part) and is
+     * unstable for virtual displays, therefore other solution was used.
      *
      * The accepted solution was to use the "InstanceID" and EDID (just to be
      * on the safe side). "InstanceID" is semi-stable, it has some parts that

src/windows/include/displaydevice/windows/winutils.h → src/windows/include/displaydevice/windows/winapiutils.h

@@ -1,8 +1,5 @@
 #pragma once
 
-// system includes
-#include <optional>
-
 // local includes
 #include "winapilayerinterface.h"
 
@@ -45,6 +42,22 @@ namespace display_device::win_utils {
   [[nodiscard]] bool
   isActive(const DISPLAYCONFIG_PATH_INFO &path);
 
+  /**
+   * @brief Mark the display device path as active.
+   * @param path Path to mark.
+   * @see WinApiLayerInterface::queryDisplayConfig on how to get paths from the system.
+   *
+   * EXAMPLES:
+   * ```cpp
+   * DISPLAYCONFIG_PATH_INFO path;
+   * if (!isActive(path)) {
+   *   setActive(path);
+   * }
+   * ```
+   */
+  void
+  setActive(DISPLAYCONFIG_PATH_INFO &path);
+
   /**
    * @brief Get the source mode index from the path.
    *
@@ -66,6 +79,70 @@ namespace display_device::win_utils {
   [[nodiscard]] std::optional<UINT32>
   getSourceIndex(const DISPLAYCONFIG_PATH_INFO &path, const std::vector<DISPLAYCONFIG_MODE_INFO> &modes);
 
+  /**
+   * @brief Set the source mode index in the path.
+   * @param path Path to modify.
+   * @param index Index value to set or empty optional to mark the index as invalid.
+   * @see query_display_config on how to get paths and modes from the system.
+   *
+   * EXAMPLES:
+   * ```cpp
+   * DISPLAYCONFIG_PATH_INFO path;
+   * set_source_index(path, 5);
+   * set_source_index(path, std::nullopt);
+   * ```
+   */
+  void
+  setSourceIndex(DISPLAYCONFIG_PATH_INFO &path, const std::optional<UINT32> &index);
+
+  /**
+   * @brief Set the target mode index in the path.
+   * @param path Path to modify.
+   * @param index Index value to set or empty optional to mark the index as invalid.
+   * @see query_display_config on how to get paths and modes from the system.
+   *
+   * EXAMPLES:
+   * ```cpp
+   * DISPLAYCONFIG_PATH_INFO path;
+   * set_target_index(path, 5);
+   * set_target_index(path, std::nullopt);
+   * ```
+   */
+  void
+  setTargetIndex(DISPLAYCONFIG_PATH_INFO &path, const std::optional<UINT32> &index);
+
+  /**
+   * @brief Set the desktop mode index in the path.
+   * @param path Path to modify.
+   * @param index Index value to set or empty optional to mark the index as invalid.
+   * @see query_display_config on how to get paths and modes from the system.
+   *
+   * EXAMPLES:
+   * ```cpp
+   * DISPLAYCONFIG_PATH_INFO path;
+   * set_desktop_index(path, 5);
+   * set_desktop_index(path, std::nullopt);
+   * ```
+   */
+  void
+  setDesktopIndex(DISPLAYCONFIG_PATH_INFO &path, const std::optional<UINT32> &index);
+
+  /**
+   * @brief Set the clone group id in the path.
+   * @param path Path to modify.
+   * @param id Id value to set or empty optional to mark the id as invalid.
+   * @see query_display_config on how to get paths and modes from the system.
+   *
+   * EXAMPLES:
+   * ```cpp
+   * DISPLAYCONFIG_PATH_INFO path;
+   * set_clone_group_id(path, 5);
+   * set_clone_group_id(path, std::nullopt);
+   * ```
+   */
+  void
+  setCloneGroupId(DISPLAYCONFIG_PATH_INFO &path, const std::optional<UINT32> &id);
+
   /**
    * @brief Get the source mode from the list at the specified index.
    *
@@ -123,4 +200,24 @@ namespace display_device::win_utils {
    */
   [[nodiscard]] std::optional<ValidatedDeviceInfo>
   getDeviceInfoForValidPath(const WinApiLayerInterface &w_api, const DISPLAYCONFIG_PATH_INFO &path, bool must_be_active);
+
+  /**
+   * @brief Collect arbitrary source data from provided paths.
+   *
+   * This function filters paths that can be used later on and
+   * collects for a quick lookup.
+   *
+   * @param paths List of paths.
+   * @returns Data for valid paths.
+   * @see WinApiLayerInterface::queryDisplayConfig on how to get paths from the system.
+   *
+   * EXAMPLES:
+   * ```cpp
+   * std::vector<DISPLAYCONFIG_PATH_INFO> paths;
+   * const WinApiLayerInterface* iface = getIface(...);
+   * const auto path_data = collectSourceDataForMatchingPaths(*iface, paths);
+   * ```
+   */
+  [[nodiscard]] PathSourceIndexDataMap
+  collectSourceDataForMatchingPaths(const WinApiLayerInterface &w_api, const std::vector<DISPLAYCONFIG_PATH_INFO> &paths);
 }  // namespace display_device::win_utils