/*
 This Source Code Form is subject to the terms of the Mozilla Public
 License, v. 2.0. If a copy of the MPL was not distributed with this
 file, You can obtain one at http://mozilla.org/MPL/2.0/.
*/


/*!
  \page vitelotte_user_manual_mvg_file_format_page The MVG File Format

  \section vitelotte_user_manual_mvg_file_format_intro_sec Introduction

  In order to save VGMesh to disk we provide a file format called MVG (for Mesh-based Vector Graphics). MVGs are simple text files with a syntax inspired from the OBJ file format. It supports meshes of arbitrary dimensions, any combination of attributes and nodes (including unknown and invalid nodes). This format is also easily extensible.

  The MVG file format is designed to be easy to use, human-readable and hackable.

  Several sample MVGs are available in `examples/Vitelotte/samples`.


  \section vitelotte_user_manual_mvg_file_format_description_sec Description

  MVG files start with a header followed by a body. The body contains the block of vertex declarations, followed by the block of nodes declarations and then the block of faces declaration, in this order. Vertices and nodes are referenced by index in the order of their apparition in the file.

  \warning Note that unlike obj files, the first elements have the index 0.

  Blank lines and lines starting with # are ignored, but can not be placed on the first line. It is not possible to place a comment on the same line than a declaration.

  Each line is in the form a declaration and starts with a keyword describing the kind of object declared, like 'v' for vertices of 'f' for faces. Lines starting with an unknown keyword are ignored by the parser. This allow to extend mvg files while keeping them readable by unaware applications.


  \subsection vitelotte_user_manual_mvg_file_format_description_header_subsec Header

  A MVG file starts with a header. The first line _must_ be

  \code
  mvg 1.0
  \endcode

  The following lines declare respectively the number of dimensions, the number of value coefficients and the active attributes of the mesh:

  \code
  dimensions 2
  coefficients 4
  attributes none
  \endcode

  The parameter of `attributes` can be:

  - `none`: no attributes are enabled.
  - `linear`: equivalent to VGMesh::LINEAR_FLAGS.
  - `quadratic`: equivalent to VGMesh::QUADRATIC_FLAGS.
  - `morley`: equivalent to VGMesh::MORLEY_FLAGS.
  - `fv`: equivalent to VGMesh::FV_FLAGS.
  - an integer: any combination of flags, directly represented as a number. Human-readable forms should be preferred when possible.

  Finally, you can declare the number of vertices, nodes and faces. These declarations are optional and only serve as hint for the parser to reserve memory (in other words they do not need to be accurate, which helps manual edition of files):

  \code
  vertices 1747
  nodes 0
  faces 3475
  \endcode


  \subsection vitelotte_user_manual_mvg_file_format_description_body_subsec Body

  Vertex declarations are straightforward:
  \code
  v COORDINATES
  \endcode
  where \c COORDINATES are the coordinates of the vertex, separated by spaces or tabs. The number of coordinates must match the number of dimensions declared in the header.

  Node declarations are similar to vertex:
  \code
  n COEFFICIENTS
  \endcode
  where \c COEFFICIENTS are the coefficients, separated by spaces or tabs. The number of coordinates must match the number of coefficients declared in the header. Unknown nodes are declared like this:
  \code
  n void
  \endcode

  Faces declarations are more involved as they contain connectivity to both vertices and nodes. With no attributes enabled, they are simply:
  \code
  f VERTEX_INDICES
  \endcode
  where VERTEX_INDICES is the list of the face vertices indices (or 'x' for invalid nodes), ordered counter-clockwise. If the attirbute TO_VERTEX_VALUE is enabled, the declaration become
  \code
  f V0/NV0 V1/NV1 V2/NV2 ...
  \endcode
  where Vi is the index of the ith vertex of the face and NVi is the index of the to-vertex node attached to Vi. If FROM_VERTEX_VALUE is enabled too (to allow singularities), vertex declaration become
  \code
  Vi/NVi_in/NVi_out
  \endcode
  Where NVi_in is the node attached to the ingoing halfedge of Vi and NVi_out the node attached to the outgoing halfedge. As most of the meshes only contains a few singular vertices, it is a waste of space to systematically duplicate nodes and it makes the file harder to tweak. So there is a special rule that permits to omit the second node if it is the same as the first, leading to declarations such as
  \code
  f V0/NV0 V1/NV1_in/NV1_out V2/NV2
  \endcode
  where only V1 is singular.

  Edge attributes (EDGE_VALUE and EDGE_GRADIENT), if enabled, are placed after vertices declaration, speared by the '-' token:
  \code
  f VERTICES - EDGES
  \endcode
  VERTICES are the vertex declaration as above and EDGES should be as many edge declarations as there is vertex. The first edge declaration correspond to the edge V0-V1, the second to V1-V2 and so on. Edge declarations take the form `N0/N1/...` where Ni are node indices. If there is only one edge attribute enabled, an edge declaration is simply a single node index. If both are enabled, EDGE_VALUE is the first index and EDGE_GRADIENT the second. If none is enabled, the whole edge declaration is discarded, '-' included.

  While not used yet in Vitelotte, you may wish to add faces declaration (for example if you have elements with internal nodes that are not attached to vertices or edges). They should be added after edges node, separated by the '-' token.

  In the end, a complete triangular face declaration with fv attributes and a singular vertex look like this:
  \code
  f V0/NV0 V1/NV1_in/NV1_out V2/NV2 - NEv0/NEg0 NEv1/NEg1 NEv2/NEg2
  \endcode


  \section vitelotte_user_manual_mvg_file_format_reading_writing_sec Reading and Writing MVG

  Reading a MVG can be done with the class MVGReader declared in the header `vitelotte_io.h`. In one line:
  \code{.cpp}
  MVGReader<Mesh>().read(inStream, mesh);
  \endcode
  where `inStream` is an input iosteam.

  The MVGReader object has two purpose. First, it encapsulate all temporary data required to read a MVG. You can read several MVG with a single reader in order to allocate all these objects only once. The second use is error reporting. When an error or a warning is encountered, MVGReader calls a callback. By default, it just print the message on stderr, but you may wish to customize it. You can change the callbacks with OBJReader::setErrorCallback (MVGReader inherits OBJReader).

  Writing MVGs is very similar to reading:
  \code{.cpp}
  MVGWriter<Mesh>().write(outStream, mesh);
  \endcode
  MVGWriter constructor takes the version of the MVG to produce as an optional parameter which default to the latest version (anyway, 1.0 is the only version existing right now).


 */
