1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/libs/assimp/assimp/Exporter.hpp	Sat Feb 01 19:58:19 2014 +0200
     1.3 @@ -0,0 +1,305 @@
     1.4 +/*
     1.5 +---------------------------------------------------------------------------
     1.6 +Open Asset Import Library (assimp)
     1.7 +---------------------------------------------------------------------------
     1.8 +
     1.9 +Copyright (c) 2006-2011, assimp team
    1.10 +
    1.11 +All rights reserved.
    1.12 +
    1.13 +Redistribution and use of this software in source and binary forms, 
    1.14 +with or without modification, are permitted provided that the following 
    1.15 +conditions are met:
    1.16 +
    1.17 +* Redistributions of source code must retain the above
    1.18 +copyright notice, this list of conditions and the
    1.19 +following disclaimer.
    1.20 +
    1.21 +* Redistributions in binary form must reproduce the above
    1.22 +copyright notice, this list of conditions and the
    1.23 +following disclaimer in the documentation and/or other
    1.24 +materials provided with the distribution.
    1.25 +
    1.26 +* Neither the name of the assimp team, nor the names of its
    1.27 +contributors may be used to endorse or promote products
    1.28 +derived from this software without specific prior
    1.29 +written permission of the assimp team.
    1.30 +
    1.31 +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
    1.32 +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
    1.33 +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
    1.34 +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 
    1.35 +OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
    1.36 +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 
    1.37 +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
    1.38 +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 
    1.39 +THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
    1.40 +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
    1.41 +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    1.42 +---------------------------------------------------------------------------
    1.43 +*/
    1.44 +
    1.45 +/** @file  export.hpp
    1.46 +*  @brief Defines the CPP-API for the Assimp export interface
    1.47 +*/
    1.48 +#ifndef AI_EXPORT_HPP_INC
    1.49 +#define AI_EXPORT_HPP_INC
    1.50 +
    1.51 +#ifndef ASSIMP_BUILD_NO_EXPORT
    1.52 +
    1.53 +#include "cexport.h"
    1.54 +
    1.55 +namespace Assimp	{
    1.56 +	class ExporterPimpl;
    1.57 +	class IOSystem;
    1.58 +
    1.59 +
    1.60 +// ----------------------------------------------------------------------------------
    1.61 +/** CPP-API: The Exporter class forms an C++ interface to the export functionality 
    1.62 + * of the Open Asset Import Library. Note that the export interface is available
    1.63 + * only if Assimp has been built with ASSIMP_BUILD_NO_EXPORT not defined.
    1.64 + * 
    1.65 + * The interface is modelled after the importer interface and mostly
    1.66 + * symmetric. The same rules for threading etc. apply.
    1.67 + *
    1.68 + * In a nutshell, there are two export interfaces: #Export, which writes the
    1.69 + * output file(s) either to the regular file system or to a user-supplied 
    1.70 + * #IOSystem, and #ExportToBlob which returns a linked list of memory
    1.71 + * buffers (blob), each referring to one output file (in most cases
    1.72 + * there will be only one output file of course, but this extra complexity is
    1.73 + * needed since Assimp aims at supporting a wide range of file formats). 
    1.74 + * 
    1.75 + * #ExportToBlob is especially useful if you intend to work 
    1.76 + * with the data in-memory. 
    1.77 +*/
    1.78 +class ASSIMP_API Exporter
    1.79 +	// TODO: causes good ol' base class has no dll interface warning
    1.80 +//#ifdef __cplusplus
    1.81 +//	: public boost::noncopyable
    1.82 +//#endif // __cplusplus
    1.83 +{
    1.84 +public:
    1.85 +
    1.86 +	/** Function pointer type of a Export worker function */
    1.87 +	typedef void (*fpExportFunc)(const char*,IOSystem*,const aiScene*);
    1.88 +
    1.89 +	/** Internal description of an Assimp export format option */
    1.90 +	struct ExportFormatEntry
    1.91 +	{
    1.92 +		/// Public description structure to be returned by aiGetExportFormatDescription()
    1.93 +		aiExportFormatDesc mDescription;
    1.94 +
    1.95 +		// Worker function to do the actual exporting
    1.96 +		fpExportFunc mExportFunction;
    1.97 +
    1.98 +		// Postprocessing steps to be executed PRIOR to invoking mExportFunction
    1.99 +		unsigned int mEnforcePP;
   1.100 +
   1.101 +		// Constructor to fill all entries
   1.102 +		ExportFormatEntry( const char* pId, const char* pDesc, const char* pExtension, fpExportFunc pFunction, unsigned int pEnforcePP = 0u)
   1.103 +		{
   1.104 +			mDescription.id = pId;
   1.105 +			mDescription.description = pDesc;
   1.106 +			mDescription.fileExtension = pExtension;
   1.107 +			mExportFunction = pFunction;
   1.108 +			mEnforcePP = pEnforcePP;
   1.109 +		}
   1.110 +
   1.111 +		ExportFormatEntry() : mExportFunction(), mEnforcePP() {}
   1.112 +	};
   1.113 +
   1.114 +
   1.115 +public:
   1.116 +
   1.117 +	
   1.118 +	Exporter();
   1.119 +	~Exporter();
   1.120 +
   1.121 +public:
   1.122 +
   1.123 +
   1.124 +	// -------------------------------------------------------------------
   1.125 +	/** Supplies a custom IO handler to the exporter to use to open and
   1.126 +	 * access files. 
   1.127 +	 * 
   1.128 +	 * If you need #Export to use custom IO logic to access the files, 
   1.129 +	 * you need to supply a custom implementation of IOSystem and 
   1.130 +	 * IOFile to the exporter. 
   1.131 +	 *
   1.132 +	 * #Exporter takes ownership of the object and will destroy it 
   1.133 +	 * afterwards. The previously assigned handler will be deleted.
   1.134 +	 * Pass NULL to take again ownership of your IOSystem and reset Assimp
   1.135 +	 * to use its default implementation, which uses plain file IO.
   1.136 +	 *
   1.137 +	 * @param pIOHandler The IO handler to be used in all file accesses 
   1.138 +	 *   of the Importer. */
   1.139 +	void SetIOHandler( IOSystem* pIOHandler);
   1.140 +
   1.141 +	// -------------------------------------------------------------------
   1.142 +	/** Retrieves the IO handler that is currently set.
   1.143 +	 * You can use #IsDefaultIOHandler() to check whether the returned
   1.144 +	 * interface is the default IO handler provided by ASSIMP. The default
   1.145 +	 * handler is active as long the application doesn't supply its own
   1.146 +	 * custom IO handler via #SetIOHandler().
   1.147 +	 * @return A valid IOSystem interface, never NULL. */
   1.148 +	IOSystem* GetIOHandler() const;
   1.149 +
   1.150 +	// -------------------------------------------------------------------
   1.151 +	/** Checks whether a default IO handler is active 
   1.152 +	 * A default handler is active as long the application doesn't 
   1.153 +	 * supply its own custom IO handler via #SetIOHandler().
   1.154 +	 * @return true by default */
   1.155 +	bool IsDefaultIOHandler() const;
   1.156 +
   1.157 +
   1.158 +
   1.159 +	// -------------------------------------------------------------------
   1.160 +	/** Exports the given scene to a chosen file format. Returns the exported 
   1.161 +	* data as a binary blob which you can write into a file or something.
   1.162 +	* When you're done with the data, simply let the #Exporter instance go 
   1.163 +	* out of scope to have it released automatically.
   1.164 +	* @param pScene The scene to export. Stays in possession of the caller,
   1.165 +	*   is not changed by the function.
   1.166 +	* @param pFormatId ID string to specify to which format you want to 
   1.167 +	*   export to. Use 
   1.168 +	* #GetExportFormatCount / #GetExportFormatDescription to learn which 
   1.169 +	*   export formats are available.
   1.170 +	* @param pPreprocessing See the documentation for #Export
   1.171 +	* @return the exported data or NULL in case of error.
   1.172 +	* @note If the Exporter instance did already hold a blob from
   1.173 +	*   a previous call to #ExportToBlob, it will be disposed. 
   1.174 +	*   Any IO handlers set via #SetIOHandler are ignored here.*/
   1.175 +	const aiExportDataBlob* ExportToBlob(  const aiScene* pScene, const char* pFormatId, unsigned int pPreprocessing = 0u );
   1.176 +	inline const aiExportDataBlob* ExportToBlob(  const aiScene* pScene, const std::string& pFormatId, unsigned int pPreprocessing = 0u );
   1.177 +
   1.178 +
   1.179 +	// -------------------------------------------------------------------
   1.180 +	/** Convenience function to export directly to a file. Use
   1.181 +	 *  #SetIOSystem to supply a custom IOSystem to gain fine-grained control
   1.182 +	 *  about the output data flow of the export process.
   1.183 +	 * @param pBlob A data blob obtained from a previous call to #aiExportScene. Must not be NULL.
   1.184 +	 * @param pPath Full target file name. Target must be accessible.
   1.185 +	 * @param pPreprocessing Accepts any choice of the #aiPostProcessing enumerated
   1.186 +	 *   flags, but in reality only a subset of them makes sense here. Specifying
   1.187 +	 *   'preprocessing' flags is useful if the input scene does not conform to 
   1.188 +	 *   Assimp's default conventions as specified in the @link data Data Structures Page @endlink. 
   1.189 +	 *   In short, this means the geometry data should use a right-handed coordinate systems, face 
   1.190 +	 *   winding should be counter-clockwise and the UV coordinate origin is assumed to be in
   1.191 +	 *   the upper left. The #aiProcess_MakeLeftHanded, #aiProcess_FlipUVs and 
   1.192 +	 *   #aiProcess_FlipWindingOrder flags are used in the import side to allow users
   1.193 +	 *   to have those defaults automatically adapted to their conventions. Specifying those flags
   1.194 +	 *   for exporting has the opposite effect, respectively. Some other of the
   1.195 +	 *   #aiPostProcessSteps enumerated values may be useful as well, but you'll need
   1.196 +	 *   to try out what their effect on the exported file is. Many formats impose
   1.197 +	 *   their own restrictions on the structure of the geometry stored therein,
   1.198 +	 *   so some preprocessing may have little or no effect at all, or may be
   1.199 +	 *   redundant as exporters would apply them anyhow. A good example 
   1.200 +	 *   is triangulation - whilst you can enforce it by specifying
   1.201 +	 *   the #aiProcess_Triangulate flag, most export formats support only
   1.202 +	 *  triangulate data so they would run the step even if it wasn't requested.
   1.203 +	 * @return AI_SUCCESS if everything was fine. */
   1.204 +	aiReturn Export( const aiScene* pScene, const char* pFormatId, const char* pPath, unsigned int pPreprocessing = 0u);
   1.205 +	inline aiReturn Export( const aiScene* pScene, const std::string& pFormatId, const std::string& pPath,  unsigned int pPreprocessing = 0u);
   1.206 +
   1.207 +
   1.208 +	// -------------------------------------------------------------------
   1.209 +	/** Returns an error description of an error that occurred in #Export
   1.210 +	 *    or #ExportToBlob
   1.211 +	 *
   1.212 +	 * Returns an empty string if no error occurred.
   1.213 +	 * @return A description of the last error, an empty string if no 
   1.214 +	 *   error occurred. The string is never NULL.
   1.215 +	 *
   1.216 +	 * @note The returned function remains valid until one of the 
   1.217 +	 * following methods is called: #Export, #ExportToBlob, #FreeBlob */
   1.218 +	const char* GetErrorString() const;
   1.219 +
   1.220 +
   1.221 +	// -------------------------------------------------------------------
   1.222 +	/** Return the blob obtained from the last call to #ExportToBlob */
   1.223 +	const aiExportDataBlob* GetBlob() const;
   1.224 +
   1.225 +
   1.226 +	// -------------------------------------------------------------------
   1.227 +	/** Orphan the blob from the last call to #ExportToBlob. This means
   1.228 +	 *  the caller takes ownership and is thus responsible for calling
   1.229 +	 *  the C API function #aiReleaseExportBlob to release it. */
   1.230 +	const aiExportDataBlob* GetOrphanedBlob() const;
   1.231 +
   1.232 +
   1.233 +	// -------------------------------------------------------------------
   1.234 +	/** Frees the current blob.
   1.235 +	 *
   1.236 +	 *  The function does nothing if no blob has previously been 
   1.237 +	 *  previously produced via #ExportToBlob. #FreeBlob is called
   1.238 +	 *  automatically by the destructor. The only reason to call
   1.239 +	 *  it manually would be to reclain as much storage as possible
   1.240 +	 *  without giving up the #Exporter instance yet. */
   1.241 +	void FreeBlob( );
   1.242 +
   1.243 +
   1.244 +	// -------------------------------------------------------------------
   1.245 +	/** Returns the number of export file formats available in the current
   1.246 +	 *  Assimp build. Use #Exporter::GetExportFormatDescription to
   1.247 +	 *  retrieve infos of a specific export format */
   1.248 +	size_t GetExportFormatCount() const;
   1.249 +
   1.250 +
   1.251 +	// -------------------------------------------------------------------
   1.252 +	/** Returns a description of the nth export file format. Use #
   1.253 +	 *  #Exporter::GetExportFormatCount to learn how many export 
   1.254 +	 *  formats are supported. 
   1.255 +	 * @param pIndex Index of the export format to retrieve information 
   1.256 +	 *  for. Valid range is 0 to #Exporter::GetExportFormatCount
   1.257 +	 * @return A description of that specific export format. 
   1.258 +	 *  NULL if pIndex is out of range. */
   1.259 +	const aiExportFormatDesc* GetExportFormatDescription( size_t pIndex ) const;
   1.260 +
   1.261 +
   1.262 +	// -------------------------------------------------------------------
   1.263 +	/** Register a custom exporter. Custom export formats are limited to
   1.264 +	 *    to the current #Exporter instance and do not affect the
   1.265 +	 *    library globally.
   1.266 +	 *  @param desc Exporter description.
   1.267 +	 *  @return aiReturn_SUCCESS if the export format was successfully
   1.268 +	 *    registered. A common cause that would prevent an exporter
   1.269 +	 *    from being registered is that its format id is already
   1.270 +	 *    occupied by another format. */
   1.271 +	aiReturn RegisterExporter(const ExportFormatEntry& desc);
   1.272 +
   1.273 +
   1.274 +	// -------------------------------------------------------------------
   1.275 +	/** Remove an export format previously registered with #RegisterExporter
   1.276 +	 *  from the #Exporter instance (this can also be used to drop
   1.277 +	 *  builtin exporters because those are implicitly registered
   1.278 +	 *  using #RegisterExporter).
   1.279 +	 *  @param id Format id to be unregistered, this refers to the
   1.280 +	 *    'id' field of #aiExportFormatDesc. 
   1.281 +	 *  @note Calling this method on a format description not yet registered
   1.282 +	 *    has no effect.*/
   1.283 +	void UnregisterExporter(const char* id);
   1.284 +
   1.285 +
   1.286 +protected:
   1.287 +
   1.288 +	// Just because we don't want you to know how we're hacking around.
   1.289 +	ExporterPimpl* pimpl;
   1.290 +};
   1.291 +
   1.292 +
   1.293 +// ----------------------------------------------------------------------------------
   1.294 +inline const aiExportDataBlob* Exporter :: ExportToBlob(  const aiScene* pScene, const std::string& pFormatId,unsigned int pPreprocessing ) 
   1.295 +{
   1.296 +	return ExportToBlob(pScene,pFormatId.c_str(),pPreprocessing);
   1.297 +}
   1.298 +
   1.299 +// ----------------------------------------------------------------------------------
   1.300 +inline aiReturn Exporter :: Export( const aiScene* pScene, const std::string& pFormatId, const std::string& pPath, unsigned int pPreprocessing )
   1.301 +{
   1.302 +	return Export(pScene,pFormatId.c_str(),pPath.c_str(),pPreprocessing);
   1.303 +}
   1.304 +
   1.305 +} // namespace Assimp
   1.306 +#endif // ASSIMP_BUILD_NO_EXPORT
   1.307 +#endif // AI_EXPORT_HPP_INC
   1.308 +