nuclear@0:
nuclear@0: #ifndef INCLUDED_ASSBIN_CHUNKS_H
nuclear@0: #define INCLUDED_ASSBIN_CHUNKS_H
nuclear@0:
nuclear@0: #define ASSBIN_VERSION_MAJOR 1
nuclear@0: #define ASSBIN_VERSION_MINOR 0
nuclear@0:
nuclear@0: /**
nuclear@0: @page assfile .ASS File formats
nuclear@0:
nuclear@0: @section over Overview
nuclear@0: Assimp provides its own interchange format, which is intended to applications which need
nuclear@0: to serialize 3D-models and to reload them quickly. Assimp's file formats are designed to
nuclear@0: be read by Assimp itself. They encode additional information needed by Assimp to optimize
nuclear@0: its postprocessing pipeline. If you once apply specific steps to a scene, then save it
nuclear@0: and reread it from an ASS format using the same post processing settings, they won't
nuclear@0: be executed again.
nuclear@0:
nuclear@0: The format comes in two flavours: XML and binary - both of them hold a complete dump of
nuclear@0: the 'aiScene' data structure returned by the APIs. The focus for the binary format
nuclear@0: (.assbin) is fast loading. Optional deflate compression helps reduce file size. The XML
nuclear@0: flavour, .assxml or simply .xml, is just a plain-to-xml conversion of aiScene.
nuclear@0:
nuclear@0: ASSBIN is Assimp's binary interchange format. assimp_cmd (<root>/tools/assimp_cmd) is able to
nuclear@0: write it and the core library provides a loader for it.
nuclear@0:
nuclear@0: @section assxml XML File format
nuclear@0:
nuclear@0: The format is pretty much self-explanatory due to its similarity to the in-memory aiScene structure.
nuclear@0: With few exceptions, C structures are wrapped in XML elements.
nuclear@0:
nuclear@0: The DTD for ASSXML can be found in <root>/doc/AssXML_Scheme.xml. Or have look
nuclear@0: at the output files generated by assimp_cmd.
nuclear@0:
nuclear@0: @section assbin Binary file format
nuclear@0:
nuclear@0: The ASSBIN file format is composed of chunks to represent the hierarchical aiScene data structure.
nuclear@0: This makes the format extensible and allows backward-compatibility with future data structure
nuclear@0: versions. The <root>/code/assbin_chunks.h header contains some magic constants
nuclear@0: for use by stand-alone ASSBIN loaders. Also, Assimp's own file writer can be found
nuclear@0: in <root>/tools/assimp_cmd/WriteDumb.cpp (yes, the 'b' is no typo ...).
nuclear@0:
nuclear@0: @verbatim
nuclear@0:
nuclear@0: -------------------------------------------------------------------------------
nuclear@0: 1. File structure:
nuclear@0: -------------------------------------------------------------------------------
nuclear@0:
nuclear@0: ----------------------
nuclear@0: | Header (500 bytes) |
nuclear@0: ----------------------
nuclear@0: | Variable chunks |
nuclear@0: ----------------------
nuclear@0:
nuclear@0: -------------------------------------------------------------------------------
nuclear@0: 2. Definitions:
nuclear@0: -------------------------------------------------------------------------------
nuclear@0:
nuclear@0: integer is four bytes wide, stored in little-endian byte order.
nuclear@0: short is two bytes wide, stored in little-endian byte order.
nuclear@0: byte is a single byte.
nuclear@0: string is an integer n followed by n UTF-8 characters, not terminated by zero
nuclear@0: float is an IEEE 754 single-precision floating-point value
nuclear@0: double is an IEEE 754 double-precision floating-point value
nuclear@0: t[n] is an array of n elements of type t
nuclear@0:
nuclear@0: -------------------------------------------------------------------------------
nuclear@0: 2. Header:
nuclear@0: -------------------------------------------------------------------------------
nuclear@0:
nuclear@0: byte[44] Magic identification string for ASSBIN files.
nuclear@0: 'ASSIMP.binary'
nuclear@0:
nuclear@0: integer Major version of the Assimp library which wrote the file
nuclear@0: integer Minor version of the Assimp library which wrote the file
nuclear@0: match these against ASSBIN_VERSION_MAJOR and ASSBIN_VERSION_MINOR
nuclear@0:
nuclear@0: integer SVN revision of the Assimp library (intended for our internal
nuclear@0: debugging - if you write Ass files from your own APPs, set this value to 0.
nuclear@0: integer Assimp compile flags
nuclear@0:
nuclear@0: short 0 for normal files, 1 for shortened dumps for regression tests
nuclear@0: these should have the file extension assbin.regress
nuclear@0:
nuclear@0: short 1 if the data after the header is compressed with the DEFLATE algorithm,
nuclear@0: 0 for uncompressed files.
nuclear@0: For compressed files, the first integer after the header is
nuclear@0: always the uncompressed data size
nuclear@0:
nuclear@0: byte[256] Zero-terminated source file name, UTF-8
nuclear@0: byte[128] Zero-terminated command line parameters passed to assimp_cmd, UTF-8
nuclear@0:
nuclear@0: byte[64] Reserved for future use
nuclear@0: ---> Total length: 512 bytes
nuclear@0:
nuclear@0: -------------------------------------------------------------------------------
nuclear@0: 3. Chunks:
nuclear@0: -------------------------------------------------------------------------------
nuclear@0:
nuclear@0: integer Magic chunk ID (ASSBIN_CHUNK_XXX)
nuclear@0: integer Chunk data length, in bytes
nuclear@0: (unknown chunks are possible, a good reader skips over them)
nuclear@0:
nuclear@0: byte[n] length-of-chunk bytes of data, depending on the chunk type
nuclear@0:
nuclear@0: Chunks can contain nested chunks. Nested chunks are ALWAYS at the end of the chunk,
nuclear@0: their size is included in length-of-chunk.
nuclear@0:
nuclear@0: The chunk layout for all ASSIMP data structures is derived from their C declarations.
nuclear@0: The general 'rule' to get from Assimp headers to the serialized layout is:
nuclear@0:
nuclear@0: 1. POD members (i.e. aiMesh::mPrimitiveTypes, aiMesh::mNumVertices),
nuclear@0: in order of declaration.
nuclear@0:
nuclear@0: 2. Array-members (aiMesh::mFaces, aiMesh::mVertices, aiBone::mWeights),
nuclear@0: in order of declaration.
nuclear@0:
nuclear@0: 2. Object array members (i.e aiMesh::mBones, aiScene::mMeshes) are stored in
nuclear@0: subchunks directly following the data written in 1.) and 2.)
nuclear@0:
nuclear@0:
nuclear@0: Of course, there are some exceptions to this general order:
nuclear@0:
nuclear@0: [[aiScene]]
nuclear@0:
nuclear@0: - The root node holding the scene structure is naturally stored in
nuclear@0: a ASSBIN_CHUNK_AINODE subchunk following 1.) and 2.) (which is
nuclear@0: empty for aiScene).
nuclear@0:
nuclear@0: [[aiMesh]]
nuclear@0:
nuclear@0: - mTextureCoords and mNumUVComponents are serialized as follows:
nuclear@0:
nuclear@0: [number of used uv channels times]
nuclear@0: integer mNumUVComponents[n]
nuclear@0: float mTextureCoords[n][mNumUVComponents[n]]
nuclear@0:
nuclear@0: -> more than AI_MAX_TEXCOORD_CHANNELS can be stored. This allows Assimp
nuclear@0: builds with different settings for AI_MAX_TEXCOORD_CHANNELS to exchange
nuclear@0: data. Unlike the in-memory format, only the used components of the
nuclear@0: UV coordinates are written to disk. If mNumUVComponents[0] is 1, the
nuclear@0: corresponding mTextureCoords array consists of mNumTextureCoords*1
nuclear@0: single floats.
nuclear@0:
nuclear@0: - The array member block of aiMesh is prefixed with an integer that specifies
nuclear@0: the kinds of vertex components actually present in the mesh. This is a
nuclear@0: bitwise combination of the ASSBIN_MESH_HAS_xxx constants.
nuclear@0:
nuclear@0: [[aiFace]]
nuclear@0:
nuclear@0: - mNumIndices is stored as short
nuclear@0: - mIndices are written as short, if aiMesh::mNumVertices<65536
nuclear@0:
nuclear@0: [[aiNode]]
nuclear@0:
nuclear@0: - mParent is omitted
nuclear@0:
nuclear@0: [[aiLight]]
nuclear@0:
nuclear@0: - mAttenuationXXX not written if aiLight::mType == aiLightSource_DIRECTIONAL
nuclear@0: - mAngleXXX not written if aiLight::mType != aiLightSource_SPOT
nuclear@0:
nuclear@0: [[aiMaterial]]
nuclear@0:
nuclear@0: - mNumAllocated is omitted, for obvious reasons :-)
nuclear@0:
nuclear@0:
nuclear@0: @endverbatim*/
nuclear@0:
nuclear@0:
nuclear@0: #define ASSBIN_HEADER_LENGTH 512
nuclear@0:
nuclear@0: // these are the magic chunk identifiers for the binary ASS file format
nuclear@0: #define ASSBIN_CHUNK_AICAMERA 0x1234
nuclear@0: #define ASSBIN_CHUNK_AILIGHT 0x1235
nuclear@0: #define ASSBIN_CHUNK_AITEXTURE 0x1236
nuclear@0: #define ASSBIN_CHUNK_AIMESH 0x1237
nuclear@0: #define ASSBIN_CHUNK_AINODEANIM 0x1238
nuclear@0: #define ASSBIN_CHUNK_AISCENE 0x1239
nuclear@0: #define ASSBIN_CHUNK_AIBONE 0x123a
nuclear@0: #define ASSBIN_CHUNK_AIANIMATION 0x123b
nuclear@0: #define ASSBIN_CHUNK_AINODE 0x123c
nuclear@0: #define ASSBIN_CHUNK_AIMATERIAL 0x123d
nuclear@0: #define ASSBIN_CHUNK_AIMATERIALPROPERTY 0x123e
nuclear@0:
nuclear@0: #define ASSBIN_MESH_HAS_POSITIONS 0x1
nuclear@0: #define ASSBIN_MESH_HAS_NORMALS 0x2
nuclear@0: #define ASSBIN_MESH_HAS_TANGENTS_AND_BITANGENTS 0x4
nuclear@0: #define ASSBIN_MESH_HAS_TEXCOORD_BASE 0x100
nuclear@0: #define ASSBIN_MESH_HAS_COLOR_BASE 0x10000
nuclear@0:
nuclear@0: #define ASSBIN_MESH_HAS_TEXCOORD(n) (ASSBIN_MESH_HAS_TEXCOORD_BASE << n)
nuclear@0: #define ASSBIN_MESH_HAS_COLOR(n) (ASSBIN_MESH_HAS_COLOR_BASE << n)
nuclear@0:
nuclear@0:
nuclear@0: #endif // INCLUDED_ASSBIN_CHUNKS_H