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