D3DCompile2 함수(d3dcompiler.h)

아티클
03/05/2024

Microsoft HLSL(High Level Shader Language) 코드를 지정된 대상에 대한 바이트코드로 컴파일합니다.

구문

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
);

매개 변수

[in] pSrcData

형식: LPCVOID

컴파일되지 않은 셰이더 데이터(ASCII HLSL 코드)에 대한 포인터입니다.

[in] SrcDataSize

형식: SIZE_T

pSrcData가 가리키는 메모리 블록의 크기(바이트)입니다.

[in, optional] pSourceName

형식: LPCSTR

오류 메시지에 사용할 원본 데이터를 식별하는 이름을 포함하는 null로 끝나는 상수 문자열에 대한 선택적 포인터입니다. 사용하지 않으면 을 NULL로 설정합니다.

[in, optional] pDefines

형식: const D3D_SHADER_MACRO*

셰이더 매크로를 정의하는 D3D_SHADER_MACRO 구조체의 선택적 배열입니다. 각 매크로 정의에는 이름과 null로 종료된 정의가 포함됩니다. 사용하지 않으면 을 NULL로 설정합니다. 배열의 마지막 구조체는 종결자로 사용되며 모든 멤버를 NULL로 설정해야 합니다.

[in, optional] pInclude

형식: ID3DInclude*

컴파일러가 포함 파일을 처리하는 데 사용하는 ID3DInclude 인터페이스에 대한 포인터입니다. 이 매개 변수를 NULL 로 설정하고 셰이더에 #include 포함하는 경우 컴파일 오류가 발생합니다. 기본 포함 처리기에 대한 포인터인 D3D_COMPILE_STANDARD_FILE_INCLUDE 매크로를 전달할 수 있습니다. 이 기본 포함 처리기에는 현재 디렉터리를 기준으로 하는 파일과 초기 소스 파일의 디렉터리를 기준으로 하는 파일이 포함됩니다. D3D_COMPILE_STANDARD_FILE_INCLUDE 사용하는 경우 pSourceName 매개 변수에서 원본 파일 이름을 지정해야 합니다. 컴파일러는 pSourceName에서 초기 상대 디렉터리를 파생합니다.

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

[in] pEntrypoint

형식: LPCSTR

셰이더 실행이 시작되는 셰이더 진입점 함수의 이름을 포함하는 null로 끝나는 상수 문자열에 대한 포인터입니다. 효과를 컴파일할 때 D3DCompile2는 pEntrypoint를 무시합니다. 호출된 함수가 사용하지 않을 경우 포인터 매개 변수를 NULL로 설정하는 것이 좋은 프로그래밍 방식이므로 pEntrypoint를 NULL로 설정하는 것이 좋습니다.

[in] pTarget

형식: LPCSTR

컴파일할 셰이더 대상 또는 셰이더 기능 집합을 지정하는 null로 끝나는 상수 문자열에 대한 포인터입니다. 셰이더 대상은 셰이더 모델(예: 셰이더 모델 2, 셰이더 모델 3, 셰이더 모델 4 또는 셰이더 모델 5)일 수 있습니다. 대상은 효과 유형(예: fx_4_1)일 수도 있습니다. 다양한 프로필이 지원하는 대상에 대한 자세한 내용은 컴파일러 대상 지정을 참조하세요.

[in] Flags1

형식: UINT

셰이더 D3D 컴파일 상수 의 조합은 비트 OR 연산을 사용하여 결합됩니다. 결과 값은 컴파일러가 HLSL 코드를 컴파일하는 방법을 지정합니다.

[in] Flags2

형식: UINT

비트 OR 연산을 사용하여 결합된 효과 D3D 컴파일 효과 상수의 조합입니다. 결과 값은 컴파일러가 효과를 컴파일하는 방법을 지정합니다. 효과 파일이 아닌 셰이더를 컴파일하는 경우 D3DCompile2 는 Flags2를 무시합니다. 호출된 함수가 이 매개 변수를 사용하지 않을 경우 비점수 매개 변수를 0으로 설정하는 것이 좋은 프로그래밍 방식이므로 Flags2 를 0으로 설정하는 것이 좋습니다.

[in] SecondaryDataFlags

형식: UINT

비트 OR 연산을 사용하여 결합된 다음 플래그의 조합입니다. 결과 값은 컴파일러가 HLSL 코드를 컴파일하는 방법을 지정합니다.

플래그	설명
D3DCOMPILE_SECDATA_MERGE_UAV_SLOTS(0x01)	pSecondaryData 매개 변수가 가리키는 보조 데이터의 UAV(순서가 지정되지 않은 액세스 뷰) 슬롯을 병합합니다.
D3DCOMPILE_SECDATA_PRESERVE_TEMPLATE_SLOTS(0x02)	pSecondaryData 매개 변수가 가리키는 보조 데이터의 템플릿 슬롯을 유지합니다.
D3DCOMPILE_SECDATA_REQUIRE_TEMPLATE_MATCH(0x04)	컴파일러가 HLSL 코드를 컴파일할 때 pSecondaryData 매개 변수가 가리키는 보조 데이터의 템플릿이 일치하도록 요구합니다.

pSecondaryData가 NULL이면 0으로 설정합니다.

[in, optional] pSecondaryData

형식: LPCVOID

보조 데이터에 대한 포인터입니다. 보조 데이터를 전달하지 않으면 NULL로 설정합니다. 이 보조 데이터를 사용하여 UAV 슬롯을 두 셰이더에 맞춥니다. 셰이더 A에 UAV가 있고 일부 슬롯에 바인딩되어 있다고 가정합니다. 이름이 같은 UAV가 B에서 A와 동일한 슬롯에 매핑되도록 셰이더 B를 컴파일하려면 A의 바이트 코드를 D3DCompile2 에 보조 데이터로 전달합니다.

[in] SecondaryDataSize

형식: SIZE_T

pSecondaryData가 가리키는 메모리 블록의 크기(바이트)입니다. pSecondaryData가 NULL이면 0으로 설정합니다.

[out] ppCode

형식: ID3DBlob**

컴파일된 코드에 액세스하는 데 사용할 수 있는 ID3DBlob 인터페이스에 대한 포인터를 수신하는 변수에 대한 포인터입니다.

[out, optional] ppErrorMsgs

형식: ID3DBlob**

컴파일러 오류 메시지에 액세스하는 데 사용할 수 있는 ID3DBlob 인터페이스에 대한 포인터를 수신하는 변수에 대한 포인터이거나 오류가 없는 경우 NULL 입니다.

반환 값

형식: HRESULT

Direct3D 11 반환 코드 중 하나를 반환합니다.

설명

D3DCompile2와 D3DCompile의 차이점은 D3DCompile2가 바이트코드 생성 방법의 일부 측면을 제어하는 데 사용할 수 있는 몇 가지 선택적 매개 변수(SecondaryDataFlags, pSecondaryData 및 SecondaryDataSize)를 사용한다는 것입니다. 자세한 내용은 이러한 매개 변수에 대한 설명을 참조하세요. 그렇지 않으면 D3DCompile2와 D3DCompile 간에 생성된 바이트코드의 효율성에 차이가 없습니다.

UWP용 셰이더 컴파일

오프라인 셰이더를 컴파일하려면 효과 컴파일러 도구를 사용하는 것이 좋습니다. 미리 모든 셰이더를 컴파일할 수 없는 경우 더 비싼 셰이더와 시작 및 대부분의 성능에 민감한 경로에 필요한 셰이더를 컴파일하고 런타임에 나머지를 컴파일하는 것이 좋습니다. 다음과 유사한 프로세스를 사용하여 사용자 인터페이스 스레드를 차단하지 않고 UWP 애플리케이션에서 로드되거나 생성된 셰이더를 컴파일할 수 있습니다.

Visual Studio 2015+를 사용하여 UWP 앱을 개발하려면 새 항목 "shader.hlsl"을 추가합니다.
- Visual Studio의 솔루션 폴더 보기에서 shaders.hlsl 항목을 선택하고 속성을 마우스 오른쪽 단추로 클릭합니다.
- 콘텐츠 항목이 예로 설정되어 있는지 확인합니다.
- 항목 유형이 텍스트로 설정되어 있는지 확인합니다.
- XAML에 단추를 추가하고, 적절하게 이름을 지정하고(이 예제에서는 "TheButton"), Click 처리기를 추가합니다.

이제 다음을 .cpp 파일에 추가합니다.

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

다음 코드를 사용하여 D3DCompile2를 호출합니다. 여기서는 오류 검사 또는 처리가 없으며, 이 코드는 백그라운드에서 I/O 및 컴파일을 모두 수행할 수 있음을 보여 줍니다. 따라서 UI의 응답성이 높아진 것입니다.

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());
}

요구 사항

요구 사항	값
대상 플랫폼	Windows
헤더	d3dcompiler.h
라이브러리	D3DCompiler.lib
DLL	D3DCompiler_47.dll

D3DCompile2 함수(d3dcompiler.h)

구문

매개 변수

반환 값

설명

UWP용 셰이더 컴파일

요구 사항

참조

피드백

피드백

추가 리소스