1 #ifndef INCLUDED_ASSBIN_CHUNKS_H 2 #define INCLUDED_ASSBIN_CHUNKS_H 3 4 #define ASSBIN_VERSION_MAJOR 1 5 #define ASSBIN_VERSION_MINOR 0 6 7 /** 8 @page assfile .ASS File formats 9 10 @section over Overview 11 Assimp provides its own interchange format, which is intended to applications which need 12 to serialize 3D-models and to reload them quickly. Assimp's file formats are designed to 13 be read by Assimp itself. They encode additional information needed by Assimp to optimize 14 its postprocessing pipeline. If you once apply specific steps to a scene, then save it 15 and reread it from an ASS format using the same post processing settings, they won't 16 be executed again. 17 18 The format comes in two flavours: XML and binary - both of them hold a complete dump of 19 the 'aiScene' data structure returned by the APIs. The focus for the binary format 20 (<tt>.assbin</tt>) is fast loading. Optional deflate compression helps reduce file size. The XML 21 flavour, <tt>.assxml</tt> or simply .xml, is just a plain-to-xml conversion of aiScene. 22 23 ASSBIN is Assimp's binary interchange format. assimp_cmd (<tt><root>/tools/assimp_cmd</tt>) is able to 24 write it and the core library provides a loader for it. 25 26 @section assxml XML File format 27 28 The format is pretty much self-explanatory due to its similarity to the in-memory aiScene structure. 29 With few exceptions, C structures are wrapped in XML elements. 30 31 The DTD for ASSXML can be found in <tt><root>/doc/AssXML_Scheme.xml</tt>. Or have look 32 at the output files generated by assimp_cmd. 33 34 @section assbin Binary file format 35 36 The ASSBIN file format is composed of chunks to represent the hierarchical aiScene data structure. 37 This makes the format extensible and allows backward-compatibility with future data structure 38 versions. The <tt><root>/code/assbin_chunks.h</tt> header contains some magic constants 39 for use by stand-alone ASSBIN loaders. Also, Assimp's own file writer can be found 40 in <tt><root>/tools/assimp_cmd/WriteDump.cpp</tt> (yes, the 'b' is no typo ...). 41 42 @verbatim 43 44 ------------------------------------------------------------------------------- 45 1. File structure: 46 ------------------------------------------------------------------------------- 47 48 ---------------------- 49 | Header (512 bytes) | 50 ---------------------- 51 | Variable chunks | 52 ---------------------- 53 54 ------------------------------------------------------------------------------- 55 2. Definitions: 56 ------------------------------------------------------------------------------- 57 58 integer is four bytes wide, stored in little-endian byte order. 59 short is two bytes wide, stored in little-endian byte order. 60 byte is a single byte. 61 string is an integer n followed by n UTF-8 characters, not terminated by zero 62 float is an IEEE 754 single-precision floating-point value 63 double is an IEEE 754 double-precision floating-point value 64 t[n] is an array of n elements of type t 65 66 ------------------------------------------------------------------------------- 67 2. Header: 68 ------------------------------------------------------------------------------- 69 70 byte[44] Magic identification string for ASSBIN files. 71 'ASSIMP.binary' 72 73 integer Major version of the Assimp library which wrote the file 74 integer Minor version of the Assimp library which wrote the file 75 match these against ASSBIN_VERSION_MAJOR and ASSBIN_VERSION_MINOR 76 77 integer SVN revision of the Assimp library (intended for our internal 78 debugging - if you write Ass files from your own APPs, set this value to 0. 79 integer Assimp compile flags 80 81 short 0 for normal files, 1 for shortened dumps for regression tests 82 these should have the file extension assbin.regress 83 84 short 1 if the data after the header is compressed with the DEFLATE algorithm, 85 0 for uncompressed files. 86 For compressed files, the first integer after the header is 87 always the uncompressed data size 88 89 byte[256] Zero-terminated source file name, UTF-8 90 byte[128] Zero-terminated command line parameters passed to assimp_cmd, UTF-8 91 92 byte[64] Reserved for future use 93 ---> Total length: 512 bytes 94 95 ------------------------------------------------------------------------------- 96 3. Chunks: 97 ------------------------------------------------------------------------------- 98 99 integer Magic chunk ID (ASSBIN_CHUNK_XXX) 100 integer Chunk data length, in bytes 101 (unknown chunks are possible, a good reader skips over them) 102 (chunk-data-length does not include the first two integers) 103 104 byte[n] chunk-data-length bytes of data, depending on the chunk type 105 106 Chunks can contain nested chunks. Nested chunks are ALWAYS at the end of the chunk, 107 their size is included in chunk-data-length. 108 109 The chunk layout for all ASSIMP data structures is derived from their C declarations. 110 The general 'rule' to get from Assimp headers to the serialized layout is: 111 112 1. POD members (i.e. aiMesh::mPrimitiveTypes, aiMesh::mNumVertices), 113 in order of declaration. 114 115 2. Array-members (aiMesh::mFaces, aiMesh::mVertices, aiBone::mWeights), 116 in order of declaration. 117 118 2. Object array members (i.e aiMesh::mBones, aiScene::mMeshes) are stored in 119 subchunks directly following the data written in 1.) and 2.) 120 121 122 Of course, there are some exceptions to this general order: 123 124 [[aiScene]] 125 126 - The root node holding the scene structure is naturally stored in 127 a ASSBIN_CHUNK_AINODE subchunk following 1.) and 2.) (which is 128 empty for aiScene). 129 130 [[aiMesh]] 131 132 - mTextureCoords and mNumUVComponents are serialized as follows: 133 134 [number of used uv channels times] 135 integer mNumUVComponents[n] 136 float mTextureCoords[n][3] 137 138 -> more than AI_MAX_TEXCOORD_CHANNELS can be stored. This allows Assimp 139 builds with different settings for AI_MAX_TEXCOORD_CHANNELS to exchange 140 data. 141 -> the on-disk format always uses 3 floats to write UV coordinates. 142 If mNumUVComponents[0] is 1, the corresponding mTextureCoords array 143 consists of 3 floats. 144 145 - The array member block of aiMesh is prefixed with an integer that specifies 146 the kinds of vertex components actually present in the mesh. This is a 147 bitwise combination of the ASSBIN_MESH_HAS_xxx constants. 148 149 [[aiFace]] 150 151 - mNumIndices is stored as short 152 - mIndices are written as short, if aiMesh::mNumVertices<65536 153 154 [[aiNode]] 155 156 - mParent is omitted 157 158 [[aiLight]] 159 160 - mAttenuationXXX not written if aiLight::mType == aiLightSource_DIRECTIONAL 161 - mAngleXXX not written if aiLight::mType != aiLightSource_SPOT 162 163 [[aiMaterial]] 164 165 - mNumAllocated is omitted, for obvious reasons :-) 166 167 168 @endverbatim*/ 169 170 171 #define ASSBIN_HEADER_LENGTH 512 172 173 // these are the magic chunk identifiers for the binary ASS file format 174 #define ASSBIN_CHUNK_AICAMERA 0x1234 175 #define ASSBIN_CHUNK_AILIGHT 0x1235 176 #define ASSBIN_CHUNK_AITEXTURE 0x1236 177 #define ASSBIN_CHUNK_AIMESH 0x1237 178 #define ASSBIN_CHUNK_AINODEANIM 0x1238 179 #define ASSBIN_CHUNK_AISCENE 0x1239 180 #define ASSBIN_CHUNK_AIBONE 0x123a 181 #define ASSBIN_CHUNK_AIANIMATION 0x123b 182 #define ASSBIN_CHUNK_AINODE 0x123c 183 #define ASSBIN_CHUNK_AIMATERIAL 0x123d 184 #define ASSBIN_CHUNK_AIMATERIALPROPERTY 0x123e 185 186 #define ASSBIN_MESH_HAS_POSITIONS 0x1 187 #define ASSBIN_MESH_HAS_NORMALS 0x2 188 #define ASSBIN_MESH_HAS_TANGENTS_AND_BITANGENTS 0x4 189 #define ASSBIN_MESH_HAS_TEXCOORD_BASE 0x100 190 #define ASSBIN_MESH_HAS_COLOR_BASE 0x10000 191 192 #define ASSBIN_MESH_HAS_TEXCOORD(n) (ASSBIN_MESH_HAS_TEXCOORD_BASE << n) 193 #define ASSBIN_MESH_HAS_COLOR(n) (ASSBIN_MESH_HAS_COLOR_BASE << n) 194 195 196 #endif // INCLUDED_ASSBIN_CHUNKS_H 197