1/****************************************************************************************
2
3 Copyright (C) 2015 Autodesk, Inc.
4 All rights reserved.
5
6 Use of this software is subject to the terms of the Autodesk license agreement
7 provided at the time of installation or download, or which otherwise accompanies
8 this software in either electronic or hard copy form.
9
10****************************************************************************************/
11
12//! \file fbxcluster.h
13#ifndef _FBXSDK_SCENE_GEOMETRY_CLUSTER_H_
14#define _FBXSDK_SCENE_GEOMETRY_CLUSTER_H_
15
16#include <fbxsdk/fbxsdk_def.h>
17
18#include <fbxsdk/scene/geometry/fbxsubdeformer.h>
19
20#include <fbxsdk/fbxsdk_nsbegin.h>
21
22/** Class for clusters (links).
23 * A cluster, or link, is an entity acting on a geometry (FbxGeometry).
24 * More precisely, the cluster acts on a subset of the geometry's control points.
25 * For each control point that the cluster acts on, the intensity of the cluster's
26 * action is modulated by a weight. The link mode (ELinkMode) specifies how
27 * the weights are taken into account.
28 *
29 * The cluster's link node specifies the node (FbxNode) that influences the
30 * control points of the cluster. If the node is animated, the control points
31 * will move accordingly.
32 *
33 * A cluster is usually part of a skin (\see FbxDeformer, FbxSkin). For example,
34 * imagine a mesh representing a humanoid, and imagine a skeleton made of bones.
35 * Each bone is represented by a node in FBX.
36 * To bind the geometry to the nodes,
37 * we create a skin (FbxSkin). The skin has many clusters, each one corresponding
38 * to a bone.
39 * Each node influences some control
40 * points of the mesh. A node has a high influence on some of the points (high weight)
41 * and lower influence on some other points (low weight). Some points of the mesh
42 * are not affected at all by the bone, so they would not be part of the corresponding
43 * cluster.
44 *
45 *\nosubgrouping
46 */
47class FBXSDK_DLL FbxCluster : public FbxSubDeformer
48{
49 FBXSDK_OBJECT_DECLARE(FbxCluster,FbxSubDeformer);
50
51public:
52 /**
53 * \name General Functions
54 */
55 //@{
56 /** Get the type of the sub deformer.
57 * \return SubDeformer type identifier: eCluster.
58 */
59 EType GetSubDeformerType() const {return eCluster; };
60
61 /** Restore the cluster to its initial state.
62 * Calling this function will clear the following:
63 * \li Pointer to linked node.
64 * \li Pointer to associate model.
65 * \li Control point indices and weights.
66 * \li Transformation matrices.
67 */
68 void Reset();
69 //@}
70 /**
71 * \name Link Mode, Link Node, Associate Model
72 */
73 //@{
74 /** Link modes.
75 * The link mode sets how the link influences the position of a control
76 * point and the relationship between the weights assigned to a control
77 * point. The weights assigned to a control point are distributed among
78 * the set of links associated with an instance of class FbxGeometry.
79 */
80 enum ELinkMode
81 {
82 eNormalize, /*!< In mode eNormalize, the sum of the weights assigned to a control point
83 is normalized to 1.0. Setting the associate model in this mode is not
84 relevant. The influence of the link is a function of the displacement of the
85 link node relative to the node containing the control points.*/
86 eAdditive,
87 /*!< In mode eAdditive, the sum of the weights assigned to a control point
88 is kept as is. It is the only mode where setting the associate model is
89 relevant. The influence of the link is a function of the displacement of
90 the link node relative to the node containing the control points or,
91 if set, the associate model. The weight gives the proportional displacement
92 of a control point. For example, if the weight of a link over a control
93 point is set to 2.0, a displacement of the link node of 1 unit in the X
94 direction relative to the node containing the control points or, if set,
95 the associate model, triggers a displacement of the control point of 2
96 units in the same direction.*/
97 eTotalOne
98 /*!< Mode eTotalOne is identical to mode eNormalize except that the sum of the
99 weights assigned to a control point is not normalized and must equal 1.0.*/
100 };
101
102 /** Set the link mode.
103 * \param pMode The link mode.
104 * \remarks All the links associated to an instance of class FbxGeometry must have the same link mode.
105 */
106 void SetLinkMode(ELinkMode pMode);
107
108 /** Get the link mode.
109 * \return The link mode.
110 */
111 ELinkMode GetLinkMode() const;
112
113 /** Set the link node. The link node is the node which influences the displacement
114 * of the control points. Typically, the link node is the bone a skin is attached to.
115 * \param pNode The link node.
116 */
117 void SetLink(const FbxNode* pNode);
118
119 /** Get the link node. The link node is the node which influences the displacement
120 * of the control points. Typically, the link node is the bone a skin is attached to.
121 * \return The link node or \c NULL if FbxCluster::SetLink() has not been called before.
122 */
123 FbxNode* GetLink();
124
125 /** Get the link node (as const). The link node is the node which influences the displacement
126 * of the control points. Typically, the link node is the bone a skin is attached to.
127 * \return The link node or \c NULL if FbxCluster::SetLink() has not been called before.
128 */
129 const FbxNode* GetLink() const;
130
131 /** Set the associate model.
132 * The associate model is optional. It is only relevant if the link mode
133 * is of type eAdditive. If set, the associate model is the node used as a reference to
134 * measure the relative displacement of the link node. Otherwise, the displacement of
135 * the link node is measured relative to the node containing the control points.
136 * Typically, the associate model node is the parent of the bone a skin is attached to.
137 * \param pNode The associate model node.
138 */
139 void SetAssociateModel(FbxNode* pNode);
140
141 /** Get the associate model.
142 * The associate model is optional. It is only relevant if the link mode is of type
143 * eAdditive. If set, the associate model is the node used as a reference to
144 * measure the relative displacement of the link node. Otherwise, the displacement of
145 * the link node is measured relative the the node containing the control points.
146 * Typically, the associate model node is the parent of the bone a skin is attached to.
147 * \return The associate model node or \c NULL if FbxCluster::SetAssociateModel() has not been called before.
148 */
149 FbxNode* GetAssociateModel() const;
150 //@}
151 /**
152 * \name Control Points
153 * A link has an array of indices to control points and associated weights.
154 * The indices refer to the control points in the instance of class FbxGeometry
155 * owning the link. The weights are the influence of the link node over the
156 * displacement of the indexed control points.
157 */
158 //@{
159
160 /** Add an element in both arrays of control point indices and weights.
161 * \param pIndex The index of the control point.
162 * \param pWeight The link weight for this control point.
163 */
164 void AddControlPointIndex(int pIndex, double pWeight);
165
166 /** Get the length of the arrays of control point indices and weights.
167 * \return Length of the arrays of control point indices and weights.
168 * Returns 0 if no control point indices have been added or the arrays have been reset.
169 */
170 int GetControlPointIndicesCount() const;
171
172 /** Get the array of control point indices.
173 * \return Pointer to the array of control point indices.
174 * \c NULL if no control point indices have been added or the array has been reset.
175 */
176 int* GetControlPointIndices() const;
177
178 /** Get the array of control point weights.
179 * \return Pointer to the array of control point weights.
180 * \c NULL if no control point indices have been added or the array has been reset.
181 */
182 double* GetControlPointWeights() const;
183
184 //@}
185
186 /** Set the array size for the three arrays: the array of control point indices, the array of weights
187 * and the array of blend weights.
188 * \param pCount The new count.
189 */
190 void SetControlPointIWCount(int pCount);
191
192 /**
193 * \name Transformation matrices
194 * A link has three transformation matrices:
195 * \li Transform refers to the global initial transform of the geometry node that contains the link node.
196 * \li TransformLink refers to global initial transform of the link node.
197 * \li TransformAssociateModel refers to the global initial transform of the associate model.
198 *
199 * For example, given a mesh binding with several bones(links), Transform is the global transform
200 * of the mesh at the binding moment, TransformLink is the global transform of the bone(link)
201 * at the binding moment, TransformAssociateModel is the global transform of the associate model
202 * at the binding moment.
203 */
204 //@{
205
206 /** Set matrix associated with the node containing the link.
207 * \param pMatrix Transformation matrix.
208 */
209 void SetTransformMatrix(const FbxAMatrix& pMatrix);
210
211 /** Get matrix associated with the node containing the link.
212 * \param pMatrix Transformation matrix to be filled with appropriate data.
213 * \return Input parameter matrix filled with appropriate data.
214 */
215 FbxAMatrix& GetTransformMatrix(FbxAMatrix& pMatrix) const;
216
217 /** Set matrix associated with the link node.
218 * \param pMatrix Transformation matrix.
219 */
220 void SetTransformLinkMatrix(const FbxAMatrix& pMatrix);
221
222 /** Get matrix associated with the link node.
223 * \param pMatrix Transformation matrix to be filled with appropriate data..
224 * \return Input parameter matrix filled with appropriate data.
225 */
226 FbxAMatrix& GetTransformLinkMatrix(FbxAMatrix& pMatrix) const;
227
228 /** Set matrix associated with the associate model.
229 * \param pMatrix Transformation matrix.
230 */
231 void SetTransformAssociateModelMatrix(const FbxAMatrix& pMatrix);
232
233 /** Get matrix associated with the associate model.
234 * \param pMatrix Transformation matrix to be filled with appropriate data..
235 * \return Input parameter matrix filled with appropriate data.
236 */
237 FbxAMatrix& GetTransformAssociateModelMatrix(FbxAMatrix& pMatrix) const;
238
239 /** Set matrix associated with the parent node.
240 * \param pMatrix Transformation matrix.
241 */
242 void SetTransformParentMatrix(const FbxAMatrix& pMatrix);
243
244 /** Get matrix associated with the parent node.
245 * \param pMatrix Transformation matrix to be filled with appropriate data..
246 * \return Input parameter matrix filled with appropriate data.
247 */
248 FbxAMatrix& GetTransformParentMatrix(FbxAMatrix& pMatrix) const;
249
250 /** Get the Transform Parent set flag value.
251 * \return \c true if transform matrix associated with parent node is set.
252 */
253 bool IsTransformParentSet() const { return mIsTransformParentSet; }
254
255 //@}
256
257/*****************************************************************************************************************************
258** WARNING! Anything beyond these lines is for internal use, may not be documented and is subject to change without notice! **
259*****************************************************************************************************************************/
260#ifndef DOXYGEN_SHOULD_SKIP_THIS
261 virtual FbxObject& Copy(const FbxObject& pObject);
262 void SetUserData(const char* pUserDataID, const char* pUserData);
263 const char* GetUserDataID () const;
264 const char* GetUserData () const;
265 const char* GetUserData (const char* pUserDataID) const;
266
267 // For pre version 6 support
268 FbxString mBeforeVersion6LinkName;
269 FbxString mBeforeVersion6AssociateModelName;
270
271
272protected:
273 virtual void Construct(const FbxObject* pFrom);
274 virtual void ConstructProperties(bool pForceSet);
275
276 virtual FbxStringList GetTypeFlags() const;
277
278 ELinkMode mLinkMode;
279 FbxString mUserDataID;
280 FbxString mUserData;
281 FbxArray<int> mControlPointIndices;
282 FbxArray<double> mControlPointWeights;
283 FbxMatrix mTransform;
284 FbxMatrix mTransformLink;
285 FbxMatrix mTransformAssociate;
286 FbxMatrix mTransformParent;
287 bool mIsTransformParentSet;
288
289 FbxPropertyT<FbxReference> SrcModelReference;
290#endif /* !DOXYGEN_SHOULD_SKIP_THIS *****************************************************************************************/
291};
292
293#include <fbxsdk/fbxsdk_nsend.h>
294
295#endif /* _FBXSDK_SCENE_GEOMETRY_CLUSTER_H_ */
296