source: NonGTP/FCollada/FUtils/FUDaeWriter.h @ 964

Revision 964, 14.6 KB checked in by igarcia, 18 years ago (diff)
RevLine 
[964]1/*
2        Copyright (C) 2005-2006 Feeling Software Inc.
3        MIT License: http://www.opensource.org/licenses/mit-license.php
4*/
5
6/**
7        @file FUDaeWriter.h
8        This file contains the FUDaeWriter namespace.
9*/
10
11#ifndef _FU_DAE_WRITER_H_
12#define _FU_DAE_WRITER_H_
13
14#ifdef HAS_LIBXML
15
16#include "FUtils/FUDaeEnum.h"
17#include "FUtils/FUDaeSyntax.h"
18#include "FUtils/FUUri.h"
19#include "FUtils/FUXmlWriter.h"
20
21/**
22        Common COLLADA XML writing functions.
23        Based on top of the FUXmlWriter namespace and the LibXML2 library.
24        This whole namespace is considered external and should only be used
25        by the FCollada library.
26       
27        @ingroup FUtils
28*/
29namespace FUDaeWriter
30{
31        using namespace FUXmlWriter;
32
33        /** Common accessor type string arrays.
34                These are NULL-terminated and can be used with the AddAccessor function. */
35        struct FCOLLADA_EXPORT FUDaeAccessor
36        {
37                static const char* XYZW[]; /**< Use for vector and position sources. */
38                static const char* RGBA[]; /**< Use for color sources. */
39                static const char* STPQ[]; /**< Use for texture coordinate sources. */
40        };
41
42        /** Writes out the \<extra\>\<technique\> element unto the given parent xml tree node.
43                This function ensures that only one \<extra\> element exists and that only
44                one \<technique\> element exists for the given profile.
45                @param parent The parent XML tree node.
46                @param profile The application-specific profile name.
47                @return The \<technique\> XML tree node. */
48        FCOLLADA_EXPORT xmlNode* AddExtraTechniqueChild(xmlNode* parent, const char* profile);
49
50        /** Writes out the \<technique\> element unto the given parent xml tree node.
51                This function ensures that only one \<technique\> element exists for the given profile.
52                @param parent The parent XML tree node.
53                @param profile The application-specific profile name.
54                @return The \<technique\> XML tree node. */
55        FCOLLADA_EXPORT xmlNode* AddTechniqueChild(xmlNode* parent, const char* profile);
56
57        /** Writes out a COLLADA parameter element.
58                This is used for the source accessors.
59                A COLLADA parameter has the form: \<param name='' type=''\>value\</param\>.
60                @param parent The parent XML tree node.
61                @param name The name attribute value.
62                @param type The type attribute value.
63                @return The created \<param\> XML tree node. */
64        FCOLLADA_EXPORT xmlNode* AddParameter(xmlNode* parent, const char* name, const char* type);
65
66        /** Writes out a COLLADA input element.
67                This is a very common element. For example, it is used in
68                the \<polygons\>, \<sampler\> and \<joints\> elements.
69                A COLLADA input has the form: \<input source='\#source_id' semantic='' offset='' set=''/\>.
70                @param parent The parent XML tree node.
71                @param sourceId The source attribute value.
72                        This is the COLLADA id of a valid \<source\> element.
73                @param semantic The semantic attribute value.
74                        This is a valid COLLADA semantic.
75                        For example: POSITION, TEXCOORD, WEIGHT, IN_TANGENT.
76                @param offset The optional offset attribute value.
77                        When used in conjunction with the \<v\> or the \<p\> elements, this is
78                        the offset for the input data indices within the interleaved indices.
79                @param set The optional set attribute value.
80                        This unsigned integer is used to tied together multiple inputs.
81                @return The created \<input\> XML tree node. */
82        FCOLLADA_EXPORT xmlNode* AddInput(xmlNode* parent, const char* sourceId, const char* semantic, int32 offset=-1, int32 set=-1);
83        inline xmlNode* AddInput(xmlNode* parent, const string& sourceId, const char* semantic, int32 offset=-1, int32 set=-1) { return AddInput(parent, sourceId.c_str(), semantic, offset, set); } /**< See above. */
84
85        /** Writes out a COLLADA strongly-typed data array.
86                To write out data values, it is preferable to use the AddSourceX functions.
87                @param parent The parent XML tree node.
88                @param id The COLLADA id of the array.
89                        This id is used only by the accessor of a source.
90                @param arrayType The strongly-typed name of the array.
91                        For example: \<float_array\>, \<Name_array\>.
92                @param content The array content.
93                @param count The number of entries within the content of the array.
94                @return The created XML tree node. */
95        FCOLLADA_EXPORT xmlNode* AddArray(xmlNode* parent, const char* id, const char* arrayType, const char* content, size_t count);
96
97        /** Writes out a COLLADA array of matrices.
98                To write out data values, it is preferable to use the AddSourceX functions.
99                @param parent The parent XML tree node.
100                @param id The COLLADA id of the array.
101                        This id is used only by the accessor of a source.
102                @param values A list of matrices.
103                @param lengthFactor An optional scale factor for
104                        the translation column of the matrices.
105                @return The created XML tree node. */
106        FCOLLADA_EXPORT xmlNode* AddArray(xmlNode* parent, const char* id, const FMMatrix44List& values, float lengthFactor=1.0f);
107
108        /** Writes out a COLLADA array of 3D vectors.
109                To write out data values, it is preferable to use the AddSourceX functions.
110                @param parent The parent XML tree node.
111                @param id The COLLADA id of the array.
112                        This id is used only by the accessor of a source.
113                @param values A list of 3D vectors.
114                @param lengthFactor An optional scale factor for all the 3D vectors.
115                @return The created XML tree node. */
116        FCOLLADA_EXPORT xmlNode* AddArray(xmlNode* parent, const char* id, const FMVector3List& values, float lengthFactor=1.0f);
117
118        /** Writes out a COLLADA array of floating-point values.
119                To write out data values, it is preferable to use the AddSourceX functions.
120                @param parent The parent XML tree node.
121                @param id The COLLADA id of the array.
122                        This id is used only by the accessor of a source.
123                @param values A list of floating-point values.
124                @param lengthFactor An optional scale factor for all the floating-point values.
125                @return The created XML tree node. */
126        FCOLLADA_EXPORT xmlNode* AddArray(xmlNode* parent, const char* id, const FloatList& values, float lengthFactor=1.0f);
127
128        /** Writes out a COLLADA array of UTF-8 tokens.
129                To write out data values, it is preferable to use the AddSourceX functions.
130                @param parent The parent XML tree node.
131                @param id The COLLADA id of the array.
132                        This id is used only by the accessor of a source.
133                @param values A list of UTF-8 tokens. The members of this list will appear
134                        space-separated within the COLLADA document.
135                @param arrayType The COLLADA element name for the output array.
136                        Defaults to \<Name_array\>. This might also be \<IDRef_array\>.
137                @return The created XML tree node. */
138        FCOLLADA_EXPORT xmlNode* AddArray(xmlNode* parent, const char* id, const StringList& values, const char* arrayType=DAE_NAME_ARRAY_ELEMENT);
139
140        /** Writes out a COLLADA accessor to be used within a source.
141                This function should really be called only from within AddSourceX functions.
142                @param parent The parent XML tree node.
143                @param arrayId The COLLADA id of the array.
144                @param count The number of complete elements within the array.
145                @param stride The number of values that should be used together to create one array element.
146                @param parameters The list of parameter names.
147                        Some valid parameter names are available in the FUDaeAccessor class.
148                @param type The type name of the parameters. Examples: float, float4x4, Name or IDRef.
149                @return The created XML tree node. */
150        FCOLLADA_EXPORT xmlNode* AddAccessor(xmlNode* parent, const char* arrayId, size_t count, size_t stride=1, const char** parameters=NULL, const char* type=NULL);
151        inline xmlNode* AddAccessor(xmlNode* parent, const string& arrayId, size_t count, size_t stride=1, const char** parameters=NULL, const char* type=NULL) { return AddAccessor(parent, arrayId.c_str(), count, stride, parameters, type); } /**< See above. */
152
153        /** Writes out a COLLADA multi-dimensional source of floating-point values.
154                @param parent The parent XML tree node.
155                @param id The COLLADA id of the source.
156                @param values The list of floating-point values.
157                @param stride The number of dimensions. This is the number of
158                        floating-point values that should be used together to create one element.
159                @param parameters The list of accessor parameter names.
160                        Some valid parameter names are available in the FUDaeAccessor class.
161                @param lengthFactor An optional scale factor for all the floating-point values.
162                @return The created XML tree node. */
163        FCOLLADA_EXPORT xmlNode* AddSourceFloat(xmlNode* parent, const char* id, const FloatList& values, size_t stride=1, const char** parameters=NULL, float lengthFactor=1.0f);
164        inline xmlNode* AddSourceFloat(xmlNode* parent, const string& id, const FloatList& values, size_t stride=1, const char** parameters=NULL, float lengthFactor=1.0f) { return AddSourceFloat(parent, id.c_str(), values, stride, parameters, lengthFactor); } /**< See above. */
165
166        /** Writes out a COLLADA source of floating-point values.
167                @param parent The parent XML tree node.
168                @param id The COLLADA id of the source.
169                @param values The list of floating-point values.
170                @param parameter The accessor parameter name.
171                        Some valid parameter names are available in the FUDaeAccessor class.
172                @param lengthFactor An optional scale factor for all the floating-point values.
173                @return The created XML tree node. */
174        FCOLLADA_EXPORT xmlNode* AddSourceFloat(xmlNode* parent, const char* id, const FloatList& values, const char* parameter=NULL, float lengthFactor=1.0f);
175        inline xmlNode* AddSourceFloat(xmlNode* parent, const string& id, const FloatList& values, const char* parameter=NULL, float lengthFactor=1.0f) { return AddSourceFloat(parent, id.c_str(), values, parameter, lengthFactor); } /**< See above. */
176
177        /** Writes out a COLLADA source of matrices.
178                @param parent The parent XML tree node.
179                @param id The COLLADA id of the source.
180                @param values The list of matrices.
181                @param lengthFactor An optional scale factor for all the floating-point values.
182                @return The created XML tree node. */
183        FCOLLADA_EXPORT xmlNode* AddSourceMatrix(xmlNode* parent, const char* id, const FMMatrix44List& values, float lengthFactor=1.0f);
184        inline xmlNode* AddSourceMatrix(xmlNode* parent, const string& id, const FMMatrix44List& values, float lengthFactor=1.0f) { return AddSourceMatrix(parent, id.c_str(), values, lengthFactor); } /**< See above. */
185
186        /** Writes out a COLLADA source of matrices.
187                @param parent The parent XML tree node.
188                @param id The COLLADA id of the source.
189                @param values The list of matrices.
190                @return The created XML tree node. */
191        FCOLLADA_EXPORT xmlNode* AddSourceColor(xmlNode* parent, const char* id, const FMVector3List& values);
192        inline xmlNode* AddSourceColor(xmlNode* parent, const string& id, const FMVector3List& values) { return AddSourceColor(parent, id.c_str(), values); } /**< See above. */
193
194        /** Writes out a COLLADA source of texture coordinates.
195                @param parent The parent XML tree node.
196                @param id The COLLADA id of the source.
197                @param values The list of 3D texture coordinates.
198                @return The created XML tree node. */
199        FCOLLADA_EXPORT xmlNode* AddSourceTexcoord(xmlNode* parent, const char* id, const FMVector3List& values);
200        inline xmlNode* AddSourceTexcoord(xmlNode* parent, const string& id, const FMVector3List& values) { return AddSourceTexcoord(parent, id.c_str(), values); } /**< See above. */
201
202        /** Writes out a COLLADA source of 3D positions or vectors.
203                @param parent The parent XML tree node.
204                @param id The COLLADA id of the source.
205                @param values The list of 3D vectors.
206                @param lengthFactor An optional scale factor for all the 3D vectors.
207                @return The created XML tree node. */
208        FCOLLADA_EXPORT xmlNode* AddSourcePosition(xmlNode* parent, const char* id, const FMVector3List& values, float lengthFactor=1.0f);
209        inline xmlNode* AddSourcePosition(xmlNode* parent, const string& id, const FMVector3List& values, float lengthFactor=1.0f) { return AddSourcePosition(parent, id.c_str(), values, lengthFactor); } /**< See above. */
210
211        /** Writes out a COLLADA source of UTF-8 tokens.
212                @param parent The parent XML tree node.
213                @param id The COLLADA id of the source.
214                @param values The list of UTF-8 tokens. This list will be space-
215                        separated within the COLLADA document, so you none of the
216                        token should have spaces in them.
217                @param parameter The name of the accessor parameter.
218                @return The created XML tree node. */
219        FCOLLADA_EXPORT xmlNode* AddSourceString(xmlNode* parent, const char* id, const StringList& values, const char* parameter=NULL);
220        inline xmlNode* AddSourceString(xmlNode* parent, const string& id, const StringList& values, const char* parameter=NULL) { return AddSourceString(parent, id.c_str(), values, parameter); } /**< See above. */
221
222        /** Writes out a COLLADA source of COLLADA references.
223                @param parent The parent XML tree node.
224                @param id The COLLADA id of the source.
225                @param values The list of COLLADA references.
226                @param parameter The name of the accessor parameter.
227                @return The created XML tree node. */
228        FCOLLADA_EXPORT xmlNode* AddSourceIDRef(xmlNode* parent, const char* id, const StringList& values, const char* parameter=NULL);
229        inline xmlNode* AddSourceIDRef(xmlNode* parent, const string& id, const StringList& values, const char* parameter=NULL) { return AddSourceIDRef(parent, id.c_str(), values, parameter); } /**< See above. */
230
231        /** Writes out a COLLADA source of interpolation tokens.
232                This function is used within the export of animation curves.
233                @param parent The parent XML tree node.
234                @param id The COLLADA id of the source.
235                @param interpolations The list of interpolation tokens.
236                @return The created XML tree node. */
237        FCOLLADA_EXPORT xmlNode* AddSourceInterpolation(xmlNode* parent, const char* id, const FUDaeInterpolationList& interpolations);
238        inline xmlNode* AddSourceInterpolation(xmlNode* parent, const string& id, const FUDaeInterpolationList& values) { return AddSourceInterpolation(parent, id.c_str(), values); } /**< See above. */
239
240        /** Cleans up a given name into a valid COLLADA id.
241                This function does no check for uniqueness.
242                @param id A name.
243                @return A valid COLLADA id. */
244        FCOLLADA_EXPORT string CleanId(const char* id);
245        inline string CleanId(const string& id) { return CleanId(id.c_str()); } /**< See above. */
246
247        /** Cleans up a given name into a valid COLLADA name.
248                @param name A name.
249                @return A valid COLLADA name. */
250        FCOLLADA_EXPORT fstring CleanName(const fchar* name);
251        inline fstring CleanName(const fstring& name) { return CleanName(name.c_str()); } /**< See above. */
252
253        /** Adds the 'sid' attribute to a given XML tree node.
254                The sub-id is verified to ensure uniqueness within the scope.
255                @param node The XML tree node.
256                @param wantedSid The wanted sub-id.
257                @return The actual sub-id written to the XML tree node. */
258        FCOLLADA_EXPORT string AddNodeSid(xmlNode* node, const char* wantedSid);
259};
260
261#endif // HAS_LIBXML
262
263#endif // _FU_DAE_WRITER_H_
Note: See TracBrowser for help on using the repository browser.