com.io7m.smfj 0.11.0 Specification
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Contents
  ─────────────────────────────────────────────────────────────────────────────
  1 Notational Conventions ........................................ conventions
    1.1 Overview ......................................... conventions.overview
    1.2 Unicode ........................................... conventions.unicode
    1.3 EBNF ................................................. conventions.ebnf
    1.4 Haskell ........................................... conventions.haskell
    1.5 JPRA ................................................. conventions.jpra
    1.6 Requirement Levels ................................... conventions.reqs
  2 Model ..................................................... smf_model.model
    2.1 Overview ........................................... smf_model.overview
    2.2 Versioning ....................................... smf_model.versioning
    2.3 Mesh ................................................... smf_model.mesh
    2.4 Attributes ........................................ smf_model.attribute
    2.5 Vertices ............................................. smf_model.vertex
    2.6 Triangles .......................................... smf_model.triangle
    2.7 Coordinate System .................................... smf_model.coords
    2.8 Schema ID ......................................... smf_model.schema_id
    2.9 Metadata ........................................... smf_model.metadata
  3 SMF/B - Binary Encoding .............................................. smfb
    3.1 Overview ................................................ smfb.overview
    3.2 Header .................................................... smfb.header
    3.3 Sections ................................................ smfb.sections
    3.4 Section - end ....................................... smfb.sections.end
    3.5 Section - smf ....................................... smfb.sections.smf
    3.6 Section - triangles ........................... smfb.sections.triangles
    3.7 Section - vertices-noninterleaved smfb.sections.vertices-noninterleaved
    3.8 Section - metadata ............................. smfb.sections.metadata
    3.9 Example .................................................. smfb.example
  4 SMF/T - Text Encoding ................................................ smft
    4.1 Overview ................................................ smft.overview
    4.2 Sections ................................................ smft.sections
    4.3 Section - smf ....................................... smft.sections.smf
    4.4 Section - triangles ........................... smft.sections.triangles
    4.5 Section - vertices-noninterleaved smft.sections.vertices-noninterleaved
    4.6 Section - metadata ............................. smft.sections.metadata
    4.7 Example .................................................. smft.example
  5 Specification History ............................................. history
    5.1 History ............................................... history.history


1 Notational Conventions [id: conventions]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Contents
  ─────────────────────────────────────────────────────────────────────────────
  1.1 Overview ........................................... conventions.overview
  1.2 Unicode ............................................. conventions.unicode
  1.3 EBNF ................................................... conventions.ebnf
  1.4 Haskell ............................................. conventions.haskell
  1.5 JPRA ................................................... conventions.jpra
  1.6 Requirement Levels ..................................... conventions.reqs


1.1 Overview [id: conventions.overview]

1     This section of the specification documents all notational conventions
      used throughout.

1.2 Unicode [id: conventions.unicode]

1     The specification makes reference to the Unicode character set which, at
      the time of writing, is at version 9.0. The specification often
      references specific Unicode characters, and does so using the standard
      notation U+NNNN, where N represents a hexadecimal digit. For example,
      U+03BB corresponds to the lowercase lambda symbol λ.

1.3 EBNF [id: conventions.ebnf]

1     The specification gives grammar definitions in ISO/IEC 14977:1996
      Extended Backus-Naur form.

1.4 Haskell [id: conventions.haskell]

1     Rather than rely on untyped and ambiguous mathematical notation, this
      documentation expresses all mathematics and type definitions in strict
      Haskell 2010 [url: http://www.haskell.org/onlinereport/haskell2010/] with
      no extensions. All Haskell sources are included along with the
      documentation and can therefore be executed from the command line GHCi
      [url: http://www.haskell.org/haskellwiki/GHC/GHCi] tool in order to
      interactively check results and experiment with functions.

2     When used within prose, functions are referred to using fully qualified
      notation, such as (Vector3f.cross n t). This is the application of the
      cross function defined in the Vector3f module, to the arguments n and t.

1.5 JPRA [id: conventions.jpra]

1     Definitions of binary structures are given as jpra [url:
      http://io7m.github.io/jpra/] language definitions. All values are
      considered to be in big-endian byte order unless otherwise specified.

1.6 Requirement Levels [id: conventions.reqs]

1     This specification uses terms such as MUST, MUST NOT, SHOULD, SHOULD NOT,
      etc, according to the definitions given in RFC 2119 [url:
      http://www.ietf.org/rfc/rfc2119.txt].

2 Model [id: smf_model.model]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Contents
  ─────────────────────────────────────────────────────────────────────────────
  2.1 Overview ............................................. smf_model.overview
  2.2 Versioning ......................................... smf_model.versioning
    2.2.1 Overview ............................................................
    2.2.2 Forward Compatibility ...................... smf_model.versioning.fwd
    2.2.3 Backward Compatibility ..................... smf_model.versioning.bwd
    2.2.4 Compatibility .............................. smf_model.versioning.cmp
  2.3 Mesh ..................................................... smf_model.mesh
  2.4 Attributes .......................................... smf_model.attribute
  2.5 Vertices ............................................... smf_model.vertex
  2.6 Triangles ............................................ smf_model.triangle
  2.7 Coordinate System ...................................... smf_model.coords
  2.8 Schema ID ........................................... smf_model.schema_id
  2.9 Metadata ............................................. smf_model.metadata


2.1 Overview [id: smf_model.overview]

1     The SMF model is a minimalist, portable storage model for triangle mesh
      data. SMF files are intended to be consumed by 3D rendering engines
      directly and therefore do not contain any complex interchange features
      common to formats such as COLLADA [0]. The text [ref: smft] and binary
      [ref: smfb] encodings of the model are designed to be trivial to parse
      and to permit the easy construction of extremely fast event-based parsers
      that do not require loading the entire file into memory for processing.

2     The format is versioned [ref: smf_model.versioning], and is specified in
      a manner that allows for implementations to provide strong guarantees of
      forwards and backwards compatibility as the specification evolves.

3     The version of the SMF model described by this specification is (1, 0).
      See versioning [ref: smf_model.versioning] for details.

2.2 Versioning [id: smf_model.versioning]

2.2.1 Overview

1     The SMF specification is versioned via a restricted subset of the
      Semantic Versioning [url: http://semver.org/] specification. The SMF
      specification has a major and minor version number, with major version
      increments denoting incompatible changes, and minor version increments
      denoting new functionality. There is no patch version number. A version
      of the specification with major version m and minor version n is denoted
      as specification version (m, n).

2.2.2 Forward Compatibility [id: smf_model.versioning.fwd]

1     Assuming a version of the SMF specification m, an update to the
      specification that yields version n such that n > m is considered to be
      forwards compatible if a parser that supports format version m can read
      files that were written using format version n.

2.2.3 Backward Compatibility [id: smf_model.versioning.bwd]

1     Assuming a version of the SMF specification m, an update to the
      specification that yields version n such that n > m is considered to be
      backwards compatible if a parser that supports format version n can read
      files that were written using format version m.

2.2.4 Compatibility [id: smf_model.versioning.cmp]

1     The SMF specification is designed such that a correctly-written parser
      implementation that supports a major version m is able to support the set
      of versions ∀n. (m, n). This implies full forwards and backwards
      compatibility for parsers when the major version is unchanged.

2     Changes that would cause a parser supporting an older version of the
      specification to fail to read a file written according to a newer version
      of the specification MUST imply an increment in the major version of the
      specification.

3     Changes that would cause a parser supporting a newer version of the
      specification to fail to read a file written according to an older
      version of the specification MUST imply an increment in the major version
      of the specification.

4     An implication of the above rules is that new features added to the
      specification must be added in a manner that allows them to be ignored by
      older parsers, lest the major version of the specification be incremented
      on every update.

2.3 Mesh [id: smf_model.mesh]

1     A mesh in the SMF model is a set of triangles [ref: smf_model.triangle].

2.4 Attributes [id: smf_model.attribute]

1     An attribute in the SMF model is a uniquely-named array of elements of a
      given type. All attributes within a particular SMF file have the same
      number of elements. The type of an attribute is a 3-tuple (c, n, s),
      where c is a component type, n is a component count, and s is a component
      size expressed in bits.

2     This version of the specification defines three basic component types:
      signed integers, unsigned integers, and floating point numbers. Floating
      point numbers are IEEE 754 [url: https://en.wikipedia.org/wiki/IEEE_754]
      floating point values.

      2.4.4.3 Attribute Type
      ──────────────────────

      module Attribute where

      data ComponentType =
          IntegerSigned
        | IntegerUnsigned
        | FloatingPoint

      data AttributeType = AttributeType {
        attribute_component_type  :: ComponentType,
        attribute_component_count :: Word32,
        attribute_component_size  :: Word32
      }

      data Attribute = Attribute {
        attribute_name :: String,
        attribute_type :: AttributeType
      }



4     Implementations are required to support attributes of at least the
      following types:

      2.4.4.5 Types
      ─────────────

      ┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┬───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┬─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
      │ Component Type                                                                                                                                       │ Component Count                                                                                                                                       │ Component size (bits)                                                                                                                                       │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ Signed integer                                                                                                                                       │ 1                                                                                                                                                     │ 8                                                                                                                                                           │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ Signed integer                                                                                                                                       │ 2                                                                                                                                                     │ 8                                                                                                                                                           │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ Signed integer                                                                                                                                       │ 3                                                                                                                                                     │ 8                                                                                                                                                           │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ Signed integer                                                                                                                                       │ 4                                                                                                                                                     │ 8                                                                                                                                                           │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ Signed integer                                                                                                                                       │ 1                                                                                                                                                     │ 16                                                                                                                                                          │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ Signed integer                                                                                                                                       │ 2                                                                                                                                                     │ 16                                                                                                                                                          │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ Signed integer                                                                                                                                       │ 3                                                                                                                                                     │ 16                                                                                                                                                          │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ Signed integer                                                                                                                                       │ 4                                                                                                                                                     │ 16                                                                                                                                                          │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ Signed integer                                                                                                                                       │ 1                                                                                                                                                     │ 32                                                                                                                                                          │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ Signed integer                                                                                                                                       │ 2                                                                                                                                                     │ 32                                                                                                                                                          │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ Signed integer                                                                                                                                       │ 3                                                                                                                                                     │ 32                                                                                                                                                          │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ Signed integer                                                                                                                                       │ 4                                                                                                                                                     │ 32                                                                                                                                                          │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ Signed integer                                                                                                                                       │ 1                                                                                                                                                     │ 64                                                                                                                                                          │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ Signed integer                                                                                                                                       │ 2                                                                                                                                                     │ 64                                                                                                                                                          │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ Signed integer                                                                                                                                       │ 3                                                                                                                                                     │ 64                                                                                                                                                          │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ Signed integer                                                                                                                                       │ 4                                                                                                                                                     │ 64                                                                                                                                                          │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ Unsigned integer                                                                                                                                     │ 1                                                                                                                                                     │ 8                                                                                                                                                           │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ Unsigned integer                                                                                                                                     │ 2                                                                                                                                                     │ 8                                                                                                                                                           │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ Unsigned integer                                                                                                                                     │ 3                                                                                                                                                     │ 8                                                                                                                                                           │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ Unsigned integer                                                                                                                                     │ 4                                                                                                                                                     │ 8                                                                                                                                                           │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ Unsigned integer                                                                                                                                     │ 1                                                                                                                                                     │ 16                                                                                                                                                          │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ Unsigned integer                                                                                                                                     │ 2                                                                                                                                                     │ 16                                                                                                                                                          │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ Unsigned integer                                                                                                                                     │ 3                                                                                                                                                     │ 16                                                                                                                                                          │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ Unsigned integer                                                                                                                                     │ 4                                                                                                                                                     │ 16                                                                                                                                                          │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ Unsigned integer                                                                                                                                     │ 1                                                                                                                                                     │ 32                                                                                                                                                          │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ Unsigned integer                                                                                                                                     │ 2                                                                                                                                                     │ 32                                                                                                                                                          │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ Unsigned integer                                                                                                                                     │ 3                                                                                                                                                     │ 32                                                                                                                                                          │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ Unsigned integer                                                                                                                                     │ 4                                                                                                                                                     │ 32                                                                                                                                                          │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ Unsigned integer                                                                                                                                     │ 1                                                                                                                                                     │ 64                                                                                                                                                          │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ Unsigned integer                                                                                                                                     │ 2                                                                                                                                                     │ 64                                                                                                                                                          │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ Unsigned integer                                                                                                                                     │ 3                                                                                                                                                     │ 64                                                                                                                                                          │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ Unsigned integer                                                                                                                                     │ 4                                                                                                                                                     │ 64                                                                                                                                                          │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ IEEE754 floating point                                                                                                                               │ 1                                                                                                                                                     │ 16                                                                                                                                                          │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ IEEE754 floating point                                                                                                                               │ 2                                                                                                                                                     │ 16                                                                                                                                                          │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ IEEE754 floating point                                                                                                                               │ 3                                                                                                                                                     │ 16                                                                                                                                                          │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ IEEE754 floating point                                                                                                                               │ 4                                                                                                                                                     │ 16                                                                                                                                                          │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ IEEE754 floating point                                                                                                                               │ 1                                                                                                                                                     │ 32                                                                                                                                                          │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ IEEE754 floating point                                                                                                                               │ 2                                                                                                                                                     │ 32                                                                                                                                                          │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ IEEE754 floating point                                                                                                                               │ 3                                                                                                                                                     │ 32                                                                                                                                                          │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ IEEE754 floating point                                                                                                                               │ 4                                                                                                                                                     │ 32                                                                                                                                                          │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ IEEE754 floating point                                                                                                                               │ 1                                                                                                                                                     │ 64                                                                                                                                                          │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ IEEE754 floating point                                                                                                                               │ 2                                                                                                                                                     │ 64                                                                                                                                                          │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ IEEE754 floating point                                                                                                                               │ 3                                                                                                                                                     │ 64                                                                                                                                                          │
      ├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
      │ IEEE754 floating point                                                                                                                               │ 4                                                                                                                                                     │ 64                                                                                                                                                          │
      └──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┴─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘












































2.5 Vertices [id: smf_model.vertex]

1     A vertex is an abstract object consisting of exactly one element taken
      from each of the defined attributes [ref: smf_model.attribute]. A vertex
      can essentially be considered to be an array index; The vertex at index n
      can be considered to be the aggregation of the nth elements of all of the
      defined attributes. Vertices are numbered starting at 0.

2.6 Triangles [id: smf_model.triangle]

1     A triangle is a 3-tuple of vertices [ref: smf_model.vertex]. In the SMF
      model, a triangle references vertices by their numeric index.

2.7 Coordinate System [id: smf_model.coords]

1     A coordinate system in the SMF model is a set of three axis names and a
      triangle winding order. The axis names specify which Cartesian coordinate
      system axes correspond to the right, up, and forward directions. The
      winding order specifies whether vertices for triangles are given in
      clockwise or counter-clockwise order. A coordinate system is only valid
      if the three chosen axes have different axis names. The axisName function
      relates an axis to an axis name. The axisValid function gives a formal
      definition of the validity of sets of axes.

      2.7.4.2 Axis
      ────────────

      module Axis where

      data Axis
        = PositiveX
        | PositiveY
        | PositiveZ
        | NegativeX
        | NegativeY
        | NegativeZ

      data AxisName
        = AxisX
        | AxisY
        | AxisZ

      axisName :: Axis -> AxisName
      axisName PositiveX = AxisX
      axisName NegativeX = AxisX
      axisName PositiveY = AxisY
      axisName NegativeY = AxisY
      axisName PositiveZ = AxisZ
      axisName NegativeZ = AxisZ

      data AxisSystem = AxisSystem {
        axis_right   :: Axis,
        axis_up      :: Axis,
        axis_forward :: Axis
      }

      axisValid :: (Axis, Axis, Axis) -> Bool
      axisValid (right, up, forward) =
        case (axisName right, axisName up, axisName forward) of
          (AxisX, AxisY, AxisZ) -> True
          (AxisZ, AxisX, AxisY) -> True
          (AxisY, AxisZ, AxisX) -> True
          _                     -> False

      data WindingOrder
        = WindingOrderClockwise
        | WindingOrderCounterClockwise

      data CoordinateSystem = CoordinateSystem {
        coords_axes  :: AxisSystem,
        coords_order :: WindingOrder
      }


2.8 Schema ID [id: smf_model.schema_id]

1     A schema identifier is an optional identifier that can be inserted into
      SMF files. Because the SMF model does not predefine any particular
      attributes [ref: smf_model.attribute], tools that consume SMF files
      cannot know ahead of time if the file they have just loaded will actually
      contain the attributes that they are expecting. A schema identifier
      effectively provides a concrete name for a set of attributes so that
      tools that process SMF files can perform validation of attributes based
      on the identifier. It is somewhat analogous to XML namespace [1]
      declarations; The author of a particular document inserts an XML
      namespace identifier into their document, and validation tools use this
      identifier to locate schema definitions against which the document is
      then validated.

2     A schema identifier consists of a string and two integer values:

      2.8.4.3 Schema Identifier
      ─────────────────────────

      data SchemaIdentifier = SchemaIdentifier {
        schema_id            :: String,
        schema_version_major :: Word32,
        schema_version_minor :: Word32
      }



4     The schema_id uniquely identifies the schema, and the
      schema_version_major and schema_version_minor values identify the version
      of the schema.

5     Schema names may be at most 64 characters in length and must conform to
      the following syntax:

      2.8.4.6 Schema Name Syntax
      ──────────────────────────

      schema_segment =
        ? [\p{IsAlphabetic}][\p{IsAlphabetic}\p{IsDigit}_]* ? ;

      schema_name =
        schema_segment , { "." , schema_segment } ;



2.9 Metadata [id: smf_model.metadata]

1     The SMF model supports the inclusion of arbitrary metadata. A metadata
      value is an opaque data value with a schema identifier specified in the
      same manner as the schema identifier [ref: smf_model.schema_id].
      Applications may use the metadata facilities to associate small amounts
      of extra information with mesh data. Typical uses include checksums,
      copyright information, and generating software package version
      information.

3 SMF/B - Binary Encoding [id: smfb]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Contents
  ─────────────────────────────────────────────────────────────────────────────
  3.1 Overview .................................................. smfb.overview
  3.2 Header ...................................................... smfb.header
  3.3 Sections .................................................. smfb.sections
    3.3.1 Definition ........................................ smfb.sections.def
    3.3.2 Alignment ................................... smfb.sections.alignment
    3.3.3 Available Sections .......................... smfb.sections.available
    3.3.4 Enumerating Sections ...................... smfb.sections.enumerating
  3.4 Section - end ......................................... smfb.sections.end
    3.4.1 Definition .................................... smfb.sections.end.def
    3.4.2 Cardinality/Ordering .................. smfb.sections.end.cardinality
    3.4.3 Magic Number ................................ smfb.sections.end.magic
    3.4.4 Data ......................................... smfb.sections.end.data
  3.5 Section - smf ......................................... smfb.sections.smf
    3.5.1 Definition .................................... smfb.sections.smf.def
    3.5.2 Cardinality/Ordering .................. smfb.sections.smf.cardinality
    3.5.3 Magic Number ................................ smfb.sections.smf.magic
    3.5.4 Data ......................................... smfb.sections.smf.data
  3.6 Section - triangles ............................. smfb.sections.triangles
    3.6.1 Definition .............................. smfb.sections.triangles.def
    3.6.2 Cardinality/Ordering ............ smfb.sections.triangles.cardinality
    3.6.3 Magic Number .......................... smfb.sections.triangles.magic
    3.6.4 Data ................................... smfb.sections.triangles.data
  3.7 Section - vertices-noninterleaved . smfb.sections.vertices-noninterleaved
    3.7.1 Definition ................ smfb.sections.vertices-noninterleaved.def
    3.7.2 Cardinality/Ordering smfb.sections.vertices-noninterleaved.cardinality
    3.7.3 Magic Number ............ smfb.sections.vertices-noninterleaved.magic
    3.7.4 Data ..................... smfb.sections.vertices-noninterleaved.data
  3.8 Section - metadata ............................... smfb.sections.metadata
    3.8.1 Definition ............................... smfb.sections.metadata.def
    3.8.2 Cardinality/Ordering ............. smfb.sections.metadata.cardinality
    3.8.3 Magic Number ........................... smfb.sections.metadata.magic
    3.8.4 Data .................................... smfb.sections.metadata.data
  3.9 Example .................................................... smfb.example


3.1 Overview [id: smfb.overview]

1     The SMF/B format is a binary encoding for the SMF model [ref:
      smf_model.model].

2     An SMF/B file begins with a simple fixed-size header [ref: smfb.header]
      followed by a series of sections [ref: smfb.sections] containing data and
      metadata.

3     All data in an SMF/B file is written in big-endian byte order.

3.2 Header [id: smfb.header]

1     An SMF/B file begins with the following fixed-size structure:

      3.2.2 SMF/B Header
      ──────────────────

      [record SMFBHeaderStart
        ([field magic           [integer unsigned 64]]
         [field version_major   [integer unsigned 32]]
         [field version_minor   [integer unsigned 32]])]



3     The value of the magic field MUST be 0x89534D460D0A1A0A. Implementations
      MUST immediately reject any files that do not begin with this magic
      number. The derivation of this constant is taken almost verbatim from the
      PNG [2] file format with the characters PNG changed to SMF.

4     The version_major field specifies the major [ref: smf_model.versioning]
      version number of the specification to which the data in the file is
      expected to conform. The version_minor field specifies the minor [ref:
      smf_model.versioning] version number of the specification to which the
      data in the file is expected to conform.

3.3 Sections [id: smfb.sections]

3.3.1 Definition [id: smfb.sections.def]

1     Directly following the header [ref: smfb.header], an SMF/B file consists
      of a series of sections. A section begins with the following fixed-size
      structure:

      3.3.1.2 Section header
      ──────────────────────

      [record SMFBSection
        ([field id   [integer unsigned 64]]
         [field size [integer unsigned 64]])]



3     The id field of the section header identifies the type of the section.
      The size field of the section header specifies the data size; the size in
      octets of the data that follows the section header. The data size
      necessarily includes any trailing padding octets that may be inserted in
      order to guarantee that the start of the next section (if any) is
      correctly aligned [ref: smfb.sections.alignment]. This implies that the
      data size of any given section MUST be a multiple of the alignment [ref:
      smfb.sections.alignment] size.

4     Implementations MUST ignore any content inside a section of an
      unrecognized type [3]. As sections explicitly state the size of their own
      data, implementations can simply seek forwards in the file by the
      specified data size to reach the next section.

5     The first section in an SMF/B file MUST be an smf [ref:
      smfb.sections.smf] section. The last section in an SMF/B file MUST be an
      end [ref: smfb.sections.end] section.

3.3.2 Alignment [id: smfb.sections.alignment]

1     Sections MUST be aligned to 16 octet boundaries. As the section header
      [ref: smfb.header] is defined to be exactly 16 octets, this implies that
      the data within a section will also be aligned to a 16 octet boundary
      [4]. Implementations MUST reject SMF/B files containing one or more
      incorrectly aligned sections.

3.3.3 Available Sections [id: smfb.sections.available]

1     This version of the specification defines the following sections:

      3.3.3.2 Sections
      ────────────────

      • end [ref: smfb.sections.end]
      • metadata [ref: smfb.sections.metadata]
      • smf [ref: smfb.sections.smf]
      • triangles [ref: smfb.sections.triangles]
      • vertices-noninterleaved [ref: smfb.sections.vertices-noninterleaved]



3.3.4 Enumerating Sections [id: smfb.sections.enumerating]

1     Note: This subsection is informative.

2     The design of sections allows for implementations to quickly enumerate
      all sections within a file using the following strategy:

      3.3.4.3 Enumerating Sections
      ────────────────────────────

      void showSections()
      {
        // Read SMF header
        long smf = readUnsigned64();
        int major = readUnsigned32();
        int minor = readUnsigned32();

        // Read all sections
        while (bytesRemaining()) {
          long offset = currentOffset();
          long magic = readUnsigned64();
          long size = readUnsigned64();

          System.out.printf(
          "section: %s %s %s\n",
          Long.toUnsignedString(offset),
          Long.toUnsignedString(magic, 16),
          Long.toUnsignedString(size));

          seek(size);
        }
      }


4     The bytesAvailable method is assumed to return true if there are any
      bytes remaining in the file. The currentOffset method is assumed to
      return the current read position in octets within the file. The
      readUnsigned64 method is assumed to read a 64-bit big-endian integer from
      the current file, advancing the current read position by 8 octets. The
      readUnsigned32 method is assumed to read a 32-bit big-endian integer from
      the current file, advancing the current read position by 4 octets.

3.4 Section - end [id: smfb.sections.end]

3.4.1 Definition [id: smfb.sections.end.def]

1     The end section indicates the end of an SMF/B file.

3.4.2 Cardinality/Ordering [id: smfb.sections.end.cardinality]

1     An end section must appear exactly once in an SMF/B file.

2     The end section MUST be the last section in an SMF/B file.
      Implementations MUST reject SMF/B files that do not contain a terminating
      end section.

3.4.3 Magic Number [id: smfb.sections.end.magic]

1     The end section is identified by the magic number 0x534D465F454E4421.

3.4.4 Data [id: smfb.sections.end.data]

1     The end section contains no data. The specified data size [ref:
      smfb.sections.def.size] for the section MUST be 0.

3.5 Section - smf [id: smfb.sections.smf]

3.5.1 Definition [id: smfb.sections.smf.def]

1     The smf section specifies information common to all sections in an SMF/B
      file.

3.5.2 Cardinality/Ordering [id: smfb.sections.smf.cardinality]

1     An smf section MUST appear exactly once in an SMF/B file.

2     The smf section MUST be the first section in an SMF/B file.
      Implementations MUST reject SMF/B files that do not start with an smf
      section.

3.5.3 Magic Number [id: smfb.sections.smf.magic]

1     The smf section is identified by the magic number 0x534D465F48454144.

3.5.4 Data [id: smfb.sections.smf.data]

1     The smf section begins with the following structure:

      3.5.4.2 SMF Header
      ──────────────────

      [record SMFBv1_0Header
        ([field schema                   SMFBv1SchemaID]
         [field vertex_count             [integer unsigned 64]]
         [field triangle_count           [integer unsigned 64]]
         [field triangle_index_size_bits [integer unsigned 32]]
         [field attribute_count          [integer unsigned 32]]
         [field attribute_offset         [integer unsigned 32]]
         [field coordinate_system        SMFBv1CoordinateSystems]
         [padding-octets                 2])]



3     The schema field specifies the schema identifier [ref:
      smf_model.schema_id] for the model:

      3.5.4.4 Schema Identifier
      ─────────────────────────

      [record SMFBv1SchemaID
        ([field schema_id            [string 64 "UTF-8"]]
         [field schema_version_major [integer unsigned 32]]
         [field schema_version_minor [integer unsigned 32]]
         [padding-octets             4])]



5     If the length of the schema_id field is 0, the schema identifier as a
      whole is ignored.

6     The vertex_count field specifies the number of vertices that will be
      specified in a vertices-noninterleaved [ref:
      smfb.sections.vertices-noninterleaved] section.

7     The triangle_count field specifies the number of triangles that will be
      specified in a triangles [ref: smfb.sections.triangles] section. The
      triangle_size field specifies the size in bits of the individual vertex
      indices within each triangle.

8     The attribute_count field specifies the number of attributes [ref:
      smf_model.attribute] that will be declared. The attribute_offset field
      specifies a relative offset in octets, from the start of the
      attribute_offset field, at which a list of attributes will be declared.
      The purpose of this field is to allow for forward compatibility: Future
      updates to this specification may add extra fields to the end of the
      header structure, and the value of this field allows older
      implementations to skip those newer fields.

9     The coordinate_system field specifies the coordinate system [ref:
      smf_model.coords] of the model:

      3.5.4.10 Coordinate System
      ──────────────────────────

      [packed SMFBv1CoordinateSystems
        ([field right   [integer unsigned 3]]
         [field up      [integer unsigned 3]]
         [field forward [integer unsigned 3]]
         [field winding [integer unsigned 2]]
         [padding-bits  5])]



11    The axis and winding order values are related to integer values via the
      following functions:

      3.5.4.12 Coordinate System Mapping
      ──────────────────────────────────

      import qualified Axis as A

      axisOrdinal :: A.Axis -> Integer
      axisOrdinal A.PositiveX = 0
      axisOrdinal A.PositiveY = 1
      axisOrdinal A.PositiveZ = 2
      axisOrdinal A.NegativeX = 3
      axisOrdinal A.NegativeY = 4
      axisOrdinal A.NegativeZ = 5

      windingOrdinal :: A.WindingOrder -> Integer
      windingOrdinal A.WindingOrderClockwise        = 0
      windingOrdinal A.WindingOrderCounterClockwise = 1



13    Directly following the end of the header structure, is a series of
      attribute declarations:

      3.5.4.14 Attribute
      ──────────────────

      [record SMFBv1Attribute
        ([field name            [string 64 "UTF-8"]]
         [field component_kind  [integer unsigned 32]]
         [field component_count [integer unsigned 32]]
         [field component_size  [integer unsigned 32]])]



15    The name field specifies the name of the attribute. The component_kind
      field specifies the type of the attribute components. The component_count
      field specifies the number of components in each value in the attribute,
      and the component_size field specifies the size in bits of each component
      value.

16    Attribute component types are related to integer values via the following
      function:

      3.5.4.17 Attribute Type Mapping
      ───────────────────────────────

      import qualified Attribute as A

      attributeTypeOrdinal :: A.ComponentType -> Integer
      attributeTypeOrdinal A.IntegerSigned   = 0
      attributeTypeOrdinal A.IntegerUnsigned = 1
      attributeTypeOrdinal A.FloatingPoint   = 2


3.6 Section - triangles [id: smfb.sections.triangles]

3.6.1 Definition [id: smfb.sections.triangles.def]

1     The triangles section specifies triangle data.

3.6.2 Cardinality/Ordering [id: smfb.sections.triangles.cardinality]

1     An triangles section can appear [0, 1] times in an SMF/B file.

2     The triangles section has no requirements on ordering.

3.6.3 Magic Number [id: smfb.sections.triangles.magic]

1     The triangles section is identified by the magic number
      0x534D465F54524953.

3.6.4 Data [id: smfb.sections.triangles.data]

1     Triangles are specified as an array of 3-element unsigned integer
      vectors, with each integer component being of the size declared in the
      preceding smf [ref: smfb.sections.smf.data] section. No padding is
      inserted between triangles, but padding may need to be added at the end
      of the array in order to ensure proper section alignment [ref:
      smfb.sections.alignment].

3.7 Section - vertices-noninterleaved [id: smfb.sections.vertices-noninterleaved]

3.7.1 Definition [id: smfb.sections.vertices-noninterleaved.def]

1     The vertices-noninterleaved section specifies vertex data for all
      declared attributes [ref: smf_model.attribute].

3.7.2 Cardinality/Ordering [id: smfb.sections.vertices-noninterleaved.cardinality]

1     A vertices-noninterleaved section can appear [0, 1] times in an SMF/B
      file.

2     The vertices-noninterleaved section has no requirements on ordering.

3.7.3 Magic Number [id: smfb.sections.vertices-noninterleaved.magic]

1     The vertices-noninterleaved section is identified by the magic number
      0x534D465F56444E49.

3.7.4 Data [id: smfb.sections.vertices-noninterleaved.data]

1     The data for each attribute is given in full in the order in which the
      attributes were declared in the header. Specifically, in a file
      containing v vertices and a list of attributes a of length n, the data of
      the section will contain v values of the type specified in a !! 0,
      followed by v values of the type specified by a !! 1, and so on up to
      a !! (n - 1). All values are stored in big-endian form.

2     The start of the data for each attribute is aligned to the next 16 octet
      boundary regardless of type. The alignment is achieved by inserting
      padding octets at the end of the data for each attribute so that the
      start of the data for the next attribute, or the start of the next
      section, occurs on a 16 octet boundary.

3.8 Section - metadata [id: smfb.sections.metadata]

3.8.1 Definition [id: smfb.sections.metadata.def]

1     The metadata section specifies arbitrary metadata.

3.8.2 Cardinality/Ordering [id: smfb.sections.metadata.cardinality]

1     A metadata section can appear [0, n] times in an SMF/B file, for any n.

2     The metadata section has no requirements on ordering.

3.8.3 Magic Number [id: smfb.sections.metadata.magic]

1     The metadata section is identified by the magic number
      0x534D465F4D455441.

3.8.4 Data [id: smfb.sections.metadata.data]

1     The data of a metadata section starts with the following fixed-size
      header:

      3.8.4.2 Metadata Header
      ───────────────────────

      [record SMFBv1MetadataID
        ([field meta_schema_id            [string 64 "UTF-8"]]
         [field meta_schema_version_major [integer unsigned 32]]
         [field meta_schema_version_minor [integer unsigned 32]]
         [field meta_size                 [integer unsigned 32]])]



3     The meta_schema_id, meta_schema_version_major, and
      meta_schema_version_minor fields are intended to provide type information
      for the metadata. They have the same semantics and purpose as schema
      identifiers [ref: smf_model.schema_id]. The meta_size field specifies the
      size in octets of the metadata.

3.9 Example [id: smfb.example]

1     A diagram of an example SMF/B file is as follows:

      3.9.4.2 Example
      ───────────────

      [image: layout.svg.png] (Example file)


4 SMF/T - Text Encoding [id: smft]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Contents
  ─────────────────────────────────────────────────────────────────────────────
  4.1 Overview .................................................. smft.overview
  4.2 Sections .................................................. smft.sections
    4.2.1 Definition ........................................ smft.sections.def
    4.2.2 Available Sections .......................... smft.sections.available
  4.3 Section - smf ......................................... smft.sections.smf
    4.3.1 Definition .................................... smft.sections.smf.def
    4.3.2 Subcommands .................................. smft.sections.smf.subs
    4.3.3 Subcommand - attribute ............. smft.sections.smf.subs.attribute
    4.3.4 Subcommand - coordinates ......... smft.sections.smf.subs.coordinates
    4.3.5 Subcommand - schema ................... smft.sections.smf.subs.schema
    4.3.6 Subcommand - triangles ............. smft.sections.smf.subs.triangles
    4.3.7 Subcommand - vertices ............... smft.sections.smf.subs.vertices
  4.4 Section - triangles ............................. smft.sections.triangles
    4.4.1 Definition .............................. smft.sections.triangles.def
  4.5 Section - vertices-noninterleaved . smft.sections.vertices-noninterleaved
    4.5.1 Definition ................ smft.sections.vertices-noninterleaved.def
    4.5.2 Subcommands .............. smft.sections.vertices-noninterleaved.subs
    4.5.3 Subcommand - attribute smft.sections.vertices-noninterleaved.attribute
  4.6 Section - metadata ............................... smft.sections.metadata
    4.6.1 Definition ............................... smft.sections.metadata.def
  4.7 Example .................................................... smft.example


4.1 Overview [id: smft.overview]

1     The SMF/T format is a text encoding for the SMF model [ref:
      smf_model.model]. Data specified in the text encoding is separated into
      explicitly delimited sections [ref: smft.sections].

2     The format is line-based, and lines (excluding the very first line in the
      file) containing only whitespace, or lines beginning with U+0023 # are
      ignored. In a given line, whitespace between tokens is insignificant.

4.2 Sections [id: smft.sections]

4.2.1 Definition [id: smft.sections.def]

1     A section is started with a section command [ref: smft.sections] and
      terminated with a corresponding end [ref: smft.sections.end] command.
      Implementations MUST ignore any content between and including an
      unrecognized section command and the corresponding end command [5].

2     The first line of an SMF/T file MUST begin an smf [ref:
      smft.sections.smf] section.

3     A section is terminated with an end command. Implementations MUST raise
      errors if an end-of-file condition is encountered before an end command
      is given for the current section.

      4.2.1.4 end
      ───────────

      end =
        "end" ;


5     The command takes no arguments.

4.2.2 Available Sections [id: smft.sections.available]

1     This version of the specification defines the following sections:

      4.2.2.2 Sections
      ────────────────

      • smf [ref: smft.sections.smf]
      • triangles [ref: smft.sections.triangles]
      • vertices-noninterleaved [ref: smft.sections.vertices-noninterleaved]
      • metadata [ref: smft.sections.metadata]



4.3 Section - smf [id: smft.sections.smf]

4.3.1 Definition [id: smft.sections.smf.def]

1     The smf section specifies the major and minor version of the
      specification to which the rest of the file is expected to conform. The
      first argument specifies the major version, and the second argument
      specifies the minor version. Implementations MUST immediately reject
      files that are of unsupported major versions, and MUST halt processing of
      the rest of the file if the version numbers cannot be parsed.

2     The command takes the following arguments:

      4.3.1.3 smf Arguments
      ─────────────────────

      0.  The non-negative SMF major version
      1.  The non-negative SMF minor version



      4.3.1.4 smf
      ───────────

      smf =
        "smf" , integer-unsigned , integer-unsigned ;


5     The contents of an smf section are a series of subcommands [ref:
      smft.sections.smf.subs] with at most one subcommand appearing on each
      line within the section. A subcommand consists of the subcommand's name
      and a series of zero or more arguments. Implementations MUST ignore
      subcommands that have unrecognized names, but SHOULD log warning messages
      to indicate that unrecognized subcommands have been specified.

4.3.2 Subcommands [id: smft.sections.smf.subs]

1     This version of the specification defines the following smf subcommands:

      4.3.2.2 Subcommands
      ───────────────────

      • attribute [ref: smft.sections.smf.subs.attribute]
      • coordinates [ref: smft.sections.smf.subs.coordinates]
      • schema [ref: smft.sections.smf.subs.schema]
      • triangles [ref: smft.sections.smf.subs.triangles]
      • vertices [ref: smft.sections.smf.subs.vertices]



4.3.3 Subcommand - attribute [id: smft.sections.smf.subs.attribute]

1     The attribute subcommand specifies an attribute [ref:
      smf_model.attribute] that will appear in the model.

      4.3.3.2 attribute
      ─────────────────

      attribute_name_raw =
        ? [\p{IsAlphabetic}\p{IsDigit}_\-\.:]{1,64} ? ;

      attribute_name_quoted =
        """ , attribute_name_raw , """ ;

      attribute_name =
        attribute_name_raw | attribute_name_quoted ;

      attribute_type =
        "integer-signed" | "integer-unsigned" | "float" ;

      smf_attribute =
        "attribute" , attribute_name , attribute_type , integer-unsigned , integer-unsigned ;



3     The subcommand takes the following arguments:

      4.3.3.4 attributes Arguments
      ────────────────────────────

      0.  The name of the attribute
      1.  The type of the components in the attribute
      2.  The non-negative number of components in the attribute
      3.  The non-negative size in bits of an individual component



5     The subcommand is allowed to appear any number of times, but all
      specified attribute names must be unique.

4.3.4 Subcommand - coordinates [id: smft.sections.smf.subs.coordinates]

1     The coordinates subcommand specifies the coordinate space [ref:
      smf_model.coords] of the mesh data that will appear in the model.

      4.3.4.2 coordinates
      ───────────────────

      axis =
        "+x" | "-x" | "+y" | "-y" | "+z" | "-z" ;

      winding_order =
        "clockwise" | "counter-clockwise" ;

      smf_coordinates =
        "coordinates" , <axis> , <axis> , <axis> , <winding_order> ;



3     The subcommand takes the following arguments:

      4.3.4.4 coordinates Arguments
      ─────────────────────────────

      0.  The axis for the right direction
      1.  The axis for the up direction
      2.  The axis for the forward direction
      3.  The triangle winding order



5     If the subcommand does not appear in the section, implementations MUST
      behave as if the following subcommand had been specified:

      4.3.4.6 coordinates Default
      ───────────────────────────

      coordinates +x +y -z counter-clockwise


4.3.5 Subcommand - schema [id: smft.sections.smf.subs.schema]

1     The schema command specifies the schema identifier [ref:
      smf_model.schema_id] for the file.

      4.3.5.2 schema
      ──────────────

      smf_schema =
        "schema" , schema_name , integer-unsigned , integer-unsigned ;


3     The command takes the following arguments:

      4.3.5.4 schema Arguments
      ────────────────────────

      0.  The schema ID string
      1.  The non-negative schema major version
      2.  The non-negative schema minor version



4.3.6 Subcommand - triangles [id: smft.sections.smf.subs.triangles]

1     The triangles subcommand specifies the number of triangles [ref:
      smf_model.triangle] that will appear in the model, and the size of the
      vertex indices in bits.

      4.3.6.2 triangles
      ─────────────────

      smf_triangles =
        "triangles" , integer-unsigned , integer-unsigned ;


3     The subcommand takes the following arguments:

      4.3.6.4 triangles Arguments
      ───────────────────────────

      0.  The non-negative triangle count
      1.  The non-negative size in bits of a triangle vertex index



5     If the subcommand does not appear in the section, implementations MUST
      behave as if the following subcommand had been specified:

      4.3.6.6 vertices Default
      ────────────────────────

      trianges 0 32


4.3.7 Subcommand - vertices [id: smft.sections.smf.subs.vertices]

1     The vertices subcommand specifies the number of vertices [ref:
      smf_model.vertex] that will appear in the model for each attribute.

      4.3.7.2 vertices
      ────────────────

      smf_vertices =
        "vertices" , integer-unsigned ;


3     The subcommand takes the following arguments:

      4.3.7.4 vertices Arguments
      ──────────────────────────

      0.  The non-negative number of vertices that will appear in the file



5     If the subcommand does not appear in the section, implementations MUST
      behave as if the following subcommand had been specified:

      4.3.7.6 vertices Default
      ────────────────────────

      vertices 0


4.4 Section - triangles [id: smft.sections.triangles]

4.4.1 Definition [id: smft.sections.triangles.def]

1     The triangles section specifies triangle data that will appear in the
      model.

      4.4.1.2 triangles
      ─────────────────

      data_command_triangles =
        "triangles" ;


3     The command takes no arguments.

4     In a file that is specified to contain k triangles, the next k non-empty,
      non-commented lines will contain exactly 3 whitespace-separated unsigned
      integer values each representing the index of a vertex. Implementations
      MUST raise errors if there are not exactly k triangles specified before
      section's end [ref: smft.sections.end] command.

4.5 Section - vertices-noninterleaved [id: smft.sections.vertices-noninterleaved]

4.5.1 Definition [id: smft.sections.vertices-noninterleaved.def]

1     The vertices-noninterleaved section specifies the vertex data that will
      appear in the model.

2     The contents of a vertices-noninterleaved section are a series of
      subcommands [ref: smft.sections.vertices-noninterleaved.subs] with at
      most one subcommand appearing on each line within the section. A
      subcommand consists of the subcommand's name and a series of zero or more
      arguments. Implementations MUST ignore subcommands that have unrecognized
      names, but SHOULD log warning messages to indicate that unrecognized
      subcommands have been specified.

4.5.2 Subcommands [id: smft.sections.vertices-noninterleaved.subs]

1     This version of the specification defines the following
      vertices-noninterleaved subcommands:

      4.5.2.2 Subcommands
      ───────────────────

      • attribute [ref: smft.sections.vertices-noninterleaved.attribute]



4.5.3 Subcommand - attribute [id: smft.sections.vertices-noninterleaved.attribute]

1     The attribute subcommand indicates the start of data for an attribute.

      4.5.3.2 attribute
      ─────────────────

      vertices_noninterleaved_attribute =
        "attribute" , attribute_name ;


3     The command takes the following arguments:

      4.5.3.4 attribute Arguments
      ───────────────────────────

      0.  The name of the attribute



5     The named attribute must have been declared in the smf [ref:
      smft.sections.smf] section; Implementations MUST raise errors when
      encountering attribute subcommands that name attributes that were not
      declared in the smf [ref: smft.sections.smf] section.

6     For an attribute a that specifies c components of type t, in a file that
      is specified to contain v vertices, the next v non-empty, non-commented
      lines will contain exactly c whitespace-separated values of type t.
      Implementations MUST raise errors if there are not exactly v vertex
      values specified before section's end [ref: smft.sections.end] command or
      the start of the next attribute subcommand, whichever occurs first.

4.6 Section - metadata [id: smft.sections.metadata]

4.6.1 Definition [id: smft.sections.metadata.def]

1     The metadata section specifies an item of optional metadata that will be
      attached to the model.

      4.6.1.2 metadata
      ────────────────

      metadata =
        "metadata" , schema_name , integer-unsigned , integer-unsigned , integer-unsigned ;



3     The command takes the following arguments:

      4.6.1.4 meta Arguments
      ──────────────────────

      0.  The schema ID
      1.  The major version of the schema
      2.  The minor version of the schema
      3.  The non-negative number of lines of metadata that will follow the
          command



5     For any v, s, and n, the command meta v s n will indicate that the next n
      non-empty, non-commented lines will contain RFC4648 base64url [url:
      https://tools.ietf.org/html/rfc4648] encoded data of a type with vendor v
      and schema s. Implementations MUST raise errors if there are not exactly
      n lines of data specified before the section's end [ref:
      smft.sections.end] command.

4.7 Example [id: smft.example]

1     The following is a complete example of an SMF/T file:

      4.7.1.2 smf
      ───────────

      smf 1 0
      schema com.io7m.example.smf 1 0
      vertices 9
      triangles 4 32
      coordinates +x +y -z counter-clockwise
      attribute "POSITION" float 3 32
      attribute "NORMAL" float 3 32
      attribute "UV:UVMap" float 2 32
      attribute "GROUP:group0" float 1 32
      end

      #
      # This is a comment and will be ignored.
      #

      vertices-noninterleaved
      attribute "POSITION"
      0.000000000000000 0.000000000000000 0.000000000000000
      1.000000000000000 0.000000000000000 0.000000000000000
      0.000000000000000 0.000000000000000 -2.000000000000000
      1.000000000000000 0.000000000000000 -2.000000000000000
      2.000000000000000 0.000000000000000 0.000000000000000
      2.000000000000000 0.000000000000000 -2.000000000000000
      1.000000000000000 0.000000000000000 0.000000000000000
      1.000000000000000 0.000000000000000 -2.000000000000000
      1.000000000000000 0.000000000000000 0.000000000000000
      attribute "NORMAL"
      0.000000000000000 1.000000000000000 0.000000000000000
      0.000000000000000 0.999999940395355 0.000000000000000
      0.000000000000000 1.000000000000000 0.000000000000000
      0.000000000000000 1.000000000000000 0.000000000000000
      0.000000000000000 1.000000000000000 0.000000000000000
      0.000000000000000 1.000000000000000 0.000000000000000
      0.000000000000000 0.999999940395355 0.000000000000000
      0.000000000000000 1.000000000000000 0.000000000000000
      0.000000000000000 0.999999940395355 0.000000000000000
      attribute "UV:UVMap"
      0.112528264522552 0.912521243095398
      0.112528264522552 0.712549567222595
      0.512471735477448 0.912521243095398
      0.696853816509247 0.614087224006653
      0.396896183490753 0.464108407497406
      0.696853816509247 0.464108407497406
      0.396896213293076 0.614087224006653
      0.512471735477448 0.712549448013306
      0.396896213293076 0.614087224006653
      attribute "GROUP:group0"
      0.000000000000000
      0.300000011920929
      0.200000002980232
      0.400000005960465
      0.600000023841858
      0.699999988079071
      0.300000011920929
      0.400000005960465
      0.300000011920929
      end

      triangles
      1 2 0
      6 5 3
      1 7 2
      8 4 5
      end

      metadata com.example.metadata.example0 1 0 1
      aGVsbG8taGVsbG8K
      end

      metadata com.example.metadata.example3 2 0 5
      AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1
      Njc4OTo7PD0-P0BBQkNERUZHSElKS0xNTk9QUVJTVFVWV1hZWltcXV5fYGFiY2RlZmdoaWpr
      bG1ub3BxcnN0dXZ3eHl6e3x9fn-AgYKDhIWGh4iJiouMjY6PkJGSk5SVlpeYmZqbnJ2en6Ch
      oqOkpaanqKmqq6ytrq-wsbKztLW2t7i5uru8vb6_wMHCw8TFxsfIycrLzM3Oz9DR0tPU1dbX
      2Nna29zd3t_g4eLj5OXm5-jp6uvs7e7v8PHy8_T19vf4-fr7_P3-_w==
      end



5 Specification History [id: history]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Contents
  ─────────────────────────────────────────────────────────────────────────────
  5.1 History ................................................. history.history


5.1 History [id: history.history]

1     This section provides a brief summary of specification changes over time.

      5.1.2 History
      ─────────────

      • 1.0 Initial specification.




Footnotes
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[0]   https://en.wikipedia.org/wiki/COLLADA [url:
      https://en.wikipedia.org/wiki/COLLADA]

[1]   https://en.wikipedia.org/wiki/XML_Namespace [url:
      https://en.wikipedia.org/wiki/XML_Namespace]

[2]   https://en.wikipedia.org/wiki/Portable_Network_Graphics#File_header [url:
      https://en.wikipedia.org/wiki/Portable_Network_Graphics#File_header]

[3]   Ignoring unrecognized sections allows for forwards compatibility: An
      implementation supporting version m can read a file of version n, where m
      < n, and ignore any new sections specified by format n that it does not
      understand.

[4]   The requirement for data to be aligned to 16 octet boundaries is intended
      to facilitate implementations using vector instruction sets such as SSE
      [url: https://en.wikipedia.org/wiki/Streaming_SIMD_Extensions] to
      efficiently operate on memory-mapped SMF/B files.

[5]   Ignoring unrecognized sections allows for forwards compatibility: An
      implementation supporting version m can read a file of version n, where m
      < n, and ignore any new sections specified by format n that it does not
      understand.

