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