1 FlatBuffers {#flatbuffers_index} 2 =========== 3 4 # Overview {#flatbuffers_overview} 5 6 [FlatBuffers](@ref flatbuffers_overview) is an efficient cross platform 7 serialization library for C++, C#, C, Go, Java, JavaScript, PHP, and Python. 8 It was originally created at Google for game development and other 9 performance-critical applications. 10 11 It is available as Open Source on [GitHub](http://github.com/google/flatbuffers) 12 under the Apache license, v2 (see LICENSE.txt). 13 14 ## Why use FlatBuffers? 15 16 - **Access to serialized data without parsing/unpacking** - What sets 17 FlatBuffers apart is that it represents hierarchical data in a flat 18 binary buffer in such a way that it can still be accessed directly 19 without parsing/unpacking, while also still supporting data 20 structure evolution (forwards/backwards compatibility). 21 22 - **Memory efficiency and speed** - The only memory needed to access 23 your data is that of the buffer. It requires 0 additional allocations 24 (in C++, other languages may vary). FlatBuffers is also very 25 suitable for use with mmap (or streaming), requiring only part of the 26 buffer to be in memory. Access is close to the speed of raw 27 struct access with only one extra indirection (a kind of vtable) to 28 allow for format evolution and optional fields. It is aimed at 29 projects where spending time and space (many memory allocations) to 30 be able to access or construct serialized data is undesirable, such 31 as in games or any other performance sensitive applications. See the 32 [benchmarks](@ref flatbuffers_benchmarks) for details. 33 34 - **Flexible** - Optional fields means not only do you get great 35 forwards and backwards compatibility (increasingly important for 36 long-lived games: don't have to update all data with each new 37 version!). It also means you have a lot of choice in what data you 38 write and what data you don't, and how you design data structures. 39 40 - **Tiny code footprint** - Small amounts of generated code, and just 41 a single small header as the minimum dependency, which is very easy 42 to integrate. Again, see the benchmark section for details. 43 44 - **Strongly typed** - Errors happen at compile time rather than 45 manually having to write repetitive and error prone run-time checks. 46 Useful code can be generated for you. 47 48 - **Convenient to use** - Generated C++ code allows for terse access 49 & construction code. Then there's optional functionality for parsing 50 schemas and JSON-like text representations at runtime efficiently if 51 needed (faster and more memory efficient than other JSON 52 parsers). 53 54 Java and Go code supports object-reuse. C# has efficient struct based 55 accessors. 56 57 - **Cross platform code with no dependencies** - C++ code will work 58 with any recent gcc/clang and VS2010. Comes with build files for the tests & 59 samples (Android .mk files, and cmake for all other platforms). 60 61 ### Why not use Protocol Buffers, or .. ? 62 63 Protocol Buffers is indeed relatively similar to FlatBuffers, 64 with the primary difference being that FlatBuffers does not need a parsing/ 65 unpacking step to a secondary representation before you can 66 access data, often coupled with per-object memory allocation. The code 67 is an order of magnitude bigger, too. Protocol Buffers has neither optional 68 text import/export nor schema language features like unions. 69 70 ### But all the cool kids use JSON! 71 72 JSON is very readable (which is why we use it as our optional text 73 format) and very convenient when used together with dynamically typed 74 languages (such as JavaScript). When serializing data from statically 75 typed languages, however, JSON not only has the obvious drawback of runtime 76 inefficiency, but also forces you to write *more* code to access data 77 (counterintuitively) due to its dynamic-typing serialization system. 78 In this context, it is only a better choice for systems that have very 79 little to no information ahead of time about what data needs to be stored. 80 81 If you do need to store data that doesn't fit a schema, FlatBuffers also 82 offers a schema-less (self-describing) version! 83 84 Read more about the "why" of FlatBuffers in the 85 [white paper](@ref flatbuffers_white_paper). 86 87 ### Who uses FlatBuffers? 88 - [Cocos2d-x](http://www.cocos2d-x.org/), the #1 open source mobile game 89 engine, uses it to serialize all their 90 [game data](http://www.cocos2d-x.org/reference/native-cpp/V3.5/d7/d2d/namespaceflatbuffers.html). 91 - [Facebook](http://facebook.com/) uses it for client-server communication in 92 their Android app. They have a nice 93 [article](https://code.facebook.com/posts/872547912839369/improving-facebook-s-performance-on-android-with-flatbuffers/) 94 explaining how it speeds up loading their posts. 95 - [Fun Propulsion Labs](https://developers.google.com/games/#Tools) 96 at Google uses it extensively in all their libraries and games. 97 98 ## Usage in brief 99 100 This section is a quick rundown of how to use this system. Subsequent 101 sections provide a more in-depth usage guide. 102 103 - Write a schema file that allows you to define the data structures 104 you may want to serialize. Fields can have a scalar type 105 (ints/floats of all sizes), or they can be a: string; array of any type; 106 reference to yet another object; or, a set of possible objects (unions). 107 Fields are optional and have defaults, so they don't need to be 108 present for every object instance. 109 110 - Use `flatc` (the FlatBuffer compiler) to generate a C++ header (or 111 Java/C#/Go/Python.. classes) with helper classes to access and construct 112 serialized data. This header (say `mydata_generated.h`) only depends on 113 `flatbuffers.h`, which defines the core functionality. 114 115 - Use the `FlatBufferBuilder` class to construct a flat binary buffer. 116 The generated functions allow you to add objects to this 117 buffer recursively, often as simply as making a single function call. 118 119 - Store or send your buffer somewhere! 120 121 - When reading it back, you can obtain the pointer to the root object 122 from the binary buffer, and from there traverse it conveniently 123 in-place with `object->field()`. 124 125 ## In-depth documentation 126 127 - How to [build the compiler](@ref flatbuffers_guide_building) and samples on 128 various platforms. 129 - How to [use the compiler](@ref flatbuffers_guide_using_schema_compiler). 130 - How to [write a schema](@ref flatbuffers_guide_writing_schema). 131 - How to [use the generated C++ code](@ref flatbuffers_guide_use_cpp) in your 132 own programs. 133 - How to [use the generated Java/C# code](@ref flatbuffers_guide_use_java_c-sharp) 134 in your own programs. 135 - How to [use the generated Go code](@ref flatbuffers_guide_use_go) in your 136 own programs. 137 - How to [use FlatBuffers in C with `flatcc`](@ref flatbuffers_guide_use_c) in your 138 own programs. 139 - [Support matrix](@ref flatbuffers_support) for platforms/languages/features. 140 - Some [benchmarks](@ref flatbuffers_benchmarks) showing the advantage of 141 using FlatBuffers. 142 - A [white paper](@ref flatbuffers_white_paper) explaining the "why" of 143 FlatBuffers. 144 - How to use the [schema-less](@ref flexbuffers) version of 145 FlatBuffers. 146 - A description of the [internals](@ref flatbuffers_internals) of FlatBuffers. 147 - A formal [grammar](@ref flatbuffers_grammar) of the schema language. 148 149 ## Online resources 150 151 - [GitHub repository](http://github.com/google/flatbuffers) 152 - [Landing page](http://google.github.io/flatbuffers) 153 - [FlatBuffers Google Group](https://groups.google.com/forum/#!forum/flatbuffers) 154 - [FlatBuffers Issues Tracker](http://github.com/google/flatbuffers/issues) 155 - Independent implementations & tools: 156 - [FlatCC](https://github.com/dvidelabs/flatcc) Alternative FlatBuffers 157 parser, code generator and runtime all in C. 158 - Videos: 159 - Colt's [DevByte](https://www.youtube.com/watch?v=iQTxMkSJ1dQ). 160 - GDC 2015 [Lightning Talk](https://www.youtube.com/watch?v=olmL1fUnQAQ). 161 - FlatBuffers for [Go](https://www.youtube.com/watch?v=-BPVId_lA5w). 162 - Evolution of FlatBuffers 163 [visualization](https://www.youtube.com/watch?v=a0QE0xS8rKM). 164 - Useful documentation created by others: 165 - [FlatBuffers in Go](https://rwinslow.com/tags/flatbuffers/) 166 - [FlatBuffers in Android](http://frogermcs.github.io/flatbuffers-in-android-introdution/) 167 - [Parsing JSON to FlatBuffers in Java](http://frogermcs.github.io/json-parsing-with-flatbuffers-in-android/) 168 - [FlatBuffers in Unity](http://exiin.com/blog/flatbuffers-for-unity-sample-code/) 169
