vrshoot
view libs/assimp/assimp/cexport.h @ 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 cexport.h
43 * @brief Defines the C-API for the Assimp export interface
44 */
45 #ifndef AI_EXPORT_H_INC
46 #define AI_EXPORT_H_INC
48 #ifndef ASSIMP_BUILD_NO_EXPORT
50 #include "types.h"
52 #ifdef __cplusplus
53 extern "C" {
54 #endif
56 struct aiScene; // aiScene.h
57 struct aiFileIO; // aiFileIO.h
59 // --------------------------------------------------------------------------------
60 /** Describes an file format which Assimp can export to. Use #aiGetExportFormatCount() to
61 * learn how many export formats the current Assimp build supports and #aiGetExportFormatDescription()
62 * to retrieve a description of an export format option.
63 */
64 struct aiExportFormatDesc
65 {
66 /// a short string ID to uniquely identify the export format. Use this ID string to
67 /// specify which file format you want to export to when calling #aiExportScene().
68 /// Example: "dae" or "obj"
69 const char* id;
71 /// A short description of the file format to present to users. Useful if you want
72 /// to allow the user to select an export format.
73 const char* description;
75 /// Recommended file extension for the exported file in lower case.
76 const char* fileExtension;
77 };
80 // --------------------------------------------------------------------------------
81 /** Returns the number of export file formats available in the current Assimp build.
82 * Use aiGetExportFormatDescription() to retrieve infos of a specific export format.
83 */
84 ASSIMP_API size_t aiGetExportFormatCount(void);
87 // --------------------------------------------------------------------------------
88 /** Returns a description of the nth export file format. Use #aiGetExportFormatCount()
89 * to learn how many export formats are supported.
90 * @param pIndex Index of the export format to retrieve information for. Valid range is
91 * 0 to #aiGetExportFormatCount()
92 * @return A description of that specific export format. NULL if pIndex is out of range.
93 */
94 ASSIMP_API const C_STRUCT aiExportFormatDesc* aiGetExportFormatDescription( size_t pIndex);
97 // --------------------------------------------------------------------------------
98 /** Create a modifyable copy of a scene.
99 * This is useful to import files via Assimp, change their topology and
100 * export them again. Since the scene returned by the various importer functions
101 * is const, a modifyable copy is needed.
102 * @param pIn Valid scene to be copied
103 * @param pOut Receives a modifyable copy of the scene.
104 */
105 ASSIMP_API void aiCopyScene(const C_STRUCT aiScene* pIn,
106 C_STRUCT aiScene** pOut);
108 // --------------------------------------------------------------------------------
109 /** Exports the given scene to a chosen file format and writes the result file(s) to disk.
110 * @param pScene The scene to export. Stays in possession of the caller, is not changed by the function.
111 * The scene is expected to conform to Assimp's Importer output format as specified
112 * in the @link data Data Structures Page @endlink. In short, this means the model data
113 * should use a right-handed coordinate systems, face winding should be counter-clockwise
114 * and the UV coordinate origin is assumed to be in the upper left. If your input data
115 * uses different conventions, have a look at the last parameter.
116 * @param pFormatId ID string to specify to which format you want to export to. Use
117 * aiGetExportFormatCount() / aiGetExportFormatDescription() to learn which export formats are available.
118 * @param pFileName Output file to write
119 * @param pIO custom IO implementation to be used. Use this if you use your own storage methods.
120 * If none is supplied, a default implementation using standard file IO is used. Note that
121 * #aiExportSceneToBlob is provided as convenience function to export to memory buffers.
122 * @param pPreprocessing Accepts any choice of the #aiPostProcessing enumerated
123 * flags, but in reality only a subset of them makes sense here. Specifying
124 * 'preprocessing' flags is useful if the input scene does not conform to
125 * Assimp's default conventions as specified in the @link data Data Structures Page @endlink.
126 * In short, this means the geometry data should use a right-handed coordinate systems, face
127 * winding should be counter-clockwise and the UV coordinate origin is assumed to be in
128 * the upper left. The #aiProcess_MakeLeftHanded, #aiProcess_FlipUVs and
129 * #aiProcess_FlipWindingOrder flags are used in the import side to allow users
130 * to have those defaults automatically adapted to their conventions. Specifying those flags
131 * for exporting has the opposite effect, respectively. Some other of the
132 * #aiPostProcessSteps enumerated values may be useful as well, but you'll need
133 * to try out what their effect on the exported file is. Many formats impose
134 * their own restrictions on the structure of the geometry stored therein,
135 * so some preprocessing may have little or no effect at all, or may be
136 * redundant as exporters would apply them anyhow. A good example
137 * is triangulation - whilst you can enforce it by specifying
138 * the #aiProcess_Triangulate flag, most export formats support only
139 * triangulate data so they would run the step anyway.
140 * @return a status code indicating the result of the export
141 */
142 ASSIMP_API aiReturn aiExportScene( const C_STRUCT aiScene* pScene,
143 const char* pFormatId,
144 const char* pFileName,
145 unsigned int pPreprocessing);
148 // --------------------------------------------------------------------------------
149 /** Exports the given scene to a chosen file format using custom IO logic supplied by you.
150 * @param pScene The scene to export. Stays in possession of the caller, is not changed by the function.
151 * @param pFormatId ID string to specify to which format you want to export to. Use
152 * aiGetExportFormatCount() / aiGetExportFormatDescription() to learn which export formats are available.
153 * @param pFileName Output file to write
154 * @param pIO custom IO implementation to be used. Use this if you use your own storage methods.
155 * If none is supplied, a default implementation using standard file IO is used. Note that
156 * #aiExportSceneToBlob is provided as convenience function to export to memory buffers.
157 * @param pPreprocessing Please see the documentation for #aiExportScene
158 * @return a status code indicating the result of the export
159 * @note Include <aiFileIO.h> for the definition of #aiFileIO.
160 */
161 ASSIMP_API aiReturn aiExportSceneEx( const C_STRUCT aiScene* pScene,
162 const char* pFormatId,
163 const char* pFileName,
164 C_STRUCT aiFileIO* pIO,
165 unsigned int pPreprocessing );
168 // --------------------------------------------------------------------------------
169 /** Describes a blob of exported scene data. Use #aiExportSceneToBlob() to create a blob containing an
170 * exported scene. The memory referred by this structure is owned by Assimp. Use #aiReleaseExportedFile()
171 * to free its resources. Don't try to free the memory on your side - it will crash for most build configurations
172 * due to conflicting heaps.
173 *
174 * Blobs can be nested - each blob may reference another blob, which may in turn reference another blob and so on.
175 * This is used when exporters write more than one output file for a given #aiScene. See the remarks for
176 * #aiExportDataBlob::name for more information.
177 */
178 struct aiExportDataBlob
179 {
180 /// Size of the data in bytes
181 size_t size;
183 /// The data.
184 void* data;
186 /** Name of the blob. An empty string always
187 indicates the first (and primary) blob,
188 which contains the actual file data.
189 Any other blobs are auxiliary files produced
190 by exporters (i.e. material files). Existence
191 of such files depends on the file format. Most
192 formats don't split assets across multiple files.
194 If used, blob names usually contain the file
195 extension that should be used when writing
196 the data to disc.
197 */
198 aiString name;
200 /** Pointer to the next blob in the chain or NULL if there is none. */
201 aiExportDataBlob * next;
203 #ifdef __cplusplus
204 /// Default constructor
205 aiExportDataBlob() { size = 0; data = next = NULL; }
206 /// Releases the data
207 ~aiExportDataBlob() { delete [] static_cast<unsigned char*>( data ); delete next; }
209 private:
210 // no copying
211 aiExportDataBlob(const aiExportDataBlob& );
212 aiExportDataBlob& operator= (const aiExportDataBlob& );
213 #endif // __cplusplus
214 };
216 // --------------------------------------------------------------------------------
217 /** Exports the given scene to a chosen file format. Returns the exported data as a binary blob which
218 * you can write into a file or something. When you're done with the data, use #aiReleaseExportBlob()
219 * to free the resources associated with the export.
220 * @param pScene The scene to export. Stays in possession of the caller, is not changed by the function.
221 * @param pFormatId ID string to specify to which format you want to export to. Use
222 * #aiGetExportFormatCount() / #aiGetExportFormatDescription() to learn which export formats are available.
223 * @param pPreprocessing Please see the documentation for #aiExportScene
224 * @return the exported data or NULL in case of error
225 */
226 ASSIMP_API const C_STRUCT aiExportDataBlob* aiExportSceneToBlob( const C_STRUCT aiScene* pScene, const char* pFormatId, unsigned int pPreprocessing );
229 // --------------------------------------------------------------------------------
230 /** Releases the memory associated with the given exported data. Use this function to free a data blob
231 * returned by aiExportScene().
232 * @param pData the data blob returned by #aiExportSceneToBlob
233 */
234 ASSIMP_API C_STRUCT void aiReleaseExportBlob( const C_STRUCT aiExportDataBlob* pData );
236 #ifdef __cplusplus
237 }
238 #endif
240 #endif // ASSIMP_BUILD_NO_EXPORT
241 #endif // AI_EXPORT_H_INC