Debian Codegraph @

third_party/smol-v/source/smolv.h

raw
1 // smol-v - public domain - https://github.com/aras-p/smol-v
2 // authored on 2016 by Aras Pranckevicius
3 // no warranty implied; use at your own risk
4 //
5 //
6 // ### OVERVIEW:
7 //
8 // SMOL-V encodes Vulkan/Khronos SPIR-V format programs into a form that is smaller, and is more
9 // compressible. Normally no changes to the programs are done; they decode
10 // into exactly same program as what was encoded. Optionally, debug information
11 // can be removed too.
12 //
13 // SPIR-V is a very verbose format, several times larger than same programs expressed in other
14 // shader formats (e.g. DX11 bytecode, GLSL, DX9 bytecode etc.). The SSA-form with ever increasing
15 // IDs is not very appreciated by regular data compressors either. SMOL-V does several things
16 // to improve this:
17 // - Many words, especially ones that most often have small values, are encoded using
18 // "varint" scheme (1-5 bytes per word, with just one byte for values in 0..127 range).
19 // See https://developers.google.com/protocol-buffers/docs/encoding
20 // - Some IDs used in the program are delta-encoded, relative to previously seen IDs (e.g. Result
21 // IDs). Often instructions reference things that were computed just before, so this results in
22 // small deltas. These values are also encoded using "varint" scheme.
23 // - Reordering instruction opcodes so that the most common ones are the smallest values, for smaller
24 // varint encoding.
25 // - Encoding several instructions in a more compact form, e.g. the "typical <=4 component swizzle"
26 // shape of a VectorShuffle instruction, or sequences of MemberDecorate instructions.
27 //
28 // A somewhat similar utility is spirv-remap from glslang, see
29 // https://github.com/KhronosGroup/glslang/blob/master/README-spirv-remap.txt
30 //
31 //
32 // ### USAGE:
33 //
34 // Add source/smolv.h and source/smolv.cpp to your C++ project build.
35 // Currently it might require C++11 or somesuch; I only tested with Visual Studio 2010, 2015 and Mac Xcode 7.3.
36 //
37 // smolv::Encode and smolv::Decode is the basic functionality.
38 //
39 // Other functions are for development/statistics purposes, to figure out frequencies and
40 // distributions of the instructions.
41 //
42 // There's a test + compression benchmarking suite in testing/testmain.cpp; using that needs adding
43 // other files under testing/external to the build too (3rd party code: glslang remapper, Zstd, LZ4).
44 //
45 //
46 // ### LIMITATIONS / TODO:
47 //
48 // - SPIR-V where the words got stored in big-endian layout is not supported yet.
49 // - The whole thing might not work on Big-Endian CPUs. It might, but I'm not 100% sure.
50 // - Not much prevention is done against malformed/corrupted inputs, TODO.
51 // - Out of memory cases are not handled. The code will either throw exception
52 // or crash, depending on your compilation flags.
53
54 #pragma once
55
56 #include <stdint.h>
57 #include <vector>
58 #include <cstddef>
59
60 namespace smolv
61 {
62 typedef std::vector<uint8_t> ByteArray;
63
64 enum EncodeFlags
65 {
66 kEncodeFlagStripDebugInfo = (1<<0), // Strip all optional SPIR-V instructions (debug names etc.)
67 };
68
69
70 // -------------------------------------------------------------------
71 // Encoding / Decoding
72
73 // Encode SPIR-V into SMOL-V.
74 //
75 // Resulting data is appended to outSmolv array (the array is not cleared).
76 //
77 // flags is bitset of EncodeFlags values.
78 //
79 // Returns false on malformed SPIR-V input; if that happens the output array might get
80 // partial/broken SMOL-V program.
81 bool Encode(const void* spirvData, size_t spirvSize, ByteArray& outSmolv, uint32_t flags);
82
83
84 // Decode SMOL-V into SPIR-V.
85 //
86 // Resulting data is written into the passed buffer. Get required buffer space with
87 // GetDecodeBufferSize; this is the size of decoded SPIR-V program.
88 //
89 // Decoding does no memory allocations.
90 //
91 // Returns false on malformed input; if that happens the output buffer might be only partially
92 // written to.
93 bool Decode(const void* smolvData, size_t smolvSize, void* spirvOutputBuffer, size_t spirvOutputBufferSize);
94
95
96 // Given a SMOL-V program, get size of the decoded SPIR-V program.
97 // This is the buffer size that Decode expects.
98 //
99 // Returns zero on malformed input (just checks the header, not the full input).
100 size_t GetDecodedBufferSize(const void* smolvData, size_t smolvSize);
101
102
103 // -------------------------------------------------------------------
104 // Computing instruction statistics on SPIR-V/SMOL-V programs
105
106 struct Stats;
107
108 Stats* StatsCreate();
109 void StatsDelete(Stats* s);
110
111 bool StatsCalculate(Stats* stats, const void* spirvData, size_t spirvSize);
112 bool StatsCalculateSmol(Stats* stats, const void* smolvData, size_t smolvSize);
113 void StatsPrint(const Stats* stats);
114
115 } // namespace smolv