[ Vulkan 연구 ] HLSL to SPIR-V : 5. DXC 기본 옵션 분석

주의 : 초심자 튜토리얼은 아닙니다. 그러므로, 실제 API 호출 용례를 알고자 한다면, 샘플이나 튜토리얼을 찾아서 확인해 보세요.

주의 : 완전히 이해하고 작성한 글이 아니므로 잘못된 내용이 포함되어 있을 수 있습니다.

주의 : 이상하면 참고자료를 확인하세요.

---

[ HLSL to SPIR-V Feature Mapping Manual ] 에 커맨드라인 옵션들에 대한 설명들이 나와 있기는 하지만, 정확하게 어떤 것을 이야기하는지 이해할 수 없는 것들도 있습니다.

그래서 소스 코드를 분석해서 정확하게 각 옵션들의 의미를 파악해 보기로 했습니다. 아래 블록은 "dxc -help" 를 실행했을 때 나오는 설명들입니다. SPIR-V 전용 옵션들은 여기에서는 배제했습니다. 나중에 다른 챕터에서 다룰 계획입니다.

Common Options:

  -help              Display available options

  -nologo            Suppress copyright message

  -Qunused-arguments Don't emit warning for unused driver arguments

Compilation Options:

  -all_resources_bound    Enables agressive flattening

  -auto-binding-space <value>

                          Set auto binding space - enables auto resource binding in libraries

  -Cc                     Output color coded assembly listings

  -default-linkage <value>

                          Set default linkage for non-shader functions when compiling or linking to a library target (internal, external)

  -denorm <value>         select denormal value options (any, preserve, ftz). any is the default.

  -D <value>              Define macro

  -enable-16bit-types     Enable 16bit types and disable min precision types. Available in HLSL 2018 and shader model 6.2

  -export-shaders-only    Only export shaders when compiling a library

  -exports <value>        Specify exports when compiling a library: export1[[,export1_clone,...]=internal_name][;...]

  -E <value>              Entry point name

  -Fc <file>              Output assembly code listing file

  -Fd <file>              Write debug information to the given file, or automatically named file in directory when ending in '\'

  -Fe <file>              Output warnings and errors to the given file

  -Fh <file>              Output header file containing object code

  -flegacy-macro-expansion

                          Expand the operands before performing token-pasting operation (fxc behavior)

  -flegacy-resource-reservation

                          Reserve unused explicit register assignments for compatibility with shader model 5.0 and below

  -force_rootsig_ver <profile>

                          force root signature version (rootsig_1_1 if omitted)

  -Fo <file>              Output object file

  -Gec                    Enable backward compatibility mode

  -Ges                    Enable strict mode

  -Gfa                    Avoid flow control constructs

  -Gfp                    Prefer flow control constructs

  -Gis                    Force IEEE strictness

  -HV <value>             HLSL version (2016, 2017, 2018). Default is 2018

  -H                      Show header includes and nesting depth

  -ignore-line-directives Ignore line directives

  -I <value>              Add directory to include search path

  -Lx                     Output hexadecimal literals

  -Ni                     Output instruction numbers in assembly listings

  -no-warnings            Suppress warnings

  -not_use_legacy_cbuf_load

                          Do not use legacy cbuffer load

  -No                     Output instruction byte offsets in assembly listings

  -Odump                  Print the optimizer commands.

  -Od                     Disable optimizations

  -pack_optimized         Optimize signature packing assuming identical signature provided for each connecting stage

  -pack_prefix_stable     (default) Pack signatures preserving prefix-stable property - appended elements will not disturb placement of prior elements

  -recompile              recompile from DXIL container with Debug Info or Debug Info bitcode file

  -res_may_alias          Assume that UAVs/SRVs may alias

  -rootsig-define <value> Read root signature from a #define

  -T <profile>            Set target profile.

        <profile>: ps_6_0, ps_6_1, ps_6_2, ps_6_3, ps_6_4, ps_6_5,

                 vs_6_0, vs_6_1, vs_6_2, vs_6_3, vs_6_4, vs_6_5,

                 cs_6_0, cs_6_1, cs_6_2, cs_6_3, cs_6_4, cs_6_5,

                 gs_6_0, gs_6_1, gs_6_2, gs_6_3, gs_6_4, gs_6_5,

                 ds_6_0, ds_6_1, ds_6_2, ds_6_3, ds_6_4, ds_6_5,

                 hs_6_0, hs_6_1, hs_6_2, hs_6_3, hs_6_4, hs_6_5,

                 lib_6_3, lib_6_4, lib_6_5, ms_6_5, as_6_5

  -Vd                     Disable validation

  -Vi                     Display details about the include process.

  -Vn <name>              Use <name> as variable name in header file

  -WX                     Treat warnings as errors

  -Zi                     Enable debug information

  -Zpc                    Pack matrices in column-major order

  -Zpr                    Pack matrices in row-major order

  -Zsb                    Build debug name considering only output binary

  -Zss                    Build debug name considering source information

Optimization Options:

  -O0 Optimization Level 0

  -O1 Optimization Level 1

  -O2 Optimization Level 2

  -O3 Optimization Level 3 (Default)

SPIR-V CodeGen Options:

  -fspv-debug=<value>     Specify whitelist of debug info category (file -> source -> line, tool)

  -fspv-extension=<value> Specify SPIR-V extension permitted to use

  -fspv-reflect           Emit additional SPIR-V instructions to aid reflection

  -fspv-target-env=<value>

                          Specify the target environment: vulkan1.0 (default) or vulkan1.1

  -fvk-b-shift <shift> <space>

                          Specify Vulkan binding number shift for b-type register

  -fvk-bind-globals <binding> <set>

                          Specify Vulkan binding number and set number for the $Globals cbuffer

  -fvk-bind-register <type-number> <space> <binding> <set>

                          Specify Vulkan descriptor set and binding for a specific register

  -fvk-invert-y           Negate SV_Position.y before writing to stage output in VS/DS/GS to accommodate Vulkan's coordinate system

  -fvk-s-shift <shift> <space>

                          Specify Vulkan binding number shift for s-type register

  -fvk-t-shift <shift> <space>

                          Specify Vulkan binding number shift for t-type register

  -fvk-u-shift <shift> <space>

                          Specify Vulkan binding number shift for u-type register

  -fvk-use-dx-layout      Use DirectX memory layout for Vulkan resources

  -fvk-use-dx-position-w  Reciprocate SV_Position.w after reading from stage input in PS to accommodate the difference between Vulkan and DirectX

  -fvk-use-gl-layout      Use strict OpenGL std140/std430 memory layout for Vulkan resources

  -fvk-use-scalar-layout  Use scalar memory layout for Vulkan resources

  -Oconfig=<value>        Specify a comma-separated list of SPIRV-Tools passes to customize optimization configuration (see http://khr.io/hlsl2spirv#optimization)

  -spirv                  Generate SPIR-V code

Utility Options:

  -dumpbin              Load a binary file rather than compiling

  -extractrootsignature Extract root signature from shader bytecode (must be used with /Fo <file>)

  -getprivate <file>    Save private data from shader blob

  -P <value>            Preprocess to file (must be used alone)

  -Qembed_debug         Embed PDB in shader container (must be used with /Zi)

  -Qstrip_debug         Strip debug information from 4_0+ shader bytecode  (must be used with /Fo <file>)

  -Qstrip_priv          Strip private data from shader bytecode  (must be used with /Fo <file>)

  -Qstrip_reflect       Strip reflection data from shader bytecode  (must be used with /Fo <file>)

  -Qstrip_rootsignature Strip root signature data from shader bytecode  (must be used with /Fo <file>)

  -setprivate <file>    Private data to add to compiled shader blob

  -setrootsignature <file>

                        Attach root signature to shader bytecode

  -verifyrootsignature <file>

                        Verify shader bytecode with root signature

이 옵션들을 모두 살펴 볼 것은 아니구요, 그냥 -help 만 봐도 쉽게 이해할 수 있는 것들은 배제하겠습니다. 그리고 별로 빈도가 높아 보이지 않는 것들도 배제했습니다. 댓글로 특정 옵션에 대한 정확한 동작에 대해서 문의하신다면 내용을 추가하도록 하겠습니다.

기본 형식

다음과 같이 옵션 다음에 컴파일할 소스 파일 경로를 넣습니다.

dxc [ options... ] $(SourceFilePath)

$(SourceFilePath) 는 커맨드 실행 디렉토리에 대한 상대 경로일 수도 있고 절대 경로일 수도 있습니다.

옵션을 위한 플래그들은 '-' 접두어로 시작하며, 값을 받는 옵션이라면 "-O" 를 제외하고는 모두 한 칸을 띄고 값을 입력합니다.

-spriv

가장 먼저 지정해야 할 값이 없는 옵션입니다. SPIR-V 파일을 생성하라는 의미입니다. 벌칸을 사용한다는 가정하에서지만, 이것을 빼먹어서는 안 됩니다.

dxc -spirv

-T

셰이더 프로우파일 문자열입니다.

dxc -T $(shader_name)_$(major_version)_$(minor_version)

$(shader_name) 은 각 셰이더 타입의 머리글자 혹은 약자입니다.

• vs : Vertex Shader.

• hs : Hull Shader.

• ds : Domain Shader.

• gs : Geometry Shader.

• ps : Pixel Shader.

• cs : Compute Shader.

• lib : shader LIBrary. 한 번도 써 본 적이 없어서 모르겠는데, [ Using shader linking ] 에서 정보를 얻을 수 있습니다.

문제는 셰이더의 버전인데요, 이것은 메이저와 마이너로 나뉩니다. 이것을 임의로 지정하는 것은 아니구요, [ Shader Models vs Shader Profiles ] 에 가면 셰이더 모델에서 이용가능한 셰이더 프로우파일들의 목록을 확인하실 수 있습니다.

-E

셰이더 프로우파일에 대한 진입 함수에 대한 문자열입니다. 

dxc -E mainVS

그냥 함수 이름을 기입하면 됩니다. 만약 이를 지정하지 않으면 기본적으로는 "main" 이 사용됩니다.

-D

디파인 매크로를 설정하는 문자열입니다.

만약 여러 개의 매크로를 설정해야 한다면, 여러 개의 -D 플래그를 사용해야 합니다. 예를 들면 아래 블록과 같이 할 수 있습니다.

dxc -D USE_POSITION -D USE_NORMAL=1

다들 아실거라 생각하지만 부연하자면, '=' 을 사용하지 않으면 "#ifdef" 를 사용해서 조건을 검사하고, 사용하면 "#if" 를 사용해서 조건을 검사합니다.

-I

HLSL 파일을 작성하다가 보면 인클루딩을 해야 하는 경우가 있습니다. 인클루딩해야 할 파일이 존재하는 폴더 경로에 대한 문자열입니다.

#include "test_include.hlsl" VSOutput mainVS( VSInput In ) { VSOutput Out = ( VSOutput )0; Out.Position = In.Position; Out.Normal = In.Normal; Out.Color = In.Color; return Out; }

공용 HLSL 파일을 위한 폴더를 나누거나 종류별로 HLSL 파일을 나눠서 관리하다가 보면, 인클루드해야 하는 파일이 다른 디렉토리에 존재할 수 있습니다. 만약 같은 폴더에 대상 파일이 존재한다면 아무런 문제가 없지만, 그렇지 않다면 아래처럼 경로를 지정해야 합니다.

dxc -I C:\OtherFolder1 -I C:\OtherFolder2 -I ..\

여러 개의 폴더를 지정하려면 여러 개의 -I 플래그를 사용합니다. 경로는 절대 경로여도 되고 커맨드를 실행한 폴더에 대한 상대 경로여도 됩니다.

-O

최적화 수준을 지정하는 문자열입니다. 

이것은 특이하게 한칸 띄고 값을 지정하는 것이 아니라 바로 붙여서 지정합니다( 예를 들어 -O1 ).

dxc -O{0|1|2|3}

0 ~ 3 까지 지정할 수 있고 숫자가 낮을 수록 최적화를 덜 한다는 이야기입니다. 값의 크기는 코드를 생성하는 속도와 반비례하며 코드 실행 속도와 비례합니다.

-Fo

SPIR-V 를 생성할 경로에 대한 문자열입니다.

절대경로여도 되고 커맨드를 실행한 폴더에 대한 상대 경로여도 됩니다( 폴더를 지정하지 않으면 커맨드를 실행한 폴더에 생성됩니다 ).

이름은 마음대로 지정하시면 됩니다. 보통은 "[$(Identifier)_]$(StageName).spv" 라고 지정하는듯 합니다.

dxc -Fo my_vertex.spv

만약 이 옵션을 지정하지 않으면 콘솔창에다가 디스어셈블리 결과를 출력합니다.

-Fc

-Fo 에서 지정한 SPIR-V 파일에 대한 디스어셈블리 파일을 생성할 경로에 대한 문자열입니다. 

절대경로여도 되고 커맨드를 실행한 폴더에 대한 상대 경로여도 됩니다.

이름과 확장자는 마음대로 지정하시면 됩니다. 텍스트 파일로 생성되기 때문에 txt 인 것이 좋을 것 같습니다.

dxc -Fc my_vertex_disassembly.txt

-Fh

코드를 포함하고 있는 헤더 파일의 경로에 대한 문자열입니다.

dxc -Fh my_vertex_header.txt

헤더라고 하니, 엄청나게 헷갈리는데요, C/C++ 에서 사용할 수 있는 이진코드 배열을 정의하는 파일입니다. 열어 보니 디스어셈블리 내용도 포함하고 있더군요.

만약 코드에다가 SPIR-V 를 하드코딩하고 싶다면 이것을 사용할 수 있을 것 같네요.

-Fe

경고나 에러를 출력할 파일의 경로에 대한 문자열입니다. 만약 이 옵션을 지정하지 않으면 콘솔창에다가 결과를 출력합니다.

dxc -Fe my_vertex_output.txt

커맨드라인 프로그램을 사용하면 그 결과를 확인하기 위해서 stderr, stdout 에 대한 파이프를 만들어야 하는 경우가 있습니다. 매우 귀찮은 작업이죠.

그럴 경우에 텍스트로부터 한 번에 출력 결과를 읽어들일 수 있다면 매우 유용합니다.

주의할 점은 다음과 같습니다.

• 성공시에는 아무런 로그도 남지 않습니다.

• 표준 출력창의 내용을 redirect 한 것이므로 실패했을 경우에도 콘솔창에는 로그가 남지 않습니다.