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

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

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

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

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

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

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

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