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: (<tt>.assbin</tt>) is fast loading. Optional deflate compression helps reduce file size. The XML
nuclear@0: flavour, <tt>.assxml</tt> 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 (<tt>&lt;root&gt;/tools/assimp_cmd</tt>) 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 <tt>&lt;root&gt;/doc/AssXML_Scheme.xml</tt>. 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 <tt>&lt;root&gt;/code/assbin_chunks.h</tt> 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 <tt>&lt;root&gt;/tools/assimp_cmd/WriteDumb.cpp</tt> (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