From 2d9b3ade18ac388dfd1a884c5317a44622d66e9b Mon Sep 17 00:00:00 2001 From: Wouter van Oortmerssen Date: Mon, 8 Dec 2014 16:47:00 -0800 Subject: [PATCH] Various documentation clarifications. Change-Id: Ibc2bd88a636f3b4abf82a7c2722fc1e354dab848 Tested: on Linux. --- docs/html/index.html | 8 ++++---- docs/html/md__cpp_usage.html | 2 +- docs/html/md__java_usage.html | 7 ++++--- docs/html/md__schemas.html | 8 +++++++- docs/html/navtree.js | 2 +- docs/html/pages.html | 2 +- docs/source/CppUsage.md | 5 +++-- docs/source/FlatBuffers.md | 16 ++++++++-------- docs/source/JavaUsage.md | 11 ++++++++--- docs/source/Schemas.md | 16 +++++++++++++++- 10 files changed, 52 insertions(+), 25 deletions(-) diff --git a/docs/html/index.html b/docs/html/index.html index ab9ec47ba..639c1dae4 100644 --- a/docs/html/index.html +++ b/docs/html/index.html @@ -53,7 +53,7 @@ $(document).ready(function(){initNavTree('index.html','');});
FlatBuffers Documentation
-

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).

Why use FlatBuffers?

    @@ -65,7 +65,7 @@ $(document).ready(function(){initNavTree('index.html','');});

  • 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/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).
    • +
  • 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.

@@ -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.

  • 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/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 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().
    • @@ -87,7 +87,7 @@ $(document).ready(function(){initNavTree('index.html','');});
  • How to use the compiler.
  • How to write a schema.
  • How to use the generated C++ code in your own programs.
    • -
  • How to use the generated Java code in your own programs.
    • +
  • How to use the generated Java/C# code in your own programs.
  • How to use the generated Go code in your own programs.
  • Some benchmarks showing the advantage of using FlatBuffers.
  • A white paper explaining the "why" of FlatBuffers.
    • diff --git a/docs/html/md__cpp_usage.html b/docs/html/md__cpp_usage.html index d71a278bb..0a7ac1f56 100644 --- a/docs/html/md__cpp_usage.html +++ b/docs/html/md__cpp_usage.html @@ -86,7 +86,7 @@ $(document).ready(function(){initNavTree('md__cpp_usage.html','');});

    Reading in C++

    If you've received a buffer from somewhere (disk, network, etc.) you can directly start traversing it using:

    auto monster = GetMonster(buffer_pointer);
    -

    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.

assert(monster->hp() == 80);
assert(monster->mana() == 150); // default
assert(strcmp(monster->name()->c_str(), "MyMonster") == 0);
diff --git a/docs/html/md__java_usage.html b/docs/html/md__java_usage.html index 9e3f2a620..25d325ef9 100644 --- a/docs/html/md__java_usage.html +++ b/docs/html/md__java_usage.html @@ -4,7 +4,7 @@ -FlatBuffers: Use in Java +FlatBuffers: Use in Java/C @@ -50,10 +50,11 @@ $(document).ready(function(){initNavTree('md__java_usage.html','');});
-
Use in Java
+
Use in Java/C
-

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:

ByteBuffer bb = ByteBuffer.wrap(data);
Monster monster = Monster.getRootAsMonster(bb);
diff --git a/docs/html/md__schemas.html b/docs/html/md__schemas.html index daa5ab371..e154a2022 100644 --- a/docs/html/md__schemas.html +++ b/docs/html/md__schemas.html @@ -93,12 +93,15 @@ root_type Monster;

Structs

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).

Types

-

Builtin scalar types are:

+

Built-in scalar types are:

  • 8 bit: byte ubyte bool
  • 16 bit: short ushort
  • 32 bit: int uint float
  • 64 bit: long ulong double
    • +
+

Built-in non-scalar types:

+
  • Vector of any other type (denoted with [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.
  • References to other tables or structs, enums or unions (see below).
    • @@ -111,6 +114,8 @@ root_type Monster;

    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

    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.

    Namespaces

    These will generate the corresponding namespace in C++ for all helper code, and packages in Java. You can use . to specify nested namespaces / packages.

    Includes

    @@ -126,6 +131,7 @@ root_type Monster;

    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";

    Comments & documentation

    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.

    diff --git a/docs/html/navtree.js b/docs/html/navtree.js index 9ff8c25e1..70056c0be 100644 --- a/docs/html/navtree.js +++ b/docs/html/navtree.js @@ -6,7 +6,7 @@ var NAVTREE = [ "Writing a schema", "md__schemas.html", null ], [ "Use in C++", "md__cpp_usage.html", null ], [ "Use in Go", "md__go_usage.html", null ], - [ "Use in Java", "md__java_usage.html", null ], + [ "Use in Java/C", "md__java_usage.html", null ], [ "Benchmarks", "md__benchmarks.html", null ], [ "FlatBuffers white paper", "md__white_paper.html", null ], [ "FlatBuffer Internals", "md__internals.html", null ], diff --git a/docs/html/pages.html b/docs/html/pages.html index 5810c7225..30291b36a 100644 --- a/docs/html/pages.html +++ b/docs/html/pages.html @@ -60,7 +60,7 @@ $(document).ready(function(){initNavTree('pages.html','');});  Writing a schema  Use in C++  Use in Go - Use in Java + Use in Java/C  Benchmarks  FlatBuffers white paper  FlatBuffer Internals diff --git a/docs/source/CppUsage.md b/docs/source/CppUsage.md index a941ce40f..62c45d816 100755 --- a/docs/source/CppUsage.md +++ b/docs/source/CppUsage.md @@ -119,8 +119,9 @@ directly start traversing it using: auto monster = GetMonster(buffer_pointer); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -`monster` is of type `Monster *`, and points to somewhere inside your -buffer. If you look in your generated header, you'll see it has +`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. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp} diff --git a/docs/source/FlatBuffers.md b/docs/source/FlatBuffers.md index fd3085551..05e8c8e63 100644 --- a/docs/source/FlatBuffers.md +++ b/docs/source/FlatBuffers.md @@ -1,7 +1,7 @@ # FlatBuffers FlatBuffers is an efficient cross platform serialization library for C++, -with support for Java and Go. It was created at Google specifically for game +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). @@ -48,8 +48,8 @@ It is available as open source under the Apache license, v2 (see LICENSE.txt). Java and Go code supports object-reuse. -- **Cross platform C++11/Java/Go code with no dependencies** - will work with - any recent gcc/clang and VS2010. Comes with build files for the tests & +- **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 .. ? @@ -87,10 +87,10 @@ sections provide a more in-depth usage guide. 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/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 `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 @@ -110,7 +110,7 @@ sections provide a more in-depth usage guide. - 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 code](md__java_usage.html) in your own +- 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. diff --git a/docs/source/JavaUsage.md b/docs/source/JavaUsage.md index e6321b655..9586f4c5e 100755 --- a/docs/source/JavaUsage.md +++ b/docs/source/JavaUsage.md @@ -1,7 +1,12 @@ -# Use in Java +# Use in Java/C# -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 diff --git a/docs/source/Schemas.md b/docs/source/Schemas.md index 9d568d023..9fce33667 100755 --- a/docs/source/Schemas.md +++ b/docs/source/Schemas.md @@ -82,7 +82,7 @@ parent object, and use no virtual table). ### Types -Builtin scalar types are: +Built-in scalar types are: - 8 bit: `byte ubyte bool` @@ -92,6 +92,8 @@ Builtin scalar types are: - 64 bit: `long ulong double` +Built-in non-scalar types: + - Vector of any other type (denoted with `[type]`). Nesting vectors is not supported, instead you can wrap the inner vector in a table. @@ -137,6 +139,14 @@ 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. + ### Namespaces These will generate the corresponding namespace in C++ for all helper @@ -195,6 +205,10 @@ without one, you can always still do so by calling 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: