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
11Assimp provides its own interchange format, which is intended to applications which need
12to serialize 3D-models and to reload them quickly. Assimp's file formats are designed to
13be read by Assimp itself. They encode additional information needed by Assimp to optimize
14its postprocessing pipeline. If you once apply specific steps to a scene, then save it
15and reread it from an ASS format using the same post processing settings, they won't
16be executed again.
17
18The format comes in two flavours: XML and binary - both of them hold a complete dump of
19the '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
21flavour, <tt>.assxml</tt> or simply .xml, is just a plain-to-xml conversion of aiScene.
22
23ASSBIN is Assimp's binary interchange format. assimp_cmd (<tt>&lt;root&gt;/tools/assimp_cmd</tt>) is able to
24write it and the core library provides a loader for it.
25
26@section assxml XML File format
27
28The format is pretty much self-explanatory due to its similarity to the in-memory aiScene structure.
29With few exceptions, C structures are wrapped in XML elements.
30
31The DTD for ASSXML can be found in <tt>&lt;root&gt;/doc/AssXML_Scheme.xml</tt>. Or have look
32at the output files generated by assimp_cmd.
33
34@section assbin Binary file format
35
36The ASSBIN file format is composed of chunks to represent the hierarchical aiScene data structure.
37This makes the format extensible and allows backward-compatibility with future data structure
38versions. The <tt>&lt;root&gt;/code/assbin_chunks.h</tt> header contains some magic constants
39for use by stand-alone ASSBIN loaders. Also, Assimp's own file writer can be found
40in <tt>&lt;root&gt;/tools/assimp_cmd/WriteDumb.cpp</tt> (yes, the 'b' is no typo ...).
41
42@verbatim
43
44-------------------------------------------------------------------------------
451. File structure:
46-------------------------------------------------------------------------------
47
48----------------------
49| Header (512 bytes) |
50----------------------
51| Variable chunks |
52----------------------
53
54-------------------------------------------------------------------------------
552. Definitions:
56-------------------------------------------------------------------------------
57
58integer is four bytes wide, stored in little-endian byte order.
59short is two bytes wide, stored in little-endian byte order.
60byte is a single byte.
61string is an integer n followed by n UTF-8 characters, not terminated by zero
62float is an IEEE 754 single-precision floating-point value
63double is an IEEE 754 double-precision floating-point value
64t[n] is an array of n elements of type t
65
66-------------------------------------------------------------------------------
672. Header:
68-------------------------------------------------------------------------------
69
70byte[44] Magic identification string for ASSBIN files.
71 'ASSIMP.binary'
72
73integer Major version of the Assimp library which wrote the file
74integer Minor version of the Assimp library which wrote the file
75 match these against ASSBIN_VERSION_MAJOR and ASSBIN_VERSION_MINOR
76
77integer 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.
79integer Assimp compile flags
80
81short 0 for normal files, 1 for shortened dumps for regression tests
82 these should have the file extension assbin.regress
83
84short 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
89byte[256] Zero-terminated source file name, UTF-8
90byte[128] Zero-terminated command line parameters passed to assimp_cmd, UTF-8
91
92byte[64] Reserved for future use
93---> Total length: 512 bytes
94
95-------------------------------------------------------------------------------
963. Chunks:
97-------------------------------------------------------------------------------
98
99integer Magic chunk ID (ASSBIN_CHUNK_XXX)
100integer 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
104byte[n] chunk-data-length bytes of data, depending on the chunk type
105
106Chunks can contain nested chunks. Nested chunks are ALWAYS at the end of the chunk,
107their size is included in chunk-data-length.
108
109The chunk layout for all ASSIMP data structures is derived from their C declarations.
110The 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