주의 : 초심자 튜토리얼은 아닙니다. 그러므로, 실제 API 호출 용례를 알고자 한다면, 샘플이나 튜토리얼을 찾아서 확인해 보세요.
주의 : 완전히 이해하고 작성한 글이 아니므로 잘못된 내용이 포함되어 있을 수 있습니다.
주의 : 이상하면 참고자료를 확인하세요.
그래서 소스 코드를 분석해서 정확하게 각 옵션들의 의미를 파악해 보기로 했습니다. 아래 블록은 "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 만 봐도 쉽게 이해할 수 있는 것들은 배제하겠습니다. 그리고 별로 빈도가 높아 보이지 않는 것들도 배제했습니다. 댓글로 특정 옵션에 대한 정확한 동작에 대해서 문의하신다면 내용을 추가하도록 하겠습니다.
다음과 같이 옵션 다음에 컴파일할 소스 파일 경로를 넣습니다.
$(SourceFilePath) 는 커맨드 실행 디렉토리에 대한 상대 경로일 수도 있고 절대 경로일 수도 있습니다.
옵션을 위한 플래그들은 '-' 접두어로 시작하며, 값을 받는 옵션이라면 "-O" 를 제외하고는 모두 한 칸을 띄고 값을 입력합니다.
가장 먼저 지정해야 할 값이 없는 옵션입니다. SPIR-V 파일을 생성하라는 의미입니다. 벌칸을 사용한다는 가정하에서지만, 이것을 빼먹어서는 안 됩니다.
셰이더 프로우파일 문자열입니다.
$(shader_name) 은 각 셰이더 타입의 머리글자 혹은 약자입니다.
그냥 함수 이름을 기입하면 됩니다. 만약 이를 지정하지 않으면 기본적으로는 "main" 이 사용됩니다.
디파인 매크로를 설정하는 문자열입니다.
만약 여러 개의 매크로를 설정해야 한다면, 여러 개의 -D 플래그를 사용해야 합니다. 예를 들면 아래 블록과 같이 할 수 있습니다.
HLSL 파일을 작성하다가 보면 인클루딩을 해야 하는 경우가 있습니다. 인클루딩해야 할 파일이 존재하는 폴더 경로에 대한 문자열입니다.
공용 HLSL 파일을 위한 폴더를 나누거나 종류별로 HLSL 파일을 나눠서 관리하다가 보면, 인클루드해야 하는 파일이 다른 디렉토리에 존재할 수 있습니다. 만약 같은 폴더에 대상 파일이 존재한다면 아무런 문제가 없지만, 그렇지 않다면 아래처럼 경로를 지정해야 합니다.
여러 개의 폴더를 지정하려면 여러 개의 -I 플래그를 사용합니다. 경로는 절대 경로여도 되고 커맨드를 실행한 폴더에 대한 상대 경로여도 됩니다.
0 ~ 3 까지 지정할 수 있고 숫자가 낮을 수록 최적화를 덜 한다는 이야기입니다. 값의 크기는 코드를 생성하는 속도와 반비례하며 코드 실행 속도와 비례합니다.
SPIR-V 를 생성할 경로에 대한 문자열입니다.
절대경로여도 되고 커맨드를 실행한 폴더에 대한 상대 경로여도 됩니다( 폴더를 지정하지 않으면 커맨드를 실행한 폴더에 생성됩니다 ).
이름은 마음대로 지정하시면 됩니다. 보통은 "[$(Identifier)_]$(StageName).spv" 라고 지정하는듯 합니다.
만약 이 옵션을 지정하지 않으면 콘솔창에다가 디스어셈블리 결과를 출력합니다.
절대경로여도 되고 커맨드를 실행한 폴더에 대한 상대 경로여도 됩니다.
이름과 확장자는 마음대로 지정하시면 됩니다. 텍스트 파일로 생성되기 때문에 txt 인 것이 좋을 것 같습니다.
코드를 포함하고 있는 헤더 파일의 경로에 대한 문자열입니다.
헤더라고 하니, 엄청나게 헷갈리는데요, C/C++ 에서 사용할 수 있는 이진코드 배열을 정의하는 파일입니다. 열어 보니 디스어셈블리 내용도 포함하고 있더군요.
만약 코드에다가 SPIR-V 를 하드코딩하고 싶다면 이것을 사용할 수 있을 것 같네요.
경고나 에러를 출력할 파일의 경로에 대한 문자열입니다. 만약 이 옵션을 지정하지 않으면 콘솔창에다가 결과를 출력합니다.
커맨드라인 프로그램을 사용하면 그 결과를 확인하기 위해서 stderr, stdout 에 대한 파이프를 만들어야 하는 경우가 있습니다. 매우 귀찮은 작업이죠.
그럴 경우에 텍스트로부터 한 번에 출력 결과를 읽어들일 수 있다면 매우 유용합니다.
주의할 점은 다음과 같습니다.