vrshoot

annotate libs/assimp/assbin_chunks.h @ 1:e7ca128b8713

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