Compiles Microsoft High Level Shader Language (HLSL) code into bytecode for a given target.

Syntax

HRESULT D3DCompile2(  [in]            LPCVOID                pSrcData,  [in]            SIZE_T                 SrcDataSize,  [in, optional]  LPCSTR                 pSourceName,  [in, optional]  const D3D_SHADER_MACRO *pDefines,  [in, optional]  ID3DInclude            *pInclude,  [in]            LPCSTR                 pEntrypoint,  [in]            LPCSTR                 pTarget,  [in]            UINT                   Flags1,  [in]            UINT                   Flags2,  [in]            UINT                   SecondaryDataFlags,  [in, optional]  LPCVOID                pSecondaryData,  [in]            SIZE_T                 SecondaryDataSize,  [out]           ID3DBlob               **ppCode,  [out, optional] ID3DBlob               **ppErrorMsgs);

Parameters

[in] pSrcData

Type:LPCVOID

A pointer to uncompiled shader data (ASCII HLSL code).

[in] SrcDataSize

Type:SIZE_T

The size, in bytes, of the block of memory thatpSrcData points to.

[in, optional] pSourceName

Type:LPCSTR

An optional pointer to a constant null-terminated string containing the name that identifies the source data to use in error messages. If not used, set toNULL.

[in, optional] pDefines

Type:constD3D_SHADER_MACRO*

An optional array ofD3D_SHADER_MACRO structures that define shader macros. Each macro definition contains a name and a null-terminated definition. If not used, set toNULL. The last structure in the array serves as a terminator and must have all members set toNULL.

[in, optional] pInclude

Type:ID3DInclude*

A pointer to anID3DInclude interface that the compiler uses to handle include files. If you set this parameter toNULL and the shader contains a #include, a compile error occurs. You can pass theD3D_COMPILE_STANDARD_FILE_INCLUDE macro, which is a pointer to a default include handler. This default include handler includes files that are relative to the current directory and files that are relative to the directory of the initial source file. When you useD3D_COMPILE_STANDARD_FILE_INCLUDE, you must specify the source file name in thepSourceName parameter; the compiler will derive the initial relative directory frompSourceName.

#define D3D_COMPILE_STANDARD_FILE_INCLUDE ((ID3DInclude*)(UINT_PTR)1)

[in] pEntrypoint

Type:LPCSTR

A pointer to a constant null-terminated string that contains the name of the shader entry point function where shader execution begins. When you compile an effect,D3DCompile2 ignorespEntrypoint; we recommend that you setpEntrypoint toNULL because it is good programming practice to set a pointer parameter toNULL if the called function will not use it.

[in] pTarget

Type:LPCSTR

A pointer to a constant null-terminated string that specifies the shader target or set of shader features to compile against. The shader target can be a shader model (for example, shader model 2, shader model 3, shader model 4, or shader model 5). The target can also be an effect type (for example, fx_4_1). For info about the targets that various profiles support, seeSpecifying Compiler Targets.

[in] Flags1

Type:UINT

A combination of shaderD3D compile constants that are combined by using a bitwiseOR operation. The resulting value specifies how the compiler compiles the HLSL code.

[in] Flags2

Type:UINT

A combination of effectD3D compile effect constants that are combined by using a bitwiseOR operation. The resulting value specifies how the compiler compiles the effect. When you compile a shader and not an effect file,D3DCompile2 ignoresFlags2; we recommend that you setFlags2 to zero because it is good programming practice to set a nonpointer parameter to zero if the called function will not use it.

[in] SecondaryDataFlags

Type:UINT

A combination of the following flags that are combined by using a bitwiseOR operation. The resulting value specifies how the compiler compiles the HLSL code.

IfpSecondaryData isNULL, set to zero.

[in, optional] pSecondaryData

Type:LPCVOID

A pointer to secondary data. If you don't pass secondary data, set toNULL. Use this secondary data to align UAV slots in two shaders. Suppose shader A has UAVs and they are bound to some slots. To compile shader B such that UAVs with the same names are mapped in B to the same slots as in A, pass A’s byte code toD3DCompile2 as the secondary data.

[in] SecondaryDataSize

Type:SIZE_T

The size, in bytes, of the block of memory thatpSecondaryData points to. IfpSecondaryData isNULL, set to zero.

[out] ppCode

Type:ID3DBlob**

A pointer to a variable that receives a pointer to theID3DBlob interface that you can use to access the compiled code.

[out, optional] ppErrorMsgs

Type:ID3DBlob**

A pointer to a variable that receives a pointer to theID3DBlob interface that you can use to access compiler error messages, orNULL if there are no errors.

Return value

Type:HRESULT

Returns one of theDirect3D 11 return codes.

Remarks

The difference betweenD3DCompile2 andD3DCompile is thatD3DCompile2 takes some optional parameters (SecondaryDataFlags,pSecondaryData andSecondaryDataSize) that can be used to control some aspects of how bytecode is generated. Refer to the descriptions of these parameters for more details. There is no difference otherwise to the efficiency of the bytecode generated betweenD3DCompile2 andD3DCompile.

Compiling shaders for UWP

To compile offline shaders the recommended approach is to use theEffect-compiler tool. If you can't compile all of your shaders ahead of time, then consider compiling the more expensive ones and the ones that your startup and most performance-sensitive paths require, and compiling the rest at runtime. You can use a process similar to the following to compile a loaded or generated shader in a UWP application without blocking your user interface thread.

• Using Visual Studio 2015+ to develop the UWP app, add the new item "shader.hlsl".

  • In theSolution Folder view of Visual Studio, select theshaders.hlsl item, right-click forProperties.
  • Make sure the itemContent is set toYes.
  • Make sure theItem Type is set toText.
  • Add a button to XAML, name it appropriately ("TheButton" in this example), and add aClick handler.

• Now add these includes to your .cpp file:

  #include <ppltasks.h>#include <d3dcompiler.h>#include <Robuffer.h>

• Use the following code to callD3DCompile2. Note that there's no error checking or handling here, and also that this code demonstrates that you can do both I/O and compilation in the background, which leaves your UI more responsive.

void App1::DirectXPage::TheButton_Click(Platform::Object^ sender, Windows::UI::Xaml::RoutedEventArgs^ e){  std::shared_ptr<Microsoft::WRL::ComPtr<ID3DBlob>> blobRef = std::make_shared<Microsoft::WRL::ComPtr<ID3DBlob>>();  // Load a file and compile it.  auto fileOp = Windows::ApplicationModel::Package::Current->InstalledLocation->GetFileAsync(L"shader.hlsl");  create_task(fileOp).then([this](Windows::Storage::StorageFile^ file) -> IAsyncOperation<Windows::Storage::Streams::IBuffer^>^  {    // Do file I/O in background thread (use_arbitrary).    return Windows::Storage::FileIO::ReadBufferAsync(file);  }, task_continuation_context::use_arbitrary())    .then([this, blobRef](Windows::Storage::Streams::IBuffer^ buffer)  {    // Do compilation in background thread (use_arbitrary).    // Cast to Object^, then to its underlying IInspectable interface.    Microsoft::WRL::ComPtr<IInspectable> insp(reinterpret_cast<IInspectable*>(buffer));    // Query the IBufferByteAccess interface.    Microsoft::WRL::ComPtr<Windows::Storage::Streams::IBufferByteAccess> bufferByteAccess;    insp.As(&bufferByteAccess);    // Retrieve the buffer data.    byte *pBytes = nullptr;    bufferByteAccess->Buffer(&pBytes);    Microsoft::WRL::ComPtr<ID3DBlob> blob;    Microsoft::WRL::ComPtr<ID3DBlob> errMsgs;    D3DCompile2(pBytes, buffer->Length, "shader.hlsl", nullptr, nullptr, "main", "ps_5_0", 0, 0, 0, nullptr, 0, blob.GetAddressOf(), errMsgs.GetAddressOf());    *blobRef = blob;  }, task_continuation_context::use_arbitrary())    .then([this, blobRef]()  {    // Update UI / use shader on foreground thread.    wchar_t message[40];    swprintf_s(message, L"blob is %u bytes long", (unsigned)(*blobRef)->GetBufferSize());    this->TheButton->Content = ref new Platform::String(message);  }, task_continuation_context::use_current());}

Requirements

See also

• Functions
• Specifying D3D12 Root Signatures in HLSL