1/*
2---------------------------------------------------------------------------
3Open Asset Import Library (assimp)
4---------------------------------------------------------------------------
5
6Copyright (c) 2006-2019, assimp team
7
8
9
10All rights reserved.
11
12Redistribution and use of this software in source and binary forms,
13with or without modification, are permitted provided that the following
14conditions 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
30THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
31"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
32LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
33A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
34OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
35SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
36LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
37DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
38THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
39(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
40OF 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>
62extern "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// -------------------------------------------------------------------------------
80struct 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// -------------------------------------------------------------------------------
242struct 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

source code of qt3d/src/3rdparty/assimp/src/include/assimp/scene.h