miniassimp

annotate include/miniassimp/scene.h @ 0:879c81d94345

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