docs/source/FlatBuffers.md

# FlatBuffers

FlatBuffers is an efficient cross platform serialization library for C++,
with support for Java, C# and Go. It was created at Google specifically for game
development and other performance-critical applications.

It is available as open source under the Apache license, v2 (see LICENSE.txt).

## Why use FlatBuffers?

-   **Access to serialized data without parsing/unpacking** - What sets
    FlatBuffers apart is that it represents hierarchical data in a flat
    binary buffer in such a way that it can still be accessed directly
    without parsing/unpacking, while also still supporting data
    structure evolution (forwards/backwards compatibility).

-   **Memory efficiency and speed** - The only memory needed to access
    your data is that of the buffer. It requires 0 additional allocations.
    FlatBuffers is also very
    suitable for use with mmap (or streaming), requiring only part of the
    buffer to be in memory. Access is close to the speed of raw
    struct access with only one extra indirection (a kind of vtable) to
    allow for format evolution and optional fields. It is aimed at
    projects where spending time and space (many memory allocations) to
    be able to access or construct serialized data is undesirable, such
    as in games or any other performance sensitive applications. See the
    [benchmarks](md__benchmarks.html) for details.

-   **Flexible** - Optional fields means not only do you get great
    forwards and backwards compatibility (increasingly important for
    long-lived games: don't have to update all data with each new
    version!). It also means you have a lot of choice in what data you
    write and what data you don't, and how you design data structures.

-   **Tiny code footprint** - Small amounts of generated code, and just
    a single small header as the minimum dependency, which is very easy
    to integrate. Again, see the benchmark section for details.

-   **Strongly typed** - Errors happen at compile time rather than
    manually having to write repetitive and error prone run-time checks.
    Useful code can be generated for you.

-   **Convenient to use** - Generated C++ code allows for terse access
    & construction code. Then there's optional functionality for parsing
    schemas and JSON-like text representations at runtime efficiently if
    needed (faster and more memory efficient than other JSON
    parsers).

    Java and Go code supports object-reuse.

-   **Cross platform C++11/Java/C#/Go code with no dependencies** - will work
    with any recent gcc/clang and VS2010. Comes with build files for the tests &
    samples (Android .mk files, and cmake for all other platforms).

### Why not use Protocol Buffers, or .. ?

Protocol Buffers is indeed relatively similar to FlatBuffers,
with the primary difference being that FlatBuffers does not need a parsing/
unpacking step to a secondary representation before you can
access data, often coupled with per-object memory allocation. The code
is an order of magnitude bigger, too. Protocol Buffers has neither optional
text import/export nor schema language features like unions.

### But all the cool kids use JSON!

JSON is very readable (which is why we use it as our optional text
format) and very convenient when used together with dynamically typed
languages (such as JavaScript). When serializing data from statically
typed languages, however, JSON not only has the obvious drawback of runtime
inefficiency, but also forces you to write *more* code to access data
(counterintuitively) due to its dynamic-typing serialization system.
In this context, it is only a better choice for systems that have very
little to no information ahead of time about what data needs to be stored.

Read more about the "why" of FlatBuffers in the
[white paper](md__white_paper.html).

## Usage in brief

This section is a quick rundown of how to use this system. Subsequent
sections provide a more in-depth usage guide.

-   Write a schema file that allows you to define the data structures
    you may want to serialize. Fields can have a scalar type
    (ints/floats of all sizes), or they can be a: string; array of any type;
    reference to yet another object; or, a set of possible objects (unions).
    Fields are optional and have defaults, so they don't need to be
    present for every object instance.

-   Use `flatc` (the FlatBuffer compiler) to generate a C++ header (or
    Java/C#/Go classes) with helper classes to access and construct serialized
    data. This header (say `mydata_generated.h`) only depends on
    `flatbuffers.h`, which defines the core functionality.

-   Use the `FlatBufferBuilder` class to construct a flat binary buffer.
    The generated functions allow you to add objects to this
    buffer recursively, often as simply as making a single function call.

-   Store or send your buffer somewhere!

-   When reading it back, you can obtain the pointer to the root object
    from the binary buffer, and from there traverse it conveniently
    in-place with `object->field()`.

## In-depth documentation

-   How to [build the compiler](md__building.html) and samples on various
    platforms.
-   How to [use the compiler](md__compiler.html).
-   How to [write a schema](md__schemas.html).
-   How to [use the generated C++ code](md__cpp_usage.html) in your own
    programs.
-   How to [use the generated Java/C# code](md__java_usage.html) in your own
    programs.
-   How to [use the generated Go code](md__go_usage.html) in your own
    programs.
-   Some [benchmarks](md__benchmarks.html) showing the advantage of using
    FlatBuffers.
-   A [white paper](md__white_paper.html) explaining the "why" of FlatBuffers.
-   A description of the [internals](md__internals.html) of FlatBuffers.
-   A formal [grammar](md__grammar.html) of the schema language.

## Online resources

-   [github repository](http://github.com/google/flatbuffers)
-   [landing page](http://google.github.io/flatbuffers)
-   [FlatBuffers Google Group](http://group.google.com/group/flatbuffers)
-   [FlatBuffers Issues Tracker](http://github.com/google/flatbuffers/issues)