ID3D11Device1::CreateDeviceContextState method (d3d11_1.h)

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

Syntax

HRESULT CreateDeviceContextState(
                  UINT                    Flags,
  [in]            const D3D_FEATURE_LEVEL *pFeatureLevels,
                  UINT                    FeatureLevels,
                  UINT                    SDKVersion,
                  REFIID                  EmulatedInterface,
  [out, optional] D3D_FEATURE_LEVEL       *pChosenFeatureLevel,
  [out, optional] 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, 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.

[in] pFeatureLevels

Type: const D3D_FEATURE_LEVEL*

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, ID3D10Device1, ID3D11Device, and ID3D11Device1 interfaces. See Remarks.

[out, optional] pChosenFeatureLevel

Type: D3D_FEATURE_LEVEL*

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.

[out, optional] ppContextState

Type: ID3DDeviceContextState**

The address of a pointer to an ID3DDeviceContextState object that represents the state of a 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 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 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 Direct3D 10 equivalents. Because the Direct3D 11 context is active, a Direct3D 10 interface is inactive when you first retrieve it via QueryInterface. This means that you cannot immediately pass a Direct3D 10 interface that you retrieved from a Direct3D 11 device to a function. You must first call SwapDeviceContextState to activate a 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 that the runtime does not disable because they are not immediate context methods.

Windows Phone 8: This API is supported.

Requirements

See also

ID3D11Device1