ID3D11Device1::CreateDeviceContextState Method

Creates a context state object that holds all Microsoft Direct3D state and some Microsoft Direct3D behavior.

Note Some API items are indicated as (desktop) here, indicating that the API item is desktop-only, not for Xbox titles. Such API items are wrapped in #pragma region Desktop Family, in the .h file.

For example, in the present topic, the following items are desktop-only:

• ID3D10Device1 and its methods, in d3d10_1.h.

Syntax

public:
HRESULT CreateDeviceContextState(
         UINT Flags,
         const D3D_FEATURE_LEVEL *pFeatureLevels,
         UINT FeatureLevels,
         UINT SDKVersion,
         REFIID EmulatedInterface,
         D3D_FEATURE_LEVEL *pChosenFeatureLevel,
         ID3DDeviceContextState **ppContextState
)  

Parameters

Flags
Type: UINT 

A combination of D3D11_1_CREATE_DEVICE_CONTEXT_STATE_FLAG values that are combined by using a bitwise OR operation. The resulting value specifies how to create the context state object. The D3D11_1_CREATE_DEVICE_CONTEXT_STATE_SINGLETHREADED flag is currently the only defined flag. If the original device was created with D3D11_CREATE_DEVICE_SINGLETHREADED (this flag is supported for Windows only, not Xbox One), you must create all context state objects from that device with the D3D11_1_CREATE_DEVICE_CONTEXT_STATE_SINGLETHREADED flag.

If you set the single-threaded flag for both the context state object and the device, you guarantee that you will call the whole set of context methods and device methods only from one thread. You therefore do not need to use critical sections to synchronize access to the device context, and the runtime can avoid working with those processor-intensive critical sections.

pFeatureLevels
Type: D3D_FEATURE_LEVEL *

[in]

A pointer to an array of D3D_FEATURE_LEVEL values. The array can contain elements from the following list and determines the order of feature levels for which creation is attempted. Unlike D3D11CreateDevice, you can’t set pFeatureLevels to NULL because there is no default feature level array.

{
  D3D_FEATURE_LEVEL_11_1,
  D3D_FEATURE_LEVEL_11_0,
  D3D_FEATURE_LEVEL_10_1,
  D3D_FEATURE_LEVEL_10_0,
  D3D_FEATURE_LEVEL_9_3,
  D3D_FEATURE_LEVEL_9_2,
  D3D_FEATURE_LEVEL_9_1,
};  

FeatureLevels
Type: UINT 

The number of elements in pFeatureLevels. Unlike D3D11CreateDevice, you must set FeatureLevels to greater than 0 because you can’t set pFeatureLevels to NULL.

SDKVersion
Type: UINT 

The SDK version. You must set this parameter to D3D11_SDK_VERSION.

EmulatedInterface
Type: REFIID 

The globally unique identifier (GUID) for the emulated interface. This value specifies the behavior of the device when the context state object is active. Valid values are obtained by using the __uuidof operator on the ID3D10Device (desktop), ID3D10Device1 (desktop), ID3D11Device, and ID3D11Device1 interfaces. See Remarks.

pChosenFeatureLevel
Type: D3D_FEATURE_LEVEL *

[out, optional] A pointer to a variable that receives a D3D_FEATURE_LEVEL value from the pFeatureLevels array. This is the first array value with which CreateDeviceContextState succeeded in creating the context state object. If the call to CreateDeviceContextState fails, the variable pointed to by pChosenFeatureLevel is set to zero.

ppContextState
Type: ID3DDeviceContextState **

[out, optional] The address of a pointer to an ID3DDeviceContextState object that represents the state of a Microsoft Direct3D device.

Return value

Type: HRESULT 

This method returns one of the Direct3D 11 return codes.

Remarks

The REFIID value of the emulated interface is a GUID obtained by use of the __uuidof operator. For example, __uuidof(ID3D11Device) gets the GUID of the interface to a Microsoft Direct3D 11 device.

Call the ID3D11DeviceContext1::SwapDeviceContextState method to activate the context state object. When the context state object is active, the device behaviors that are associated with both the context state object’s feature level and its compatible interface are activated on the Microsoft Direct3D device until the next call to SwapDeviceContextState.

When a context state object is active, the runtime disables certain methods on the device and context interfaces. For example, a context state object that is created with __uuidof(ID3D11Device) will cause the runtime to turn off most of the Microsoft Direct3D 10 device interfaces, and a context state object that is created with __uuidof(ID3D10Device1) or __uuidof(ID3D10Device) will cause the runtime to turn off most of the ID3D11DeviceContext methods. This behavior ensures that a user of either emulated interface cannot set device state that the other emulated interface is unable to express. This restriction helps guarantee that the ID3D10Device1 emulated interface (desktop) accurately reflects the full state of the pipeline and that the emulated interface will not operate contrary to its original interface definition.

For example, suppose the tessellation stage is made active through the ID3D11DeviceContext interface when you create the device through D3D11CreateDevice or D3D11CreateDeviceAndSwapChain, instead of through the Microsoft Direct3D 10 equivalents. Because the Microsoft Direct3D 11 context is active, a Microsoft Direct3D 10 interface is inactive when you first retrieve it via QueryInterface. This means that you cannot immediately pass a Microsoft Direct3D 10 interface that you retrieved from a Microsoft Direct3D 11 device to a function. You must first call SwapDeviceContextState to activate a Microsoft Direct3D 10-compatible context state object.

The following table shows the methods that are active and inactive for each emulated interface.

The following table shows the immediate context methods that the runtime disables when the indicated context state objects are active.

The following table shows the immediate context methods that the runtime does not disable when the indicated context state objects are active.

The following table shows the ID3D10Device interface methods (desktop) that the runtime does not disable because they are not immediate context methods.

Requirements

Header: Declared in d3d11_x.h (d3d11_1.h on other Windows platforms).

Library: Use d3d11_x.lib (d3d11.lib on other Windows platforms).

See also

ID3D11Device1

ID3D11Device1 Members