1FlatBuffers    {#flatbuffers_index}
2===========
3
4# Overview {#flatbuffers_overview}
5
6[FlatBuffers](@ref flatbuffers_overview) is an efficient cross platform
7serialization library for C++, C#, C, Go, Java, JavaScript, PHP, and Python.
8It was originally created at Google for game development and other
9performance-critical applications.
10
11It is available as Open Source on [GitHub](http://github.com/google/flatbuffers)
12under 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
63Protocol Buffers is indeed relatively similar to FlatBuffers,
64with the primary difference being that FlatBuffers does not need a parsing/
65unpacking step to a secondary representation before you can
66access data, often coupled with per-object memory allocation. The code
67is an order of magnitude bigger, too. Protocol Buffers has neither optional
68text import/export nor schema language features like unions.
69
70### But all the cool kids use JSON!
71
72JSON is very readable (which is why we use it as our optional text
73format) and very convenient when used together with dynamically typed
74languages (such as JavaScript). When serializing data from statically
75typed languages, however, JSON not only has the obvious drawback of runtime
76inefficiency, but also forces you to write *more* code to access data
77(counterintuitively) due to its dynamic-typing serialization system.
78In this context, it is only a better choice for systems that have very
79little to no information ahead of time about what data needs to be stored.
80
81If you do need to store data that doesn't fit a schema, FlatBuffers also
82offers a schema-less (self-describing) version!
83
84Read 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
100This section is a quick rundown of how to use this system. Subsequent
101sections 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