1 | /* |
2 | --------------------------------------------------------------------------- |
3 | Open Asset Import Library (assimp) |
4 | --------------------------------------------------------------------------- |
5 | |
6 | Copyright (c) 2006-2017, assimp team |
7 | |
8 | |
9 | All rights reserved. |
10 | |
11 | Redistribution and use of this software in source and binary forms, |
12 | with or without modification, are permitted provided that the following |
13 | conditions are met: |
14 | |
15 | * Redistributions of source code must retain the above |
16 | copyright notice, this list of conditions and the |
17 | following disclaimer. |
18 | |
19 | * Redistributions in binary form must reproduce the above |
20 | copyright notice, this list of conditions and the |
21 | following disclaimer in the documentation and/or other |
22 | materials provided with the distribution. |
23 | |
24 | * Neither the name of the assimp team, nor the names of its |
25 | contributors may be used to endorse or promote products |
26 | derived from this software without specific prior |
27 | written permission of the assimp team. |
28 | |
29 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
30 | "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
31 | LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |
32 | A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT |
33 | OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
34 | SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |
35 | LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
36 | DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
37 | THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
38 | (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE |
39 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
40 | --------------------------------------------------------------------------- |
41 | */ |
42 | |
43 | /** @file scene.h |
44 | * @brief Defines the data structures in which the imported scene is returned. |
45 | */ |
46 | #pragma once |
47 | #ifndef AI_SCENE_H_INC |
48 | #define AI_SCENE_H_INC |
49 | |
50 | #include "types.h" |
51 | #include "texture.h" |
52 | #include "mesh.h" |
53 | #include "light.h" |
54 | #include "camera.h" |
55 | #include "material.h" |
56 | #include "anim.h" |
57 | #include "metadata.h" |
58 | |
59 | #ifdef __cplusplus |
60 | extern "C" { |
61 | #endif |
62 | |
63 | #ifdef __GNUC__ |
64 | #pragma GCC diagnostic push |
65 | #pragma GCC diagnostic ignored "-Wattributes" |
66 | #endif |
67 | |
68 | // ------------------------------------------------------------------------------- |
69 | /** |
70 | * A node in the imported hierarchy. |
71 | * |
72 | * Each node has name, a parent node (except for the root node), |
73 | * a transformation relative to its parent and possibly several child nodes. |
74 | * Simple file formats don't support hierarchical structures - for these formats |
75 | * the imported scene does consist of only a single root node without children. |
76 | */ |
77 | // ------------------------------------------------------------------------------- |
78 | struct ASSIMP_API aiNode |
79 | { |
80 | /** The name of the node. |
81 | * |
82 | * The name might be empty (length of zero) but all nodes which |
83 | * need to be referenced by either bones or animations are named. |
84 | * Multiple nodes may have the same name, except for nodes which are referenced |
85 | * by bones (see #aiBone and #aiMesh::mBones). Their names *must* be unique. |
86 | * |
87 | * Cameras and lights reference a specific node by name - if there |
88 | * are multiple nodes with this name, they are assigned to each of them. |
89 | * <br> |
90 | * There are no limitations with regard to the characters contained in |
91 | * the name string as it is usually taken directly from the source file. |
92 | * |
93 | * Implementations should be able to handle tokens such as whitespace, tabs, |
94 | * line feeds, quotation marks, ampersands etc. |
95 | * |
96 | * Sometimes assimp introduces new nodes not present in the source file |
97 | * into the hierarchy (usually out of necessity because sometimes the |
98 | * source hierarchy format is simply not compatible). Their names are |
99 | * surrounded by @verbatim <> @endverbatim e.g. |
100 | * @verbatim<DummyRootNode> @endverbatim. |
101 | */ |
102 | C_STRUCT aiString mName; |
103 | |
104 | /** The transformation relative to the node's parent. */ |
105 | C_STRUCT aiMatrix4x4 mTransformation; |
106 | |
107 | /** Parent node. NULL if this node is the root node. */ |
108 | C_STRUCT aiNode* mParent; |
109 | |
110 | /** The number of child nodes of this node. */ |
111 | unsigned int mNumChildren; |
112 | |
113 | /** The child nodes of this node. NULL if mNumChildren is 0. */ |
114 | C_STRUCT aiNode** mChildren; |
115 | |
116 | /** The number of meshes of this node. */ |
117 | unsigned int mNumMeshes; |
118 | |
119 | /** The meshes of this node. Each entry is an index into the |
120 | * mesh list of the #aiScene. |
121 | */ |
122 | unsigned int* mMeshes; |
123 | |
124 | /** Metadata associated with this node or NULL if there is no metadata. |
125 | * Whether any metadata is generated depends on the source file format. See the |
126 | * @link importer_notes @endlink page for more information on every source file |
127 | * format. Importers that don't document any metadata don't write any. |
128 | */ |
129 | C_STRUCT aiMetadata* mMetaData; |
130 | |
131 | #ifdef __cplusplus |
132 | /** Constructor */ |
133 | aiNode(); |
134 | |
135 | /** Construction from a specific name */ |
136 | explicit aiNode(const std::string& name); |
137 | |
138 | /** Destructor */ |
139 | ~aiNode(); |
140 | |
141 | /** Searches for a node with a specific name, beginning at this |
142 | * nodes. Normally you will call this method on the root node |
143 | * of the scene. |
144 | * |
145 | * @param name Name to search for |
146 | * @return NULL or a valid Node if the search was successful. |
147 | */ |
148 | inline |
149 | const aiNode* FindNode(const aiString& name) const { |
150 | return FindNode(name.data); |
151 | } |
152 | |
153 | inline |
154 | aiNode* FindNode(const aiString& name) { |
155 | return FindNode(name.data); |
156 | } |
157 | |
158 | const aiNode* FindNode(const char* name) const; |
159 | |
160 | aiNode* FindNode(const char* name); |
161 | |
162 | /** |
163 | * @brief Will add new children. |
164 | * @param numChildren Number of children to add. |
165 | * @param children The array with pointers showing to the children. |
166 | */ |
167 | void addChildren(unsigned int numChildren, aiNode **children); |
168 | #endif // __cplusplus |
169 | }; |
170 | |
171 | #ifdef __GNUC__ |
172 | #pragma GCC diagnostic pop |
173 | #endif |
174 | |
175 | // ------------------------------------------------------------------------------- |
176 | /** |
177 | * Specifies that the scene data structure that was imported is not complete. |
178 | * This flag bypasses some internal validations and allows the import |
179 | * of animation skeletons, material libraries or camera animation paths |
180 | * using Assimp. Most applications won't support such data. |
181 | */ |
182 | #define AI_SCENE_FLAGS_INCOMPLETE 0x1 |
183 | |
184 | /** |
185 | * This flag is set by the validation postprocess-step (aiPostProcess_ValidateDS) |
186 | * if the validation is successful. In a validated scene you can be sure that |
187 | * any cross references in the data structure (e.g. vertex indices) are valid. |
188 | */ |
189 | #define AI_SCENE_FLAGS_VALIDATED 0x2 |
190 | |
191 | /** |
192 | * This flag is set by the validation postprocess-step (aiPostProcess_ValidateDS) |
193 | * if the validation is successful but some issues have been found. |
194 | * This can for example mean that a texture that does not exist is referenced |
195 | * by a material or that the bone weights for a vertex don't sum to 1.0 ... . |
196 | * In most cases you should still be able to use the import. This flag could |
197 | * be useful for applications which don't capture Assimp's log output. |
198 | */ |
199 | #define AI_SCENE_FLAGS_VALIDATION_WARNING 0x4 |
200 | |
201 | /** |
202 | * This flag is currently only set by the aiProcess_JoinIdenticalVertices step. |
203 | * It indicates that the vertices of the output meshes aren't in the internal |
204 | * verbose format anymore. In the verbose format all vertices are unique, |
205 | * no vertex is ever referenced by more than one face. |
206 | */ |
207 | #define AI_SCENE_FLAGS_NON_VERBOSE_FORMAT 0x8 |
208 | |
209 | /** |
210 | * Denotes pure height-map terrain data. Pure terrains usually consist of quads, |
211 | * sometimes triangles, in a regular grid. The x,y coordinates of all vertex |
212 | * positions refer to the x,y coordinates on the terrain height map, the z-axis |
213 | * stores the elevation at a specific point. |
214 | * |
215 | * TER (Terragen) and HMP (3D Game Studio) are height map formats. |
216 | * @note Assimp is probably not the best choice for loading *huge* terrains - |
217 | * fully triangulated data takes extremely much free store and should be avoided |
218 | * as long as possible (typically you'll do the triangulation when you actually |
219 | * need to render it). |
220 | */ |
221 | #define AI_SCENE_FLAGS_TERRAIN 0x10 |
222 | |
223 | /** |
224 | * Specifies that the scene data can be shared between structures. For example: |
225 | * one vertex in few faces. \ref AI_SCENE_FLAGS_NON_VERBOSE_FORMAT can not be |
226 | * used for this because \ref AI_SCENE_FLAGS_NON_VERBOSE_FORMAT has internal |
227 | * meaning about postprocessing steps. |
228 | */ |
229 | #define AI_SCENE_FLAGS_ALLOW_SHARED 0x20 |
230 | |
231 | // ------------------------------------------------------------------------------- |
232 | /** The root structure of the imported data. |
233 | * |
234 | * Everything that was imported from the given file can be accessed from here. |
235 | * Objects of this class are generally maintained and owned by Assimp, not |
236 | * by the caller. You shouldn't want to instance it, nor should you ever try to |
237 | * delete a given scene on your own. |
238 | */ |
239 | // ------------------------------------------------------------------------------- |
240 | struct aiScene |
241 | { |
242 | /** Any combination of the AI_SCENE_FLAGS_XXX flags. By default |
243 | * this value is 0, no flags are set. Most applications will |
244 | * want to reject all scenes with the AI_SCENE_FLAGS_INCOMPLETE |
245 | * bit set. |
246 | */ |
247 | unsigned int mFlags; |
248 | |
249 | /** The root node of the hierarchy. |
250 | * |
251 | * There will always be at least the root node if the import |
252 | * was successful (and no special flags have been set). |
253 | * Presence of further nodes depends on the format and content |
254 | * of the imported file. |
255 | */ |
256 | C_STRUCT aiNode* mRootNode; |
257 | |
258 | /** The number of meshes in the scene. */ |
259 | unsigned int mNumMeshes; |
260 | |
261 | /** The array of meshes. |
262 | * |
263 | * Use the indices given in the aiNode structure to access |
264 | * this array. The array is mNumMeshes in size. If the |
265 | * AI_SCENE_FLAGS_INCOMPLETE flag is not set there will always |
266 | * be at least ONE material. |
267 | */ |
268 | C_STRUCT aiMesh** mMeshes; |
269 | |
270 | /** The number of materials in the scene. */ |
271 | unsigned int mNumMaterials; |
272 | |
273 | /** The array of materials. |
274 | * |
275 | * Use the index given in each aiMesh structure to access this |
276 | * array. The array is mNumMaterials in size. If the |
277 | * AI_SCENE_FLAGS_INCOMPLETE flag is not set there will always |
278 | * be at least ONE material. |
279 | */ |
280 | C_STRUCT aiMaterial** mMaterials; |
281 | |
282 | /** The number of animations in the scene. */ |
283 | unsigned int mNumAnimations; |
284 | |
285 | /** The array of animations. |
286 | * |
287 | * All animations imported from the given file are listed here. |
288 | * The array is mNumAnimations in size. |
289 | */ |
290 | C_STRUCT aiAnimation** mAnimations; |
291 | |
292 | /** The number of textures embedded into the file */ |
293 | unsigned int mNumTextures; |
294 | |
295 | /** The array of embedded textures. |
296 | * |
297 | * Not many file formats embed their textures into the file. |
298 | * An example is Quake's MDL format (which is also used by |
299 | * some GameStudio versions) |
300 | */ |
301 | C_STRUCT aiTexture** mTextures; |
302 | |
303 | /** The number of light sources in the scene. Light sources |
304 | * are fully optional, in most cases this attribute will be 0 |
305 | */ |
306 | unsigned int mNumLights; |
307 | |
308 | /** The array of light sources. |
309 | * |
310 | * All light sources imported from the given file are |
311 | * listed here. The array is mNumLights in size. |
312 | */ |
313 | C_STRUCT aiLight** mLights; |
314 | |
315 | /** The number of cameras in the scene. Cameras |
316 | * are fully optional, in most cases this attribute will be 0 |
317 | */ |
318 | unsigned int mNumCameras; |
319 | |
320 | /** The array of cameras. |
321 | * |
322 | * All cameras imported from the given file are listed here. |
323 | * The array is mNumCameras in size. The first camera in the |
324 | * array (if existing) is the default camera view into |
325 | * the scene. |
326 | */ |
327 | C_STRUCT aiCamera** mCameras; |
328 | |
329 | #ifdef __cplusplus |
330 | |
331 | //! Default constructor - set everything to 0/NULL |
332 | ASSIMP_API aiScene(); |
333 | |
334 | //! Destructor |
335 | ASSIMP_API ~aiScene(); |
336 | |
337 | //! Check whether the scene contains meshes |
338 | //! Unless no special scene flags are set this will always be true. |
339 | inline bool HasMeshes() const { |
340 | return mMeshes != NULL && mNumMeshes > 0; |
341 | } |
342 | |
343 | //! Check whether the scene contains materials |
344 | //! Unless no special scene flags are set this will always be true. |
345 | inline bool HasMaterials() const { |
346 | return mMaterials != NULL && mNumMaterials > 0; |
347 | } |
348 | |
349 | //! Check whether the scene contains lights |
350 | inline bool HasLights() const { |
351 | return mLights != NULL && mNumLights > 0; |
352 | } |
353 | |
354 | //! Check whether the scene contains textures |
355 | inline bool HasTextures() const { |
356 | return mTextures != NULL && mNumTextures > 0; |
357 | } |
358 | |
359 | //! Check whether the scene contains cameras |
360 | inline bool HasCameras() const { |
361 | return mCameras != NULL && mNumCameras > 0; |
362 | } |
363 | |
364 | //! Check whether the scene contains animations |
365 | inline bool HasAnimations() const { |
366 | return mAnimations != NULL && mNumAnimations > 0; |
367 | } |
368 | |
369 | #endif // __cplusplus |
370 | |
371 | /** Internal data, do not touch */ |
372 | #ifdef __cplusplus |
373 | void* mPrivate; |
374 | #else |
375 | char* mPrivate; |
376 | #endif |
377 | |
378 | }; |
379 | |
380 | #ifdef __cplusplus |
381 | } //! namespace Assimp |
382 | #endif |
383 | |
384 | #endif // AI_SCENE_H_INC |
385 | |