miniassimp
view include/miniassimp/scene.h @ 0:879c81d94345
initial commit
| author | John Tsiombikas <nuclear@member.fsf.org> |
|---|---|
| date | Mon, 28 Jan 2019 18:19:26 +0200 |
| parents | |
| children |
line source
1 /*
2 ---------------------------------------------------------------------------
3 Open Asset Import Library (assimp)
4 ---------------------------------------------------------------------------
6 Copyright (c) 2006-2018, assimp team
10 All rights reserved.
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:
16 * Redistributions of source code must retain the above
17 copyright notice, this list of conditions and the
18 following disclaimer.
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.
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.
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 */
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
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"
60 #ifdef __cplusplus
61 extern "C" {
62 #endif
64 // -------------------------------------------------------------------------------
65 /**
66 * A node in the imported hierarchy.
67 *
68 * Each node has name, a parent node (except for the root node),
69 * a transformation relative to its parent and possibly several child nodes.
70 * Simple file formats don't support hierarchical structures - for these formats
71 * the imported scene does consist of only a single root node without children.
72 */
73 // -------------------------------------------------------------------------------
74 struct ASSIMP_API aiNode
75 {
76 /** The name of the node.
77 *
78 * The name might be empty (length of zero) but all nodes which
79 * need to be referenced by either bones or animations are named.
80 * Multiple nodes may have the same name, except for nodes which are referenced
81 * by bones (see #aiBone and #aiMesh::mBones). Their names *must* be unique.
82 *
83 * Cameras and lights reference a specific node by name - if there
84 * are multiple nodes with this name, they are assigned to each of them.
85 * <br>
86 * There are no limitations with regard to the characters contained in
87 * the name string as it is usually taken directly from the source file.
88 *
89 * Implementations should be able to handle tokens such as whitespace, tabs,
90 * line feeds, quotation marks, ampersands etc.
91 *
92 * Sometimes assimp introduces new nodes not present in the source file
93 * into the hierarchy (usually out of necessity because sometimes the
94 * source hierarchy format is simply not compatible). Their names are
95 * surrounded by @verbatim <> @endverbatim e.g.
96 * @verbatim<DummyRootNode> @endverbatim.
97 */
98 C_STRUCT aiString mName;
100 /** The transformation relative to the node's parent. */
101 C_STRUCT aiMatrix4x4 mTransformation;
103 /** Parent node. NULL if this node is the root node. */
104 C_STRUCT aiNode* mParent;
106 /** The number of child nodes of this node. */
107 unsigned int mNumChildren;
109 /** The child nodes of this node. NULL if mNumChildren is 0. */
110 C_STRUCT aiNode** mChildren;
112 /** The number of meshes of this node. */
113 unsigned int mNumMeshes;
115 /** The meshes of this node. Each entry is an index into the
116 * mesh list of the #aiScene.
117 */
118 unsigned int* mMeshes;
120 /** Metadata associated with this node or NULL if there is no metadata.
121 * Whether any metadata is generated depends on the source file format. See the
122 * @link importer_notes @endlink page for more information on every source file
123 * format. Importers that don't document any metadata don't write any.
124 */
125 C_STRUCT aiMetadata* mMetaData;
127 #ifdef __cplusplus
128 /** Constructor */
129 aiNode();
131 /** Construction from a specific name */
132 explicit aiNode(const std::string& name);
134 /** Destructor */
135 ~aiNode();
137 /** Searches for a node with a specific name, beginning at this
138 * nodes. Normally you will call this method on the root node
139 * of the scene.
140 *
141 * @param name Name to search for
142 * @return NULL or a valid Node if the search was successful.
143 */
144 inline
145 const aiNode* FindNode(const aiString& name) const {
146 return FindNode(name.data);
147 }
149 inline
150 aiNode* FindNode(const aiString& name) {
151 return FindNode(name.data);
152 }
154 const aiNode* FindNode(const char* name) const;
156 aiNode* FindNode(const char* name);
158 /**
159 * @brief Will add new children.
160 * @param numChildren Number of children to add.
161 * @param children The array with pointers showing to the children.
162 */
163 void addChildren(unsigned int numChildren, aiNode **children);
164 #endif // __cplusplus
165 };
167 // -------------------------------------------------------------------------------
168 /**
169 * Specifies that the scene data structure that was imported is not complete.
170 * This flag bypasses some internal validations and allows the import
171 * of animation skeletons, material libraries or camera animation paths
172 * using Assimp. Most applications won't support such data.
173 */
174 #define AI_SCENE_FLAGS_INCOMPLETE 0x1
176 /**
177 * This flag is set by the validation postprocess-step (aiPostProcess_ValidateDS)
178 * if the validation is successful. In a validated scene you can be sure that
179 * any cross references in the data structure (e.g. vertex indices) are valid.
180 */
181 #define AI_SCENE_FLAGS_VALIDATED 0x2
183 /**
184 * This flag is set by the validation postprocess-step (aiPostProcess_ValidateDS)
185 * if the validation is successful but some issues have been found.
186 * This can for example mean that a texture that does not exist is referenced
187 * by a material or that the bone weights for a vertex don't sum to 1.0 ... .
188 * In most cases you should still be able to use the import. This flag could
189 * be useful for applications which don't capture Assimp's log output.
190 */
191 #define AI_SCENE_FLAGS_VALIDATION_WARNING 0x4
193 /**
194 * This flag is currently only set by the aiProcess_JoinIdenticalVertices step.
195 * It indicates that the vertices of the output meshes aren't in the internal
196 * verbose format anymore. In the verbose format all vertices are unique,
197 * no vertex is ever referenced by more than one face.
198 */
199 #define AI_SCENE_FLAGS_NON_VERBOSE_FORMAT 0x8
201 /**
202 * Denotes pure height-map terrain data. Pure terrains usually consist of quads,
203 * sometimes triangles, in a regular grid. The x,y coordinates of all vertex
204 * positions refer to the x,y coordinates on the terrain height map, the z-axis
205 * stores the elevation at a specific point.
206 *
207 * TER (Terragen) and HMP (3D Game Studio) are height map formats.
208 * @note Assimp is probably not the best choice for loading *huge* terrains -
209 * fully triangulated data takes extremely much free store and should be avoided
210 * as long as possible (typically you'll do the triangulation when you actually
211 * need to render it).
212 */
213 #define AI_SCENE_FLAGS_TERRAIN 0x10
215 /**
216 * Specifies that the scene data can be shared between structures. For example:
217 * one vertex in few faces. \ref AI_SCENE_FLAGS_NON_VERBOSE_FORMAT can not be
218 * used for this because \ref AI_SCENE_FLAGS_NON_VERBOSE_FORMAT has internal
219 * meaning about postprocessing steps.
220 */
221 #define AI_SCENE_FLAGS_ALLOW_SHARED 0x20
223 // -------------------------------------------------------------------------------
224 /** The root structure of the imported data.
225 *
226 * Everything that was imported from the given file can be accessed from here.
227 * Objects of this class are generally maintained and owned by Assimp, not
228 * by the caller. You shouldn't want to instance it, nor should you ever try to
229 * delete a given scene on your own.
230 */
231 // -------------------------------------------------------------------------------
232 struct aiScene
233 {
234 /** Any combination of the AI_SCENE_FLAGS_XXX flags. By default
235 * this value is 0, no flags are set. Most applications will
236 * want to reject all scenes with the AI_SCENE_FLAGS_INCOMPLETE
237 * bit set.
238 */
239 unsigned int mFlags;
241 /** The root node of the hierarchy.
242 *
243 * There will always be at least the root node if the import
244 * was successful (and no special flags have been set).
245 * Presence of further nodes depends on the format and content
246 * of the imported file.
247 */
248 C_STRUCT aiNode* mRootNode;
250 /** The number of meshes in the scene. */
251 unsigned int mNumMeshes;
253 /** The array of meshes.
254 *
255 * Use the indices given in the aiNode structure to access
256 * this array. The array is mNumMeshes in size. If the
257 * AI_SCENE_FLAGS_INCOMPLETE flag is not set there will always
258 * be at least ONE material.
259 */
260 C_STRUCT aiMesh** mMeshes;
262 /** The number of materials in the scene. */
263 unsigned int mNumMaterials;
265 /** The array of materials.
266 *
267 * Use the index given in each aiMesh structure to access this
268 * array. The array is mNumMaterials in size. If the
269 * AI_SCENE_FLAGS_INCOMPLETE flag is not set there will always
270 * be at least ONE material.
271 */
272 C_STRUCT aiMaterial** mMaterials;
274 /** The number of animations in the scene. */
275 unsigned int mNumAnimations;
277 /** The array of animations.
278 *
279 * All animations imported from the given file are listed here.
280 * The array is mNumAnimations in size.
281 */
282 C_STRUCT aiAnimation** mAnimations;
284 /** The number of textures embedded into the file */
285 unsigned int mNumTextures;
287 /** The array of embedded textures.
288 *
289 * Not many file formats embed their textures into the file.
290 * An example is Quake's MDL format (which is also used by
291 * some GameStudio versions)
292 */
293 C_STRUCT aiTexture** mTextures;
295 /** The number of light sources in the scene. Light sources
296 * are fully optional, in most cases this attribute will be 0
297 */
298 unsigned int mNumLights;
300 /** The array of light sources.
301 *
302 * All light sources imported from the given file are
303 * listed here. The array is mNumLights in size.
304 */
305 C_STRUCT aiLight** mLights;
307 /** The number of cameras in the scene. Cameras
308 * are fully optional, in most cases this attribute will be 0
309 */
310 unsigned int mNumCameras;
312 /** The array of cameras.
313 *
314 * All cameras imported from the given file are listed here.
315 * The array is mNumCameras in size. The first camera in the
316 * array (if existing) is the default camera view into
317 * the scene.
318 */
319 C_STRUCT aiCamera** mCameras;
321 /**
322 * @brief The global metadata assigned to the scene itself.
323 *
324 * This data contains global metadata which belongs to the scene like
325 * unit-conversions, versions, vendors or other model-specific data. This
326 * can be used to store format-specific metadata as well.
327 */
328 C_STRUCT aiMetadata* mMetaData;
331 #ifdef __cplusplus
333 //! Default constructor - set everything to 0/NULL
334 ASSIMP_API aiScene();
336 //! Destructor
337 ASSIMP_API ~aiScene();
339 //! Check whether the scene contains meshes
340 //! Unless no special scene flags are set this will always be true.
341 inline bool HasMeshes() const {
342 return mMeshes != NULL && mNumMeshes > 0;
343 }
345 //! Check whether the scene contains materials
346 //! Unless no special scene flags are set this will always be true.
347 inline bool HasMaterials() const {
348 return mMaterials != NULL && mNumMaterials > 0;
349 }
351 //! Check whether the scene contains lights
352 inline bool HasLights() const {
353 return mLights != NULL && mNumLights > 0;
354 }
356 //! Check whether the scene contains textures
357 inline bool HasTextures() const {
358 return mTextures != NULL && mNumTextures > 0;
359 }
361 //! Check whether the scene contains cameras
362 inline bool HasCameras() const {
363 return mCameras != NULL && mNumCameras > 0;
364 }
366 //! Check whether the scene contains animations
367 inline bool HasAnimations() const {
368 return mAnimations != NULL && mNumAnimations > 0;
369 }
371 //! Returns a short filename from a full path
372 static const char* GetShortFilename(const char* filename) {
373 const char* lastSlash = strrchr(filename, '/');
374 if (lastSlash == 0) {
375 lastSlash = strrchr(filename, '\\');
376 }
377 const char* shortFilename = lastSlash != 0 ? lastSlash + 1 : filename;
378 return shortFilename;
379 }
381 //! Returns an embedded texture
382 const aiTexture* GetEmbeddedTexture(const char* filename) const {
383 const char* shortFilename = GetShortFilename(filename);
384 for (unsigned int i = 0; i < mNumTextures; i++) {
385 const char* shortTextureFilename = GetShortFilename(mTextures[i]->mFilename.C_Str());
386 if (strcmp(shortTextureFilename, shortFilename) == 0) {
387 return mTextures[i];
388 }
389 }
390 return 0;
391 }
392 #endif // __cplusplus
394 /** Internal data, do not touch */
395 #ifdef __cplusplus
396 void* mPrivate;
397 #else
398 char* mPrivate;
399 #endif
401 };
403 #ifdef __cplusplus
404 } //! namespace Assimp
405 #endif
407 #endif // AI_SCENE_H_INC