Skip to content

F
flatbuffers
Commit 69a31b80 authored by Mark Klara's avatar Mark Klara
Browse files
Options

Revamping the FlatBuffers docs. 

Adding an API reference for the supported languages.

General docs cleanup, including a new `tutorial` section that
supports all of the supported languages.

Added samples for each supported language to mirror the new
tutorial page.

Cleaned up all the links by making them `@ref` style links,
instead of referencing the names of the generated `.html` files.

Removed all generated files that were unnecessarily committed.

Also fixed the C# tests (two were failing due to a missing file).

Bug: b/25801305

Tested: Tested all samples on Ubuntu, Mac, and Android. Docs were
generated using doxygen and viewed on Chrome.

Change-Id: I2acaba6e332a15ae2deff5f26a4a25da7bd2c954
parent d75d29e2
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 124 additions and 1729 deletions
docs/documentation.html deleted 100755 → 0
View file @ d75d29e2
<html>
<head>
<meta http-equiv="refresh" content="0;url=html/index.html">
</head>
<body>
<a href="html/index.html">Click here if you are not redirected.</a>
</body>
</html>
docs/html/doxygen.css deleted 100644 → 0
View file @ d75d29e2
This diff is collapsed.
docs/html/dynsections.js deleted 100644 → 0
View file @ d75d29e2
function toggleVisibility(linkObj)
{
var base = $(linkObj).attr('id');
var summary = $('#'+base+'-summary');
var content = $('#'+base+'-content');
var trigger = $('#'+base+'-trigger');
var src=$(trigger).attr('src');
if (content.is(':visible')===true) {
content.hide();
summary.show();
$(linkObj).addClass('closed').removeClass('opened');
$(trigger).attr('src',src.substring(0,src.length-8)+'closed.png');
} else {
content.show();
summary.hide();
$(linkObj).removeClass('closed').addClass('opened');
$(trigger).attr('src',src.substring(0,src.length-10)+'open.png');
}
return false;
}
function updateStripes()
{
$('table.directory tr').
removeClass('even').filter(':visible:even').addClass('even');
}
function toggleLevel(level)
{
$('table.directory tr').each(function() {
var l = this.id.split('_').length-1;
var i = $('#img'+this.id.substring(3));
var a = $('#arr'+this.id.substring(3));
if (l<level+1) {
i.removeClass('iconfopen iconfclosed').addClass('iconfopen');
a.html('&#9660;');
$(this).show();
} else if (l==level+1) {
i.removeClass('iconfclosed iconfopen').addClass('iconfclosed');
a.html('&#9658;');
$(this).show();
} else {
$(this).hide();
}
});
updateStripes();
}
function toggleFolder(id)
{
// the clicked row
var currentRow = $('#row_'+id);
// all rows after the clicked row
var rows = currentRow.nextAll("tr");
var re = new RegExp('^row_'+id+'\\d+_$', "i"); //only one sub
// only match elements AFTER this one (can't hide elements before)
var childRows = rows.filter(function() { return this.id.match(re); });
// first row is visible we are HIDING
if (childRows.filter(':first').is(':visible')===true) {
// replace down arrow by right arrow for current row
var currentRowSpans = currentRow.find("span");
currentRowSpans.filter(".iconfopen").removeClass("iconfopen").addClass("iconfclosed");
currentRowSpans.filter(".arrow").html('&#9658;');
rows.filter("[id^=row_"+id+"]").hide(); // hide all children
} else { // we are SHOWING
// replace right arrow by down arrow for current row
var currentRowSpans = currentRow.find("span");
currentRowSpans.filter(".iconfclosed").removeClass("iconfclosed").addClass("iconfopen");
currentRowSpans.filter(".arrow").html('&#9660;');
// replace down arrows by right arrows for child rows
var childRowsSpans = childRows.find("span");
childRowsSpans.filter(".iconfopen").removeClass("iconfopen").addClass("iconfclosed");
childRowsSpans.filter(".arrow").html('&#9658;');
childRows.show(); //show all children
}
updateStripes();
}
function toggleInherit(id)
{
var rows = $('tr.inherit.'+id);
var img = $('tr.inherit_header.'+id+' img');
var src = $(img).attr('src');
if (rows.filter(':first').is(':visible')===true) {
rows.css('display','none');
$(img).attr('src',src.substring(0,src.length-8)+'closed.png');
} else {
rows.css('display','table-row'); // using show() causes jump in firefox
$(img).attr('src',src.substring(0,src.length-10)+'open.png');
}
}
docs/html/index.html deleted 100644 → 0
View file @ d75d29e2
This diff is collapsed.
docs/html/jquery.js deleted 100644 → 0
View file @ d75d29e2
This source diff could not be displayed because it is too large. You can view the blob instead.
docs/html/md__benchmarks.html deleted 100644 → 0
View file @ d75d29e2
<!-- HTML header for doxygen 1.8.6-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.7"/>
<title>FlatBuffers: Benchmarks</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
$(window).load(resizeHeight);
</script>
<link href="style.css" rel="stylesheet" type="text/css" />
<link href="https://fonts.googleapis.com/css?family=Roboto:300,400,400italic,500,500italic,700,700italic|Roboto+Mono:400,700" rel="stylesheet">
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea" style="height: 110px;">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="commonprojectlogo">
<img alt="Logo" src="fpl_logo_small.png"/>
</td>
<td style="padding-left: 0.5em;">
<div id="projectname">FlatBuffers
</div>
<div style="font-size:12px;">
An open source project by <a href="https://developers.google.com/games/#Tools">FPL</a>.
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.7 -->
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('md__benchmarks.html','');});
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<div class="title">Benchmarks </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>Comparing against other serialization solutions, running on Windows 7 64bit. We use the LITE runtime for Protocol Buffers (less code / lower overhead), Rapid JSON (one of the fastest C++ JSON parsers around), and pugixml, also one of the fastest XML parsers.</p>
<p>We also compare against code that doesn't use a serialization library at all (the column "Raw structs"), which is what you get if you write hardcoded code that just writes structs. This is the fastest possible, but of course is not cross platform nor has any kind of forwards / backwards compatibility.</p>
<p>We compare against Flatbuffers with the binary wire format (as intended), and also with JSON as the wire format with the optional JSON parser (which, using a schema, parses JSON into a binary buffer that can then be accessed as before).</p>
<p>The benchmark object is a set of about 10 objects containing an array, 4 strings, and a large variety of int/float scalar values of all sizes, meant to be representative of game data, e.g. a scene format.</p>
<table class="doxtable">
<tr>
<th></th><th>FlatBuffers (binary) </th><th>Protocol Buffers LITE </th><th>Rapid JSON </th><th>FlatBuffers (JSON) </th><th>pugixml </th><th>Raw structs </th></tr>
<tr>
<td>Decode + Traverse + Dealloc (1 million times, seconds) </td><td>0.08 </td><td>302 </td><td>583 </td><td>105 </td><td>196 </td><td>0.02 </td></tr>
<tr>
<td>Decode / Traverse / Dealloc (breakdown) </td><td>0 / 0.08 / 0 </td><td>220 / 0.15 / 81 </td><td>294 / 0.9 / 287 </td><td>70 / 0.08 / 35 </td><td>41 / 3.9 / 150 </td><td>0 / 0.02 / 0 </td></tr>
<tr>
<td>Encode (1 million times, seconds) </td><td>3.2 </td><td>185 </td><td>650 </td><td>169 </td><td>273 </td><td>0.15 </td></tr>
<tr>
<td>Wire format size (normal / zlib, bytes) </td><td>344 / 220 </td><td>228 / 174 </td><td>1475 / 322 </td><td>1029 / 298 </td><td>1137 / 341 </td><td>312 / 187 </td></tr>
<tr>
<td>Memory needed to store decoded wire (bytes / blocks) </td><td>0 / 0 </td><td>760 / 20 </td><td>65689 / 4 </td><td>328 / 1 </td><td>34194 / 3 </td><td>0 / 0 </td></tr>
<tr>
<td>Transient memory allocated during decode (KB) </td><td>0 </td><td>1 </td><td>131 </td><td>4 </td><td>34 </td><td>0 </td></tr>
<tr>
<td>Generated source code size (KB) </td><td>4 </td><td>61 </td><td>0 </td><td>4 </td><td>0 </td><td>0 </td></tr>
<tr>
<td>Field access in handwritten traversal code </td><td>typed accessors </td><td>typed accessors </td><td>manual error checking </td><td>typed accessors </td><td>manual error checking </td><td>typed but no safety </td></tr>
<tr>
<td>Library source code (KB) </td><td>15 </td><td>some subset of 3800 </td><td>87 </td><td>43 </td><td>327 </td><td>0 </td></tr>
</table>
<h3>Some other serialization systems we compared against but did not benchmark (yet), in rough order of applicability:</h3>
<ul>
<li>Cap'n'Proto promises to reduce Protocol Buffers much like FlatBuffers does, though with a more complicated binary encoding and less flexibility (no optional fields to allow deprecating fields or serializing with missing fields for which defaults exist). It currently also isn't fully cross-platform portable (lack of VS support).</li>
<li>msgpack: has very minimal forwards/backwards compatibility support when used with the typed C++ interface. Also lacks VS2010 support.</li>
<li>Thrift: very similar to Protocol Buffers, but appears to be less efficient, and have more dependencies.</li>
<li>YAML: a superset of JSON and otherwise very similar. Used by e.g. Unity.</li>
<li>C# comes with built-in serialization functionality, as used by Unity also. Being tied to the language, and having no automatic versioning support limits its applicability.</li>
<li>Project Anarchy (the free mobile engine by Havok) comes with a serialization system, that however does no automatic versioning (have to code around new fields manually), is very much tied to the rest of the engine, and works without a schema to generate code (tied to your C++ class definition).</li>
</ul>
<h3>Code for benchmarks</h3>
<p>Code for these benchmarks sits in <code>benchmarks/</code> in git branch <code>benchmarks</code>. It sits in its own branch because it has submodule dependencies that the main project doesn't need, and the code standards do not meet those of the main project. Please read <code>benchmarks/cpp/README.txt</code> before working with the code. </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- Google Analytics -->
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-49880327-7', 'auto');
ga('send', 'pageview');
</script>
</body>
</html>
docs/html/md__building.html deleted 100644 → 0
View file @ d75d29e2
<!-- HTML header for doxygen 1.8.6-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.7"/>
<title>FlatBuffers: Building</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
$(window).load(resizeHeight);
</script>
<link href="style.css" rel="stylesheet" type="text/css" />
<link href="https://fonts.googleapis.com/css?family=Roboto:300,400,400italic,500,500italic,700,700italic|Roboto+Mono:400,700" rel="stylesheet">
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea" style="height: 110px;">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="commonprojectlogo">
<img alt="Logo" src="fpl_logo_small.png"/>
</td>
<td style="padding-left: 0.5em;">
<div id="projectname">FlatBuffers
</div>
<div style="font-size:12px;">
An open source project by <a href="https://developers.google.com/games/#Tools">FPL</a>.
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.7 -->
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('md__building.html','');});
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<div class="title">Building </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>There are project files for Visual Studio and Xcode that should allow you to build the compiler <code>flatc</code>, the samples and the tests out of the box.</p>
<p>Alternatively, the distribution comes with a <code>cmake</code> file that should allow you to build project/make files for any platform. For details on <code>cmake</code>, see <a href="http://www.cmake.org">http://www.cmake.org</a>. In brief, depending on your platform, use one of e.g.: </p><pre class="fragment">cmake -G "Unix Makefiles"
cmake -G "Visual Studio 10"
cmake -G "Xcode"
</pre><p>Then, build as normal for your platform. This should result in a <code>flatc</code> executable, essential for the next steps. Note that to use clang instead of gcc, you may need to set up your environment variables, e.g. <code>CC=/usr/bin/clang CXX=/usr/bin/clang++ cmake -G "Unix Makefiles"</code>.</p>
<p>Optionally, run the <code>flattests</code> executable to ensure everything is working correctly on your system. If this fails, please contact us!</p>
<p>Note that you MUST be in the root of the FlatBuffers distribution when you run 'flattests' (and the samples), or it will fail to load its files.</p>
<p>Building should also produce two sample executables, <code>sample_binary</code> and <code>sample_text</code>, see the corresponding <code>.cpp</code> file in the samples directory.</p>
<p>There is an <code>android</code> directory that contains all you need to build the test executable on android (use the included <code>build_apk.sh</code> script, or use <code>ndk_build</code> / <code>adb</code> etc. as usual). Upon running, it will output to the log if tests succeeded or not.</p>
<p>There is usually no runtime to compile, as the code consists of a single header, <code>include/flatbuffers/flatbuffers.h</code>. You should add the <code>include</code> folder to your include paths. If you wish to be able to load schemas and/or parse text into binary buffers at runtime, you additionally need the other headers in <code>include/flatbuffers</code>. You must also compile/link <code>src/idl_parser.cpp</code> (and <code>src/idl_gen_text.cpp</code> if you also want to be able convert binary to text).</p>
<p>For applications on Google Play that integrate this library, usage is tracked. This tracking is done automatically using the embedded version string (flatbuffer_version_string), and helps us continue to optimize it. Aside from consuming a few extra bytes in your application binary, it shouldn't affect your application at all. We use this information to let us know if FlatBuffers is useful and if we should continue to invest in it. Since this is open source, you are free to remove the version string but we would appreciate if you would leave it in. </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- Google Analytics -->
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-49880327-7', 'auto');
ga('send', 'pageview');
</script>
</body>
</html>
docs/html/md__compiler.html deleted 100644 → 0
View file @ d75d29e2
<!-- HTML header for doxygen 1.8.6-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.7"/>
<title>FlatBuffers: Using the schema compiler</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
$(window).load(resizeHeight);
</script>
<link href="style.css" rel="stylesheet" type="text/css" />
<link href="https://fonts.googleapis.com/css?family=Roboto:300,400,400italic,500,500italic,700,700italic|Roboto+Mono:400,700" rel="stylesheet">
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea" style="height: 110px;">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="commonprojectlogo">
<img alt="Logo" src="fpl_logo_small.png"/>
</td>
<td style="padding-left: 0.5em;">
<div id="projectname">FlatBuffers
</div>
<div style="font-size:12px;">
An open source project by <a href="https://developers.google.com/games/#Tools">FPL</a>.
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.7 -->
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('md__compiler.html','');});
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<div class="title">Using the schema compiler </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>Usage: </p><pre class="fragment">flatc [ GENERATOR OPTIONS ] [ -o PATH ] [ -I PATH ] [ -S ] FILES...
[ -- FILES...]
</pre><p>The files are read and parsed in order, and can contain either schemas or data (see below). Data files are processed according to the definitions of the most recent schema specified.</p>
<p><code>--</code> indicates that the following files are binary files in FlatBuffer format conforming to the schema indicated before it.</p>
<p>Depending on the flags passed, additional files may be generated for each file processed:</p>
<p>For any schema input files, one or more generators can be specified:</p>
<ul>
<li><code>--cpp</code>, <code>-c</code> : Generate a C++ header for all definitions in this file (as <code>filename_generated.h</code>).</li>
<li><code>--java</code>, <code>-j</code> : Generate Java code.</li>
<li><code>--csharp</code>, <code>-n</code> : Generate C# code.</li>
<li><code>--go</code>, <code>-g</code> : Generate Go code.</li>
<li><code>--python</code>, <code>-p</code>: Generate Python code.</li>
<li><code>--javascript</code>, <code>-s</code>: Generate JavaScript code.</li>
<li><code>--php</code>: Generate PHP code.</li>
</ul>
<p>For any data input files:</p>
<ul>
<li><code>--binary</code>, <code>-b</code> : If data is contained in this file, generate a <code>filename.bin</code> containing the binary flatbuffer (or a different extension if one is specified in the schema).</li>
<li><code>--json</code>, <code>-t</code> : If data is contained in this file, generate a <code>filename.json</code> representing the data in the flatbuffer.</li>
</ul>
<p>Additional options:</p>
<ul>
<li><code>-o PATH</code> : Output all generated files to PATH (either absolute, or relative to the current directory). If omitted, PATH will be the current directory. PATH should end in your systems path separator, e.g. <code>/</code> or <code>\</code>.</li>
<li><code>-I PATH</code> : when encountering <code>include</code> statements, attempt to load the files from this path. Paths will be tried in the order given, and if all fail (or none are specified) it will try to load relative to the path of the schema file being parsed.</li>
<li><code>-M</code> : Print make rules for generated files.</li>
<li><code>--strict-json</code> : Require &amp; generate strict JSON (field names are enclosed in quotes, no trailing commas in tables/vectors). By default, no quotes are required/generated, and trailing commas are allowed.</li>
<li><code>--defaults-json</code> : Output fields whose value is equal to the default value when writing JSON text.</li>
<li><code>--no-prefix</code> : Don't prefix enum values in generated C++ by their enum type.</li>
<li><code>--scoped-enums</code> : Use C++11 style scoped and strongly typed enums in generated C++. This also implies <code>--no-prefix</code>.</li>
<li><code>--gen-includes</code> : (deprecated), this is the default behavior. If the original behavior is required (no include statements) use <code>--no-includes.</code></li>
<li><code>--no-includes</code> : Don't generate include statements for included schemas the generated file depends on (C++).</li>
<li><code>--gen-mutable</code> : Generate additional non-const accessors for mutating FlatBuffers in-place.</li>
<li><code>--gen-onefile</code> : Generate single output file (useful for C#)</li>
<li><code>--gen-all</code>: Generate not just code for the current schema files, but for all files it includes as well. If the language uses a single file for output (by default the case for C++ and JS), all code will end up in this one file.</li>
<li><code>--raw-binary</code> : Allow binaries without a file_indentifier to be read. This may crash flatc given a mismatched schema.</li>
<li><code>--proto</code>: Expect input files to be .proto files (protocol buffers). Output the corresponding .fbs file. Currently supports: <code>package</code>, <code>message</code>, <code>enum</code>, nested declarations, <code>import</code> (use <code>-I</code> for paths), <code>extend</code>, <code>oneof</code>, <code>group</code>. Does not support, but will skip without error: <code>option</code>, <code>service</code>, <code>extensions</code>, and most everything else.</li>
<li><code>--schema</code>: Serialize schemas instead of JSON (use with -b). This will output a binary version of the specified schema that itself corresponds to the reflection/reflection.fbs schema. Loading this binary file is the basis for reflection functionality.</li>
</ul>
<p>NOTE: short-form options for generators are deprecated, use the long form whenever possible. </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- Google Analytics -->
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-49880327-7', 'auto');
ga('send', 'pageview');
</script>
</body>
</html>
docs/html/md__cpp_usage.html deleted 100644 → 0
View file @ d75d29e2
This diff is collapsed.
docs/html/md__go_usage.html deleted 100644 → 0
View file @ d75d29e2
<!-- HTML header for doxygen 1.8.6-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.7"/>
<title>FlatBuffers: Use in Go</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
$(window).load(resizeHeight);
</script>
<link href="style.css" rel="stylesheet" type="text/css" />
<link href="https://fonts.googleapis.com/css?family=Roboto:300,400,400italic,500,500italic,700,700italic|Roboto+Mono:400,700" rel="stylesheet">
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea" style="height: 110px;">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="commonprojectlogo">
<img alt="Logo" src="fpl_logo_small.png"/>
</td>
<td style="padding-left: 0.5em;">
<div id="projectname">FlatBuffers
</div>
<div style="font-size:12px;">
An open source project by <a href="https://developers.google.com/games/#Tools">FPL</a>.
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.7 -->
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('md__go_usage.html','');});
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<div class="title">Use in Go </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>There's experimental support for reading FlatBuffers in Go. Generate code for Go with the <code>-g</code> option to <code>flatc</code>.</p>
<p>See <code>go_test.go</code> for an example. You import the generated code, read a FlatBuffer binary file into a <code>[]byte</code>, which you pass to the <code>GetRootAsMonster</code> function:</p>
<div class="fragment"><div class="line"><span class="keyword">import</span> (</div>
<div class="line"> example <span class="stringliteral">&quot;MyGame/Example&quot;</span></div>
<div class="line"> flatbuffers <span class="stringliteral">&quot;github.com/google/flatbuffers/go&quot;</span></div>
<div class="line"></div>
<div class="line"> io/ioutil</div>
<div class="line">)</div>
<div class="line"></div>
<div class="line">buf, err := ioutil.ReadFile(<span class="stringliteral">&quot;monster.dat&quot;</span>)</div>
<div class="line"><span class="comment">// handle err</span></div>
<div class="line">monster := example.GetRootAsMonster(buf, 0)</div>
</div><!-- fragment --><p>Now you can access values like this:</p>
<div class="fragment"><div class="line">hp := monster.Hp()</div>
<div class="line">pos := monster.Pos(nil)</div>
</div><!-- fragment --><p>Note that whenever you access a new object like in the <code>Pos</code> example above, a new temporary accessor object gets created. If your code is very performance sensitive (you iterate through a lot of objects), you can replace nil with a pointer to a <code>Vec3</code> object you've already created. This allows you to reuse it across many calls and reduce the amount of object allocation (and thus garbage collection) your program does.</p>
<p>To access vectors you pass an extra index to the vector field accessor. Then a second method with the same name suffixed by <code>Length</code> let's you know the number of elements you can access:</p>
<div class="fragment"><div class="line"><span class="keywordflow">for</span> i := 0; i &lt; monster.InventoryLength(); i++ {</div>
<div class="line"> monster.Inventory(i) <span class="comment">// do something here</span></div>
<div class="line">}</div>
</div><!-- fragment --><p>You can also construct these buffers in Go using the functions found in the generated code, and the FlatBufferBuilder class:</p>
<div class="fragment"><div class="line">builder := flatbuffers.NewBuilder(0)</div>
</div><!-- fragment --><p>Create strings:</p>
<div class="fragment"><div class="line">str := builder.CreateString(<span class="stringliteral">&quot;MyMonster&quot;</span>)</div>
</div><!-- fragment --><p>Create a table with a struct contained therein:</p>
<div class="fragment"><div class="line">example.MonsterStart(builder)</div>
<div class="line">example.MonsterAddPos(builder, example.CreateVec3(builder, 1.0, 2.0, 3.0, 3.0, 4, 5, 6))</div>
<div class="line">example.MonsterAddHp(builder, 80)</div>
<div class="line">example.MonsterAddName(builder, str)</div>
<div class="line">example.MonsterAddInventory(builder, inv)</div>
<div class="line">example.MonsterAddTest_Type(builder, 1)</div>
<div class="line">example.MonsterAddTest(builder, mon2)</div>
<div class="line">example.MonsterAddTest4(builder, test4s)</div>
<div class="line">mon := example.MonsterEnd(builder)</div>
</div><!-- fragment --><p>Unlike C++, Go does not support table creation functions like 'createMonster()'. This is to create the buffer without using temporary object allocation (since the <code>Vec3</code> is an inline component of <code>Monster</code>, it has to be created right where it is added, whereas the name and the inventory are not inline, and <b>must</b> be created outside of the table creation sequence). Structs do have convenient methods that allow you to construct them in one call. These also have arguments for nested structs, e.g. if a struct has a field <code>a</code> and a nested struct field <code>b</code> (which has fields <code>c</code> and <code>d</code>), then the arguments will be <code>a</code>, <code>c</code> and <code>d</code>.</p>
<p>Vectors also use this start/end pattern to allow vectors of both scalar types and structs:</p>
<div class="fragment"><div class="line">example.MonsterStartInventoryVector(builder, 5)</div>
<div class="line"><span class="keywordflow">for</span> i := 4; i &gt;= 0; i-- {</div>
<div class="line"> builder.PrependByte(byte(i))</div>
<div class="line">}</div>
<div class="line">inv := builder.EndVector(5)</div>
</div><!-- fragment --><p>The generated method 'StartInventoryVector' is provided as a convenience function which calls 'StartVector' with the correct element size of the vector type which in this case is 'ubyte' or 1 byte per vector element. You pass the number of elements you want to write. You write the elements backwards since the buffer is being constructed back to front. Use the correct <code>Prepend</code> call for the type, or <code>PrependUOffsetT</code> for offsets. You then pass <code>inv</code> to the corresponding <code>Add</code> call when you construct the table containing it afterwards.</p>
<p>There are <code>Prepend</code> functions for all the scalar types. You use <code>PrependUOffset</code> for any previously constructed objects (such as other tables, strings, vectors). For structs, you use the appropriate <code>create</code> function in-line, as shown above in the <code>Monster</code> example.</p>
<p>Once you're done constructing a buffer, you call <code>Finish</code> with the root object offset (<code>mon</code> in the example above). Your data now resides in Builder.Bytes. Important to note is that the real data starts at the index indicated by Head(), for Offset() bytes (this is because the buffer is constructed backwards). If you wanted to read the buffer right after creating it (using <code>GetRootAsMonster</code> above), the second argument, instead of <code>0</code> would thus also be <code>Head()</code>.</p>
<h2>Text Parsing</h2>
<p>There currently is no support for parsing text (Schema's and JSON) directly from Go, though you could use the C++ parser through cgo. Please see the C++ documentation for more on text parsing. </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- Google Analytics -->
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-49880327-7', 'auto');
ga('send', 'pageview');
</script>
</body>
</html>
docs/html/md__grammar.html deleted 100644 → 0
View file @ d75d29e2
<!-- HTML header for doxygen 1.8.6-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.7"/>
<title>FlatBuffers: Grammar of the schema language</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
$(window).load(resizeHeight);
</script>
<link href="style.css" rel="stylesheet" type="text/css" />
<link href="https://fonts.googleapis.com/css?family=Roboto:300,400,400italic,500,500italic,700,700italic|Roboto+Mono:400,700" rel="stylesheet">
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea" style="height: 110px;">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="commonprojectlogo">
<img alt="Logo" src="fpl_logo_small.png"/>
</td>
<td style="padding-left: 0.5em;">
<div id="projectname">FlatBuffers
</div>
<div style="font-size:12px;">
An open source project by <a href="https://developers.google.com/games/#Tools">FPL</a>.
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.7 -->
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('md__grammar.html','');});
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<div class="title">Grammar of the schema language </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>schema = include* ( namespace_decl | type_decl | enum_decl | root_decl | file_extension_decl | file_identifier_decl | attribute_decl | object )*</p>
<p>include = <code>include</code> string_constant <code>;</code></p>
<p>namespace_decl = <code>namespace</code> ident ( <code>.</code> ident )* <code>;</code></p>
<p>attribute_decl = <code>attribute</code> string_constant <code>;</code></p>
<p>type_decl = ( <code>table</code> | <code>struct</code> ) ident metadata <code>{</code> field_decl+ <code>}</code></p>
<p>enum_decl = ( <code>enum</code> | <code>union</code> ) ident [ <code>:</code> type ] metadata <code>{</code> commasep( enumval_decl ) <code>}</code></p>
<p>root_decl = <code>root_type</code> ident <code>;</code></p>
<p>field_decl = ident <code>:</code> type [ <code>=</code> scalar ] metadata <code>;</code></p>
<p>type = <code>bool</code> | <code>byte</code> | <code>ubyte</code> | <code>short</code> | <code>ushort</code> | <code>int</code> | <code>uint</code> | <code>float</code> | <code>long</code> | <code>ulong</code> | <code>double</code> | <code>string</code> | <code>[</code> type <code>]</code> | ident</p>
<p>enumval_decl = ident [ <code>=</code> integer_constant ]</p>
<p>metadata = [ <code>(</code> commasep( ident [ <code>:</code> single_value ] ) <code>)</code> ]</p>
<p>scalar = integer_constant | float_constant</p>
<p>object = { commasep( ident <code>:</code> value ) }</p>
<p>single_value = scalar | string_constant</p>
<p>value = single_value | object | <code>[</code> commasep( value ) <code>]</code></p>
<p>commasep(x) = [ x ( <code>,</code> x )* ]</p>
<p>file_extension_decl = <code>file_extension</code> string_constant <code>;</code></p>
<p>file_identifier_decl = <code>file_identifier</code> string_constant <code>;</code></p>
<p>integer_constant = -?[0-9]+ | <code>true</code> | <code>false</code></p>
<p>float_constant = -?[0-9]+.[0-9]+((e|E)(+|-)?[0-9]+)? </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- Google Analytics -->
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-49880327-7', 'auto');
ga('send', 'pageview');
</script>
</body>
</html>
docs/html/md__internals.html deleted 100644 → 0
View file @ d75d29e2
This diff is collapsed.
docs/html/md__java_usage.html deleted 100644 → 0
View file @ d75d29e2
This diff is collapsed.
docs/html/md__python_usage.html deleted 100644 → 0
View file @ d75d29e2
This diff is collapsed.
docs/html/md__schemas.html deleted 100644 → 0
View file @ d75d29e2
This diff is collapsed.
docs/html/md__support.html deleted 100644 → 0
View file @ d75d29e2
<!-- HTML header for doxygen 1.8.6-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.7"/>
<title>FlatBuffers: Platform / Language / Feature support</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
$(window).load(resizeHeight);
</script>
<link href="style.css" rel="stylesheet" type="text/css" />
<link href="https://fonts.googleapis.com/css?family=Roboto:300,400,400italic,500,500italic,700,700italic|Roboto+Mono:400,700" rel="stylesheet">
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea" style="height: 110px;">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="commonprojectlogo">
<img alt="Logo" src="fpl_logo_small.png"/>
</td>
<td style="padding-left: 0.5em;">
<div id="projectname">FlatBuffers
</div>
<div style="font-size:12px;">
An open source project by <a href="https://developers.google.com/games/#Tools">FPL</a>.
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.7 -->
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('md__support.html','');});
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<div class="title">Platform / Language / Feature support </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>FlatBuffers is actively being worked on, which means that certain platform / language / feature combinations may not be available yet.</p>
<p>This page tries to track those issues, to make informed decisions easier. In general:</p>
<ul>
<li>Languages: language support beyond the ones created by the original FlatBuffer authors typically depends on community contributions.</li>
<li>Features: C++ was the first language supported, since our original target was high performance game development. It thus has the richest feature set, and is likely most robust. Other languages are catching up however.</li>
<li>Platforms: All language implementations are typically portable to most platforms, unless where noted otherwise.</li>
</ul>
<p>NOTE: this table is a start, it needs to be extended.</p>
<table class="doxtable">
<tr>
<th>Feature </th><th>C++ </th><th>Java </th><th>C# </th><th>Go </th><th>Python </th><th>JS </th><th>C </th><th>PHP </th><th>Ruby </th></tr>
<tr>
<td>Codegen for all basic features </td><td>Yes </td><td>Yes </td><td>Yes </td><td>Yes </td><td>Yes </td><td>Yes </td><td>WiP </td><td>WiP </td><td>WiP </td></tr>
<tr>
<td>JSON parsing </td><td>Yes </td><td>No </td><td>No </td><td>No </td><td>No </td><td>No </td><td>No </td><td>No </td><td>No </td></tr>
<tr>
<td>Simple mutation </td><td>Yes </td><td>WIP </td><td>WIP </td><td>No </td><td>No </td><td>No </td><td>No </td><td>No </td><td>No </td></tr>
<tr>
<td>Reflection </td><td>Yes </td><td>No </td><td>No </td><td>No </td><td>No </td><td>No </td><td>No </td><td>No </td><td>No </td></tr>
<tr>
<td>Buffer verifier </td><td>Yes </td><td>No </td><td>No </td><td>No </td><td>No </td><td>No </td><td>No </td><td>No </td><td>No </td></tr>
<tr>
<td>Testing: basic </td><td>Yes </td><td>Yes </td><td>Yes </td><td>Yes </td><td>Yes </td><td>Yes </td><td>? </td><td>? </td><td>? </td></tr>
<tr>
<td>Testing: fuzz </td><td>Yes </td><td>No </td><td>No </td><td>Yes </td><td>Yes </td><td>No </td><td>? </td><td>? </td><td>? </td></tr>
<tr>
<td>Performance: </td><td>Superb </td><td>Great </td><td>Great </td><td>Great </td><td>Ok </td><td>? </td><td>Superb</td><td>? </td><td>? </td></tr>
<tr>
<td>Platform: Windows </td><td>VS2010 </td><td>Yes </td><td>Yes </td><td>? </td><td>? </td><td>? </td><td>? </td><td>? </td><td>? </td></tr>
<tr>
<td>Platform: Linux </td><td>GCC282 </td><td>Yes </td><td>? </td><td>Yes </td><td>Yes </td><td>? </td><td>? </td><td>? </td><td>? </td></tr>
<tr>
<td>Platform: OS X </td><td>Xcode4 </td><td>? </td><td>? </td><td>? </td><td>Yes </td><td>? </td><td>? </td><td>? </td><td>? </td></tr>
<tr>
<td>Platform: Android </td><td>NDK10d </td><td>Yes </td><td>? </td><td>? </td><td>? </td><td>? </td><td>? </td><td>? </td><td>? </td></tr>
<tr>
<td>Platform: iOS </td><td>? </td><td>? </td><td>? </td><td>? </td><td>? </td><td>? </td><td>? </td><td>? </td><td>? </td></tr>
<tr>
<td>Engine: Unity </td><td>? </td><td>? </td><td>Yes </td><td>? </td><td>? </td><td>? </td><td>? </td><td>? </td><td>? </td></tr>
<tr>
<td>Primary authors (github) </td><td>gwvo </td><td>gwvo </td><td>ev*/js*</td><td>rw </td><td>rw </td><td>evanw/ev* </td><td>mik* </td><td>ch* </td><td>rw </td></tr>
</table>
<ul>
<li>ev = evolutional</li>
<li>js = jonsimantov</li>
<li>mik = mikkelfj</li>
<li>ch = chobie </li>
</ul>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- Google Analytics -->
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-49880327-7', 'auto');
ga('send', 'pageview');
</script>
</body>
</html>
docs/html/md__white_paper.html deleted 100644 → 0
View file @ d75d29e2
<!-- HTML header for doxygen 1.8.6-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.7"/>
<title>FlatBuffers: FlatBuffers white paper</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
$(window).load(resizeHeight);
</script>
<link href="style.css" rel="stylesheet" type="text/css" />
<link href="https://fonts.googleapis.com/css?family=Roboto:300,400,400italic,500,500italic,700,700italic|Roboto+Mono:400,700" rel="stylesheet">
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea" style="height: 110px;">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="commonprojectlogo">
<img alt="Logo" src="fpl_logo_small.png"/>
</td>
<td style="padding-left: 0.5em;">
<div id="projectname">FlatBuffers
</div>
<div style="font-size:12px;">
An open source project by <a href="https://developers.google.com/games/#Tools">FPL</a>.
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.7 -->
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('md__white_paper.html','');});
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<div class="title">FlatBuffers white paper </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>This document tries to shed some light on to the "why" of FlatBuffers, a new serialization library.</p>
<h2>Motivation</h2>
<p>Back in the good old days, performance was all about instructions and cycles. Nowadays, processing units have run so far ahead of the memory subsystem, that making an efficient application should start and finish with thinking about memory. How much you use of it. How you lay it out and access it. How you allocate it. When you copy it.</p>
<p>Serialization is a pervasive activity in a lot programs, and a common source of memory inefficiency, with lots of temporary data structures needed to parse and represent data, and inefficient allocation patterns and locality.</p>
<p>If it would be possible to do serialization with no temporary objects, no additional allocation, no copying, and good locality, this could be of great value. The reason serialization systems usually don't manage this is because it goes counter to forwards/backwards compatability, and platform specifics like endianness and alignment.</p>
<p>FlatBuffers is what you get if you try anyway.</p>
<p>In particular, FlatBuffers focus is on mobile hardware (where memory size and memory bandwidth is even more constrained than on desktop hardware), and applications that have the highest performance needs: games.</p>
<h2>FlatBuffers</h2>
<p><em>This is a summary of FlatBuffers functionality, with some rationale. A more detailed description can be found in the FlatBuffers documentation.</em></p>
<h3>Summary</h3>
<p>A FlatBuffer is a binary buffer containing nested objects (structs, tables, vectors,..) organized using offsets so that the data can be traversed in-place just like any pointer-based data structure. Unlike most in-memory data structures however, it uses strict rules of alignment and endianness (always little) to ensure these buffers are cross platform. Additionally, for objects that are tables, FlatBuffers provides forwards/backwards compatibility and general optionality of fields, to support most forms of format evolution.</p>
<p>You define your object types in a schema, which can then be compiled to C++ or Java for low to zero overhead reading &amp; writing. Optionally, JSON data can be dynamically parsed into buffers.</p>
<h3>Tables</h3>
<p>Tables are the cornerstone of FlatBuffers, since format evolution is essential for most applications of serialization. Typically, dealing with format changes is something that can be done transparently during the parsing process of most serialization solutions out there. But a FlatBuffer isn't parsed before it is accessed.</p>
<p>Tables get around this by using an extra indirection to access fields, through a <em>vtable</em>. Each table comes with a vtable (which may be shared between multiple tables with the same layout), and contains information where fields for this particular kind of instance of vtable are stored. The vtable may also indicate that the field is not present (because this FlatBuffer was written with an older version of the software, of simply because the information was not necessary for this instance, or deemed deprecated), in which case a default value is returned.</p>
<p>Tables have a low overhead in memory (since vtables are small and shared) and in access cost (an extra indirection), but provide great flexibility. Tables may even cost less memory than the equivalent struct, since fields do not need to be stored when they are equal to their default.</p>
<p>FlatBuffers additionally offers "naked" structs, which do not offer forwards/backwards compatibility, but can be even smaller (useful for very small objects that are unlikely to change, like e.g. a coordinate pair or a RGBA color).</p>
<h3>Schemas</h3>
<p>While schemas reduce some generality (you can't just read any data without having its schema), they have a lot of upsides:</p>
<ul>
<li>Most information about the format can be factored into the generated code, reducing memory needed to store data, and time to access it.</li>
<li>The strong typing of the data definitions means less error checking/handling at runtime (less can go wrong).</li>
<li>A schema enables us to access a buffer without parsing.</li>
</ul>
<p>FlatBuffer schemas are fairly similar to those of the incumbent, Protocol Buffers, and generally should be readable to those familiar with the C family of languages. We chose to improve upon the features offered by .proto files in the following ways:</p>
<ul>
<li>Deprecation of fields instead of manual field id assignment. Extending an object in a .proto means hunting for a free slot among the numbers (preferring lower numbers since they have a more compact representation). Besides being inconvenient, it also makes removing fields problematic: you either have to keep them, not making it obvious that this field shouldn't be read/written anymore, and still generating accessors. Or you remove it, but now you risk that there's still old data around that uses that field by the time someone reuses that field id, with nasty consequences.</li>
<li>Differentiating between tables and structs (see above). Effectively all table fields are <code>optional</code>, and all struct fields are <code>required</code>.</li>
<li>Having a native vector type instead of <code>repeated</code>. This gives you a length without having to collect all items, and in the case of scalars provides for a more compact representation, and one that guarantees adjacency.</li>
<li>Having a native <code>union</code> type instead of using a series of <code>optional</code> fields, all of which must be checked individually.</li>
<li>Being able to define defaults for all scalars, instead of having to deal with their optionality at each access.</li>
<li>A parser that can deal with both schemas and data definitions (JSON compatible) uniformly. </li>
</ul>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- Google Analytics -->
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-49880327-7', 'auto');
ga('send', 'pageview');
</script>
</body>
</html>
docs/html/navtree.css deleted 100644 → 0
View file @ d75d29e2
#nav-tree .children_ul {
margin:0;
padding:4px;
}
#nav-tree ul {
list-style:none outside none;
margin:0px;
padding:0px;
}
#nav-tree li {
white-space:nowrap;
margin:0px;
padding:0px;
}
#nav-tree .plus {
margin:0px;
}
#nav-tree .selected {
background-image: url('tab_a.png');
background-repeat:repeat-x;
color: #fff;
text-shadow: 0px 1px 1px rgba(0, 0, 0, 1.0);
}
#nav-tree img {
margin:0px;
padding:0px;
border:0px;
vertical-align: middle;
}
#nav-tree a {
text-decoration:none;
padding:0px;
margin:0px;
outline:none;
}
#nav-tree .label {
margin:0px;
padding:0px;
font: 12px 'Lucida Grande',Geneva,Helvetica,Arial,sans-serif;
}
#nav-tree .label a {
padding:2px;
}
#nav-tree .selected a {
text-decoration:none;
color:#fff;
}
#nav-tree .children_ul {
margin:0px;
padding:0px;
}
#nav-tree .item {
margin:0px;
padding:0px;
}
#nav-tree {
padding: 0px 0px;
background-color: #FAFAFF;
font-size:14px;
overflow:auto;
}
#doc-content {
overflow:auto;
display:block;
padding:0px;
margin:0px;
-webkit-overflow-scrolling : touch; /* iOS 5+ */
}
#side-nav {
padding:0 6px 0 0;
margin: 0px;
display:block;
position: absolute;
left: 0px;
width: 250px;
}
.ui-resizable .ui-resizable-handle {
display:block;
}
.ui-resizable-e {
background:url("ftv2splitbar.png") repeat scroll right center transparent;
cursor:e-resize;
height:100%;
right:0;
top:0;
width:6px;
}
.ui-resizable-handle {
display:none;
font-size:0.1px;
position:absolute;
z-index:1;
}
#nav-tree-contents {
margin: 6px 0px 0px 0px;
}
#nav-tree {
background-image:url('nav_h.png');
background-repeat:repeat-x;
background-color: #F9FAFC;
-webkit-overflow-scrolling : touch; /* iOS 5+ */
}
#nav-sync {
position:absolute;
top:5px;
right:24px;
z-index:0;
}
#nav-sync img {
opacity:0.3;
}
#nav-sync img:hover {
opacity:0.9;
}
@media print
{
#nav-tree { display: none; }
div.ui-resizable-handle { display: none; position: relative; }
}
docs/html/navtree.js deleted 100644 → 0
View file @ d75d29e2
This diff is collapsed.
docs/html/navtreeindex0.js deleted 100644 → 0
View file @ d75d29e2
var NAVTREEINDEX0 =
{
"index.html":[],
"md__benchmarks.html":[8],
"md__building.html":[0],
"md__compiler.html":[1],
"md__cpp_usage.html":[3],
"md__go_usage.html":[4],
"md__grammar.html":[11],
"md__internals.html":[10],
"md__java_usage.html":[5],
"md__python_usage.html":[6],
"md__schemas.html":[2],
"md__support.html":[7],
"md__white_paper.html":[9],
"pages.html":[]
};
docs/html/pages.html deleted 100644 → 0
View file @ d75d29e2
<!-- HTML header for doxygen 1.8.6-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.7"/>
<title>FlatBuffers: Related Pages</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
$(window).load(resizeHeight);
</script>
<link href="style.css" rel="stylesheet" type="text/css" />
<link href="https://fonts.googleapis.com/css?family=Roboto:300,400,400italic,500,500italic,700,700italic|Roboto+Mono:400,700" rel="stylesheet">
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea" style="height: 110px;">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="commonprojectlogo">
<img alt="Logo" src="fpl_logo_small.png"/>
</td>
<td style="padding-left: 0.5em;">
<div id="projectname">FlatBuffers
</div>
<div style="font-size:12px;">
An open source project by <a href="https://developers.google.com/games/#Tools">FPL</a>.
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.7 -->
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('pages.html','');});
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<div class="title">Related Pages</div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock">Here is a list of all related documentation pages:</div><div class="directory">
<table class="directory">
<tr id="row_0_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md__building.html" target="_self">Building</a></td><td class="desc"></td></tr>
<tr id="row_1_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md__compiler.html" target="_self">Using the schema compiler</a></td><td class="desc"></td></tr>
<tr id="row_2_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md__schemas.html" target="_self">Writing a schema</a></td><td class="desc"></td></tr>
<tr id="row_3_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md__cpp_usage.html" target="_self">Use in C++</a></td><td class="desc"></td></tr>
<tr id="row_4_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md__go_usage.html" target="_self">Use in Go</a></td><td class="desc"></td></tr>
<tr id="row_5_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md__java_usage.html" target="_self">Use in Java/C-sharp</a></td><td class="desc"></td></tr>
<tr id="row_6_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md__python_usage.html" target="_self">Use in Python</a></td><td class="desc"></td></tr>
<tr id="row_7_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md__support.html" target="_self">Platform / Language / Feature support</a></td><td class="desc"></td></tr>
<tr id="row_8_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md__benchmarks.html" target="_self">Benchmarks</a></td><td class="desc"></td></tr>
<tr id="row_9_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md__white_paper.html" target="_self">FlatBuffers white paper</a></td><td class="desc"></td></tr>
<tr id="row_10_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md__internals.html" target="_self">FlatBuffer Internals</a></td><td class="desc"></td></tr>
<tr id="row_11_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md__grammar.html" target="_self">Grammar of the schema language</a></td><td class="desc"></td></tr>
</table>
</div><!-- directory -->
</div><!-- contents -->
</div><!-- doc-content -->
<!-- Google Analytics -->
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-49880327-7', 'auto');
ga('send', 'pageview');
</script>
</body>
</html>
docs/html/resize.js deleted 100644 → 0
View file @ d75d29e2
var cookie_namespace = 'doxygen';
var sidenav,navtree,content,header;
function readCookie(cookie)
{
var myCookie = cookie_namespace+"_"+cookie+"=";
if (document.cookie)
{
var index = document.cookie.indexOf(myCookie);
if (index != -1)
{
var valStart = index + myCookie.length;
var valEnd = document.cookie.indexOf(";", valStart);
if (valEnd == -1)
{
valEnd = document.cookie.length;
}
var val = document.cookie.substring(valStart, valEnd);
return val;
}
}
return 0;
}
function writeCookie(cookie, val, expiration)
{
if (val==undefined) return;
if (expiration == null)
{
var date = new Date();
date.setTime(date.getTime()+(10*365*24*60*60*1000)); // default expiration is one week
expiration = date.toGMTString();
}
document.cookie = cookie_namespace + "_" + cookie + "=" + val + "; expires=" + expiration+"; path=/";
}
function resizeWidth()
{
var windowWidth = $(window).width() + "px";
var sidenavWidth = $(sidenav).outerWidth();
content.css({marginLeft:parseInt(sidenavWidth)+"px"});
writeCookie('width',sidenavWidth, null);
}
function restoreWidth(navWidth)
{
var windowWidth = $(window).width() + "px";
content.css({marginLeft:parseInt(navWidth)+6+"px"});
sidenav.css({width:navWidth + "px"});
}
function resizeHeight()
{
var headerHeight = header.outerHeight();
var footerHeight = footer.outerHeight();
var windowHeight = $(window).height() - headerHeight - footerHeight;
content.css({height:windowHeight + "px"});
navtree.css({height:windowHeight + "px"});
sidenav.css({height:windowHeight + "px",top: headerHeight+"px"});
}
function initResizable()
{
header = $("#top");
sidenav = $("#side-nav");
content = $("#doc-content");
navtree = $("#nav-tree");
footer = $("#nav-path");
$(".side-nav-resizable").resizable({resize: function(e, ui) { resizeWidth(); } });
$(window).resize(function() { resizeHeight(); });
var width = readCookie('width');
if (width) { restoreWidth(width); } else { resizeWidth(); }
resizeHeight();
var url = location.href;
var i=url.indexOf("#");
if (i>=0) window.location.hash=url.substr(i);
var _preventDefault = function(evt) { evt.preventDefault(); };
$("#splitbar").bind("dragstart", _preventDefault).bind("selectstart", _preventDefault);
$(document).bind('touchmove',function(e){
var device = navigator.userAgent.toLowerCase();
var ios = device.match(/(iphone|ipod|ipad)/);
if (ios) {
try {
var target = e.target;
while (target) {
if ($(target).css('-webkit-overflow-scrolling')=='touch') return;
target = target.parentNode;
}
e.preventDefault();
} catch(err) {
e.preventDefault();
}
}
});
}
docs/html/style.css deleted 100644 → 0
View file @ d75d29e2
body,
#projectname,
table,
div,
p,
dl,
.title,
.tabs,
.tabs2,
.tabs3,
#nav-tree .label {
font-family: roboto, sans-serif;
}
#commonprojectlogo {
padding: 5px 0px 5px 15px;
}
#projectname {
color: #00bcd4;
font-size: 280%;
padding: 15px 0px;
font-weight: 300;
}
#titlearea {
border-bottom: 2px solid #e5e5e5;
}
.title {
color: #212121;
font: 300 34px/40px Roboto,sans-serif;
}
#nav-tree {
background-color: #fff;
}
#navrow1, #navrow2 {
border-bottom: 2px solid #e7e7e7;
}
.tabs, .tabs2, .tabs3 {
font-size: 14px;
}
.tabs,
.tabs2,
.tabs3,
.tablist li,
.tablist li.current a {
background-image: none;
}
.tablist {
list-style: none;
}
.tablist li, .tablist li p {
margin: 0;
}
.tablist li a,
.tablist li.current a {
color: #757575;
text-shadow: none;
}
.tablist li.current a {
background: #00bcd4;
color: #fff;
}
.tablist a {
background-image: none;
border-right: 2px solid #e5e5e5;
font-weight: normal;
}
.tablist a:hover,
.tablist li.current a:hover {
background-image: none;
text-decoration: underline;
text-shadow: none;
}
.tablist a:hover {
color: #00bcd4;
}
.tablist li.current a:hover {
color: #fff;
}
div.header {
background-color: #f7f7f7;
background-image: none;
border-bottom: none;
}
#MSearchBox {
border: 1px solid #ccc;
border-radius: 5px;
display: inline-block;
height: 20px;
right: 10px;
}
#MSearchBox .left,
#MSearchBox .right,
#MSearchField {
background: none;
}
a.SelectItem:hover {
background-color: #00bcd4;
}
#nav-tree {
background-image: none;
}
#nav-tree .selected {
background-image: none;
text-shadow: none;
background-color: #f7f7f7;
}
#nav-tree a {
color: #212121;
}
#nav-tree .selected a {
color: #0288d1;
}
#nav-tree .item:hover {
background-color: #f7f7f7;
}
#nav-tree .item:hover a {
color: #0288d1;
}
#nav-tree .label {
font-size: 13px;
}
#nav-sync {
display: none;
}
.ui-resizable-e {
background: #ebebeb;
border-left: 1px solid #ddd;
border-right: 1px solid #ddd;
}
.contents tr td .image {
margin-top: 24px;
}
.image {
text-align: left;
margin-bottom: 8px;
}
a:link,
a:visited,
.contents a:link,
.contents a:visited,
a.el {
color: #0288d1;
font-weight: normal;
text-decoration: none;
}
div.contents {
margin-right: 12px;
}
.directory tr, .directory tr.even {
background: #7cb342;
border-top: 1px solid #7cb342;
}
.directory td,
.directory td.entry,
.directory td.desc {
background: rgba(255,255,255,.95);
border-left: none;
color: #212121;
padding-top: 10px;
padding-bottom: 10px;
padding-left: 8px;
padding-right: 8px;
}
.directory tr#row_0_ {
border-top-color: #7cb342;
}
.directory tr#row_0_ td {
background: #7cb342;
color: #fff;
font-size: 18px;
}
.memSeparator {
border-bottom: none;
}
.memitem {
background: #7cb342;
}
.memproto, dl.reflist dt {
background: #7cb342;
background-image: none;
border: none;
box-shadow: none;
-webkit-box-shadow: none;
color: #fff;
text-shadow: none;
}
.memproto .memtemplate,
.memproto a.el,
.memproto .paramname {
color: #fff;
}
.memdoc, dl.reflist dd {
border: none;
background-color: rgba(255,255,255,.95);
background-image: none;
box-shadow: none;
-webkit-box-shadow: none;
-webkit-border-bottom-left-radius: 0;
-webkit-border-bottom-right-radius: 0;
}
.memitem, table.doxtable, table.memberdecls {
margin-bottom: 24px;
}
table.doxtable th {
background: #7cb342;
}
table.doxtable tr {
background: #7cb342;
border-top: 1px solid #7cb342;
}
table.doxtable td, table.doxtable th {
border: none;
padding: 10px 8px;
}
table.doxtable td {
background-color: rgba(255,255,255,.95);
}
.memberdecls {
background: #7cb342;
border-top: 1px solid #7cb342;
}
.memberdecls .heading h2 {
border-bottom: none;
color: #fff;
font-size: 110%;
font-weight: bold;
margin: 0 0 0 6px;
}
.memberdecls tr:not(.heading) td {
background-color: rgba(255,255,255,.95);
}
h1, h2, h2.groupheader, h3, h4, h5, h6 {
color: #212121;
}
h1 {
border-bottom: 1px solid #ebebeb;
font: 400 28px/32px Roboto,sans-serif;
letter-spacing: -.01em;
margin: 40px 0 20px;
padding-bottom: 3px;
}
h2, h2.groupheader {
border-bottom: 1px solid #ebebeb;
font: 400 23px/32px Roboto,sans-serif;
letter-spacing: -.01em;
margin: 40px 0 20px;
padding-bottom: 3px;
}
h3 {
font: 500 20px/32px Roboto,sans-serif;
margin: 32px 0 16px;
}
h4 {
font: 500 18px/32px Roboto,sans-serif;
margin: 32px 0 16px;
}
ol,
ul {
margin: 0;
padding-left: 40px;
}
ol {
list-style: decimal outside;
}
ol ol {
list-style-type: lower-alpha;
}
ol ol ol {
list-style-type: lower-roman;
}
ul {
list-style: disc outside;
}
li,
li p {
margin: 8px 0;
padding: 0;
}
div.summary
{
float: none;
font-size: 8pt;
padding-left: 5px;
width: calc(100% - 10px);
text-align: left;
display: block;
}
div.ingroups {
margin-top: 8px;
}
div.fragment {
border: 1px solid #ddd;
color: #455a64;
font: 14px/20px Roboto Mono, monospace;
padding: 8px;
}
div.line {
line-height: 1.5;
font-size: inherit;
}
code, pre {
color: #455a64;
background: #f7f7f7;
font: 400 100%/1 Roboto Mono,monospace;
padding: 1px 4px;
}
span.preprocessor, span.comment {
color: #0b8043;
}
span.keywordtype {
color: #0097a7;
}
.paramname {
color: #ef6c00;
}
.memTemplParams {
color: #ef6c00;
}
span.mlabel {
background: rgba(255,255,255,.25);
border: none;
}
blockquote {
border: 1px solid #ddd;
}
docs/html/tabs.css deleted 100644 → 0
View file @ d75d29e2
.tabs, .tabs2, .tabs3 {
background-image: url('tab_b.png');
width: 100%;
z-index: 101;
font-size: 13px;
font-family: 'Lucida Grande',Geneva,Helvetica,Arial,sans-serif;
}
.tabs2 {
font-size: 10px;
}
.tabs3 {
font-size: 9px;
}
.tablist {
margin: 0;
padding: 0;
display: table;
}
.tablist li {
float: left;
display: table-cell;
background-image: url('tab_b.png');
line-height: 36px;
list-style: none;
}
.tablist a {
display: block;
padding: 0 20px;
font-weight: bold;
background-image:url('tab_s.png');
background-repeat:no-repeat;
background-position:right;
color: #283A5D;
text-shadow: 0px 1px 1px rgba(255, 255, 255, 0.9);
text-decoration: none;
outline: none;
}
.tabs3 .tablist a {
padding: 0 10px;
}
.tablist a:hover {
background-image: url('tab_h.png');
background-repeat:repeat-x;
color: #fff;
text-shadow: 0px 1px 1px rgba(0, 0, 0, 1.0);
text-decoration: none;
}
.tablist li.current a {
background-image: url('tab_a.png');
background-repeat:repeat-x;
color: #fff;
text-shadow: 0px 1px 1px rgba(0, 0, 0, 1.0);
}
docs/source/Benchmarks.md
View file @ 69a31b80
# Benchmarks
Benchmarks {#flatbuffers_benchmarks}
==========
Comparing against other serialization solutions, running on Windows 7
64bit. We use the LITE runtime for Protocol Buffers (less code / lower
......@@ -20,17 +21,17 @@ The benchmark object is a set of about 10 objects containing an array, 4
strings, and a large variety of int/float scalar values of all sizes,
meant to be representative of game data, e.g. a scene format.
| | FlatBuffers (binary) | Protocol Buffers LITE | Rapid JSON | FlatBuffers (JSON) | pugixml | Raw structs |
|--------------------------------------------------------|-----------------------|-----------------------|-----------------------|-----------------------| ----------------------| ----------------------|
| Decode + Traverse + Dealloc (1 million times, seconds) | 0.08 | 302 | 583 | 105 | 196 | 0.02 |
| Decode / Traverse / Dealloc (breakdown) | 0 / 0.08 / 0 | 220 / 0.15 / 81 | 294 / 0.9 / 287 | 70 / 0.08 / 35 | 41 / 3.9 / 150 | 0 / 0.02 / 0 |
| Encode (1 million times, seconds) | 3.2 | 185 | 650 | 169 | 273 | 0.15 |
| Wire format size (normal / zlib, bytes) | 344 / 220 | 228 / 174 | 1475 / 322 | 1029 / 298 | 1137 / 341 | 312 / 187 |
| Memory needed to store decoded wire (bytes / blocks) | 0 / 0 | 760 / 20 | 65689 / 4 | 328 / 1 | 34194 / 3 | 0 / 0 |
| Transient memory allocated during decode (KB) | 0 | 1 | 131 | 4 | 34 | 0 |
| Generated source code size (KB) | 4 | 61 | 0 | 4 | 0 | 0 |
| Field access in handwritten traversal code | typed accessors | typed accessors | manual error checking | typed accessors | manual error checking | typed but no safety |
| Library source code (KB) | 15 | some subset of 3800 | 87 | 43 | 327 | 0 |
| | FlatBuffers (binary) | Protocol Buffers LITE | Rapid JSON | FlatBuffers (JSON) | pugixml | Raw structs |
|--------------------------------------------------------|-----------------------|-----------------------|-----------------------|------------------------| ----------------------| ----------------------|
| Decode + Traverse + Dealloc (1 million times, seconds) | 0.08 | 302 | 583 | 105 | 196 | 0.02 |
| Decode / Traverse / Dealloc (breakdown) | 0 / 0.08 / 0 | 220 / 0.15 / 81 | 294 / 0.9 / 287 | 70 / 0.08 / 35 | 41 / 3.9 / 150 | 0 / 0.02 / 0 |
| Encode (1 million times, seconds) | 3.2 | 185 | 650 | 169 | 273 | 0.15 |
| Wire format size (normal / zlib, bytes) | 344 / 220 | 228 / 174 | 1475 / 322 | 1029 / 298 | 1137 / 341 | 312 / 187 |
| Memory needed to store decoded wire (bytes / blocks) | 0 / 0 | 760 / 20 | 65689 / 4 | 328 / 1 | 34194 / 3 | 0 / 0 |
| Transient memory allocated during decode (KB) | 0 | 1 | 131 | 4 | 34 | 0 |
| Generated source code size (KB) | 4 | 61 | 0 | 4 | 0 | 0 |
| Field access in handwritten traversal code | typed accessors | typed accessors | manual error checking | typed accessors | manual error checking | typed but no safety |
| Library source code (KB) | 15 | some subset of 3800 | 87 | 43 | 327 | 0 |
### Some other serialization systems we compared against but did not benchmark (yet), in rough order of applicability:
......@@ -58,3 +59,5 @@ Code for these benchmarks sits in `benchmarks/` in git branch `benchmarks`.
It sits in its own branch because it has submodule dependencies that the main
project doesn't need, and the code standards do not meet those of the main
project. Please read `benchmarks/cpp/README.txt` before working with the code.
<br>
docs/source/Building.md
View file @ 69a31b80
# Building
Building {#flatbuffers_guide_building}
========
## Building with Visual Studio or Xcode projects
There are project files for Visual Studio and Xcode that should allow you
to build the compiler `flatc`, the samples and the tests out of the box.
## Building with CMake
Alternatively, the distribution comes with a `cmake` file that should allow
you to build project/make files for any platform. For details on `cmake`, see
<http://www.cmake.org>. In brief, depending on your platform, use one of
......@@ -18,28 +23,45 @@ Note that to use clang instead of gcc, you may need to set up your environment
variables, e.g.
`CC=/usr/bin/clang CXX=/usr/bin/clang++ cmake -G "Unix Makefiles"`.
Optionally, run the `flattests` executable to ensure everything is working
correctly on your system. If this fails, please contact us!
Optionally, run the `flattests` executable from the root `flatbuffers/`
directory to ensure everything is working correctly on your system. If this
fails, please contact us!
Note that you MUST be in the root of the FlatBuffers distribution when you
run 'flattests' (and the samples), or it will fail to load its files.
Building should also produce two sample executables, `flatsamplebinary` and
`flatsampletext`, see the corresponding `.cpp` files in the
`flatbuffers/samples` directory.
Building should also produce two sample executables, `sample_binary` and
`sample_text`, see the corresponding `.cpp` file in the samples directory.
*Note that you MUST be in the root of the FlatBuffers distribution when you
run 'flattests' or `flatsampletext`, or it will fail to load its files.*
There is an `android` directory that contains all you need to build the test
executable on android (use the included `build_apk.sh` script, or use
## Building for Android
There is a `flatbuffers/android` directory that contains all you need to build
the test executable on android (use the included `build_apk.sh` script, or use
`ndk_build` / `adb` etc. as usual). Upon running, it will output to the log
if tests succeeded or not.
There is usually no runtime to compile, as the code consists of a single
header, `include/flatbuffers/flatbuffers.h`. You should add the
You may also run an android sample from inside the `flatbuffers/samples`, by
running the `android_sample.sh` script. Optionally, you may go to the
`flatbuffers/samples/android` folder and build the sample with the
`build_apk.sh` script or `ndk_build` / `adb` etc.
## Using FlatBuffers in your own projects.
For C++, there is usually no runtime to compile, as the code consists of a
single header, `include/flatbuffers/flatbuffers.h`. You should add the
`include` folder to your include paths. If you wish to be
able to load schemas and/or parse text into binary buffers at runtime,
you additionally need the other headers in `include/flatbuffers`. You must
also compile/link `src/idl_parser.cpp` (and `src/idl_gen_text.cpp` if you
also want to be able convert binary to text).
To see how to include FlatBuffers in any of our supported languages, please
view the [Tutorial](@ref flatbuffers_guide_tutorial) and select your appropriate
language using the radio buttons.
#### For Google Play apps
For applications on Google Play that integrate this library, usage is tracked.
This tracking is done automatically using the embedded version string
(flatbuffer_version_string), and helps us continue to optimize it.
......
docs/source/CONTRIBUTING.md 0 → 120000
View file @ 69a31b80
../../CONTRIBUTING
\ No newline at end of file
docs/source/Compiler.md
View file @ 69a31b80
# Using the schema compiler
Using the schema compiler {#flatbuffers_guide_using_schema_compiler}
=========================
Usage:
......
docs/source/CppUsage.md
View file @ 69a31b80
This diff is collapsed.
docs/source/FlatBuffers.md
View file @ 69a31b80
# FlatBuffers
FlatBuffers {#flatbuffers_index}
===========
FlatBuffers is an efficient cross platform serialization library for C++, Java,
C#, Go, Python and JavaScript (C, PHP & Ruby in progress).
It was originally created at Google for game development and other
performance-critical applications.
# Overview {#flatbuffers_overview}
[FlatBuffers](@ref flatbuffers_overview) is an efficient cross platform
serialization library for C++, C#, Go, Java, JavaScript, PHP, and Python
(C and Ruby in progress). It was originally created at Google for game
development and other performance-critical applications.
It is available as Open Source on [GitHub](http://github.com/google/flatbuffers)
under the Apache license, v2 (see LICENSE.txt).
......@@ -26,7 +29,7 @@ under the Apache license, v2 (see LICENSE.txt).
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.
[benchmarks](@ref flatbuffers_benchmarks) for details.
- **Flexible** - Optional fields means not only do you get great
forwards and backwards compatibility (increasingly important for
......@@ -76,7 +79,7 @@ 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).
[white paper](@ref flatbuffers_white_paper).
### Who uses FlatBuffers?
- [Cocos2d-x](http://www.cocos2d-x.org/), the #1 open source mobile game
......@@ -118,22 +121,23 @@ sections provide a more in-depth usage guide.
## 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.
- [Support matrix](md__support.html) for platforms/languages/features.
- Some [benchmarks](md__benchmarks.html) showing the advantage of using
- How to [build the compiler](@ref flatbuffers_guide_building) and samples on
various platforms.
- How to [use the compiler](@ref flatbuffers_guide_using_schema_compiler).
- How to [write a schema](@ref flatbuffers_guide_writing_schema).
- How to [use the generated C++ code](@ref flatbuffers_guide_use_cpp) in your
own programs.
- How to [use the generated Java/C# code](@ref flatbuffers_guide_use_java_c-sharp)
in your own programs.
- How to [use the generated Go code](@ref flatbuffers_guide_use_go) in your
own programs.
- [Support matrix](@ref flatbuffers_support) for platforms/languages/features.
- Some [benchmarks](@ref flatbuffers_benchmarks) showing the advantage of
using FlatBuffers.
- A [white paper](@ref flatbuffers_white_paper) explaining the "why" of
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.
- A description of the [internals](@ref flatbuffers_internals) of FlatBuffers.
- A formal [grammar](@ref flatbuffers_grammar) of the schema language.
## Online resources
......
docs/source/GoApi.md 0 → 100644
View file @ 69a31b80
Go API
======
\addtogroup flatbuffers_go_api
<!-- Note: The `GoApi_generate.txt` code snippet was generated using `godoc` and
customized for use with this markdown file. To regenerate the file, use the
`godoc` tool (http://godoc.org) with the files in the `flatbuffers/go`
folder.
You may need to ensure that copies of the files exist in the `src/`
subfolder at the path set by the `$GOROOT` environment variable. You can
either move the files to `$GOROOT/src/flatbuffers` manually, if `$GOROOT`
is already set, otherwise you will need to manually set the `$GOROOT`
variable to a path and create `src/flatbuffers` subfolders at that path.
Then copy the flatbuffers files into `$GOROOT/src/flatbuffers`. (Some
versions of `godoc` include a `-path` flag. This could be used instead, if
available).
Once the files exist at the `$GOROOT/src/flatbuffers` location, you can
regenerate this doc using the following command:
`godoc flatbuffers > GoApi_generated.txt`.
After the documentation is generated, you will have to manually remove any
non-user facing documentation from this file. -->
\snippet GoApi_generated.txt Go API
docs/source/GoApi_generated.txt 0 → 100644
View file @ 69a31b80
This diff is collapsed.
docs/source/GoUsage.md
View file @ 69a31b80
This diff is collapsed.
docs/source/Grammar.md
View file @ 69a31b80
# Grammar of the schema language
Grammar of the schema language {#flatbuffers_grammar}
==============================
schema = include*
( namespace\_decl | type\_decl | enum\_decl | root\_decl |
......
docs/source/Internals.md
View file @ 69a31b80
# FlatBuffer Internals
FlatBuffer Internals {#flatbuffers_internals}
====================
This section is entirely optional for the use of FlatBuffers. In normal
usage, you should never need the information contained herein. If you're
......@@ -16,7 +17,7 @@ byte-swap intrinsics.
On purpose, the format leaves a lot of details about where exactly
things live in memory undefined, e.g. fields in a table can have any
order, and objects to some extend can be stored in many orders. This is
order, and objects to some extent can be stored in many orders. This is
because the format doesn't need this information to be efficient, and it
leaves room for optimization and extension (for example, fields can be
packed in a way that is most compact). Instead, the format is defined in
......@@ -228,7 +229,12 @@ Otherwise, it uses the entry as an offset into the table to locate the field.
`FlatBufferBuilder`. You can add the fields in any order, and the `Finish`
call will ensure the correct vtable gets generated.
inline flatbuffers::Offset<Monster> CreateMonster(flatbuffers::FlatBufferBuilder &_fbb, const Vec3 *pos, int16_t mana, int16_t hp, flatbuffers::Offset<flatbuffers::String> name, flatbuffers::Offset<flatbuffers::Vector<uint8_t>> inventory, int8_t color) {
inline flatbuffers::Offset<Monster> CreateMonster(flatbuffers::FlatBufferBuilder &_fbb,
const Vec3 *pos, int16_t mana,
int16_t hp,
flatbuffers::Offset<flatbuffers::String> name,
flatbuffers::Offset<flatbuffers::Vector<uint8_t>> inventory,
int8_t color) {
MonsterBuilder builder_(_fbb);
builder_.add_inventory(inventory);
builder_.add_name(name);
......@@ -285,3 +291,5 @@ Note that this not the only possible encoding, since the writer has some
flexibility in which of the children of root object to write first (though in
this case there's only one string), and what order to write the fields in.
Different orders may also cause different alignments to happen.
<br>
docs/source/JavaCsharpUsage.md 0 → 100755
View file @ 69a31b80
This diff is collapsed.
docs/source/JavaScriptUsage.md 0 → 100755
View file @ 69a31b80
This diff is collapsed.
docs/source/JavaUsage.md deleted 100755 → 0
View file @ d75d29e2
This diff is collapsed.
docs/source/PHPUsage.md 0 → 100644
View file @ 69a31b80
This diff is collapsed.
docs/source/PythonUsage.md
View file @ 69a31b80
This diff is collapsed.
docs/source/README_TO_GENERATE_DOCS.md 0 → 100644
View file @ 69a31b80
This diff is collapsed.
docs/source/Schemas.md
View file @ 69a31b80
This diff is collapsed.
docs/source/Support.md
View file @ 69a31b80
# Platform / Language / Feature support
Platform / Language / Feature support {#flatbuffers_support}
=====================================
FlatBuffers is actively being worked on, which means that certain platform /
language / feature combinations may not be available yet.
......@@ -39,3 +40,5 @@ Primary authors (github) | gwvo | gwvo | ev*/js*| rw | rw | ev
* js = jonsimantov
* mik = mikkelfj
* ch = chobie
<br>
docs/source/Tutorial.md 0 → 100644
View file @ 69a31b80
This diff is collapsed.
docs/source/WhitePaper.md
View file @ 69a31b80
# FlatBuffers white paper
FlatBuffers white paper {#flatbuffers_white_paper}
=======================
This document tries to shed some light on to the "why" of FlatBuffers, a
new serialization library.
......@@ -124,4 +125,4 @@ offered by .proto files in the following ways:
- A parser that can deal with both schemas and data definitions (JSON
compatible) uniformly.
<br>
docs/source/doxyfile
View file @ 69a31b80
This diff is collapsed.
docs/source/doxygen_layout.xml 0 → 100644
View file @ 69a31b80
This diff is collapsed.
docs/source/groups 0 → 100644
View file @ 69a31b80
This diff is collapsed.
docs/source/style.css
View file @ 69a31b80
This diff is collapsed.
include/flatbuffers/flatbuffers.h
View file @ 69a31b80
This diff is collapsed.
java/com/google/flatbuffers/Constants.java
View file @ 69a31b80
This diff is collapsed.
java/com/google/flatbuffers/Struct.java
View file @ 69a31b80
This diff is collapsed.
java/com/google/flatbuffers/Table.java
View file @ 69a31b80
This diff is collapsed.
js/flatbuffers.js
View file @ 69a31b80
This diff is collapsed.
net/FlatBuffers/FlatBufferBuilder.cs
View file @ 69a31b80
This diff is collapsed.
php/FlatbufferBuilder.php
View file @ 69a31b80
This diff is collapsed.
python/flatbuffers/builder.py
View file @ 69a31b80
This diff is collapsed.
readme.md
View file @ 69a31b80
This diff is collapsed.
samples/SampleBinary.cs 0 → 100644
View file @ 69a31b80
This diff is collapsed.
samples/SampleBinary.java 0 → 100644
View file @ 69a31b80
This diff is collapsed.
samples/SampleBinary.php 0 → 100644
View file @ 69a31b80
This diff is collapsed.
samples/android/AndroidManifest.xml 0 → 100755
View file @ 69a31b80
This diff is collapsed.
samples/android/build_apk.sh 0 → 100755
View file @ 69a31b80
This diff is collapsed.
samples/android/jni/Android.mk
View file @ 69a31b80
This diff is collapsed.
samples/android/jni/main.cpp
View file @ 69a31b80
This diff is collapsed.
samples/android/res/values/strings.xml 0 → 100755
View file @ 69a31b80
This diff is collapsed.
samples/android_sample.sh 0 → 100755
View file @ 69a31b80
This diff is collapsed.
samples/csharp_sample.sh 0 → 100755
View file @ 69a31b80
This diff is collapsed.
samples/go_sample.sh 0 → 100755
View file @ 69a31b80
This diff is collapsed.
samples/java_sample.sh 0 → 100755
View file @ 69a31b80
This diff is collapsed.
samples/javascript_sample.sh 0 → 100755
View file @ 69a31b80
This diff is collapsed.
samples/monster.fbs
View file @ 69a31b80
This diff is collapsed.
samples/monster_generated.h deleted 100644 → 0
View file @ d75d29e2
This diff is collapsed.
samples/monsterdata.json
View file @ 69a31b80
This diff is collapsed.
samples/php_sample.sh 0 → 100755
View file @ 69a31b80
This diff is collapsed.
samples/python_sample.sh 0 → 100755
View file @ 69a31b80
This diff is collapsed.
samples/sample_binary.cpp
View file @ 69a31b80
This diff is collapsed.
samples/sample_binary.go 0 → 100644
View file @ 69a31b80
This diff is collapsed.
samples/sample_binary.py 0 → 100644
View file @ 69a31b80
This diff is collapsed.
samples/sample_text.cpp
View file @ 69a31b80
This diff is collapsed.
samples/samplebinary.js 0 → 100644
View file @ 69a31b80
This diff is collapsed.
tests/FlatBuffers.Test/Resources/monsterdata_test.mon 0 → 100644
View file @ 69a31b80
This diff is collapsed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment