vrshoot

annotate libs/assimp/assimp/Exporter.hpp @ 0:b2f14e535253

find changesets by author, revision, files, or words in the commit message
initial commit
author John Tsiombikas <nuclear@member.fsf.org>
date Sat, 01 Feb 2014 19:58:19 +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-2011, assimp team
nuclear@0 7
nuclear@0 8 All rights reserved.
nuclear@0 9
nuclear@0 10 Redistribution and use of this software in source and binary forms,
nuclear@0 11 with or without modification, are permitted provided that the following
nuclear@0 12 conditions are met:
nuclear@0 13
nuclear@0 14 * Redistributions of source code must retain the above
nuclear@0 15 copyright notice, this list of conditions and the
nuclear@0 16 following disclaimer.
nuclear@0 17
nuclear@0 18 * Redistributions in binary form must reproduce the above
nuclear@0 19 copyright notice, this list of conditions and the
nuclear@0 20 following disclaimer in the documentation and/or other
nuclear@0 21 materials provided with the distribution.
nuclear@0 22
nuclear@0 23 * Neither the name of the assimp team, nor the names of its
nuclear@0 24 contributors may be used to endorse or promote products
nuclear@0 25 derived from this software without specific prior
nuclear@0 26 written permission of the assimp team.
nuclear@0 27
nuclear@0 28 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
nuclear@0 29 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
nuclear@0 30 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
nuclear@0 31 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
nuclear@0 32 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
nuclear@0 33 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
nuclear@0 34 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
nuclear@0 35 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
nuclear@0 36 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
nuclear@0 37 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
nuclear@0 38 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
nuclear@0 39 ---------------------------------------------------------------------------
nuclear@0 40 */
nuclear@0 41
nuclear@0 42 /** @file export.hpp
nuclear@0 43 * @brief Defines the CPP-API for the Assimp export interface
nuclear@0 44 */
nuclear@0 45 #ifndef AI_EXPORT_HPP_INC
nuclear@0 46 #define AI_EXPORT_HPP_INC
nuclear@0 47
nuclear@0 48 #ifndef ASSIMP_BUILD_NO_EXPORT
nuclear@0 49
nuclear@0 50 #include "cexport.h"
nuclear@0 51
nuclear@0 52 namespace Assimp {
nuclear@0 53 class ExporterPimpl;
nuclear@0 54 class IOSystem;
nuclear@0 55
nuclear@0 56
nuclear@0 57 // ----------------------------------------------------------------------------------
nuclear@0 58 /** CPP-API: The Exporter class forms an C++ interface to the export functionality
nuclear@0 59 * of the Open Asset Import Library. Note that the export interface is available
nuclear@0 60 * only if Assimp has been built with ASSIMP_BUILD_NO_EXPORT not defined.
nuclear@0 61 *
nuclear@0 62 * The interface is modelled after the importer interface and mostly
nuclear@0 63 * symmetric. The same rules for threading etc. apply.
nuclear@0 64 *
nuclear@0 65 * In a nutshell, there are two export interfaces: #Export, which writes the
nuclear@0 66 * output file(s) either to the regular file system or to a user-supplied
nuclear@0 67 * #IOSystem, and #ExportToBlob which returns a linked list of memory
nuclear@0 68 * buffers (blob), each referring to one output file (in most cases
nuclear@0 69 * there will be only one output file of course, but this extra complexity is
nuclear@0 70 * needed since Assimp aims at supporting a wide range of file formats).
nuclear@0 71 *
nuclear@0 72 * #ExportToBlob is especially useful if you intend to work
nuclear@0 73 * with the data in-memory.
nuclear@0 74 */
nuclear@0 75 class ASSIMP_API Exporter
nuclear@0 76 // TODO: causes good ol' base class has no dll interface warning
nuclear@0 77 //#ifdef __cplusplus
nuclear@0 78 // : public boost::noncopyable
nuclear@0 79 //#endif // __cplusplus
nuclear@0 80 {
nuclear@0 81 public:
nuclear@0 82
nuclear@0 83 /** Function pointer type of a Export worker function */
nuclear@0 84 typedef void (*fpExportFunc)(const char*,IOSystem*,const aiScene*);
nuclear@0 85
nuclear@0 86 /** Internal description of an Assimp export format option */
nuclear@0 87 struct ExportFormatEntry
nuclear@0 88 {
nuclear@0 89 /// Public description structure to be returned by aiGetExportFormatDescription()
nuclear@0 90 aiExportFormatDesc mDescription;
nuclear@0 91
nuclear@0 92 // Worker function to do the actual exporting
nuclear@0 93 fpExportFunc mExportFunction;
nuclear@0 94
nuclear@0 95 // Postprocessing steps to be executed PRIOR to invoking mExportFunction
nuclear@0 96 unsigned int mEnforcePP;
nuclear@0 97
nuclear@0 98 // Constructor to fill all entries
nuclear@0 99 ExportFormatEntry( const char* pId, const char* pDesc, const char* pExtension, fpExportFunc pFunction, unsigned int pEnforcePP = 0u)
nuclear@0 100 {
nuclear@0 101 mDescription.id = pId;
nuclear@0 102 mDescription.description = pDesc;
nuclear@0 103 mDescription.fileExtension = pExtension;
nuclear@0 104 mExportFunction = pFunction;
nuclear@0 105 mEnforcePP = pEnforcePP;
nuclear@0 106 }
nuclear@0 107
nuclear@0 108 ExportFormatEntry() : mExportFunction(), mEnforcePP() {}
nuclear@0 109 };
nuclear@0 110
nuclear@0 111
nuclear@0 112 public:
nuclear@0 113
nuclear@0 114
nuclear@0 115 Exporter();
nuclear@0 116 ~Exporter();
nuclear@0 117
nuclear@0 118 public:
nuclear@0 119
nuclear@0 120
nuclear@0 121 // -------------------------------------------------------------------
nuclear@0 122 /** Supplies a custom IO handler to the exporter to use to open and
nuclear@0 123 * access files.
nuclear@0 124 *
nuclear@0 125 * If you need #Export to use custom IO logic to access the files,
nuclear@0 126 * you need to supply a custom implementation of IOSystem and
nuclear@0 127 * IOFile to the exporter.
nuclear@0 128 *
nuclear@0 129 * #Exporter takes ownership of the object and will destroy it
nuclear@0 130 * afterwards. The previously assigned handler will be deleted.
nuclear@0 131 * Pass NULL to take again ownership of your IOSystem and reset Assimp
nuclear@0 132 * to use its default implementation, which uses plain file IO.
nuclear@0 133 *
nuclear@0 134 * @param pIOHandler The IO handler to be used in all file accesses
nuclear@0 135 * of the Importer. */
nuclear@0 136 void SetIOHandler( IOSystem* pIOHandler);
nuclear@0 137
nuclear@0 138 // -------------------------------------------------------------------
nuclear@0 139 /** Retrieves the IO handler that is currently set.
nuclear@0 140 * You can use #IsDefaultIOHandler() to check whether the returned
nuclear@0 141 * interface is the default IO handler provided by ASSIMP. The default
nuclear@0 142 * handler is active as long the application doesn't supply its own
nuclear@0 143 * custom IO handler via #SetIOHandler().
nuclear@0 144 * @return A valid IOSystem interface, never NULL. */
nuclear@0 145 IOSystem* GetIOHandler() const;
nuclear@0 146
nuclear@0 147 // -------------------------------------------------------------------
nuclear@0 148 /** Checks whether a default IO handler is active
nuclear@0 149 * A default handler is active as long the application doesn't
nuclear@0 150 * supply its own custom IO handler via #SetIOHandler().
nuclear@0 151 * @return true by default */
nuclear@0 152 bool IsDefaultIOHandler() const;
nuclear@0 153
nuclear@0 154
nuclear@0 155
nuclear@0 156 // -------------------------------------------------------------------
nuclear@0 157 /** Exports the given scene to a chosen file format. Returns the exported
nuclear@0 158 * data as a binary blob which you can write into a file or something.
nuclear@0 159 * When you're done with the data, simply let the #Exporter instance go
nuclear@0 160 * out of scope to have it released automatically.
nuclear@0 161 * @param pScene The scene to export. Stays in possession of the caller,
nuclear@0 162 * is not changed by the function.
nuclear@0 163 * @param pFormatId ID string to specify to which format you want to
nuclear@0 164 * export to. Use
nuclear@0 165 * #GetExportFormatCount / #GetExportFormatDescription to learn which
nuclear@0 166 * export formats are available.
nuclear@0 167 * @param pPreprocessing See the documentation for #Export
nuclear@0 168 * @return the exported data or NULL in case of error.
nuclear@0 169 * @note If the Exporter instance did already hold a blob from
nuclear@0 170 * a previous call to #ExportToBlob, it will be disposed.
nuclear@0 171 * Any IO handlers set via #SetIOHandler are ignored here.*/
nuclear@0 172 const aiExportDataBlob* ExportToBlob( const aiScene* pScene, const char* pFormatId, unsigned int pPreprocessing = 0u );
nuclear@0 173 inline const aiExportDataBlob* ExportToBlob( const aiScene* pScene, const std::string& pFormatId, unsigned int pPreprocessing = 0u );
nuclear@0 174
nuclear@0 175
nuclear@0 176 // -------------------------------------------------------------------
nuclear@0 177 /** Convenience function to export directly to a file. Use
nuclear@0 178 * #SetIOSystem to supply a custom IOSystem to gain fine-grained control
nuclear@0 179 * about the output data flow of the export process.
nuclear@0 180 * @param pBlob A data blob obtained from a previous call to #aiExportScene. Must not be NULL.
nuclear@0 181 * @param pPath Full target file name. Target must be accessible.
nuclear@0 182 * @param pPreprocessing Accepts any choice of the #aiPostProcessing enumerated
nuclear@0 183 * flags, but in reality only a subset of them makes sense here. Specifying
nuclear@0 184 * 'preprocessing' flags is useful if the input scene does not conform to
nuclear@0 185 * Assimp's default conventions as specified in the @link data Data Structures Page @endlink.
nuclear@0 186 * In short, this means the geometry data should use a right-handed coordinate systems, face
nuclear@0 187 * winding should be counter-clockwise and the UV coordinate origin is assumed to be in
nuclear@0 188 * the upper left. The #aiProcess_MakeLeftHanded, #aiProcess_FlipUVs and
nuclear@0 189 * #aiProcess_FlipWindingOrder flags are used in the import side to allow users
nuclear@0 190 * to have those defaults automatically adapted to their conventions. Specifying those flags
nuclear@0 191 * for exporting has the opposite effect, respectively. Some other of the
nuclear@0 192 * #aiPostProcessSteps enumerated values may be useful as well, but you'll need
nuclear@0 193 * to try out what their effect on the exported file is. Many formats impose
nuclear@0 194 * their own restrictions on the structure of the geometry stored therein,
nuclear@0 195 * so some preprocessing may have little or no effect at all, or may be
nuclear@0 196 * redundant as exporters would apply them anyhow. A good example
nuclear@0 197 * is triangulation - whilst you can enforce it by specifying
nuclear@0 198 * the #aiProcess_Triangulate flag, most export formats support only
nuclear@0 199 * triangulate data so they would run the step even if it wasn't requested.
nuclear@0 200 * @return AI_SUCCESS if everything was fine. */
nuclear@0 201 aiReturn Export( const aiScene* pScene, const char* pFormatId, const char* pPath, unsigned int pPreprocessing = 0u);
nuclear@0 202 inline aiReturn Export( const aiScene* pScene, const std::string& pFormatId, const std::string& pPath, unsigned int pPreprocessing = 0u);
nuclear@0 203
nuclear@0 204
nuclear@0 205 // -------------------------------------------------------------------
nuclear@0 206 /** Returns an error description of an error that occurred in #Export
nuclear@0 207 * or #ExportToBlob
nuclear@0 208 *
nuclear@0 209 * Returns an empty string if no error occurred.
nuclear@0 210 * @return A description of the last error, an empty string if no
nuclear@0 211 * error occurred. The string is never NULL.
nuclear@0 212 *
nuclear@0 213 * @note The returned function remains valid until one of the
nuclear@0 214 * following methods is called: #Export, #ExportToBlob, #FreeBlob */
nuclear@0 215 const char* GetErrorString() const;
nuclear@0 216
nuclear@0 217
nuclear@0 218 // -------------------------------------------------------------------
nuclear@0 219 /** Return the blob obtained from the last call to #ExportToBlob */
nuclear@0 220 const aiExportDataBlob* GetBlob() const;
nuclear@0 221
nuclear@0 222
nuclear@0 223 // -------------------------------------------------------------------
nuclear@0 224 /** Orphan the blob from the last call to #ExportToBlob. This means
nuclear@0 225 * the caller takes ownership and is thus responsible for calling
nuclear@0 226 * the C API function #aiReleaseExportBlob to release it. */
nuclear@0 227 const aiExportDataBlob* GetOrphanedBlob() const;
nuclear@0 228
nuclear@0 229
nuclear@0 230 // -------------------------------------------------------------------
nuclear@0 231 /** Frees the current blob.
nuclear@0 232 *
nuclear@0 233 * The function does nothing if no blob has previously been
nuclear@0 234 * previously produced via #ExportToBlob. #FreeBlob is called
nuclear@0 235 * automatically by the destructor. The only reason to call
nuclear@0 236 * it manually would be to reclain as much storage as possible
nuclear@0 237 * without giving up the #Exporter instance yet. */
nuclear@0 238 void FreeBlob( );
nuclear@0 239
nuclear@0 240
nuclear@0 241 // -------------------------------------------------------------------
nuclear@0 242 /** Returns the number of export file formats available in the current
nuclear@0 243 * Assimp build. Use #Exporter::GetExportFormatDescription to
nuclear@0 244 * retrieve infos of a specific export format */
nuclear@0 245 size_t GetExportFormatCount() const;
nuclear@0 246
nuclear@0 247
nuclear@0 248 // -------------------------------------------------------------------
nuclear@0 249 /** Returns a description of the nth export file format. Use #
nuclear@0 250 * #Exporter::GetExportFormatCount to learn how many export
nuclear@0 251 * formats are supported.
nuclear@0 252 * @param pIndex Index of the export format to retrieve information
nuclear@0 253 * for. Valid range is 0 to #Exporter::GetExportFormatCount
nuclear@0 254 * @return A description of that specific export format.
nuclear@0 255 * NULL if pIndex is out of range. */
nuclear@0 256 const aiExportFormatDesc* GetExportFormatDescription( size_t pIndex ) const;
nuclear@0 257
nuclear@0 258
nuclear@0 259 // -------------------------------------------------------------------
nuclear@0 260 /** Register a custom exporter. Custom export formats are limited to
nuclear@0 261 * to the current #Exporter instance and do not affect the
nuclear@0 262 * library globally.
nuclear@0 263 * @param desc Exporter description.
nuclear@0 264 * @return aiReturn_SUCCESS if the export format was successfully
nuclear@0 265 * registered. A common cause that would prevent an exporter
nuclear@0 266 * from being registered is that its format id is already
nuclear@0 267 * occupied by another format. */
nuclear@0 268 aiReturn RegisterExporter(const ExportFormatEntry& desc);
nuclear@0 269
nuclear@0 270
nuclear@0 271 // -------------------------------------------------------------------
nuclear@0 272 /** Remove an export format previously registered with #RegisterExporter
nuclear@0 273 * from the #Exporter instance (this can also be used to drop
nuclear@0 274 * builtin exporters because those are implicitly registered
nuclear@0 275 * using #RegisterExporter).
nuclear@0 276 * @param id Format id to be unregistered, this refers to the
nuclear@0 277 * 'id' field of #aiExportFormatDesc.
nuclear@0 278 * @note Calling this method on a format description not yet registered
nuclear@0 279 * has no effect.*/
nuclear@0 280 void UnregisterExporter(const char* id);
nuclear@0 281
nuclear@0 282
nuclear@0 283 protected:
nuclear@0 284
nuclear@0 285 // Just because we don't want you to know how we're hacking around.
nuclear@0 286 ExporterPimpl* pimpl;
nuclear@0 287 };
nuclear@0 288
nuclear@0 289
nuclear@0 290 // ----------------------------------------------------------------------------------
nuclear@0 291 inline const aiExportDataBlob* Exporter :: ExportToBlob( const aiScene* pScene, const std::string& pFormatId,unsigned int pPreprocessing )
nuclear@0 292 {
nuclear@0 293 return ExportToBlob(pScene,pFormatId.c_str(),pPreprocessing);
nuclear@0 294 }
nuclear@0 295
nuclear@0 296 // ----------------------------------------------------------------------------------
nuclear@0 297 inline aiReturn Exporter :: Export( const aiScene* pScene, const std::string& pFormatId, const std::string& pPath, unsigned int pPreprocessing )
nuclear@0 298 {
nuclear@0 299 return Export(pScene,pFormatId.c_str(),pPath.c_str(),pPreprocessing);
nuclear@0 300 }
nuclear@0 301
nuclear@0 302 } // namespace Assimp
nuclear@0 303 #endif // ASSIMP_BUILD_NO_EXPORT
nuclear@0 304 #endif // AI_EXPORT_HPP_INC
nuclear@0 305