ID3D11DeviceContext1::SwapDeviceContextState method (d3d11_1.h)
Activates the given context state object and changes the current device behavior to Direct3D 11, Direct3D 10.1, or Direct3D 10.
Syntax
void SwapDeviceContextState(
[in] ID3DDeviceContextState *pState,
[out, optional] ID3DDeviceContextState **ppPreviousState
);
Parameters
[in] pState
A pointer to the ID3DDeviceContextState interface for the context state object that was previously created through the ID3D11Device1::CreateDeviceContextState method. If SwapDeviceContextState is called with pState set to NULL, the call has no effect.
[out, optional] ppPreviousState
A pointer to a variable that receives a pointer to the ID3DDeviceContextState interface for the previously-activated context state object.
Return value
None
Remarks
SwapDeviceContextState changes device behavior. This device behavior depends on the emulated interface that you passed to the EmulatedInterface parameter of the ID3D11Device1::CreateDeviceContextState method when you created the context state object.
SwapDeviceContextState is not supported on a deferred context.
SwapDeviceContextState disables the incompatible device interfaces ID3D10Device, ID3D10Device1, ID3D11Device, and ID3D11Device1. When a context state object is active, the runtime disables certain methods on the device and context interfaces. A context state object that is created with __uuidof(ID3D11Device1) or __uuidof(ID3D11Device) turns off most of the Direct3D 10 device interfaces. A context state object that is created with __uuidof(ID3D10Device1) or __uuidof(ID3D10Device) turns off most of the ID3D11DeviceContext methods.
For more information about this behavior, see ID3D11Device1::CreateDeviceContextState.
SwapDeviceContextState activates the context state object specified by pState. This means that the device behaviors that are associated with the context state object's feature level and compatible interface are activated on the Direct3D device until the next call to SwapDeviceContextState. In addition, any state that was saved when this context state object was last active is now reactivated, so that the previous state is replaced.
SwapDeviceContextState sets ppPreviousState to the most recently activated context state object. The object allows the caller to save and then later restore the previous device state. This behavior is useful in a plug-in architecture such as Direct2D that shares a Direct3D device with its plug-ins. A Direct2D interface can use context state objects to save and restore the application's state.
If the caller did not previously call the ID3D11Device1::CreateDeviceContextState method to create a previous context state object, SwapDeviceContextState sets ppPreviousState to the default context state object. In either case, usage of SwapDeviceContextState is the same.
The feature level that is specified by the application, and that is chosen by the context state object from the acceptable list that the application supplies to ID3D11Device1::CreateDeviceContextState, controls the feature level of the immediate context whenever the context state object is active. Because the Direct3D 11 device is free-threaded, the device methods cannot query the current immediate context feature level. Instead, the device runs at a feature level that is the maximum of all previously created context state objects' feature levels. This means that the device's feature level can increase dynamically.
The feature level of the context state object controls the functionality available from the immediate context. However, to maintain the free-threaded contract of the Direct3D 11 device methods—the resource-creation methods in particular—the upper-bound feature level of all created context state objects controls the set of resources that the device creates.
Because the context state object interface is published by the immediate context, the interface requires the same threading model as the immediate context. Specifically, SwapDeviceContextState is single-threaded with respect to the other immediate context methods and with respect to the equivalent methods of ID3D10Device.
Crucially, because only one of the Direct3D 10 or Direct3D 11 ref-count behaviors can be available at a time, one of the Direct3D 10 and Direct3D 11 interfaces must break its ref-count contract. To avoid this situation, the activation of a context state object turns off the incompatible version interface. Also, if you call a method of an incompatible version interface, the call silently fails if the method has return type void, returns an HRESULT value of E_INVALIDARG, or sets any out parameter to NULL.
When you switch from Direct3D 11 mode to either Direct3D 10 mode or Direct3D 10.1 mode, the binding behavior of the device changes. Specifically, the final release of a resource induces unbind in Direct3D 10 mode or Direct3D 10.1 mode. During final release an application releases all of the resource's references, including indirect references such as the linkage from view to resource, and the linkage from context state object to any of the context state object's bound resources. Any bound resource to which the application has no reference is unbound and destroyed, in order to maintain the Direct3D 10 behavior.
SwapDeviceContextState does not affect any state that ID3D11VideoContext sets.
Command lists that are generated by deferred contexts do not hold a reference to context state objects and are not affected by future updates to context state objects.
No asynchronous objects are affected by SwapDeviceContextState. For example, if a query is active before a call to SwapDeviceContextState, it is still active after the call.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 8 and Platform Update for Windows 7 [desktop apps | UWP apps] |
| Minimum supported server | Windows Server 2012 and Platform Update for Windows Server 2008 R2 [desktop apps | UWP apps] |
| Target Platform | Windows |
| Header | d3d11_1.h |
| Library | D3D11.lib |