vrshoot
view libs/assimp/assbin_chunks.h @ 0:b2f14e535253
initial commit
| author | John Tsiombikas <nuclear@member.fsf.org> |
|---|---|
| date | Sat, 01 Feb 2014 19:58:19 +0200 |
| parents | |
| children |
line source
2 #ifndef INCLUDED_ASSBIN_CHUNKS_H
3 #define INCLUDED_ASSBIN_CHUNKS_H
5 #define ASSBIN_VERSION_MAJOR 1
6 #define ASSBIN_VERSION_MINOR 0
8 /**
9 @page assfile .ASS File formats
11 @section over Overview
12 Assimp provides its own interchange format, which is intended to applications which need
13 to serialize 3D-models and to reload them quickly. Assimp's file formats are designed to
14 be read by Assimp itself. They encode additional information needed by Assimp to optimize
15 its postprocessing pipeline. If you once apply specific steps to a scene, then save it
16 and reread it from an ASS format using the same post processing settings, they won't
17 be executed again.
19 The format comes in two flavours: XML and binary - both of them hold a complete dump of
20 the 'aiScene' data structure returned by the APIs. The focus for the binary format
21 (<tt>.assbin</tt>) is fast loading. Optional deflate compression helps reduce file size. The XML
22 flavour, <tt>.assxml</tt> or simply .xml, is just a plain-to-xml conversion of aiScene.
24 ASSBIN is Assimp's binary interchange format. assimp_cmd (<tt><root>/tools/assimp_cmd</tt>) is able to
25 write it and the core library provides a loader for it.
27 @section assxml XML File format
29 The format is pretty much self-explanatory due to its similarity to the in-memory aiScene structure.
30 With few exceptions, C structures are wrapped in XML elements.
32 The DTD for ASSXML can be found in <tt><root>/doc/AssXML_Scheme.xml</tt>. Or have look
33 at the output files generated by assimp_cmd.
35 @section assbin Binary file format
37 The ASSBIN file format is composed of chunks to represent the hierarchical aiScene data structure.
38 This makes the format extensible and allows backward-compatibility with future data structure
39 versions. The <tt><root>/code/assbin_chunks.h</tt> header contains some magic constants
40 for use by stand-alone ASSBIN loaders. Also, Assimp's own file writer can be found
41 in <tt><root>/tools/assimp_cmd/WriteDumb.cpp</tt> (yes, the 'b' is no typo ...).
43 @verbatim
45 -------------------------------------------------------------------------------
46 1. File structure:
47 -------------------------------------------------------------------------------
49 ----------------------
50 | Header (500 bytes) |
51 ----------------------
52 | Variable chunks |
53 ----------------------
55 -------------------------------------------------------------------------------
56 2. Definitions:
57 -------------------------------------------------------------------------------
59 integer is four bytes wide, stored in little-endian byte order.
60 short is two bytes wide, stored in little-endian byte order.
61 byte is a single byte.
62 string is an integer n followed by n UTF-8 characters, not terminated by zero
63 float is an IEEE 754 single-precision floating-point value
64 double is an IEEE 754 double-precision floating-point value
65 t[n] is an array of n elements of type t
67 -------------------------------------------------------------------------------
68 2. Header:
69 -------------------------------------------------------------------------------
71 byte[44] Magic identification string for ASSBIN files.
72 'ASSIMP.binary'
74 integer Major version of the Assimp library which wrote the file
75 integer Minor version of the Assimp library which wrote the file
76 match these against ASSBIN_VERSION_MAJOR and ASSBIN_VERSION_MINOR
78 integer SVN revision of the Assimp library (intended for our internal
79 debugging - if you write Ass files from your own APPs, set this value to 0.
80 integer Assimp compile flags
82 short 0 for normal files, 1 for shortened dumps for regression tests
83 these should have the file extension assbin.regress
85 short 1 if the data after the header is compressed with the DEFLATE algorithm,
86 0 for uncompressed files.
87 For compressed files, the first integer after the header is
88 always the uncompressed data size
90 byte[256] Zero-terminated source file name, UTF-8
91 byte[128] Zero-terminated command line parameters passed to assimp_cmd, UTF-8
93 byte[64] Reserved for future use
94 ---> Total length: 512 bytes
96 -------------------------------------------------------------------------------
97 3. Chunks:
98 -------------------------------------------------------------------------------
100 integer Magic chunk ID (ASSBIN_CHUNK_XXX)
101 integer Chunk data length, in bytes
102 (unknown chunks are possible, a good reader skips over them)
104 byte[n] length-of-chunk bytes of data, depending on the chunk type
106 Chunks can contain nested chunks. Nested chunks are ALWAYS at the end of the chunk,
107 their size is included in length-of-chunk.
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:
112 1. POD members (i.e. aiMesh::mPrimitiveTypes, aiMesh::mNumVertices),
113 in order of declaration.
115 2. Array-members (aiMesh::mFaces, aiMesh::mVertices, aiBone::mWeights),
116 in order of declaration.
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.)
122 Of course, there are some exceptions to this general order:
124 [[aiScene]]
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).
130 [[aiMesh]]
132 - mTextureCoords and mNumUVComponents are serialized as follows:
134 [number of used uv channels times]
135 integer mNumUVComponents[n]
136 float mTextureCoords[n][mNumUVComponents[n]]
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. Unlike the in-memory format, only the used components of the
141 UV coordinates are written to disk. If mNumUVComponents[0] is 1, the
142 corresponding mTextureCoords array consists of mNumTextureCoords*1
143 single floats.
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.
149 [[aiFace]]
151 - mNumIndices is stored as short
152 - mIndices are written as short, if aiMesh::mNumVertices<65536
154 [[aiNode]]
156 - mParent is omitted
158 [[aiLight]]
160 - mAttenuationXXX not written if aiLight::mType == aiLightSource_DIRECTIONAL
161 - mAngleXXX not written if aiLight::mType != aiLightSource_SPOT
163 [[aiMaterial]]
165 - mNumAllocated is omitted, for obvious reasons :-)
168 @endverbatim*/
171 #define ASSBIN_HEADER_LENGTH 512
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
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
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)
196 #endif // INCLUDED_ASSBIN_CHUNKS_H