io7m | single-page | multi-page | SMF Format Specification 0.16.0-SNAPSHOT
1. Notational Conventions
Previous
Front Matter
Up
3. SMF/B - Binary Encoding
Next

# 2. Model

- 2.1. Overview
- 2.2. Versioning
  - 2.2.1. Overview
  - 2.2.2. Forward Compatibility
  - 2.2.3. Backward Compatibility
  - 2.2.4. Compatibility
- 2.3. Mesh
- 2.4. Attributes
- 2.5. Vertices
- 2.6. Triangles
- 2.7. Coordinate System
- 2.8. Schema ID
- 2.9. Metadata

## 2.1. 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 [2]. The text and binary 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, 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 (2, 0). See versioning for details.

## 2.2. Versioning

## 2.2.1. Overview

1
The SMF specification is versioned via a restricted subset of the Semantic Versioning 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

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

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

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

1
A mesh in the SMF model is a set of triangles.

## 2.4. Attributes

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 floating point values.

### 2.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
Attribute names may be at most 64 characters in length and must conform to the following syntax:

### 2.4.5. Attribute Name Syntax

    attribute_name =
      ? [a-z_.0-9]{1,64} ? ;

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

### 2.4.7. 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

1
A vertex is an abstract object consisting of exactly one element taken from each of the defined attributes. 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 the defined attributes. Vertices are numbered starting at 0.

## 2.6. Triangles

1
A triangle is a 3-tuple of vertices. In the SMF model, a triangle references vertices by their numeric index.

## 2.7. Coordinate System

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

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, 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.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.6. Schema Name Syntax

    schema_name =
      ? [a-z_.0-9]{1,64} ? ;

## 2.9. 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. 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.

## Footnotes

1 | https://en.wikipedia.org/wiki/XML_Namespace References to this footnote: 1
2 | https://en.wikipedia.org/wiki/COLLADA References to this footnote: 1

1. Notational Conventions
Previous
Front Matter
Up
3. SMF/B - Binary Encoding
Next
io7m | single-page | multi-page | SMF Format Specification 0.16.0-SNAPSHOT