include/assimp/importerdesc.h

0001 /*
0002 ---------------------------------------------------------------------------
0003 Open Asset Import Library (assimp)
0004 ---------------------------------------------------------------------------
0005
0006 Copyright (c) 2006-2024, assimp team
0007
0008 All rights reserved.
0009
0010 Redistribution and use of this software in source and binary forms,
0011 with or without modification, are permitted provided that the following
0012 conditions are met:
0013
0014 * Redistributions of source code must retain the above
0015   copyright notice, this list of conditions and the
0016   following disclaimer.
0017
0018 * Redistributions in binary form must reproduce the above
0019   copyright notice, this list of conditions and the
0020   following disclaimer in the documentation and/or other
0021   materials provided with the distribution.
0022
0023 * Neither the name of the assimp team, nor the names of its
0024   contributors may be used to endorse or promote products
0025   derived from this software without specific prior
0026   written permission of the assimp team.
0027
0028 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
0029 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
0030 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
0031 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
0032 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
0033 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
0034 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
0035 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
0036 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
0037 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
0038 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
0039 ---------------------------------------------------------------------------
0040 */
0041
0042 /** @file importerdesc.h
0043  *  @brief #aiImporterFlags, aiImporterDesc implementation.
0044  */
0045 #pragma once
0046 #ifndef AI_IMPORTER_DESC_H_INC
0047 #define AI_IMPORTER_DESC_H_INC
0048
0049 #ifdef __GNUC__
0050 #   pragma GCC system_header
0051 #endif
0052
0053 #include <assimp/types.h>
0054
0055 #ifdef __cplusplus
0056 extern "C" {
0057 #endif
0058
0059 /** Mixed set of flags for #aiImporterDesc, indicating some features
0060   *  common to many importers*/
0061 enum aiImporterFlags {
0062     /** Indicates that there is a textual encoding of the
0063      *  file format; and that it is supported.*/
0064     aiImporterFlags_SupportTextFlavour = 0x1,
0065
0066     /** Indicates that there is a binary encoding of the
0067      *  file format; and that it is supported.*/
0068     aiImporterFlags_SupportBinaryFlavour = 0x2,
0069
0070     /** Indicates that there is a compressed encoding of the
0071      *  file format; and that it is supported.*/
0072     aiImporterFlags_SupportCompressedFlavour = 0x4,
0073
0074     /** Indicates that the importer reads only a very particular
0075       * subset of the file format. This happens commonly for
0076       * declarative or procedural formats which cannot easily
0077       * be mapped to #aiScene */
0078     aiImporterFlags_LimitedSupport = 0x8,
0079
0080     /** Indicates that the importer is highly experimental and
0081       * should be used with care. This only happens for trunk
0082       * (i.e. SVN) versions, experimental code is not included
0083       * in releases. */
0084     aiImporterFlags_Experimental = 0x10
0085 };
0086
0087 /** Meta information about a particular importer. Importers need to fill
0088  *  this structure, but they can freely decide how talkative they are.
0089  *  A common use case for loader meta info is a user interface
0090  *  in which the user can choose between various import/export file
0091  *  formats. Building such an UI by hand means a lot of maintenance
0092  *  as importers/exporters are added to Assimp, so it might be useful
0093  *  to have a common mechanism to query some rough importer
0094  *  characteristics. */
0095 struct aiImporterDesc {
0096     /** Full name of the importer (i.e. Blender3D importer)*/
0097     const char *mName;
0098
0099     /** Original author (left blank if unknown or whole assimp team) */
0100     const char *mAuthor;
0101
0102     /** Current maintainer, left blank if the author maintains */
0103     const char *mMaintainer;
0104
0105     /** Implementation comments, i.e. unimplemented features*/
0106     const char *mComments;
0107
0108     /** These flags indicate some characteristics common to many
0109         importers. */
0110     unsigned int mFlags;
0111
0112     /** Minimum format version that can be loaded im major.minor format,
0113         both are set to 0 if there is either no version scheme
0114         or if the loader doesn't care. */
0115     unsigned int mMinMajor;
0116     unsigned int mMinMinor;
0117
0118     /** Maximum format version that can be loaded im major.minor format,
0119         both are set to 0 if there is either no version scheme
0120         or if the loader doesn't care. Loaders that expect to be
0121         forward-compatible to potential future format versions should
0122         indicate  zero, otherwise they should specify the current
0123         maximum version.*/
0124     unsigned int mMaxMajor;
0125     unsigned int mMaxMinor;
0126
0127     /** List of file extensions this importer can handle.
0128         List entries are separated by space characters.
0129         All entries are lower case without a leading dot (i.e.
0130         "xml dae" would be a valid value. Note that multiple
0131         importers may respond to the same file extension -
0132         assimp calls all importers in the order in which they
0133         are registered and each importer gets the opportunity
0134         to load the file until one importer "claims" the file. Apart
0135         from file extension checks, importers typically use
0136         other methods to quickly reject files (i.e. magic
0137         words) so this does not mean that common or generic
0138         file extensions such as XML would be tediously slow. */
0139     const char *mFileExtensions;
0140 };
0141
0142 /** \brief  Returns the Importer description for a given extension.
0143
0144 Will return a nullptr if no assigned importer desc. was found for the given extension
0145     \param  extension   [in] The extension to look for
0146     \return A pointer showing to the ImporterDesc, \see aiImporterDesc.
0147 */
0148 ASSIMP_API const C_STRUCT aiImporterDesc *aiGetImporterDesc(const char *extension);
0149
0150 #ifdef __cplusplus
0151 } // end of extern "C"
0152 #endif
0153
0154 #endif // AI_IMPORTER_DESC_H_INC