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