| 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 |