123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137 |
- VERSION
- --------------------------------------------------------------------------------
- spirv-remap 0.97
- INTRO:
- --------------------------------------------------------------------------------
- spirv-remap is a utility to improve compression of SPIR-V binary files via
- entropy reduction, plus optional stripping of debug information and
- load/store optimization. It transforms SPIR-V to SPIR-V, remapping IDs. The
- resulting modules have an increased ID range (IDs are not as tightly packed
- around zero), but will compress better when multiple modules are compressed
- together, since compressor's dictionary can find better cross module
- commonality.
- Remapping is accomplished via canonicalization. Thus, modules can be
- compressed one at a time with no loss of quality relative to operating on
- many modules at once. The command line tool operates on multiple modules
- only in the trivial repetition sense, for ease of use. The remapper API
- only accepts a single module at a time.
- There are two modes of use: command line, and a C++11 API. Both are
- described below.
- spirv-remap is currently in an alpha state. Although there are no known
- remapping defects, it has only been exercised on one real world game shader
- workload.
- FEEDBACK
- ---------------------------------------------------------------------------------
- Report defects, enhancement requests, code improvements, etc by creating
- issues in the glslang repository at https://github.com/KhronosGroup/glslang
- COMMAND LINE USAGE:
- --------------------------------------------------------------------------------
- Examples are given with a verbosity of one (-v), but more verbosity can be
- had via -vv, -vvv, etc, or an integer parameter to --verbose, such as
- "--verbose 4". With no verbosity, the command is silent and returns 0 on
- success, and a positive integer error on failure.
- Pre-built binaries for several OSs are available. Examples presented are
- for Linux. Command line arguments can be provided in any order.
- 1. Basic ID remapping
- Perform ID remapping on all shaders in "*.spv", writing new files with
- the same basenames to /tmp/out_dir.
- spirv-remap -v --map all --input *.spv --output /tmp/out_dir
- 2. Perform all possible size reductions
- spirv-remap-linux-64 -v --do-everything --input *.spv --output /tmp/out_dir
- Note that --do-everything is a synonym for:
- --map all --dce all --opt all --strip all
- API USAGE:
- --------------------------------------------------------------------------------
- The public interface to the remapper is defined in SPIRV/SPVRemapper.h as follows:
- namespace spv {
- class spirvbin_t
- {
- public:
- enum Options { ... };
- spirvbin_t(int verbose = 0); // construct
- // remap an existing binary in memory
- void remap(std::vector<std::uint32_t>& spv, std::uint32_t opts = DO_EVERYTHING);
- // Type for error/log handler functions
- typedef std::function<void(const std::string&)> errorfn_t;
- typedef std::function<void(const std::string&)> logfn_t;
- // Register error/log handling functions (can be c/c++ fn, lambda fn, or functor)
- static void registerErrorHandler(errorfn_t handler) { errorHandler = handler; }
- static void registerLogHandler(logfn_t handler) { logHandler = handler; }
- };
- } // namespace spv
- The class definition is in SPVRemapper.cpp.
- remap() accepts an std::vector of SPIR-V words, modifies them per the
- request given in 'opts', and leaves the 'spv' container with the result.
- It is safe to instantiate one spirvbin_t per thread and process a different
- SPIR-V in each.
- The "opts" parameter to remap() accepts a bit mask of desired remapping
- options. See REMAPPING AND OPTIMIZATION OPTIONS.
- On error, the function supplied to registerErrorHandler() will be invoked.
- This can be a standard C/C++ function, a lambda function, or a functor.
- The default handler simply calls exit(5); The error handler is a static
- member, so need only be set up once, not once per spirvbin_t instance.
- Log messages are supplied to registerLogHandler(). By default, log
- messages are eaten silently. The log handler is also a static member.
- BUILD DEPENDENCIES:
- --------------------------------------------------------------------------------
- 1. C++11 compatible compiler
- 2. cmake
- 3. glslang
- BUILDING
- --------------------------------------------------------------------------------
- The standalone remapper is built along side glslang through its
- normal build process.
- REMAPPING AND OPTIMIZATION OPTIONS
- --------------------------------------------------------------------------------
- API:
- These are bits defined under spv::spirvbin_t::, and can be
- bitwise or-ed together as desired.
- MAP_TYPES = canonicalize type IDs
- MAP_NAMES = canonicalize named data
- MAP_FUNCS = canonicalize function bodies
- DCE_FUNCS = remove dead functions
- DCE_VARS = remove dead variables
- DCE_TYPES = remove dead types
- OPT_LOADSTORE = optimize unneeded load/stores
- MAP_ALL = (MAP_TYPES | MAP_NAMES | MAP_FUNCS)
- DCE_ALL = (DCE_FUNCS | DCE_VARS | DCE_TYPES)
- OPT_ALL = (OPT_LOADSTORE)
- ALL_BUT_STRIP = (MAP_ALL | DCE_ALL | OPT_ALL)
- DO_EVERYTHING = (STRIP | ALL_BUT_STRIP)
|