DisplayState.TryFunctionalize(DisplayStateFunctionalizeOptions) Method

Definition

Namespace:

Windows.Devices.Display.Core

Attempts to "functionalize" this DisplayState by trying to evaluate the best modes on all paths given all specified DisplayPath properties as constraints. This method then (optionally, see Remarks) updates all DisplayPath and DisplayView properties with the results of the functionalization. In particular, all DisplayPath and DisplayView properties set to null will have their values computed and set.

public:
 virtual DisplayStateOperationResult ^ TryFunctionalize(DisplayStateFunctionalizeOptions options) = TryFunctionalize;

DisplayStateOperationResult TryFunctionalize(DisplayStateFunctionalizeOptions const& options);

public DisplayStateOperationResult TryFunctionalize(DisplayStateFunctionalizeOptions options);

function tryFunctionalize(options)

Public Function TryFunctionalize (options As DisplayStateFunctionalizeOptions) As DisplayStateOperationResult

Parameters

options

DisplayStateFunctionalizeOptions

The DisplayStateFunctionalizeOptions to use.

Returns

DisplayStateOperationResult

A DisplayStateOperationResult value detailing the success or failure of the operation.

Remarks

Use the ValidateTopologyOnly option to prevent updating all DisplayPath properties with the results of the functionalization.

Note that calling TryApply also implicitly functionalizes the state before applying it to the system, but TryApply never updates this state's DisplayPath properties with the results of the functionalization.

Functionalizing a DisplayState can be a fairly expensive operation, since it involves querying display drivers and comparing many possible modes. The operation will usually be cheaper if you set more of your DisplayPath properties before calling this method (or calling TryApply), since it reduces the amount of work needed to evaluate the "best" mode on a given path.

Using TryFunctionalize to determine whether the current state can be functionalized before calling TryApply is a good practice, since TryApply is always more expensive than TryFunctionalize. Once TryFunctionalize succeeds, a subsequent call to TryApply will be cheaper, since it no longer has to do the work of functionalizing modes.