1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
|
Using the `slangc` Command-Line Compiler
========================================
The `slangc` command-line tool is used to compile or cross-compile shader source code.
```
slangc [<options>] <file1> [<file2>...]
```
Simple Examples
---------------
### HLSL
When compiling an HLSL shader, you must specify the path to your shader code file as well as the "profile" to use.
To see D3D bytecode assembly for a fragment shader entry point:
slangc my-shader.hlsl -profile ps_5_0
To direct that output to a bytecode file:
slangc my-shader.hlsl -profile ps_5_0 -o my-shader.dxbc
If the entry-point function has a name other than the default `main`, then this is specified with `-entry`:
slangc my-shader.hlsl -profile ps_5_0 -entry psMain
### Slang
Compiling an entry point from a Slang file is similar to HLSL, except that you must specify the profile, the entry-point name, *and* the code generation target.
To get DXBC assembly written to the console:
slangc my-shader.slang -profile ps_5_0 -entry main -target dxbc
To get SPIR-V assembly:
slangc my-shader.slang -profile ps_5_0 -entry main -target spriv
The code generation target is implicit when writing to a file with an appropriate extension.
To write DXBC, SPIR-V, or GLSL to files, use:
slangc my-shader.slang -profile ps_5_0 -entry main -o my-shader.dxbc
slangc my-shader.slang -profile ps_5_0 -entry main -o my-shader.spv
slangc my-shader.slang -profile ps_5_0 -entry main -o my-shader.glsl
Multiple Entry Points
---------------------
If you are taking advantage of Slang's ability to automatically assign binding locations to shader parameters (textures, buffers, etc.), then you may need to specify multiple entry points or even multiple files in one compiler invocation.
When compiling HLSL or Slang code, you might have multiple entry points in one file.
In this case, specify the entry-point-specific options after the file, and make sure that the `-profile` option and any `-o` option precedes the corresponding `-entry` option:
slangc my-shader.hlsl -profile vs_5_0 -o my-shader.vs.dxbc -entry vsMain
-profile ps_5_0 -o my-shader.ps.dxbc -entry psMain
If you want to compile multiple GLSL entry points in one pass, you will need multiple files. It is also required to fully specify the profile and entry-point name in this mode.
slangc my-shader.vert -profile glsl_vertex -o my-shader.vert.spv -entry main
my-shader.frag -profile glsl_fragment -o my-shader.frag.spv -entry main
These command lines obviously aren't pleasant, but we expect that most applications that need this level of complexity will be using the API.
The ability to specify compilation actions like this on the command line is primarily intended a testing and debugging tool.
Options
-------
For completeness, here are the options that `slangc` currently accepts:
* `-D <name>[=<value>]`: Insert a preprocessor macro definition
* The space between `-D` and `<name>` is optional
* If no `<value>` is specified, Slang will define the macro with an empty value
* `-entry <name>`: Specify the name of the entry-point function
* In single-file compiles for HLSL, this defaults to `main`
* Multiple `-entry` options may appear on the command line. When they do, the input file path, `-profile` option, and `-o` option that apply for an entry point are each the first one found when scanning to the left from the `-entry` option.
* `-I <path>`: Add a path to be used in resolving `#include` and `__import` operations
* The space between `-I` and `<path>` is optional
* `-o <path>`: Specify a path where generated output should be written
* `-pass-through <name>`: Don't actually perform Slang parsing/checking/etc. on the input and instead pass it through more or less modified to the existing compiler `<name>`"
* `fxc`: Use the `D3DCompile` API as exposed by `d3dcompiler_47.dll`
* `glslang`: Use Slang's internal version of `glslang` as exposed by `slang-glslang.dll`
* These are intended for debugging/testing purposes, when you want to be able to see what these existing compilers do with the "same" input and options
* `-profile <profile>`: Specify the language "profile" to use. This is a combination of the pipeline stage (vertex, fragment, compute, etc.) and an abstract feature level. E.g., the `ps_5_0` profile specifies the fragment stage, with the Direc3D "Shader Model 5" feature level. To summarize the available profiles:
* The D3D profiles of the form `{cs,ds,gs,hs,ps,vs}_{4_0,4_1,5_0}` are supported
* The D3D profiles of the form `{vs,ps}_4_0_level_9_{0,1,3}` are supported
* Profiles of the form `glsl_{vertex,tess_control,tess_eval,geometry,fragment,compute}_<version>` are supported for all GLSL language versions where the corresponding stage is supported (e.g., there is a `glsl_fragment_110`, but the earliest compute profile is `glsl_compute_430`)
* As a convenience profiles of the form `glsl_{vertex,tess_control,tess_eval,geometry,fragment,compute}` are provided that are intended to map to the latest version of GLSL known to the Slang compiler (curently `450`)
* `-target <target>`: Specifies the desired code-generation target. Values for `<target>` are:
* `glsl`: GLSL source code
* `hlsl`: HLSL source code
* `spirv`: SPIR-V intermediate language binary.
* `spirv-assembly`: SPIR-V intermediate language assembly
* `dxbc`: Direct3D shader bytecode binary
* `dxbc-assembly`: Direct3D shader bytecode assembly
* `none`: Don't generate output code (but still perform front-end parsing/checking)
* `--`: Stop parsing options, and treat the rest of the command line as input paths
Limitations
-----------
A major limitation of the `slangc` command today is that there is no provision for getting reflection data out along with the compiled shade rcode.
For now, the command-line tool is best seen as a debugging/testing tool, and all serious applications should drive Slang through the API.
|
