<divclass="textblock"><p>FlatBuffers is an efficient cross platform serialization library for C++, with support for Java and Go. It was created at Google specifically for game development and other performance-critical applications.</p>
<divclass="textblock"><p>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.</p>
<p>It is available as open source under the Apache license, v2 (see LICENSE.txt).</p>
<p>It is available as open source under the Apache license, v2 (see LICENSE.txt).</p>
<li><pclass="startli"><b>Convenient to use</b> - 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).</p>
<li><pclass="startli"><b>Convenient to use</b> - 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).</p>
<pclass="startli">Java and Go code supports object-reuse.</p>
<pclass="startli">Java and Go code supports object-reuse.</p>
</li>
</li>
<li><b>Cross platform C++11/Java/Go code with no dependencies</b> - 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).</li>
<li><b>Cross platform C++11/Java/C#/Go code with no dependencies</b> - 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).</li>
</ul>
</ul>
<h3>Why not use Protocol Buffers, or .. ?</h3>
<h3>Why not use Protocol Buffers, or .. ?</h3>
<p>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.</p>
<p>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.</p>
<p>This section is a quick rundown of how to use this system. Subsequent sections provide a more in-depth usage guide.</p>
<p>This section is a quick rundown of how to use this system. Subsequent sections provide a more in-depth usage guide.</p>
<ul>
<ul>
<li>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.</li>
<li>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.</li>
<li>Use <code>flatc</code> (the FlatBuffer compiler) to generate a C++ header (or Java/Go classes) with helper classes to access and construct serialized data. This header (say <code>mydata_generated.h</code>) only depends on <code>flatbuffers.h</code>, which defines the core functionality.</li>
<li>Use <code>flatc</code> (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 <code>mydata_generated.h</code>) only depends on <code>flatbuffers.h</code>, which defines the core functionality.</li>
<li>Use the <code>FlatBufferBuilder</code> 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.</li>
<li>Use the <code>FlatBufferBuilder</code> 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.</li>
<li>Store or send your buffer somewhere!</li>
<li>Store or send your buffer somewhere!</li>
<li>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 <code>object->field()</code>.</li>
<li>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 <code>object->field()</code>.</li>
</div><!-- fragment --><p><code>monster</code> is of type <code>Monster *</code>, and points to somewhere inside your buffer. If you look in your generated header, you'll see it has convenient accessors for all fields, e.g.</p>
</div><!-- fragment --><p><code>monster</code> is of type <code>Monster *</code>, and points to somewhere <em>inside</em> your buffer (root object pointers are not the same as <code>buffer_pointer</code> !). If you look in your generated header, you'll see it has convenient accessors for all fields, e.g.</p>
<divclass="textblock"><p>FlatBuffers supports reading and writing binary FlatBuffers in Java. Generate code for Java with the <code>-j</code> option to <code>flatc</code>.</p>
<divclass="textblock"><p>FlatBuffers supports reading and writing binary FlatBuffers in Java and C#. Generate code for Java with the <code>-j</code> option to <code>flatc</code>, or for C# with <code>-n</code> (think .Net).</p>
<p>Note that this document is from the perspective of Java. Code for both languages is generated in the same way, with only very subtle differences, for example any <code>camelCase</code> Java call will be <code>CamelCase</code> in C#.</p>
<p>See <code>javaTest.java</code> for an example. Essentially, you read a FlatBuffer binary file into a <code>byte[]</code>, which you then turn into a <code>ByteBuffer</code>, which you pass to the <code>getRootAsMyRootType</code> function:</p>
<p>See <code>javaTest.java</code> for an example. Essentially, you read a FlatBuffer binary file into a <code>byte[]</code>, which you then turn into a <code>ByteBuffer</code>, which you pass to the <code>getRootAsMyRootType</code> function:</p>
<p>Similar to a table, only now none of the fields are optional (so no defaults either), and fields may not be added or be deprecated. Structs may only contain scalars or other structs. Use this for simple objects where you are very sure no changes will ever be made (as quite clear in the example <code>Vec3</code>). Structs use less memory than tables and are even faster to access (they are always stored in-line in their parent object, and use no virtual table).</p>
<p>Similar to a table, only now none of the fields are optional (so no defaults either), and fields may not be added or be deprecated. Structs may only contain scalars or other structs. Use this for simple objects where you are very sure no changes will ever be made (as quite clear in the example <code>Vec3</code>). Structs use less memory than tables and are even faster to access (they are always stored in-line in their parent object, and use no virtual table).</p>
<h3>Types</h3>
<h3>Types</h3>
<p>Builtin scalar types are:</p>
<p>Built-in scalar types are:</p>
<ul>
<ul>
<li>8 bit: <code>byte ubyte bool</code></li>
<li>8 bit: <code>byte ubyte bool</code></li>
<li>16 bit: <code>short ushort</code></li>
<li>16 bit: <code>short ushort</code></li>
<li>32 bit: <code>int uint float</code></li>
<li>32 bit: <code>int uint float</code></li>
<li>64 bit: <code>long ulong double</code></li>
<li>64 bit: <code>long ulong double</code></li>
</ul>
<p>Built-in non-scalar types:</p>
<ul>
<li>Vector of any other type (denoted with <code>[type]</code>). Nesting vectors is not supported, instead you can wrap the inner vector in a table.</li>
<li>Vector of any other type (denoted with <code>[type]</code>). Nesting vectors is not supported, instead you can wrap the inner vector in a table.</li>
<li><code>string</code>, which may only hold UTF-8 or 7-bit ASCII. For other text encodings or general binary data use vectors (<code>[byte]</code> or <code>[ubyte]</code>) instead.</li>
<li><code>string</code>, which may only hold UTF-8 or 7-bit ASCII. For other text encodings or general binary data use vectors (<code>[byte]</code> or <code>[ubyte]</code>) instead.</li>
<li>References to other tables or structs, enums or unions (see below).</li>
<li>References to other tables or structs, enums or unions (see below).</li>
...
@@ -111,6 +114,8 @@ root_type Monster;
...
@@ -111,6 +114,8 @@ root_type Monster;
<p>Define a sequence of named constants, each with a given value, or increasing by one from the previous one. The default first value is <code>0</code>. As you can see in the enum declaration, you specify the underlying integral type of the enum with <code>:</code> (in this case <code>byte</code>), which then determines the type of any fields declared with this enum type.</p>
<p>Define a sequence of named constants, each with a given value, or increasing by one from the previous one. The default first value is <code>0</code>. As you can see in the enum declaration, you specify the underlying integral type of the enum with <code>:</code> (in this case <code>byte</code>), which then determines the type of any fields declared with this enum type.</p>
<h3>Unions</h3>
<h3>Unions</h3>
<p>Unions share a lot of properties with enums, but instead of new names for constants, you use names of tables. You can then declare a union field which can hold a reference to any of those types, and additionally a hidden field with the suffix <code>_type</code> is generated that holds the corresponding enum value, allowing you to know which type to cast to at runtime.</p>
<p>Unions share a lot of properties with enums, but instead of new names for constants, you use names of tables. You can then declare a union field which can hold a reference to any of those types, and additionally a hidden field with the suffix <code>_type</code> is generated that holds the corresponding enum value, allowing you to know which type to cast to at runtime.</p>
<p>Unions are a good way to be able to send multiple message types as a FlatBuffer. Note that because a union field is really two fields, it must always be part of a table, it cannot be the root of a FlatBuffer by itself.</p>
<p>If you have a need to distinguish between different FlatBuffers in a more open-ended way, for example for use as files, see the file identification feature below.</p>
<h3>Namespaces</h3>
<h3>Namespaces</h3>
<p>These will generate the corresponding namespace in C++ for all helper code, and packages in Java. You can use <code>.</code> to specify nested namespaces / packages.</p>
<p>These will generate the corresponding namespace in C++ for all helper code, and packages in Java. You can use <code>.</code> to specify nested namespaces / packages.</p>
<h3>Includes</h3>
<h3>Includes</h3>
...
@@ -126,6 +131,7 @@ root_type Monster;
...
@@ -126,6 +131,7 @@ root_type Monster;
</pre><p>Identifiers must always be exactly 4 characters long. These 4 characters will end up as bytes at offsets 4-7 (inclusive) in the buffer.</p>
</pre><p>Identifiers must always be exactly 4 characters long. These 4 characters will end up as bytes at offsets 4-7 (inclusive) in the buffer.</p>
<p>For any schema that has such an identifier, <code>flatc</code> will automatically add the identifier to any binaries it generates (with <code>-b</code>), and generated calls like <code>FinishMonsterBuffer</code> also add the identifier. If you have specified an identifier and wish to generate a buffer without one, you can always still do so by calling <code>FlatBufferBuilder::Finish</code> explicitly.</p>
<p>For any schema that has such an identifier, <code>flatc</code> will automatically add the identifier to any binaries it generates (with <code>-b</code>), and generated calls like <code>FinishMonsterBuffer</code> also add the identifier. If you have specified an identifier and wish to generate a buffer without one, you can always still do so by calling <code>FlatBufferBuilder::Finish</code> explicitly.</p>
<p>After loading a buffer, you can use a call like <code>MonsterBufferHasIdentifier</code> to check if the identifier is present.</p>
<p>After loading a buffer, you can use a call like <code>MonsterBufferHasIdentifier</code> to check if the identifier is present.</p>
<p>Note that this is best for open-ended uses such as files. If you simply wanted to send one of a set of possible messages over a network for example, you'd be better off with a union.</p>
<p>Additionally, by default <code>flatc</code> will output binary files as <code>.bin</code>. This declaration in the schema will change that to whatever you want: </p><preclass="fragment">file_extension "ext";
<p>Additionally, by default <code>flatc</code> will output binary files as <code>.bin</code>. This declaration in the schema will change that to whatever you want: </p><preclass="fragment">file_extension "ext";
</pre><h3>Comments & documentation</h3>
</pre><h3>Comments & documentation</h3>
<p>May be written as in most C-based languages. Additionally, a triple comment (<code>///</code>) on a line by itself signals that a comment is documentation for whatever is declared on the line after it (table/struct/field/enum/union/element), and the comment is output in the corresponding C++ code. Multiple such lines per item are allowed.</p>
<p>May be written as in most C-based languages. Additionally, a triple comment (<code>///</code>) on a line by itself signals that a comment is documentation for whatever is declared on the line after it (table/struct/field/enum/union/element), and the comment is output in the corresponding C++ code. Multiple such lines per item are allowed.</p>
<trid="row_2_"class="even"><tdclass="entry"><spanstyle="width:16px;display:inline-block;"> </span><aclass="el"href="md__schemas.html"target="_self">Writing a schema</a></td><tdclass="desc"></td></tr>
<trid="row_2_"class="even"><tdclass="entry"><spanstyle="width:16px;display:inline-block;"> </span><aclass="el"href="md__schemas.html"target="_self">Writing a schema</a></td><tdclass="desc"></td></tr>
<trid="row_3_"><tdclass="entry"><spanstyle="width:16px;display:inline-block;"> </span><aclass="el"href="md__cpp_usage.html"target="_self">Use in C++</a></td><tdclass="desc"></td></tr>
<trid="row_3_"><tdclass="entry"><spanstyle="width:16px;display:inline-block;"> </span><aclass="el"href="md__cpp_usage.html"target="_self">Use in C++</a></td><tdclass="desc"></td></tr>
<trid="row_4_"class="even"><tdclass="entry"><spanstyle="width:16px;display:inline-block;"> </span><aclass="el"href="md__go_usage.html"target="_self">Use in Go</a></td><tdclass="desc"></td></tr>
<trid="row_4_"class="even"><tdclass="entry"><spanstyle="width:16px;display:inline-block;"> </span><aclass="el"href="md__go_usage.html"target="_self">Use in Go</a></td><tdclass="desc"></td></tr>
<trid="row_5_"><tdclass="entry"><spanstyle="width:16px;display:inline-block;"> </span><aclass="el"href="md__java_usage.html"target="_self">Use in Java</a></td><tdclass="desc"></td></tr>
<trid="row_5_"><tdclass="entry"><spanstyle="width:16px;display:inline-block;"> </span><aclass="el"href="md__java_usage.html"target="_self">Use in Java/C</a></td><tdclass="desc"></td></tr>
<trid="row_7_"><tdclass="entry"><spanstyle="width:16px;display:inline-block;"> </span><aclass="el"href="md__white_paper.html"target="_self">FlatBuffers white paper</a></td><tdclass="desc"></td></tr>
<trid="row_7_"><tdclass="entry"><spanstyle="width:16px;display:inline-block;"> </span><aclass="el"href="md__white_paper.html"target="_self">FlatBuffers white paper</a></td><tdclass="desc"></td></tr>
