1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/libs/assimp/assbin_chunks.h	Sat Feb 01 19:58:19 2014 +0200
     1.3 @@ -0,0 +1,196 @@
     1.4 +
     1.5 +#ifndef INCLUDED_ASSBIN_CHUNKS_H
     1.6 +#define INCLUDED_ASSBIN_CHUNKS_H
     1.7 +
     1.8 +#define ASSBIN_VERSION_MAJOR 1
     1.9 +#define ASSBIN_VERSION_MINOR 0
    1.10 +
    1.11 +/** 
    1.12 +@page assfile .ASS File formats
    1.13 +
    1.14 +@section over Overview
    1.15 +Assimp provides its own interchange format, which is intended to applications which need
    1.16 +to serialize 3D-models and to reload them quickly. Assimp's file formats are designed to
    1.17 +be read by Assimp itself. They encode additional information needed by Assimp to optimize
    1.18 +its postprocessing pipeline. If you once apply specific steps to a scene, then save it
    1.19 +and reread it from an ASS format using the same post processing settings, they won't
    1.20 +be executed again.
    1.21 +
    1.22 +The format comes in two flavours: XML and binary - both of them hold a complete dump of
    1.23 +the 'aiScene' data structure returned by the APIs. The focus for the binary format
    1.24 +(<tt>.assbin</tt>) is fast loading. Optional deflate compression helps reduce file size. The XML
    1.25 +flavour, <tt>.assxml</tt> or simply .xml, is just a plain-to-xml conversion of aiScene.
    1.26 +
    1.27 +ASSBIN is Assimp's binary interchange format. assimp_cmd (<tt>&lt;root&gt;/tools/assimp_cmd</tt>) is able to 
    1.28 +write it and the core library provides a loader for it.
    1.29 +
    1.30 +@section assxml XML File format
    1.31 +
    1.32 +The format is pretty much self-explanatory due to its similarity to the in-memory aiScene structure.
    1.33 +With few exceptions, C structures are wrapped in XML elements.
    1.34 +
    1.35 +The DTD for ASSXML can be found in <tt>&lt;root&gt;/doc/AssXML_Scheme.xml</tt>. Or have   look
    1.36 +at the output files generated by assimp_cmd.
    1.37 +
    1.38 +@section assbin Binary file format
    1.39 +
    1.40 +The ASSBIN file format is composed of chunks to represent the hierarchical aiScene data structure.
    1.41 +This makes the format extensible and allows backward-compatibility with future data structure
    1.42 +versions. The <tt>&lt;root&gt;/code/assbin_chunks.h</tt> header contains some magic constants
    1.43 +for use by stand-alone ASSBIN loaders. Also, Assimp's own file writer can be found
    1.44 +in <tt>&lt;root&gt;/tools/assimp_cmd/WriteDumb.cpp</tt> (yes, the 'b' is no typo ...).
    1.45 +
    1.46 +@verbatim
    1.47 +
    1.48 +-------------------------------------------------------------------------------
    1.49 +1. File structure:
    1.50 +-------------------------------------------------------------------------------
    1.51 +
    1.52 +----------------------
    1.53 +| Header (500 bytes) |
    1.54 +----------------------
    1.55 +| Variable chunks    |
    1.56 +----------------------
    1.57 +
    1.58 +-------------------------------------------------------------------------------
    1.59 +2. Definitions:
    1.60 +-------------------------------------------------------------------------------
    1.61 +
    1.62 +integer	is four bytes wide, stored in little-endian byte order.
    1.63 +short	is two bytes wide, stored in little-endian byte order.
    1.64 +byte	is a single byte.
    1.65 +string  is an integer n followed by n UTF-8 characters, not terminated by zero
    1.66 +float	is an IEEE 754 single-precision floating-point value 
    1.67 +double	is an IEEE 754 double-precision floating-point value 
    1.68 +t[n]    is an array of n elements of type t
    1.69 +
    1.70 +-------------------------------------------------------------------------------
    1.71 +2. Header:
    1.72 +-------------------------------------------------------------------------------
    1.73 +
    1.74 +byte[44]	Magic identification string for ASSBIN files.
    1.75 +                'ASSIMP.binary'
    1.76 +
    1.77 +integer		Major version of the Assimp library which wrote the file
    1.78 +integer		Minor version of the Assimp library which wrote the file
    1.79 +                match these against ASSBIN_VERSION_MAJOR and ASSBIN_VERSION_MINOR
    1.80 +
    1.81 +integer		SVN revision of the Assimp library (intended for our internal
    1.82 +            debugging - if you write Ass files from your own APPs, set this value to 0.
    1.83 +integer		Assimp compile flags
    1.84 +
    1.85 +short		0 for normal files, 1 for shortened dumps for regression tests 
    1.86 +                these should have the file extension assbin.regress
    1.87 +
    1.88 +short       1 if the data after the header is compressed with the DEFLATE algorithm,
    1.89 +            0 for uncompressed files.
    1.90 +                   For compressed files, the first integer after the header is
    1.91 +                   always the uncompressed data size
    1.92 +                
    1.93 +byte[256]	Zero-terminated source file name, UTF-8
    1.94 +byte[128]	Zero-terminated command line parameters passed to assimp_cmd, UTF-8 
    1.95 +
    1.96 +byte[64]	Reserved for future use
    1.97 +---> Total length: 512 bytes
    1.98 +
    1.99 +-------------------------------------------------------------------------------
   1.100 +3. Chunks:
   1.101 +-------------------------------------------------------------------------------
   1.102 +
   1.103 +integer		Magic chunk ID (ASSBIN_CHUNK_XXX)
   1.104 +integer		Chunk data length, in bytes 
   1.105 +                (unknown chunks are possible, a good reader skips over them)
   1.106 +
   1.107 +byte[n]		length-of-chunk bytes of data, depending on the chunk type
   1.108 +
   1.109 +Chunks can contain nested chunks. Nested chunks are ALWAYS at the end of the chunk,
   1.110 +their size is included in length-of-chunk.
   1.111 +
   1.112 +The chunk layout for all ASSIMP data structures is derived from their C declarations.
   1.113 +The general 'rule' to get from Assimp headers to the serialized layout is:
   1.114 +
   1.115 +   1. POD members (i.e. aiMesh::mPrimitiveTypes, aiMesh::mNumVertices), 
   1.116 +        in order of declaration.
   1.117 +
   1.118 +   2. Array-members (aiMesh::mFaces, aiMesh::mVertices, aiBone::mWeights), 
   1.119 +        in order of declaration.
   1.120 +
   1.121 +   2. Object array members (i.e aiMesh::mBones, aiScene::mMeshes) are stored in 
   1.122 +      subchunks directly following the data written in 1.) and 2.)
   1.123 +
   1.124 +
   1.125 +	Of course, there are some exceptions to this general order:
   1.126 +
   1.127 +[[aiScene]]
   1.128 +
   1.129 +   - The root node holding the scene structure is naturally stored in
   1.130 +     a ASSBIN_CHUNK_AINODE subchunk following 1.) and 2.) (which is 
   1.131 +	 empty for aiScene).
   1.132 +
   1.133 +[[aiMesh]]
   1.134 +
   1.135 +   - mTextureCoords and mNumUVComponents are serialized as follows:
   1.136 +
   1.137 +   [number of used uv channels times]
   1.138 +       integer mNumUVComponents[n]
   1.139 +       float mTextureCoords[n][mNumUVComponents[n]]
   1.140 +
   1.141 +       -> more than AI_MAX_TEXCOORD_CHANNELS can be stored. This allows Assimp 
   1.142 +	   builds with different settings for AI_MAX_TEXCOORD_CHANNELS to exchange
   1.143 +	   data. Unlike the in-memory format, only the used components of the 
   1.144 +	   UV coordinates are written to disk. If mNumUVComponents[0] is 1, the
   1.145 +	   corresponding mTextureCoords array consists of mNumTextureCoords*1 
   1.146 +	   single floats.
   1.147 +
   1.148 +   - The array member block of aiMesh is prefixed with an integer that specifies 
   1.149 +     the kinds of vertex components actually present in the mesh. This is a 
   1.150 +	 bitwise combination of the ASSBIN_MESH_HAS_xxx constants.
   1.151 +
   1.152 +[[aiFace]]
   1.153 +
   1.154 +   - mNumIndices is stored as short
   1.155 +   - mIndices are written as short, if aiMesh::mNumVertices<65536
   1.156 +
   1.157 +[[aiNode]]
   1.158 +
   1.159 +   - mParent is omitted
   1.160 +
   1.161 +[[aiLight]]
   1.162 +
   1.163 +   - mAttenuationXXX not written if aiLight::mType == aiLightSource_DIRECTIONAL
   1.164 +   - mAngleXXX not written if aiLight::mType != aiLightSource_SPOT
   1.165 +
   1.166 +[[aiMaterial]]
   1.167 +
   1.168 +   - mNumAllocated is omitted, for obvious reasons :-)
   1.169 +
   1.170 +
   1.171 + @endverbatim*/
   1.172 +
   1.173 +
   1.174 +#define ASSBIN_HEADER_LENGTH 512
   1.175 +
   1.176 +// these are the magic chunk identifiers for the binary ASS file format
   1.177 +#define ASSBIN_CHUNK_AICAMERA					0x1234
   1.178 +#define ASSBIN_CHUNK_AILIGHT					0x1235
   1.179 +#define ASSBIN_CHUNK_AITEXTURE					0x1236
   1.180 +#define ASSBIN_CHUNK_AIMESH						0x1237
   1.181 +#define ASSBIN_CHUNK_AINODEANIM					0x1238
   1.182 +#define ASSBIN_CHUNK_AISCENE					0x1239
   1.183 +#define ASSBIN_CHUNK_AIBONE						0x123a
   1.184 +#define ASSBIN_CHUNK_AIANIMATION				0x123b
   1.185 +#define ASSBIN_CHUNK_AINODE						0x123c
   1.186 +#define ASSBIN_CHUNK_AIMATERIAL					0x123d
   1.187 +#define ASSBIN_CHUNK_AIMATERIALPROPERTY			0x123e
   1.188 +
   1.189 +#define ASSBIN_MESH_HAS_POSITIONS					0x1
   1.190 +#define ASSBIN_MESH_HAS_NORMALS						0x2
   1.191 +#define ASSBIN_MESH_HAS_TANGENTS_AND_BITANGENTS		0x4
   1.192 +#define ASSBIN_MESH_HAS_TEXCOORD_BASE				0x100
   1.193 +#define ASSBIN_MESH_HAS_COLOR_BASE					0x10000
   1.194 +
   1.195 +#define ASSBIN_MESH_HAS_TEXCOORD(n)	(ASSBIN_MESH_HAS_TEXCOORD_BASE << n)
   1.196 +#define ASSBIN_MESH_HAS_COLOR(n)	(ASSBIN_MESH_HAS_COLOR_BASE << n)
   1.197 +
   1.198 +
   1.199 +#endif // INCLUDED_ASSBIN_CHUNKS_H