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