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.
+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).
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.
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.
@@ -76,7 +76,7 @@ $(document).ready(function(){initNavTree('index.html','');});This section is a quick rundown of how to use this system. Subsequent sections provide a more in-depth usage guide.
flatc (the FlatBuffer compiler) to generate a C++ header (or Java/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.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.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.object->field().If you've received a buffer from somewhere (disk, network, etc.) you can directly start traversing it using:
monster is of type Monster *, 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.
monster is of type Monster *, and points to somewhere inside your buffer (root object pointers are not the same as buffer_pointer !). If you look in your generated header, you'll see it has convenient accessors for all fields, e.g.
FlatBuffers supports reading and writing binary FlatBuffers in Java. Generate code for Java with the -j option to flatc.
FlatBuffers supports reading and writing binary FlatBuffers in Java and C#. Generate code for Java with the -j option to flatc, or for C# with -n (think .Net).
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 camelCase Java call will be CamelCase in C#.
See javaTest.java for an example. Essentially, you read a FlatBuffer binary file into a byte[], which you then turn into a ByteBuffer, which you pass to the getRootAsMyRootType function:
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 Vec3). 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).
Builtin scalar types are:
+Built-in scalar types are:
byte ubyte boolshort ushortint uint floatlong ulong doubleBuilt-in non-scalar types:
+[type]). Nesting vectors is not supported, instead you can wrap the inner vector in a table.string, which may only hold UTF-8 or 7-bit ASCII. For other text encodings or general binary data use vectors ([byte] or [ubyte]) instead.Define a sequence of named constants, each with a given value, or increasing by one from the previous one. The default first value is 0. As you can see in the enum declaration, you specify the underlying integral type of the enum with : (in this case byte), which then determines the type of any fields declared with this enum type.
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 _type is generated that holds the corresponding enum value, allowing you to know which type to cast to at runtime.
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.
+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.
These will generate the corresponding namespace in C++ for all helper code, and packages in Java. You can use . to specify nested namespaces / packages.
Identifiers must always be exactly 4 characters long. These 4 characters will end up as bytes at offsets 4-7 (inclusive) in the buffer.
For any schema that has such an identifier, flatc will automatically add the identifier to any binaries it generates (with -b), and generated calls like FinishMonsterBuffer 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 FlatBufferBuilder::Finish explicitly.
After loading a buffer, you can use a call like MonsterBufferHasIdentifier to check if the identifier is present.
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.
Additionally, by default flatc will output binary files as .bin. This declaration in the schema will change that to whatever you want:
file_extension "ext";
May be written as in most C-based languages. Additionally, a triple comment (///) 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.