Default implementation for the SettingsManagerInterface. More...

#include <src/windows/include/display_device/windows/settings_manager.h>

Inheritance diagram for display_device::SettingsManager:

Collaboration diagram for display_device::SettingsManager:

Public Member Functions
ApplyResult	applySettings (const SingleDisplayConfiguration &config) override
	Apply the provided configuration to the system.

EnumeratedDeviceList	enumAvailableDevices () const override
	Enumerate the available (active and inactive) devices.

const std::shared_ptr< AudioContextInterface > &	getAudioContextApi () const
	Get the audio context API.

std::string	getDisplayName (const std::string &device_id) const override
	Get the platform-specific display name associated with the device.

bool	resetPersistence () override
	Reset the persistence in case the settings cannot be reverted.

RevertResult	revertSettings () override
	Revert the applied configuration and restore the previous settings.

	SettingsManager (std::shared_ptr< WinDisplayDeviceInterface > dd_api, std::shared_ptr< AudioContextInterface > audio_context_api, std::unique_ptr< PersistentState > persistent_state, WinWorkarounds workarounds)

Public Member Functions inherited from display_device::SettingsManagerInterface
virtual	~SettingsManagerInterface ()=default
	Default virtual destructor.

Protected Member Functions
bool	prepareDisplayModes (const SingleDisplayConfiguration &config, const std::string &device_to_configure, const StringSet &additional_devices_to_configure, DdGuardFn &guard_fn, SingleDisplayConfigState &new_state, bool &system_settings_touched)
	Changes or restores the display modes based on the cached state, new state and configuration.

bool	prepareHdrStates (const SingleDisplayConfiguration &config, const std::string &device_to_configure, const StringSet &additional_devices_to_configure, DdGuardFn &guard_fn, SingleDisplayConfigState &new_state, bool &system_settings_touched)
	Changes or restores the HDR states based on the cached state, new state and configuration.

bool	preparePrimaryDevice (const SingleDisplayConfiguration &config, const std::string &device_to_configure, DdGuardFn &guard_fn, SingleDisplayConfigState &new_state, bool &system_settings_touched)
	Changes or restores the primary device based on the cached state, new state and configuration.

std::optional< std::tuple< SingleDisplayConfigState, std::string, StringSet > >	prepareTopology (const SingleDisplayConfiguration &config, const ActiveTopology &topology_before_changes, bool &release_context, bool &system_settings_touched)
	Preps the topology so that the further settings could be applied.

RevertResult	revertModifiedDisplayModes (const SingleDisplayConfigState::Modified &modified_state, DdGuardFn &guard_fn, bool &system_settings_touched)
	Revert display mode changes tracked in the modified settings state.

RevertResult	revertModifiedHdrStates (const SingleDisplayConfigState::Modified &modified_state, DdGuardFn &guard_fn, bool &system_settings_touched)
	Revert HDR changes tracked in the modified settings state.

RevertResult	revertModifiedPrimaryDevice (const SingleDisplayConfigState::Modified &modified_state, DdGuardFn &guard_fn, bool &system_settings_touched)
	Revert primary device changes tracked in the modified settings state.

RevertResult	revertModifiedSettings (const ActiveTopology &current_topology, bool &system_settings_touched, bool *switched_topology=nullptr)
	Try to revert the modified settings.

Additional Inherited Members
Public Types inherited from display_device::SettingsManagerInterface
enum class	ApplyResult { Ok , ApiTemporarilyUnavailable , DevicePrepFailed , PrimaryDevicePrepFailed , DisplayModePrepFailed , HdrStatePrepFailed , PersistenceSaveFailed }
	Outcome values when trying to apply settings. More...

enum class	RevertResult { Ok , ApiTemporarilyUnavailable , TopologyIsInvalid , SwitchingTopologyFailed , RevertingPrimaryDeviceFailed , RevertingDisplayModesFailed , RevertingHdrStatesFailed , PersistenceSaveFailed }
	Outcome values when trying to revert settings. More...

Detailed Description

Default implementation for the SettingsManagerInterface.

Constructor & Destructor Documentation

◆ SettingsManager()

display_device::SettingsManager::SettingsManager	(	std::shared_ptr< WinDisplayDeviceInterface >	dd_api,
		std::shared_ptr< AudioContextInterface >	audio_context_api,
		std::unique_ptr< PersistentState >	persistent_state,
		WinWorkarounds	workarounds )

explicit

Default constructor for the class.

Parameters

dd_api	A pointer to the Windows Display Device interface. Will throw on nullptr!
audio_context_api	[Optional] A pointer to the Audio Context interface.
persistent_state	A pointer to a class for managing persistence.
workarounds	Workaround settings for the APIs.

Member Function Documentation

◆ applySettings()

SettingsManager::ApplyResult display_device::SettingsManager::applySettings ( const SingleDisplayConfiguration & config )

nodiscardoverridevirtual

Apply the provided configuration to the system.

Parameters

config A desired configuration for the display device.

Returns: The apply result.

*Examples**

const SingleDisplayConfiguration config;
 
SettingsManagerInterface* iface = getIface(...);
const auto result = iface->applySettings(config);

Implements display_device::SettingsManagerInterface.

◆ enumAvailableDevices()

EnumeratedDeviceList display_device::SettingsManager::enumAvailableDevices ( ) const

nodiscardoverridevirtual

Enumerate the available (active and inactive) devices.

Returns: A list of available devices. Empty list can also be returned if an error has occurred.

*Examples**

const SettingsManagerInterface* iface = getIface(...);

const auto devices { iface->enumAvailableDevices() };

display_device::SettingsManagerInterface::enumAvailableDevices

virtual EnumeratedDeviceList enumAvailableDevices() const =0

Enumerate the available (active and inactive) devices.

Implements display_device::SettingsManagerInterface.

◆ getAudioContextApi()

const std::shared_ptr< AudioContextInterface > & display_device::SettingsManager::getAudioContextApi ( ) const

nodiscard

Get the audio context API.

Returns: Audio context API.

◆ getDisplayName()

std::string display_device::SettingsManager::getDisplayName ( const std::string & device_id ) const

nodiscardoverridevirtual

Get the platform-specific display name associated with the device.

Parameters

device_id A device to get display name for.

Returns: A display name or capture selector for the device, or an empty string if the device is inactive or not found. Empty string can also be returned if an error has occurred.

*Examples**

const std::string device_id { "MY_DEVICE_ID" };
const SettingsManagerInterface* iface = getIface(...);
const std::string display_name = iface->getDisplayName(device_id);

Implements display_device::SettingsManagerInterface.

◆ prepareDisplayModes()

bool display_device::SettingsManager::prepareDisplayModes	(	const SingleDisplayConfiguration &	config,
		const std::string &	device_to_configure,
		const StringSet &	additional_devices_to_configure,
		DdGuardFn &	guard_fn,
		SingleDisplayConfigState &	new_state,
		bool &	system_settings_touched )

nodiscardprotected

Changes or restores the display modes based on the cached state, new state and configuration.

Parameters

config	Configuration to be used for preparing display modes.
device_to_configure	The main device to be used for preparation.
additional_devices_to_configure	Additional devices that should be configured.
guard_fn	Reference to the guard function which will be set to restore original state (if needed) in case something else fails down the line.
new_state	Reference to the new state which is to be updated accordingly.
system_settings_touched	Inticates whether a "write" operation could have been performed on the OS.

Returns: True if no errors have occured, false otherwise.

◆ prepareHdrStates()

bool display_device::SettingsManager::prepareHdrStates	(	const SingleDisplayConfiguration &	config,
		const std::string &	device_to_configure,
		const StringSet &	additional_devices_to_configure,
		DdGuardFn &	guard_fn,
		SingleDisplayConfigState &	new_state,
		bool &	system_settings_touched )

nodiscardprotected

Changes or restores the HDR states based on the cached state, new state and configuration.

Parameters

config	Configuration to be used for preparing HDR states.
device_to_configure	The main device to be used for preparation.
additional_devices_to_configure	Additional devices that should be configured.
guard_fn	Reference to the guard function which will be set to restore original state (if needed) in case something else fails down the line.
new_state	Reference to the new state which is to be updated accordingly.
system_settings_touched	Inticates whether a "write" operation could have been performed on the OS.

Returns: True if no errors have occured, false otherwise.

◆ preparePrimaryDevice()

bool display_device::SettingsManager::preparePrimaryDevice	(	const SingleDisplayConfiguration &	config,
		const std::string &	device_to_configure,
		DdGuardFn &	guard_fn,
		SingleDisplayConfigState &	new_state,
		bool &	system_settings_touched )

nodiscardprotected

Changes or restores the primary device based on the cached state, new state and configuration.

Parameters

config	Configuration to be used for preparing primary device.
device_to_configure	The main device to be used for preparation.
guard_fn	Reference to the guard function which will be set to restore original state (if needed) in case something else fails down the line.
new_state	Reference to the new state which is to be updated accordingly.
system_settings_touched	Inticates whether a "write" operation could have been performed on the OS.

Returns: True if no errors have occured, false otherwise.

◆ prepareTopology()

std::optional< std::tuple< SingleDisplayConfigState, std::string, StringSet > > display_device::SettingsManager::prepareTopology	(	const SingleDisplayConfiguration &	config,
		const ActiveTopology &	topology_before_changes,
		bool &	release_context,
		bool &	system_settings_touched )

nodiscardprotected

Preps the topology so that the further settings could be applied.

Parameters

config	Configuration to be used for preparing topology.
topology_before_changes	The current topology before any changes.
release_context	Specifies whether the audio context should be released at the very end IF everything else has succeeded.
system_settings_touched	Inticates whether a "write" operation could have been performed on the OS.

Returns: A tuple of (new_state that is to be updated/persisted, device_to_configure, additional_devices_to_configure).

◆ resetPersistence()

bool display_device::SettingsManager::resetPersistence ( )

nodiscardoverridevirtual

Reset the persistence in case the settings cannot be reverted.

Returns: True if persistence was reset, false otherwise.

In case the settings cannot be reverted, because the display is turned or some other reason, this allows to "accept" the current state and start from scratch, but only if the persistence was cleared successfully.

*Examples**

SettingsManagerInterface* iface = getIface(...);
auto result = iface->applySettings(config);
if (result == ApplyResult::Ok) {
  // Wait for some time
  if (iface->revertSettings() != RevertResult::Ok) {
    // Wait for user input
    const bool user_wants_reset { true };
    if (user_wants_reset) {
      iface->resetPersistence();
    }
  }
}

Implements display_device::SettingsManagerInterface.

◆ revertModifiedDisplayModes()

SettingsManager::RevertResult display_device::SettingsManager::revertModifiedDisplayModes	(	const SingleDisplayConfigState::Modified &	modified_state,
		DdGuardFn &	guard_fn,
		bool &	system_settings_touched )

nodiscardprotected

Revert display mode changes tracked in the modified settings state.

Parameters

modified_state	Modified state data to revert.
guard_fn	Reference to the guard function which will be set to restore the current state if needed.
system_settings_touched	Indicates whether a "write" operation could have been performed on the OS.

Returns: Result enum indicating success or failure.

◆ revertModifiedHdrStates()

SettingsManager::RevertResult display_device::SettingsManager::revertModifiedHdrStates	(	const SingleDisplayConfigState::Modified &	modified_state,
		DdGuardFn &	guard_fn,
		bool &	system_settings_touched )

nodiscardprotected

Revert HDR changes tracked in the modified settings state.

Parameters

modified_state	Modified state data to revert.
guard_fn	Reference to the guard function which will be set to restore the current state if needed.
system_settings_touched	Indicates whether a "write" operation could have been performed on the OS.

Returns: Result enum indicating success or failure.

◆ revertModifiedPrimaryDevice()

SettingsManager::RevertResult display_device::SettingsManager::revertModifiedPrimaryDevice	(	const SingleDisplayConfigState::Modified &	modified_state,
		DdGuardFn &	guard_fn,
		bool &	system_settings_touched )

nodiscardprotected

Revert primary device changes tracked in the modified settings state.

Parameters

modified_state	Modified state data to revert.
guard_fn	Reference to the guard function which will be set to restore the current state if needed.
system_settings_touched	Indicates whether a "write" operation could have been performed on the OS.

Returns: Result enum indicating success or failure.

◆ revertModifiedSettings()

SettingsManager::RevertResult display_device::SettingsManager::revertModifiedSettings	(	const ActiveTopology &	current_topology,
		bool &	system_settings_touched,
		bool *	switched_topology = nullptr )

nodiscardprotected

Try to revert the modified settings.

Parameters

current_topology	Topology before this method is called.
system_settings_touched	Indicates whether a "write" operation could have been performed on the OS.
switched_topology	[Optional] Indicates whether the current topology was switched to revert settings.

Returns: Result enum indicating success or failure.

Warning: The method assumes that the caller will ensure restoring the topology in case of a failure!

◆ revertSettings()

SettingsManager::RevertResult display_device::SettingsManager::revertSettings ( )

nodiscardoverridevirtual

Revert the applied configuration and restore the previous settings.

Returns: True if settings were reverted or there was nothing to revert, false otherwise.

*Examples**

SettingsManagerInterface* iface = getIface(...);

const auto result = iface->revertSettings();

Implements display_device::SettingsManagerInterface.

The documentation for this class was generated from the following files:

src/windows/include/display_device/windows/settings_manager.h
src/windows/settings_manager_apply.cpp
src/windows/settings_manager_general.cpp
src/windows/settings_manager_revert.cpp

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ SettingsManager()

Member Function Documentation

◆ applySettings()

◆ enumAvailableDevices()

◆ getAudioContextApi()

◆ getDisplayName()

◆ prepareDisplayModes()

◆ prepareHdrStates()

◆ preparePrimaryDevice()

◆ prepareTopology()

◆ resetPersistence()

◆ revertModifiedDisplayModes()

◆ revertModifiedHdrStates()

◆ revertModifiedPrimaryDevice()

◆ revertModifiedSettings()

◆ revertSettings()