ID3D11DeviceContext1::PSSetConstantBuffers1 method (d3d11_1.h)
Sets the constant buffers that the pixel shader pipeline stage uses, and enables the shader to access other parts of the buffer.
Syntax
void PSSetConstantBuffers1(
[in] UINT StartSlot,
[in] UINT NumBuffers,
[in, optional] ID3D11Buffer * const *ppConstantBuffers,
[in, optional] const UINT *pFirstConstant,
[in, optional] const UINT *pNumConstants
);
Parameters
[in] StartSlot
Type: UINT
Index into the device's zero-based array to begin setting constant buffers to (ranges from 0 to D3D11_COMMONSHADER_CONSTANT_BUFFER_API_SLOT_COUNT - 1).
[in] NumBuffers
Type: UINT
Number of buffers to set (ranges from 0 to D3D11_COMMONSHADER_CONSTANT_BUFFER_API_SLOT_COUNT - StartSlot).
[in, optional] ppConstantBuffers
Type: ID3D11Buffer*
Array of constant buffers being given to the device.
[in, optional] pFirstConstant
Type: const UINT*
An array that holds the offsets into the buffers that ppConstantBuffers specifies. Each offset specifies where, from the shader's point of view, each constant buffer starts. Each offset is measured in shader constants, which are 16 bytes (4*32-bit components). Therefore, an offset of 16 indicates that the start of the associated constant buffer is 256 bytes into the constant buffer. Each offset must be a multiple of 16 constants.
[in, optional] pNumConstants
Type: const UINT*
An array that holds the numbers of constants in the buffers that ppConstantBuffers specifies. Each number specifies the number of constants that are contained in the constant buffer that the shader uses. Each number of constants starts from its respective offset that is specified in the pFirstConstant array. Each number of constants must be a multiple of 16 constants, in the range [0..4096].
Return value
None
Remarks
To enable the shader to access other parts of the buffer, call PSSetConstantBuffers1 instead of PSSetConstantBuffers. PSSetConstantBuffers1 has additional parameters pFirstConstant and pNumConstants.
The runtime drops the call to PSSetConstantBuffers1 if the numbers of constants to which pNumConstants points is larger than the maximum constant buffer size that is supported by shaders. The maximum constant buffer size that is supported by shaders holds 4096 constants, where each constant has four 32-bit components.
The values in the elements of the pFirstConstant and pFirstConstant + pNumConstants arrays can exceed the length of each buffer; from the shader's point of view, the constant buffer is the intersection of the actual memory allocation for the buffer and the following window (range):
[value in an element of pFirstConstant, value in an element of pFirstConstant + value in an element of pNumConstants]
That is, the window is the range is from (value in an element of pFirstConstant) to (value in an element of pFirstConstant + value in an element of pNumConstants).
The runtime also drops the call to PSSetConstantBuffers1 on existing drivers that do not support this offsetting.
The runtime will emulate this feature for feature level 9.1, 9.2, and 9.3; therefore, this feature is supported for feature level 9.1, 9.2, and 9.3. This feature is always available on new drivers for feature level 10 and higher.
From the shader’s point of view, element [0] in the constant buffers array is the constant at pFirstConstant.
Out of bounds access to the constant buffers from the shader to the range that is defined by pFirstConstant and pNumConstants returns 0.
If pFirstConstant and pNumConstants arrays are NULL, you get the same result as if you were binding the entire buffer into view. You get this same result if you call the PSSetConstantBuffers method. If the buffer is larger than the maximum constant buffer size that is supported by shaders (4096 elements), the shader can access only the first 4096 constants.
If either pFirstConstant or pNumConstants is NULL, the other parameter must also be NULL.
Calling PSSetConstantBuffers1 with command list emulation
The runtime's command list emulation of PSSetConstantBuffers1 sometimes doesn't actually change the offsets or sizes for the arrays of constant buffers. This behavior occurs when PSSetConstantBuffers1 doesn't effectively change the constant buffers at the beginning and end of the range of slots that you set to update. This section shows how to work around this behavior.Here is the code to check whether either the runtime emulates command lists or the driver supports command lists:
HRESULT hr = S_OK;
bool needWorkaround = false;
D3D11_DEVICE_CONTEXT_TYPE contextType = pDeviceContext->GetType();
if( D3D11_DEVICE_CONTEXT_DEFERRED == contextType)
{
D3D11_FEATURE_DATA_THREADING threadingCaps = { FALSE, FALSE };
hr = pDevice->CheckFeatureSupport( D3D11_FEATURE_THREADING, &threadingCaps, sizeof(threadingCaps) );
if( SUCCEEDED(hr) && !threadingCaps.DriverCommandLists )
{
needWorkaround = true; // the runtime emulates command lists.
}
}
If the runtime emulates command lists, you need to use one of these code snippets:
If you change the offset and size on only a single constant buffer, set the constant buffer to NULL first:
pDeviceContext->PSSetConstantBuffers1(0, 1, &CBuf, &Offset, &Count);
if( needWorkaround )
{
// Workaround for command list emulation
pDeviceContext->PSSetConstantBuffers(0, 1, &NullCBuf);
}
pDeviceContext->PSSetConstantBuffers1(0, 1, &CBuf, &Offset, &Count);
If you change multiple constant buffers, set the first and last constant buffers of the range to NULL first:
pDeviceContext->PSSetConstantBuffers1(0, 4, &CBufs, &Offsets, &Counts);
if( needWorkaround )
{
// Workaround for command list emulation
pDeviceContext->PSSetConstantBuffers(0, 1, &NullCBuf);
pDeviceContext->PSSetConstantBuffers(3, 1, &NullCBuf);
}
pDeviceContext->PSSetConstantBuffers1(0, 4, &CBufs, &Offsets, &Counts);
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 |