1 '\" t
2 .\" Title: glslc Manual
3 .\" Author: [see the "AUTHOR(S)" section]
4 .\" Generator: Asciidoctor 2.0.16
5 .\" Date: 2021-08-26
6 .\" Manual: \ \&
7 .\" Source: \ \&
8 .\" Language: English
9 .\"
10 .TH "`GLSLC`" "1" "2021-08-26" "\ \&" "\ \&"
11 .ie \n(.g .ds Aq \(aq
12 .el .ds Aq '
13 .ss \n[.ss] 0
14 .nh
15 .ad l
16 .de URL
17 \fI\\$2\fP <\\$1>\\$3
18 ..
19 .als MTO URL
20 .if \n[.g] \{\
21 . mso www.tmac
22 . am URL
23 . ad l
24 . .
25 . am MTO
26 . ad l
27 . .
28 . LINKSTYLE blue R < >
29 .\}
30 .SH "NAME"
31 `glslc` \- A command\-line GLSL/HLSL to SPIR\-V compiler with Clang\-compatible arguments.
32 .SH "SYNOPSIS"
33 .sp
34 .if n .RS 4
35 .nf
36 .fam C
37 glslc [\-\-help]
38 glslc [\-h]
39
40 glslc [\-\-show\-limits]
41
42 glslc [\-c|\-S|\-E]
43 [\-x ...] [\-std=standard]
44 [ ... options for resource bindings ... ]
45 [\-fhlsl\-offsets]
46 [\-fhlsl\-functionality1]
47 [\-fentry\-point=<name>]
48 [\-fauto\-map\-locations]
49 [\-finvert\-y]
50 [\-flimit=...]
51 [\-flimit\-file <resource\-limits\-file>]
52 [\-fshader\-stage=...]
53 [\-\-target\-env=...]
54 [\-\-target\-spv=...]
55 [\-g]
56 [\-O0|\-Os]
57 [\-Idirectory...]
58 [\-Dmacroname[=value]...]
59 [\-w] [\-Werror]
60 [\-o outfile]
61 shader...
62 .fam
63 .fi
64 .if n .RE
65 .SH "DESCRIPTION"
66 .SS "Input file languages"
67 .sp
68 glslc accepts both GLSL/HLSL source and SPIR\-V assembly files as inputs.
69 .SS "Shader stage specification"
70 .sp
71 glslc provides three ways to specify the shader stage of a GLSL source file:
72 \f(CR\-fshader\-stage=<stage>\fP, \f(CR#pragma shader_stage(<stage>)\fP, and file extension.
73 The \f(CR\-fshader\-stage=\fP option overrides \f(CR#pragma shader_stage()\fP, which overrides
74 the file extension.
75 .sp
76 Shader stages can be specified by naming a file with an appropriate extension
77 as shown in the following table. \f(CR\-fshader\-stage=\fP and \f(CR#pragma shader_stage()\fP,
78 on the other hand, enable you to specify shader stages from the command line
79 and within the source file. Possible \f(CRstage\fPs for them are also listed in
80 the following table. Details about \f(CR\-fshader\-stage=\fP can be found in
81 its own section.
82 .sp
83 .it 1 an-trap
84 .nr an-no-space-flag 1
85 .nr an-break-flag 1
86 .br
87 .B Table 1. Shader Stage Selection
88 .TS
89 allbox tab(:);
90 lt lt lt.
91 T{
92 .sp
93 Shader Stage
94 T}:T{
95 .sp
96 Shader File Extension
97 T}:T{
98 .sp
99 \f(CR<stage>\fP
100 T}
101 T{
102 .sp
103 vertex
104 T}:T{
105 .sp
106 \f(CR.vert\fP
107 T}:T{
108 .sp
109 \f(CRvertex\fP
110 T}
111 T{
112 .sp
113 fragment
114 T}:T{
115 .sp
116 \f(CR.frag\fP
117 T}:T{
118 .sp
119 \f(CRfragment\fP
120 T}
121 T{
122 .sp
123 tesselation control
124 T}:T{
125 .sp
126 \f(CR.tesc\fP
127 T}:T{
128 .sp
129 \f(CRtesscontrol\fP
130 T}
131 T{
132 .sp
133 tesselation evaluation
134 T}:T{
135 .sp
136 \f(CR.tese\fP
137 T}:T{
138 .sp
139 \f(CRtesseval\fP
140 T}
141 T{
142 .sp
143 geometry
144 T}:T{
145 .sp
146 \f(CR.geom\fP
147 T}:T{
148 .sp
149 \f(CRgeometry\fP
150 T}
151 T{
152 .sp
153 compute
154 T}:T{
155 .sp
156 \f(CR.comp\fP
157 T}:T{
158 .sp
159 \f(CRcompute\fP
160 T}
161 .TE
162 .sp
163 .sp
164 \f(CR#pragma shader_stage()\fP relies on the \f(CR#pragma\fP preprocessor directive; thus,
165 the token inside \f(CRshader_stage()\fP is not subject to preprocessor macro
166 expansion. It must be exactly one of the \f(CRstage\fPs in the above table.
167 .sp
168 \f(CR#pragma shader_stage()\fP behaves as follows:
169 .sp
170 .RS 4
171 .ie n \{\
172 \h'-04'\(bu\h'+03'\c
173 .\}
174 .el \{\
175 . sp -1
176 . IP \(bu 2.3
177 .\}
178 The first \f(CR#pragma shader_stage()\fP directive in a translation unit must
179 precede any non\-preprocessor tokens.
180 .RE
181 .sp
182 .RS 4
183 .ie n \{\
184 \h'-04'\(bu\h'+03'\c
185 .\}
186 .el \{\
187 . sp -1
188 . IP \(bu 2.3
189 .\}
190 If there is more than one \f(CR#pragma shader_stage()\fP directive in the same
191 translation unit, all the \f(CRstage\fPs specified must be the same. Otherwise,
192 glslc will issue an error.
193 .RE
194 .SS "SPIR\-V assembly files"
195 .sp
196 SPIR\-V assembly input files should follow the
197 \c
198 .URL "https://github.com/KhronosGroup/SPIRV\-Tools/blob/master/syntax.md" "syntax"
199 defined in the \c
200 .URL "https://github.com/KhronosGroup/SPIRV\-Tools" "SPIRV\-Tools"
201 project and have the \f(CR.spvasm\fP extension. Command line options treat SPIR\-V
202 assembly files differently; some may ignore them, e.g., \f(CR\-E\fP,
203 \f(CR\-S\fP, and some may even treat them not as SPIR\-V assembly
204 files, e.g., \f(CR\-fshader\-stage=\fP.
205 .SS "Output file naming"
206 .sp
207 If a name is specified via \f(CR\-o\fP, the output file will be given that name.
208 Otherwise,
209 .sp
210 .RS 4
211 .ie n \{\
212 \h'-04'\(bu\h'+03'\c
213 .\}
214 .el \{\
215 . sp -1
216 . IP \(bu 2.3
217 .\}
218 If a compilation stage selection option is given (\f(CR\-S\fP or \f(CR\-c\fP), there will
219 be one output file generated per input shader file. The generated output file
220 will end with a file extension that matches the compilation stage, which is
221 \f(CR.spvasm\fP for \f(CR\-S\fP and \f(CR.spv\fP for \f(CR\-c\fP. The name will depend on the original
222 file\(cqs name and extension.
223 .sp
224 .RS 4
225 .ie n \{\
226 \h'-04'\(bu\h'+03'\c
227 .\}
228 .el \{\
229 . sp -1
230 . IP \(bu 2.3
231 .\}
232 If the input file has a shader stage selection
233 extension, the output file will be named as by appending the file extension
234 for the compilation stage to the input file\(cqs name. E.g., \f(CRglslc \-c foo.vert\fP
235 will generate \f(CRfoo.vert.spv\fP, and \f(CRglslc \-S bar.frag\fP will generate
236 \f(CRbar.frag.spvasm\fP.
237 .RE
238 .sp
239 .RS 4
240 .ie n \{\
241 \h'-04'\(bu\h'+03'\c
242 .\}
243 .el \{\
244 . sp -1
245 . IP \(bu 2.3
246 .\}
247 Otherwise, the output file will be named as by replacing the input file\(cqs
248 file extension, if any, with the file extension for the compilation stage.
249 E.g., \f(CRglslc \-c foo\fP will generate \f(CRfoo.spv\fP, and \f(CRglslc \-S bar.glsl\fP will
250 generate \f(CRbar.spvasm\fP.
251 .RE
252 .RE
253 .sp
254 .RS 4
255 .ie n \{\
256 \h'-04'\(bu\h'+03'\c
257 .\}
258 .el \{\
259 . sp -1
260 . IP \(bu 2.3
261 .\}
262 If no compilation stage is selected, the output file will be named \f(CRa.spv\fP.
263 .RE
264 .SH "COMMAND LINE OPTIONS"
265 .SS "Overall Options"
266 .SS "\f(CR\-\-help\fP, \f(CR\-h\fP"
267 .sp
268 Option \f(CR\-\-help\fP or \f(CR\-h\fP tells the glslc compiler to display all available options and exit.
269 .SS "\f(CR\-\-show\-limits\fP"
270 .sp
271 \f(CR\-\-show\-limits\fP shows default resource limits for shader compilation. The syntax
272 is the same as accepted by \f(CR\-flimit=\fP and for the contents of the file specified
273 by \f(CR\-flimit\-file\fP.
274 .SS "\f(CR\-o\fP"
275 .sp
276 \f(CR\-o\fP lets you specify the output file\(cqs name. It cannot be used when there are
277 multiple files generated. A filename of \f(CR\-\fP represents standard output.
278 .SS "Language and Mode Selection Options"
279 .SS "\f(CR\-finvert\-y\fP"
280 .sp
281 Inverts position.Y output in a vertex shader.
282 .SS "\f(CR\-flimit=\fP"
283 .sp
284 \f(CR\-flimit=<resource\-limits>\fP lets you specify resource limits.
285 The argument should be a sequence of limit name, integer value pairs. Tokens
286 should be separated by whitespace. If the same limit is specified several
287 times, only the last setting takes effect.
288 .sp
289 Use \f(CR\-\-show\-limits\fP to show the default values, and example syntax.
290 .sp
291 This option affects all compiled shaders.
292 .SS "\f(CR\-flimit\-file\fP"
293 .sp
294 \f(CR\-flimit\-file <resource\-limits\-file>\fP lets you specify resource limits in a file.
295 The syntax of the file contents is the same as the argument to \f(CR\-flimit=\fP and
296 the output of \f(CR\-\-show\-limits\fP. This option accepts Glslang resource configuration
297 files, e.g. as emitted by \f(CRglslangValidator \-c\fP.
298 .sp
299 This option affects all compiled shaders.
300 .SS "\f(CR\-fshader\-stage=\fP"
301 .sp
302 \f(CR\-fshader\-stage=<stage>\fP lets you specify the shader stage for one or more
303 inputs from the command line.
304 .sp
305 Possible values for \f(CR<stage>\fP are listed in the Shader Stage Selection table.
306 .sp
307 \f(CR\-fshader\-stage=\fP behaves as follows:
308 .sp
309 .RS 4
310 .ie n \{\
311 \h'-04'\(bu\h'+03'\c
312 .\}
313 .el \{\
314 . sp -1
315 . IP \(bu 2.3
316 .\}
317 \f(CR\-fshader\-stage=\fP sets the shader stage for subsequent input files. It does
318 not affect the stages of any preceding inputs on the command line.
319 .RE
320 .sp
321 .RS 4
322 .ie n \{\
323 \h'-04'\(bu\h'+03'\c
324 .\}
325 .el \{\
326 . sp -1
327 . IP \(bu 2.3
328 .\}
329 When supplying more than one \f(CR\-fshader\-stage=\fP argument, the most recent
330 argument preceding an input file applies.
331 .RE
332 .sp
333 .RS 4
334 .ie n \{\
335 \h'-04'\(bu\h'+03'\c
336 .\}
337 .el \{\
338 . sp -1
339 . IP \(bu 2.3
340 .\}
341 A shader file not ending with known shader file
342 extensions must have a \f(CR\-fshader\-stage=\fP argument ahead of it to specify
343 its stage.
344 .RE
345 .sp
346 .RS 4
347 .ie n \{\
348 \h'-04'\(bu\h'+03'\c
349 .\}
350 .el \{\
351 . sp -1
352 . IP \(bu 2.3
353 .\}
354 If there is a \f(CR\-fshader\-stage=\fP before a file in which there is a \f(CR#pragma
355 shader_stage()\fP directive, the directive is ignored and the \f(CR\-fshader\-stage=\fP
356 argument is used instead.
357 .RE
358 .sp
359 .RS 4
360 .ie n \{\
361 \h'-04'\(bu\h'+03'\c
362 .\}
363 .el \{\
364 . sp -1
365 . IP \(bu 2.3
366 .\}
367 If there is a \f(CR\-fshader\-stage=\fP before a file with a known shader file
368 extension, the file extension is ignored and the \f(CR\-fshader\-stage=\fP argument
369 is used instead.
370 .RE
371 .if n .sp
372 .RS 4
373 .it 1 an-trap
374 .nr an-no-space-flag 1
375 .nr an-break-flag 1
376 .br
377 .ps +1
378 .B Caution
379 .ps -1
380 .br
381 .sp
382 \f(CR\-fshader\-stage=\fP overrides file extension; that means it should not
383 be used together with SPIR\-V assembly files because glslc will treat the given
384 SPIR\-V assembly files as GLSL source code of the given shader stage. If you
385 need to supply both SPIR\-V assembly files and \f(CR\-fshader\-stage=\fP on the same
386 command line, please put SPIR\-V assembly files ahead of the first
387 \f(CR\-fshader\-stage=\fP, since \f(CR\-fshader\-stage=\fP only affects the treatment of
388 subsequent files.
389 .sp .5v
390 .RE
391 .SS "\f(CR\-std=\fP"
392 .sp
393 \f(CR\-std=<value>\fP lets you specify a shader version and profile on the command
394 line. \f(CR<value>\fP can be any valid concatenation of a GLSL version number and
395 profile, e.g., \f(CR310es\fP, \f(CR450core\fP, etc. The profile can be omitted as allowed by
396 GLSL, e.g., \f(CR450\fP.
397 .sp
398 \f(CR\-std=\fP behaves as follows:
399 .sp
400 .RS 4
401 .ie n \{\
402 \h'-04'\(bu\h'+03'\c
403 .\}
404 .el \{\
405 . sp -1
406 . IP \(bu 2.3
407 .\}
408 \f(CR\-std=\fP affects the version of all GLSL inputs passed to \f(CRglslc\fP.
409 .RE
410 .sp
411 .RS 4
412 .ie n \{\
413 \h'-04'\(bu\h'+03'\c
414 .\}
415 .el \{\
416 . sp -1
417 . IP \(bu 2.3
418 .\}
419 \f(CR\-std=\fP is ignored for HLSL inputs.
420 .RE
421 .sp
422 .RS 4
423 .ie n \{\
424 \h'-04'\(bu\h'+03'\c
425 .\}
426 .el \{\
427 . sp -1
428 . IP \(bu 2.3
429 .\}
430 \f(CR\-std=\fP overwrites \f(CR#version\fP directives in all input shaders, including those
431 preceding the argument.
432 .RE
433 .sp
434 .RS 4
435 .ie n \{\
436 \h'-04'\(bu\h'+03'\c
437 .\}
438 .el \{\
439 . sp -1
440 . IP \(bu 2.3
441 .\}
442 If a \f(CR\-std=\fP argument specifies a different version from a \f(CR#version\fP
443 directive in an input file, \f(CRglslc\fP will issue a warning.
444 .RE
445 .sp
446 .RS 4
447 .ie n \{\
448 \h'-04'\(bu\h'+03'\c
449 .\}
450 .el \{\
451 . sp -1
452 . IP \(bu 2.3
453 .\}
454 If multiple \f(CR\-std=\fP arguments are specified on the command line, only the last
455 one takes effect.
456 .RE
457 .if n .sp
458 .RS 4
459 .it 1 an-trap
460 .nr an-no-space-flag 1
461 .nr an-break-flag 1
462 .br
463 .ps +1
464 .B Caution
465 .ps -1
466 .br
467 .sp
468 \f(CR\-std=\fP does not affect the \f(CR#version\fP directive in the preprocessed
469 output. That is, when \f(CR\-std=\fP specifies a version different from the shader
470 source code, the \f(CR#version\fP directive in preprocessed output will still be the
471 one in the source code. But \f(CR\-std=\fP does affect the behavior of \f(CR#line\fP
472 directives in the preprocessed output. Behavior of \f(CR#line\fP directives will
473 follow the version specified by \f(CR\-std=\fP.
474 .sp .5v
475 .RE
476 .SS "\f(CR\-\-target\-env=\fP"
477 .sp
478 \f(CR\-\-target\-env=<value>\fP lets you specify a target environment on the command line.
479 This affects the generation of warnings and errors. The \f(CR<value>\fP can be one of
480 the following:
481 .sp
482 .RS 4
483 .ie n \{\
484 \h'-04'\(bu\h'+03'\c
485 .\}
486 .el \{\
487 . sp -1
488 . IP \(bu 2.3
489 .\}
490 \f(CRvulkan\fP: create SPIR\-V under Vulkan 1.0 semantics.
491 .RE
492 .sp
493 .RS 4
494 .ie n \{\
495 \h'-04'\(bu\h'+03'\c
496 .\}
497 .el \{\
498 . sp -1
499 . IP \(bu 2.3
500 .\}
501 \f(CRvulkan1.0\fP: create SPIR\-V under Vulkan 1.0 semantics.
502 .RE
503 .sp
504 .RS 4
505 .ie n \{\
506 \h'-04'\(bu\h'+03'\c
507 .\}
508 .el \{\
509 . sp -1
510 . IP \(bu 2.3
511 .\}
512 \f(CRvulkan1.1\fP: create SPIR\-V under Vulkan 1.1 semantics.
513 .RE
514 .sp
515 .RS 4
516 .ie n \{\
517 \h'-04'\(bu\h'+03'\c
518 .\}
519 .el \{\
520 . sp -1
521 . IP \(bu 2.3
522 .\}
523 \f(CRvulkan1.2\fP: create SPIR\-V under Vulkan 1.2 semantics.
524 .RE
525 .sp
526 .RS 4
527 .ie n \{\
528 \h'-04'\(bu\h'+03'\c
529 .\}
530 .el \{\
531 . sp -1
532 . IP \(bu 2.3
533 .\}
534 \f(CRopengl\fP: create SPIR\-V under OpenGL 4.5 semantics.
535 .RE
536 .sp
537 .RS 4
538 .ie n \{\
539 \h'-04'\(bu\h'+03'\c
540 .\}
541 .el \{\
542 . sp -1
543 . IP \(bu 2.3
544 .\}
545 \f(CRopengl4.5\fP: create SPIR\-V under OpenGL 4.5 semantics.
546 .RE
547 .sp
548 Generated code uses SPIR\-V 1.0, except for code compiled for Vulkan 1.1, which uses
549 SPIR\-V 1.3, and code compiled for Vulkan 1.5, which uses SPIR\-V 1.5.
550 .sp
551 If this option is not specified, a default of \f(CRvulkan1.0\fP is used.
552 .sp
553 Note: Support for OpenGL compatibility profile, \f(CRopengl_compat\fP, has been removed.
554 .SS "\f(CR\-\-target\-spv=\fP"
555 .sp
556 \f(CR\-\-target\-spv=<value>\fP lets you specify the SPIR\-V version to be used by the generated
557 module. The default is to use the highest version of SPIR\-V required to be supported
558 by the target environment. The defaults for specific Vulkan target environments are
559 as follows: SPIR\-V 1.0 for Vulkan 1.0, SPIR\-V 1.3 for Vulkan 1.1, and SPIR\-V 1.5 for
560 Vulkan 1.2.
561 .sp
562 The \f(CR<value>\fP can be one of the following:
563 .sp
564 .RS 4
565 .ie n \{\
566 \h'-04'\(bu\h'+03'\c
567 .\}
568 .el \{\
569 . sp -1
570 . IP \(bu 2.3
571 .\}
572 \f(CRspv1.0\fP
573 .RE
574 .sp
575 .RS 4
576 .ie n \{\
577 \h'-04'\(bu\h'+03'\c
578 .\}
579 .el \{\
580 . sp -1
581 . IP \(bu 2.3
582 .\}
583 \f(CRspv1.1\fP
584 .RE
585 .sp
586 .RS 4
587 .ie n \{\
588 \h'-04'\(bu\h'+03'\c
589 .\}
590 .el \{\
591 . sp -1
592 . IP \(bu 2.3
593 .\}
594 \f(CRspv1.2\fP
595 .RE
596 .sp
597 .RS 4
598 .ie n \{\
599 \h'-04'\(bu\h'+03'\c
600 .\}
601 .el \{\
602 . sp -1
603 . IP \(bu 2.3
604 .\}
605 \f(CRspv1.3\fP
606 .RE
607 .sp
608 .RS 4
609 .ie n \{\
610 \h'-04'\(bu\h'+03'\c
611 .\}
612 .el \{\
613 . sp -1
614 . IP \(bu 2.3
615 .\}
616 \f(CRspv1.4\fP
617 .RE
618 .sp
619 .RS 4
620 .ie n \{\
621 \h'-04'\(bu\h'+03'\c
622 .\}
623 .el \{\
624 . sp -1
625 . IP \(bu 2.3
626 .\}
627 \f(CRspv1.5\fP
628 .RE
629 .SS "\f(CR\-x\fP"
630 .sp
631 \f(CR\-x\fP lets you specify the language of the input shader files. Valid languages
632 are \f(CRglsl\fP and \f(CRhlsl\fP. If the file extension is \f(CRhlsl\fP then the default language
633 is HLSL. Otherwise the default is \*(Aqglsl\*(Aq.
634 .sp
635 Note: HLSL compilation will use HLSL packing (offset) rules for variables
636 that are vertex shader outputs, and inputs and outputs of both geometry
637 and pixel shaders.
638 .SS "Compilation Stage Selection Options"
639 .SS "\f(CR\-c\fP"
640 .sp
641 \f(CR\-c\fP tells the glslc compiler to run the preprocessing and compiling stage.
642 Each input shader file results in a SPIR\-V binary file; these SPIR\-V binary
643 files are named by the rules in the Output File Naming
644 section.
645 .SS "\f(CR\-E\fP"
646 .sp
647 \f(CR\-E\fP tells the glslc compiler to run only the preprocessing stage. It overrides
648 \f(CR\-c\fP and \f(CR\-S\fP. Preprocessed output is written to standard output, while
649 preprocessing errors are written to standard error. If multiple input shader
650 files are given, their preprocessed output are all written to standard output,
651 in the order specified on the command line.
652 .sp
653 glslc will do nothing for SPIR\-V assembly files with this option.
654 .SS "\f(CR\-S\fP"
655 .sp
656 \f(CR\-S\fP tells the glslc compiler to run the preprocessing, compiling, and then
657 disassembling stage. It overrides \f(CR\-c\fP. Each input shader file results in a
658 SPIR\-V assembly file; these SPIR\-V assembly files are named by the rules in the
659 Output File Naming section.
660 .sp
661 glslc will do nothing for SPIR\-V assembly files with this option.
662 .SS "No Compilation Stage Selection"
663 .sp
664 If none of the above options is given, the glslc compiler will run
665 preprocessing, compiling, and linking stages.
666 .if n .sp
667 .RS 4
668 .it 1 an-trap
669 .nr an-no-space-flag 1
670 .nr an-break-flag 1
671 .br
672 .ps +1
673 .B Warning
674 .ps -1
675 .br
676 .sp
677 Linking of multiple input shader files are not supported yet.
678 .sp .5v
679 .RE
680 .SS "Preprocessor Options"
681 .SS "\f(CR\-D\fP"
682 .sp
683 \f(CR\-Dmacroname[=[value]]\fP lets you define a preprocessor macro before input shader
684 files are preprocessed. If \f(CRvalue\fP is omitted, the macro is defined with an
685 empty value.
686 .SS "\f(CR\-I\fP"
687 .sp
688 \f(CR\-Idirectory\fP or \f(CR\-I directory\fP adds the specified directory to the search path
689 for include files. The directory may be an absolute path or a relative path to
690 the current working directory.
691 .SS "Code Generation Options"
692 .SS "\f(CR\-g\fP"
693 .sp
694 Requests that the compiler place source\-level debug information into the object
695 code, such as identifier names and line numbers.
696 .sp
697 This option restrains \f(CR\-O\fP from turning on the strip\-debug\-info optimization
698 pass.
699 .if n .sp
700 .RS 4
701 .it 1 an-trap
702 .nr an-no-space-flag 1
703 .nr an-break-flag 1
704 .br
705 .ps +1
706 .B Note
707 .ps -1
708 .br
709 .sp
710 Currently this option has no effect. Full functionality depends on
711 glslang support for generating debug info.
712 .sp .5v
713 .RE
714 .SS "\f(CR\-O0\fP, \f(CR\-Os\fP"
715 .sp
716 \f(CR\-O\fP specifies which optimization level to use:
717 .sp
718 .RS 4
719 .ie n \{\
720 \h'-04'\(bu\h'+03'\c
721 .\}
722 .el \{\
723 . sp -1
724 . IP \(bu 2.3
725 .\}
726 \f(CR\-O0\fP means "no optimization". This level generates the most debuggable code.
727 .RE
728 .sp
729 .RS 4
730 .ie n \{\
731 \h'-04'\(bu\h'+03'\c
732 .\}
733 .el \{\
734 . sp -1
735 . IP \(bu 2.3
736 .\}
737 \f(CR\-O\fP means the default optimization level for better performance.
738 .RE
739 .sp
740 .RS 4
741 .ie n \{\
742 \h'-04'\(bu\h'+03'\c
743 .\}
744 .el \{\
745 . sp -1
746 . IP \(bu 2.3
747 .\}
748 \f(CR\-Os\fP enables optimizations to reduce code size.
749 .RE
750 .SS "\f(CR\-mfmt=<format>\fP"
751 .sp
752 \f(CR\-mfmt=<format>\fP selects output format for compilation output in SPIR\-V binary
753 code form. Supported options are listed in the
754 binary output format options table. This
755 option is only valid to be used when the compilation output is SPIR\-V binary
756 code. Specifying any options listed below when the output is not SPIR\-V binary
757 code, like disassembly (with \f(CR\-S\fP specified), text (with \f(CR\-M\fP, \f(CR\-MM\fP or \f(CR\-E\fP
758 specified) will trigger an error.
759 .sp
760 .it 1 an-trap
761 .nr an-no-space-flag 1
762 .nr an-break-flag 1
763 .br
764 .B Table 2. Binary Output Format Options
765 .TS
766 allbox tab(:);
767 lt lt.
768 T{
769 .sp
770 Format option
771 T}:T{
772 .sp
773 Description
774 T}
775 T{
776 .sp
777 bin
778 T}:T{
779 .sp
780 Output SPIR\-V binary code as a sequence of binary 32\-bitwords
781 in host native endianness. This is the default format for
782 SPIR\-V binary compilation output.
783 T}
784 T{
785 .sp
786 num
787 T}:T{
788 .sp
789 Output SPIR\-V binary code as a text file containing a list of
790 comma\-separated hex numbers.
791 .br
792 Example: \f(CRglslc \-c \-mfmt=num main.vert \-o output_file.txt\fP
793 .br
794 Content of the output_file.txt:
795 .br
796 0x07230203,0x00010000,0x00080001,0x00000006...
797 T}
798 T{
799 .sp
800 c
801 T}:T{
802 .sp
803 Output SPIR\-V binary code as a text file containing C\-style
804 .br
805 initializer list.
806 .br
807 This is just wrapping the output of \f(CRnum\fP option with curly
808 brackets.
809 .br
810 Example: \f(CRglslc \-c \-mfmt=c main.vert \-o output_file.txt\fP
811 .br
812 Content of output_file.txt:
813 .br
814 {0x07230203, 0x00010000, 0x00080001, 0x00000006...}
815 T}
816 .TE
817 .sp
818 .SS "\f(CR\-fhlsl\-offsets\fP"
819 .sp
820 Use HLSL packing rules instead of GLSL rules when determining offsets of
821 members of blocks. This option is always on when compiling for HLSL.
822 .SS "\f(CR\-fhlsl\-functionality1\fP"
823 .sp
824 Enable extension \f(CRSPV_GOOGLE_hlsl_functionality1\fP, and instructs the compiler
825 to:
826 .sp
827 .RS 4
828 .ie n \{\
829 \h'-04'\(bu\h'+03'\c
830 .\}
831 .el \{\
832 . sp -1
833 . IP \(bu 2.3
834 .\}
835 Annotate HLSL semantic string decorations on interface objects
836 .RE
837 .sp
838 .RS 4
839 .ie n \{\
840 \h'-04'\(bu\h'+03'\c
841 .\}
842 .el \{\
843 . sp -1
844 . IP \(bu 2.3
845 .\}
846 Explicitly record the association of a UAV resource with its companion counter buffer.
847 .RE
848 .sp
849 This option can also be spelled with an underscore: \f(CR\-fhlsl_functionality1\fP.
850 .SS "\f(CR\-fentry\-point=<name>\fP"
851 .sp
852 \f(CR\-fentry\-point=<name>\fP lets you specify the entry point name. This is only
853 significant for HLSL compilation. The default is "main".
854 .SS "\f(CR\-fauto\-map\-locations\fP"
855 .sp
856 For GLSL compilation, option \f(CR\-fauto\-map\-locations\fP directs the compiler to automatically
857 assign location numbers to user\-defined stage input and output variables if not explicitly
858 specified by the shader source.
859 .sp
860 For HLSL compilation, this option is on by default.
861 .sp
862 Client APIs normally require adjacent stages to agree on their I/O interface.
863 The compiler only sees one stage at a time, so it is strongly recommended that
864 you avoid relying on this option to assign locations.
865 .sp
866 Instead, an explicit binding number should be specified in the shader source, as follows:
867 .sp
868 .RS 4
869 .ie n \{\
870 \h'-04'\(bu\h'+03'\c
871 .\}
872 .el \{\
873 . sp -1
874 . IP \(bu 2.3
875 .\}
876 In a GLSL shader, use a \f(CRlocation\fP layout qualifier:
877 .RE
878 .sp
879 .if n .RS 4
880 .nf
881 .fam C
882 layout(location = 1) in vec4 x;
883 .fam
884 .fi
885 .if n .RE
886 .sp
887 .RS 4
888 .ie n \{\
889 \h'-04'\(bu\h'+03'\c
890 .\}
891 .el \{\
892 . sp -1
893 . IP \(bu 2.3
894 .\}
895 In an HLSL shader, use a \f(CRvk::location\fP attribute:
896 .RE
897 .sp
898 .if n .RS 4
899 .nf
900 .fam C
901 [[vk::location(1)]] float4 FooShader(
902 [[vk::location(0)]] float4 a,
903 [[vk::location(2)]] float4 b) : COLOR0 {
904 return a + b;
905 }
906 .fam
907 .fi
908 .if n .RE
909 .SS "Warning and Error Options"
910 .SS "\f(CR\-w\fP"
911 .sp
912 \f(CR\-w\fP suppresses all warning output from \f(CRglslc\fP. Any warning that would have
913 been generated is silently ignored.
914 .SS "\f(CR\-Werror\fP"
915 .sp
916 \f(CR\-Werror\fP forces any warning to be treated as an error in \f(CRglslc\fP. This means
917 that all \f(CRwarning:\fP messages are shown as \f(CRerror:\fP and any warnings will cause
918 a non\-zero exit code from \f(CRglslc\fP. If \f(CR\-w\fP is specified the warnings
919 generated are suppressed before they are converted to errors.
920 .SS "Dependency Generation Options"
921 .SS "\f(CR\-M\fP or \f(CR\-MM\fP"
922 .sp
923 \f(CR\-M\fP generates \fBmake\fP dependencies. It outputs a rule suitable for \fBmake\fP
924 describing the dependencies of the input file. Instead of outputting the result
925 of preprocessing, the preprocessor outputs one \fBmake\fP rule containing the
926 SPIR\-V object file name for that source file, a colon, and the names of all the
927 included files.
928 .sp
929 Unless specified explicitly (with \f(CR\-MT\fP), the SPIR\-V object file name in the
930 generated \fBmake\fP rules follows the rules of Output File
931 Naming as in \f(CR\-c\fP compilation stage.
932 .sp
933 Specifying \f(CR\-M\fP implies \f(CR\-E\fP, and suppresses warnings with an implicit \f(CR\-w\fP.
934 By default the output will be written to stdout, unless \f(CR\-MF\fP or \f(CR\-o\fP is
935 specified.
936 .sp
937 The dependency info file name can be specified by \f(CR\-o\fP and \f(CR\-MF\fP options. When
938 both are specified, \f(CR\-o\fP option is ignored.
939 .sp
940 Specifying multiple input files is valid when the \fBmake\fP rules are written to
941 stdout, which means neither \f(CR\-MF\fP nor \f(CR\-o\fP is specified. When \f(CR\-o\fP or \f(CR\-MF\fP is
942 specified, only one input file is allowed.
943 .sp
944 \f(CR\-MM\fP is an alias for \f(CR\-M\fP.
945 .sp
946 E.g., \f(CRglslc \-M main.vert\fP will dump \f(CRmain.vert.spv: main.vert <other included
947 files>\fP to stdout. More examples are listed in
948 Dependency Generation Examples
949 .SS "\f(CR\-MD\fP"
950 .sp
951 \f(CR\-MD\fP tells the glslc compiler to both compile the source and generate \fBmake\fP
952 dependencies. Dependencies are written to a file whose name is determined as
953 follows: If option \f(CR\-MF\fP is specified, use its argument. Otherwise, use the
954 filename formed by appending \fB.d\fP to the name of the file containing
955 compilation results.
956 .sp
957 Specifying multiple input files is valid when neither \f(CR\-MF\fP nor \f(CR\-o\fP is
958 specified. When \f(CR\-o\fP or \f(CR\-MF\fP is specified, only one input file is allowed.
959 .sp
960 E.g., \f(CRglslc \-c \-MD main.vert\fP will generate \f(CRmain.vert.spv\fP as the SPIR\-V
961 object file and \f(CRmain.vert.spv.d\fP as the dependency info file. More examples
962 are listed in Dependency Generation Examples
963 .SS "\f(CR\-MF\fP"
964 .sp
965 \f(CR\-MF\fP lets you specify the dependency info file name when used with \f(CR\-M\fP or
966 \f(CR\-MD\fP. This option is invalid when used with multiple input files.
967 .sp
968 E.g., \f(CRglslc \-c \-MD main.vert \-MF dep_info\fP will generate \f(CRmain.vert.spv\fP as
969 the SPIR\-V object file and \f(CRdep_info\fP as the dependency info file.
970 .SS "\f(CR\-MT\fP"
971 .sp
972 \f(CR\-MT\fP lets you specify the target of the rule emitted by dependency generation
973 when used with \f(CR\-M\fP or \f(CR\-MD\fP. This option is invalid when used with multiple
974 input files.
975 .sp
976 E.g., \f(CRglslc \-M main.vert \-MT target\fP will dump following dependency info to
977 stdout: \f(CRtarget: main.vert <other dependent files>\fP.
978 .sp
979 .it 1 an-trap
980 .nr an-no-space-flag 1
981 .nr an-break-flag 1
982 .br
983 .B Table 3. Dependency Generation Examples
984 .TS
985 allbox tab(:);
986 lt lt lt lt.
987 T{
988 .sp
989 Command Line Input
990 T}:T{
991 .sp
992 Compilation Output File
993 T}:T{
994 .sp
995 Dependency Output File
996 T}:T{
997 .sp
998 Dependency Info
999 T}
1000 T{
1001 .sp
1002 glslc \-M main.vert
1003 T}:T{
1004 .sp
1005 <NA>
1006 T}:T{
1007 .sp
1008 <Stdout>
1009 T}:T{
1010 .sp
1011 main.vert.spv: main.vert
1012 T}
1013 T{
1014 .sp
1015 glslc \-M a.vert b.vert
1016 T}:T{
1017 .sp
1018 <NA>
1019 T}:T{
1020 .sp
1021 <Stdout>
1022 T}:T{
1023 .sp
1024 a.vert.spv: a.vert
1025 T}
1026 T{
1027 .sp
1028 T}:T{
1029 .sp
1030 <NA>
1031 T}:T{
1032 .sp
1033 <Stdout>
1034 T}:T{
1035 .sp
1036 b.vert.spv: b.vert
1037 T}
1038 T{
1039 .sp
1040 glslc \-M main.vert \-o dep_info
1041 T}:T{
1042 .sp
1043 <NA>
1044 T}:T{
1045 .sp
1046 dep_info
1047 T}:T{
1048 .sp
1049 main.vert.spv: main.vert
1050 T}
1051 T{
1052 .sp
1053 glslc \-M main.vert \-MF dep_info
1054 T}:T{
1055 .sp
1056 <NA>
1057 T}:T{
1058 .sp
1059 dep_info
1060 T}:T{
1061 .sp
1062 main.vert.spv: main.vert
1063 T}
1064 T{
1065 .sp
1066 glslc \-M main.vert \-MT target
1067 T}:T{
1068 .sp
1069 <NA>
1070 T}:T{
1071 .sp
1072 <Stdout>
1073 T}:T{
1074 .sp
1075 target: main.vert
1076 T}
1077 T{
1078 .sp
1079 glslc \-MD main.vert
1080 T}:T{
1081 .sp
1082 a.spv
1083 T}:T{
1084 .sp
1085 main.vert.spv.d
1086 T}:T{
1087 .sp
1088 main.vert.spv: main.vert
1089 T}
1090 T{
1091 .sp
1092 glslc \-c \-MD main.vert
1093 T}:T{
1094 .sp
1095 main.vert.spv
1096 T}:T{
1097 .sp
1098 main.vert.spv.d
1099 T}:T{
1100 .sp
1101 main.vert.spv: main.vert
1102 T}
1103 T{
1104 .sp
1105 glslc \-c \-MD a.vert b.vert
1106 T}:T{
1107 .sp
1108 a.vert.spv
1109 T}:T{
1110 .sp
1111 a.vert.spv.d
1112 T}:T{
1113 .sp
1114 a.vert.spv: a.vert
1115 T}
1116 T{
1117 .sp
1118 T}:T{
1119 .sp
1120 b.vert.spv
1121 T}:T{
1122 .sp
1123 b.vert.spv.d
1124 T}:T{
1125 .sp
1126 b.vert.spv: b.vert
1127 T}
1128 T{
1129 .sp
1130 glslc \-S \-MD main.vert
1131 T}:T{
1132 .sp
1133 main.vert.spvasm
1134 T}:T{
1135 .sp
1136 main.vert.spvasm.d
1137 T}:T{
1138 .sp
1139 main.vert.spvasm: main.vert
1140 T}
1141 T{
1142 .sp
1143 glslc \-c \-MD main.vert \-MF dep_info
1144 T}:T{
1145 .sp
1146 main.vert.spv
1147 T}:T{
1148 .sp
1149 dep_info
1150 T}:T{
1151 .sp
1152 main.vert.spv: main.vert
1153 T}
1154 T{
1155 .sp
1156 glslc \-c \-MD main.vert \-o obj
1157 T}:T{
1158 .sp
1159 obj
1160 T}:T{
1161 .sp
1162 obj.d
1163 T}:T{
1164 .sp
1165 obj: main.vert
1166 T}
1167 T{
1168 .sp
1169 glslc \-c \-MD main.vert \-o obj \-MF dep_info \-MT target
1170 T}:T{
1171 .sp
1172 obj
1173 T}:T{
1174 .sp
1175 dep_info
1176 T}:T{
1177 .sp
1178 target: main.vert
1179 T}
1180 .TE
1181 .sp
1182 .SS "Resource Binding Options"
1183 .SS "\f(CR\-fauto\-bind\-uniforms\fP"
1184 .sp
1185 Option \f(CR\-fauto\-bind\-uniforms\fP directs the compiler to automatically assign
1186 binding numbers to uniform variables, when an explicit binding is not
1187 specified in the shader source.
1188 .sp
1189 An explicit binding number can be specified in the shader source by using
1190 a \f(CRbinding\fP layout qualifier. For example:
1191 .sp
1192 .if n .RS 4
1193 .nf
1194 .fam C
1195 layout(binding = 12) uniform texture2D;
1196 .fam
1197 .fi
1198 .if n .RE
1199 .SS "\f(CR\-fhlsl\-iomap\fP"
1200 .sp
1201 Option \f(CR\-fhlsl\-iomap\fP directs the compiler to use HLSL register
1202 assignments as binding values.
1203 .SS "\f(CR\-fimage\-binding\-base\fP"
1204 .sp
1205 Option \f(CR\-fimage\-binding\-base [stage] base\fP sets the lowest automatically
1206 assigned binding for images. If a stage is specified, only affects the specified
1207 stage.
1208 .sp
1209 For HLSL, sets one less than the base.
1210 .SS "\f(CR\-fsampler\-binding\-base\fP"
1211 .sp
1212 Option \f(CR\-fsampler\-binding\-base [stage] base\fP sets the lowest automatically
1213 assigned binding for samplers. If a stage is specified, only affects the specified
1214 stage.
1215 .sp
1216 For HLSL, sets one less than the base.
1217 .SS "\f(CR\-ftexture\-binding\-base\fP"
1218 .sp
1219 Option \f(CR\-ftexture\-binding\-base [stage] base\fP sets the lowest automatically
1220 assigned binding for textures. If a stage is specified, only affects the specified
1221 stage.
1222 .sp
1223 For HLSL, sets one less than the base.
1224 .SS "\f(CR\-fubo\-binding\-base\fP"
1225 .sp
1226 Option \f(CR\-fubo\-binding\-base [stage] base\fP sets the lowest automatically
1227 assigned binding for Uniform Buffer Objects (GLSL) or Cbuffers (HLSL).
1228 If a stage is specified, only affects the specified stage.
1229 .sp
1230 For HLSL, sets one less than the base.
1231 .SS "\f(CR\-fcbuffer\-binding\-base\fP"
1232 .sp
1233 Option \f(CR\-fcbuffer\-binding\-base [stage] base\fP is the same as
1234 \f(CR\-fubo\-binding\-base [stage] base\fP.
1235 .SS "\f(CR\-fssbo\-binding\-base\fP"
1236 .sp
1237 Option \f(CR\-fssbo\-binding\-base [stage] base\fP sets the lowest automatically
1238 assigned binding for Shader Storage Buffer Objects (GLSL).
1239 If a stage is specified, only affects the specified stage.
1240 .sp
1241 This only affects GLSL compilation.
1242 .SS "\f(CR\-fuav\-binding\-base\fP"
1243 .sp
1244 Option \f(CR\-fuav\-binding\-base [stage] base\fP sets one less than the lowest
1245 automatically assigned binding for Unordered Access Views (UAV).
1246 If a stage is specified, only affects the specified stage.
1247 .sp
1248 This only affects HLSL compilation.
1249 .SS "\f(CR\-fresource\-set\-binding\fP"
1250 .sp
1251 Option \f(CR\-fresource\-set\-binding [stage] <reg0> <set0> <binding0>\fP sets
1252 the descriptor set and binding for an HLSL resource, by register name.
1253 To specify settings for more registers, append their triples consisting
1254 of register name, descriptor set, and binding.
1255 .sp
1256 Example:
1257 .sp
1258 .if n .RS 4
1259 .nf
1260 .fam C
1261 # For a texture in register t1, use set 1 binding 0.
1262 # For a texture in register t2, use set 1 binding 3
1263 glslc \-x hlsl foo.frag \-fresource\-set\-binding t1 1 0 t2 1 3
1264 .fam
1265 .fi
1266 .if n .RE
1267 .sp
1268 If a stage is specified, only affects the specified stage.
1269 .sp
1270 .if n .RS 4
1271 .nf
1272 .fam C
1273 # Same as the previous example, but the settings only apply
1274 # to fragment (pixel) shaders.
1275 glslc \-x hlsl foo.frag \-fresource\-set\-binding frag t1 1 0 t2 1 3
1276 .fam
1277 .fi
1278 .if n .RE
1279 .SH "DIVERGENCE FROM AND EXTENSIONS TO GLSL SPECIFICATIONS"
1280 .SS "Source\-filename\-based \f(CR#line\fP and \f(CR__FILE__\fP"
1281 .sp
1282 This section describes how the glslc compiler extends the syntax for the \f(CR#line\fP
1283 directive and the \f(CR__FILE__\fP macro. By default, the glslc compiler enables
1284 the \f(CRGL_GOOGLE_cpp_style_line_directive\fP extension. It will generate this
1285 extended syntax in the preprocessed output (obtained via the \f(CR\-E\fP option).
1286 .if n .sp
1287 .RS 4
1288 .it 1 an-trap
1289 .nr an-no-space-flag 1
1290 .nr an-break-flag 1
1291 .br
1292 .ps +1
1293 .B Warning
1294 .ps -1
1295 .br
1296 .sp
1297 This section is still evolving. Expect changes.
1298 .sp .5v
1299 .RE
1300 .sp
1301 GLSL specifications have a notion of source strings.
1302 .RS 3
1303 .ll -.6i
1304 .sp
1305 The source for a single shader is an array of strings of characters from the
1306 character set. A single shader is made from the concatenation of these strings.
1307 .br
1308 .RE
1309 .ll
1310 .RS 5
1311 .ll -.10i
1312 \(em Section 3.2 of both version 3.30 and 4.50
1313 .RE
1314 .ll
1315 .sp
1316 With the above notion, the second parameter to the \f(CR#line\fP directive should
1317 be a constant integer expressions representing the source string number. Also
1318 the \f(CR__FILE__\fP macro will "substitute a decimal integer constant that says
1319 which source string number is currently being processed."
1320 .sp
1321 The glslc compiler implements the standard \f(CR#line\fP and \f(CR__FILE__\fP syntax. It
1322 also provides an extension, \f(CRGL_GOOGLE_cpp_style_line_directive\fP, to allow
1323 source filenames to be used instead of integer source string indices.
1324 Specifically, the \f(CR#line\fP directive can have, after macro substitution, one of
1325 the following three forms:
1326 .sp
1327 .if n .RS 4
1328 .nf
1329 .fam C
1330 #line line\-number
1331 #line line\-number integer\-source\-string\-index
1332 #line line\-number "source\-filename"
1333 .fam
1334 .fi
1335 .if n .RE
1336 .sp
1337 where \f(CRsource\-filename\fP can be any combinations of characters except double
1338 quotation marks. (Note that according to the GLSL specification, "there are
1339 no escape sequences or other uses of the backslash beyond use as the
1340 line\-continuation character".)
1341 .sp
1342 And if source\-filename\-based \f(CR#line\fP is used, the \f(CR__FILE__\fP macro expands to
1343 a string whose contents are the filename quoted with double quotation marks.
1344 The filename is dertermined as the last of
1345 .sp
1346 .RS 4
1347 .ie n \{\
1348 \h'-04'\(bu\h'+03'\c
1349 .\}
1350 .el \{\
1351 . sp -1
1352 . IP \(bu 2.3
1353 .\}
1354 The filename given to the glslc compiler,
1355 .RE
1356 .sp
1357 .RS 4
1358 .ie n \{\
1359 \h'-04'\(bu\h'+03'\c
1360 .\}
1361 .el \{\
1362 . sp -1
1363 . IP \(bu 2.3
1364 .\}
1365 The filename argument of the most recent \f(CR#line\fP directive, if any.
1366 .RE
1367 .SS "\f(CR#include\fP"
1368 .sp
1369 The glslc compiler extends GLSL with the include syntax by turning on the
1370 \f(CRGL_GOOGLE_include_directive\fP extension. It will preprocess and substitute
1371 \f(CR#include\fP directives properly with the following behaviors.
1372 .if n .sp
1373 .RS 4
1374 .it 1 an-trap
1375 .nr an-no-space-flag 1
1376 .nr an-break-flag 1
1377 .br
1378 .ps +1
1379 .B Warning
1380 .ps -1
1381 .br
1382 .sp
1383 This section is still evolving. Expect changes.
1384 .sp .5v
1385 .RE
1386 .sp
1387 If \f(CR#include\fP directives are used in a shader, there will be an \f(CR#extension
1388 GL_GOOGLE_include_directive : enable\fP line generated into the preprocessed
1389 output.
1390 .sp
1391 The \f(CRGL_GOOGLE_cpp_style_line_directive\fP extension is implicitly turned on by
1392 the \f(CRGL_GOOGLE_include_directive\fP extension.
1393 .sp
1394 The file argument to \f(CR#include\fP must be enclosed in double quotes. It must be a
1395 relative path, using whatever path separator the OS supports. However, the last
1396 path element \(em the name of the file itself \(em must not contain either \*(Aq/\*(Aq or
1397 \*(Aq\(rs\*(Aq, regardless of which path separator is used. This will not be flagged as an
1398 error but will instead trigger undefined behavior. For example, let\(cqs say there
1399 is a file named \f(CRf\(rsilename.vert\fP on a Unix OS. It is not possible to craft a
1400 \f(CR#include\fP that includes that file.
1401 .sp
1402 Furthermore, it is not possible to escape any characters in a \f(CR#include\fP
1403 directive, so the file argument cannot contain any special characters that need
1404 escaping in C.
1405 .sp
1406 The file argument is a relative path that is matched first against the including
1407 file\(cqs own directory and then against all \f(CR\-I\fP arguments in order of their
1408 appearance on the command line. If the file cannot be found, \f(CRglslc\fP aborts
1409 with an error.
|
