Debian Codegraph @

third_party/glslang/README-spirv-remap.txt

raw
1
2 VERSION
3 --------------------------------------------------------------------------------
4 spirv-remap 0.97
5
6 INTRO:
7 --------------------------------------------------------------------------------
8 spirv-remap is a utility to improve compression of SPIR-V binary files via
9 entropy reduction, plus optional stripping of debug information and
10 load/store optimization. It transforms SPIR-V to SPIR-V, remapping IDs. The
11 resulting modules have an increased ID range (IDs are not as tightly packed
12 around zero), but will compress better when multiple modules are compressed
13 together, since compressor's dictionary can find better cross module
14 commonality.
15
16 Remapping is accomplished via canonicalization. Thus, modules can be
17 compressed one at a time with no loss of quality relative to operating on
18 many modules at once. The command line tool operates on multiple modules
19 only in the trivial repetition sense, for ease of use. The remapper API
20 only accepts a single module at a time.
21
22 There are two modes of use: command line, and a C++11 API. Both are
23 described below.
24
25 spirv-remap is currently in an alpha state. Although there are no known
26 remapping defects, it has only been exercised on one real world game shader
27 workload.
28
29
30 FEEDBACK
31 --------------------------------------------------------------------------------
32 Report defects, enhancements requests, code improvements, etc to:
33 [email protected]
34
35
36 COMMAND LINE USAGE:
37 --------------------------------------------------------------------------------
38 Examples are given with a verbosity of one (-v), but more verbosity can be
39 had via -vv, -vvv, etc, or an integer parameter to --verbose, such as
40 "--verbose 4". With no verbosity, the command is silent and returns 0 on
41 success, and a positive integer error on failure.
42
43 Pre-built binaries for several OSs are available. Examples presented are
44 for Linux. Command line arguments can be provided in any order.
45
46 1. Basic ID remapping
47
48 Perform ID remapping on all shaders in "*.spv", writing new files with
49 the same basenames to /tmp/out_dir.
50
51 spirv-remap -v --map all --input *.spv --output /tmp/out_dir
52
53 2. Perform all possible size reductions
54
55 spirv-remap-linux-64 -v --do-everything --input *.spv --output /tmp/out_dir
56
57 Note that --do-everything is a synonym for:
58
59 --map all --dce all --opt all --strip all
60
61 API USAGE:
62 --------------------------------------------------------------------------------
63
64 The public interface to the remapper is defined in SPIRV/SPVRemapper.h as follows:
65
66 namespace spv {
67
68 class spirvbin_t
69 {
70 public:
71 enum Options { ... };
72 spirvbin_t(int verbose = 0); // construct
73
74 // remap an existing binary in memory
75 void remap(std::vector<std::uint32_t>& spv, std::uint32_t opts = DO_EVERYTHING);
76
77 // Type for error/log handler functions
78 typedef std::function<void(const std::string&)> errorfn_t;
79 typedef std::function<void(const std::string&)> logfn_t;
80
81 // Register error/log handling functions (can be c/c++ fn, lambda fn, or functor)
82 static void registerErrorHandler(errorfn_t handler) { errorHandler = handler; }
83 static void registerLogHandler(logfn_t handler) { logHandler = handler; }
84 };
85
86 } // namespace spv
87
88 The class definition is in SPVRemapper.cpp.
89
90 remap() accepts an std::vector of SPIR-V words, modifies them per the
91 request given in 'opts', and leaves the 'spv' container with the result.
92 It is safe to instantiate one spirvbin_t per thread and process a different
93 SPIR-V in each.
94
95 The "opts" parameter to remap() accepts a bit mask of desired remapping
96 options. See REMAPPING AND OPTIMIZATION OPTIONS.
97
98 On error, the function supplied to registerErrorHandler() will be invoked.
99 This can be a standard C/C++ function, a lambda function, or a functor.
100 The default handler simply calls exit(5); The error handler is a static
101 member, so need only be set up once, not once per spirvbin_t instance.
102
103 Log messages are supplied to registerLogHandler(). By default, log
104 messages are eaten silently. The log handler is also a static member.
105
106 BUILD DEPENDENCIES:
107 --------------------------------------------------------------------------------
108 1. C++11 compatible compiler
109 2. cmake
110 3. glslang
111
112
113 BUILDING
114 --------------------------------------------------------------------------------
115 The standalone remapper is built along side glslangValidator through its
116 normal build process.
117
118
119 REMAPPING AND OPTIMIZATION OPTIONS
120 --------------------------------------------------------------------------------
121 API:
122 These are bits defined under spv::spirvbin_t::, and can be
123 bitwise or-ed together as desired.
124
125 MAP_TYPES = canonicalize type IDs
126 MAP_NAMES = canonicalize named data
127 MAP_FUNCS = canonicalize function bodies
128 DCE_FUNCS = remove dead functions
129 DCE_VARS = remove dead variables
130 DCE_TYPES = remove dead types
131 OPT_LOADSTORE = optimize unneeded load/stores
132 MAP_ALL = (MAP_TYPES | MAP_NAMES | MAP_FUNCS)
133 DCE_ALL = (DCE_FUNCS | DCE_VARS | DCE_TYPES)
134 OPT_ALL = (OPT_LOADSTORE)
135 ALL_BUT_STRIP = (MAP_ALL | DCE_ALL | OPT_ALL)
136 DO_EVERYTHING = (STRIP | ALL_BUT_STRIP)
137