nuclear@0: nuclear@0: #ifndef INCLUDED_ASSBIN_CHUNKS_H nuclear@0: #define INCLUDED_ASSBIN_CHUNKS_H nuclear@0: nuclear@0: #define ASSBIN_VERSION_MAJOR 1 nuclear@0: #define ASSBIN_VERSION_MINOR 0 nuclear@0: nuclear@0: /** nuclear@0: @page assfile .ASS File formats nuclear@0: nuclear@0: @section over Overview nuclear@0: Assimp provides its own interchange format, which is intended to applications which need nuclear@0: to serialize 3D-models and to reload them quickly. Assimp's file formats are designed to nuclear@0: be read by Assimp itself. They encode additional information needed by Assimp to optimize nuclear@0: its postprocessing pipeline. If you once apply specific steps to a scene, then save it nuclear@0: and reread it from an ASS format using the same post processing settings, they won't nuclear@0: be executed again. nuclear@0: nuclear@0: The format comes in two flavours: XML and binary - both of them hold a complete dump of nuclear@0: the 'aiScene' data structure returned by the APIs. The focus for the binary format nuclear@0: (.assbin) is fast loading. Optional deflate compression helps reduce file size. The XML nuclear@0: flavour, .assxml or simply .xml, is just a plain-to-xml conversion of aiScene. nuclear@0: nuclear@0: ASSBIN is Assimp's binary interchange format. assimp_cmd (<root>/tools/assimp_cmd) is able to nuclear@0: write it and the core library provides a loader for it. nuclear@0: nuclear@0: @section assxml XML File format nuclear@0: nuclear@0: The format is pretty much self-explanatory due to its similarity to the in-memory aiScene structure. nuclear@0: With few exceptions, C structures are wrapped in XML elements. nuclear@0: nuclear@0: The DTD for ASSXML can be found in <root>/doc/AssXML_Scheme.xml. Or have look nuclear@0: at the output files generated by assimp_cmd. nuclear@0: nuclear@0: @section assbin Binary file format nuclear@0: nuclear@0: The ASSBIN file format is composed of chunks to represent the hierarchical aiScene data structure. nuclear@0: This makes the format extensible and allows backward-compatibility with future data structure nuclear@0: versions. The <root>/code/assbin_chunks.h header contains some magic constants nuclear@0: for use by stand-alone ASSBIN loaders. Also, Assimp's own file writer can be found nuclear@0: in <root>/tools/assimp_cmd/WriteDumb.cpp (yes, the 'b' is no typo ...). nuclear@0: nuclear@0: @verbatim nuclear@0: nuclear@0: ------------------------------------------------------------------------------- nuclear@0: 1. File structure: nuclear@0: ------------------------------------------------------------------------------- nuclear@0: nuclear@0: ---------------------- nuclear@0: | Header (500 bytes) | nuclear@0: ---------------------- nuclear@0: | Variable chunks | nuclear@0: ---------------------- nuclear@0: nuclear@0: ------------------------------------------------------------------------------- nuclear@0: 2. Definitions: nuclear@0: ------------------------------------------------------------------------------- nuclear@0: nuclear@0: integer is four bytes wide, stored in little-endian byte order. nuclear@0: short is two bytes wide, stored in little-endian byte order. nuclear@0: byte is a single byte. nuclear@0: string is an integer n followed by n UTF-8 characters, not terminated by zero nuclear@0: float is an IEEE 754 single-precision floating-point value nuclear@0: double is an IEEE 754 double-precision floating-point value nuclear@0: t[n] is an array of n elements of type t nuclear@0: nuclear@0: ------------------------------------------------------------------------------- nuclear@0: 2. Header: nuclear@0: ------------------------------------------------------------------------------- nuclear@0: nuclear@0: byte[44] Magic identification string for ASSBIN files. nuclear@0: 'ASSIMP.binary' nuclear@0: nuclear@0: integer Major version of the Assimp library which wrote the file nuclear@0: integer Minor version of the Assimp library which wrote the file nuclear@0: match these against ASSBIN_VERSION_MAJOR and ASSBIN_VERSION_MINOR nuclear@0: nuclear@0: integer SVN revision of the Assimp library (intended for our internal nuclear@0: debugging - if you write Ass files from your own APPs, set this value to 0. nuclear@0: integer Assimp compile flags nuclear@0: nuclear@0: short 0 for normal files, 1 for shortened dumps for regression tests nuclear@0: these should have the file extension assbin.regress nuclear@0: nuclear@0: short 1 if the data after the header is compressed with the DEFLATE algorithm, nuclear@0: 0 for uncompressed files. nuclear@0: For compressed files, the first integer after the header is nuclear@0: always the uncompressed data size nuclear@0: nuclear@0: byte[256] Zero-terminated source file name, UTF-8 nuclear@0: byte[128] Zero-terminated command line parameters passed to assimp_cmd, UTF-8 nuclear@0: nuclear@0: byte[64] Reserved for future use nuclear@0: ---> Total length: 512 bytes nuclear@0: nuclear@0: ------------------------------------------------------------------------------- nuclear@0: 3. Chunks: nuclear@0: ------------------------------------------------------------------------------- nuclear@0: nuclear@0: integer Magic chunk ID (ASSBIN_CHUNK_XXX) nuclear@0: integer Chunk data length, in bytes nuclear@0: (unknown chunks are possible, a good reader skips over them) nuclear@0: nuclear@0: byte[n] length-of-chunk bytes of data, depending on the chunk type nuclear@0: nuclear@0: Chunks can contain nested chunks. Nested chunks are ALWAYS at the end of the chunk, nuclear@0: their size is included in length-of-chunk. nuclear@0: nuclear@0: The chunk layout for all ASSIMP data structures is derived from their C declarations. nuclear@0: The general 'rule' to get from Assimp headers to the serialized layout is: nuclear@0: nuclear@0: 1. POD members (i.e. aiMesh::mPrimitiveTypes, aiMesh::mNumVertices), nuclear@0: in order of declaration. nuclear@0: nuclear@0: 2. Array-members (aiMesh::mFaces, aiMesh::mVertices, aiBone::mWeights), nuclear@0: in order of declaration. nuclear@0: nuclear@0: 2. Object array members (i.e aiMesh::mBones, aiScene::mMeshes) are stored in nuclear@0: subchunks directly following the data written in 1.) and 2.) nuclear@0: nuclear@0: nuclear@0: Of course, there are some exceptions to this general order: nuclear@0: nuclear@0: [[aiScene]] nuclear@0: nuclear@0: - The root node holding the scene structure is naturally stored in nuclear@0: a ASSBIN_CHUNK_AINODE subchunk following 1.) and 2.) (which is nuclear@0: empty for aiScene). nuclear@0: nuclear@0: [[aiMesh]] nuclear@0: nuclear@0: - mTextureCoords and mNumUVComponents are serialized as follows: nuclear@0: nuclear@0: [number of used uv channels times] nuclear@0: integer mNumUVComponents[n] nuclear@0: float mTextureCoords[n][mNumUVComponents[n]] nuclear@0: nuclear@0: -> more than AI_MAX_TEXCOORD_CHANNELS can be stored. This allows Assimp nuclear@0: builds with different settings for AI_MAX_TEXCOORD_CHANNELS to exchange nuclear@0: data. Unlike the in-memory format, only the used components of the nuclear@0: UV coordinates are written to disk. If mNumUVComponents[0] is 1, the nuclear@0: corresponding mTextureCoords array consists of mNumTextureCoords*1 nuclear@0: single floats. nuclear@0: nuclear@0: - The array member block of aiMesh is prefixed with an integer that specifies nuclear@0: the kinds of vertex components actually present in the mesh. This is a nuclear@0: bitwise combination of the ASSBIN_MESH_HAS_xxx constants. nuclear@0: nuclear@0: [[aiFace]] nuclear@0: nuclear@0: - mNumIndices is stored as short nuclear@0: - mIndices are written as short, if aiMesh::mNumVertices<65536 nuclear@0: nuclear@0: [[aiNode]] nuclear@0: nuclear@0: - mParent is omitted nuclear@0: nuclear@0: [[aiLight]] nuclear@0: nuclear@0: - mAttenuationXXX not written if aiLight::mType == aiLightSource_DIRECTIONAL nuclear@0: - mAngleXXX not written if aiLight::mType != aiLightSource_SPOT nuclear@0: nuclear@0: [[aiMaterial]] nuclear@0: nuclear@0: - mNumAllocated is omitted, for obvious reasons :-) nuclear@0: nuclear@0: nuclear@0: @endverbatim*/ nuclear@0: nuclear@0: nuclear@0: #define ASSBIN_HEADER_LENGTH 512 nuclear@0: nuclear@0: // these are the magic chunk identifiers for the binary ASS file format nuclear@0: #define ASSBIN_CHUNK_AICAMERA 0x1234 nuclear@0: #define ASSBIN_CHUNK_AILIGHT 0x1235 nuclear@0: #define ASSBIN_CHUNK_AITEXTURE 0x1236 nuclear@0: #define ASSBIN_CHUNK_AIMESH 0x1237 nuclear@0: #define ASSBIN_CHUNK_AINODEANIM 0x1238 nuclear@0: #define ASSBIN_CHUNK_AISCENE 0x1239 nuclear@0: #define ASSBIN_CHUNK_AIBONE 0x123a nuclear@0: #define ASSBIN_CHUNK_AIANIMATION 0x123b nuclear@0: #define ASSBIN_CHUNK_AINODE 0x123c nuclear@0: #define ASSBIN_CHUNK_AIMATERIAL 0x123d nuclear@0: #define ASSBIN_CHUNK_AIMATERIALPROPERTY 0x123e nuclear@0: nuclear@0: #define ASSBIN_MESH_HAS_POSITIONS 0x1 nuclear@0: #define ASSBIN_MESH_HAS_NORMALS 0x2 nuclear@0: #define ASSBIN_MESH_HAS_TANGENTS_AND_BITANGENTS 0x4 nuclear@0: #define ASSBIN_MESH_HAS_TEXCOORD_BASE 0x100 nuclear@0: #define ASSBIN_MESH_HAS_COLOR_BASE 0x10000 nuclear@0: nuclear@0: #define ASSBIN_MESH_HAS_TEXCOORD(n) (ASSBIN_MESH_HAS_TEXCOORD_BASE << n) nuclear@0: #define ASSBIN_MESH_HAS_COLOR(n) (ASSBIN_MESH_HAS_COLOR_BASE << n) nuclear@0: nuclear@0: nuclear@0: #endif // INCLUDED_ASSBIN_CHUNKS_H