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