Context Navigation

source: OGRE/trunk/ogrenew/OgreMain/include/OgreNode.h @ 657

Revision 657, 28.8 KB checked in by mattausch, 18 years ago (diff)
added ogre dependencies and patched ogre sources

Line
1	/*
2	-----------------------------------------------------------------------------
3	This source file is part of OGRE
4	(Object-oriented Graphics Rendering Engine)
5	For the latest info, see http://www.ogre3d.org/
6
7	Copyright (c) 2000-2005 The OGRE Team
8	Also see acknowledgements in Readme.html
9
10	This program is free software; you can redistribute it and/or modify it under
11	the terms of the GNU Lesser General Public License as published by the Free Software
12	Foundation; either version 2 of the License, or (at your option) any later
13	version.
14
15	This program is distributed in the hope that it will be useful, but WITHOUT
16	ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
17	FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
18
19	You should have received a copy of the GNU Lesser General Public License along with
20	this program; if not, write to the Free Software Foundation, Inc., 59 Temple
21	Place - Suite 330, Boston, MA 02111-1307, USA, or go to
22	http://www.gnu.org/copyleft/lesser.txt.
23	-----------------------------------------------------------------------------
24	*/
25	#ifndef _Node_H__
26	#define _Node_H__
27
28	#include "OgrePrerequisites.h"
29
30	#include "OgreMatrix3.h"
31	#include "OgreMatrix4.h"
32	#include "OgreQuaternion.h"
33	#include "OgreString.h"
34	#include "OgreRenderable.h"
35	#include "OgreIteratorWrappers.h"
36
37	namespace Ogre {
38
39
40	/** Class representing a general-purpose node an articulated scene graph.
41	@remarks
42	A node in the scene graph is a node in a structured tree. A node contains
43	information about the transformation which will apply to
44	it and all of it's children. Child nodes can have transforms of their own, which
45	are combined with their parent's transformations.
46	@par
47	This is an abstract class - concrete classes are based on this for specific purposes,
48	e.g. SceneNode, Bone
49	*/
50	class _OgreExport Node : public Renderable
51	{
52	public:
53	/** Enumeration denoting the spaces which a transform can be relative to.
54	*/
55	enum TransformSpace
56	{
57	/// Transform is relative to the local space
58	TS_LOCAL,
59	/// Transform is relative to the space of the parent node
60	TS_PARENT,
61	/// Transform is relative to world space
62	TS_WORLD
63	};
64	typedef HashMap<String, Node*> ChildNodeMap;
65	typedef MapIterator<ChildNodeMap> ChildNodeIterator;
66	typedef ConstMapIterator<ChildNodeMap> ConstChildNodeIterator;
67
68	protected:
69	/// Pointer to parent node
70	Node* mParent;
71	/// Collection of pointers to direct children; hashmap for efficiency
72	ChildNodeMap mChildren;
73
74	typedef std::set<Node*> ChildUpdateSet;
75	/// List of children which need updating, used if self is not out of date but children are
76	mutable ChildUpdateSet mChildrenToUpdate;
77	/// Flag to indicate own transform from parent is out of date
78	mutable bool mNeedParentUpdate;
79	/// Flag indicating that all children need to be updated
80	mutable bool mNeedChildUpdate;
81	/// Flag indicating that parent has been notified about update request
82	mutable bool mParentNotified ;
83
84	/// Friendly name of this node, can be automatically generated if you don't care
85	String mName;
86
87	/// Incremented count for next name extension
88	static unsigned long msNextGeneratedNameExt;
89
90	/// Stores the orientation of the node relative to it's parent.
91	Quaternion mOrientation;
92
93	/// Stores the position/translation of the node relative to its parent.
94	Vector3 mPosition;
95
96	/// Stores the scaling factor applied to this node
97	Vector3 mScale;
98
99	/// Stores whether this node inherits scale from it's parent
100	bool mInheritScale;
101
102	/// Material pointer should this node be rendered
103	mutable MaterialPtr mpMaterial;
104
105	/// Only available internally - notification of parent.
106	virtual void setParent(Node* parent);
107
108	/** Cached combined orientation.
109	@par
110	This member is the orientation derived by combining the
111	local transformations and those of it's parents.
112	This is updated when _updateFromParent is called by the
113	SceneManager or the nodes parent.
114	*/
115	mutable Quaternion mDerivedOrientation;
116
117	/** Cached combined position.
118	@par
119	This member is the position derived by combining the
120	local transformations and those of it's parents.
121	This is updated when _updateFromParent is called by the
122	SceneManager or the nodes parent.
123	*/
124	mutable Vector3 mDerivedPosition;
125
126	/** Cached combined scale.
127	@par
128	This member is the position derived by combining the
129	local transformations and those of it's parents.
130	This is updated when _updateFromParent is called by the
131	SceneManager or the nodes parent.
132	*/
133	mutable Vector3 mDerivedScale;
134
135	/** Triggers the node to update it's combined transforms.
136	@par
137	This method is called internally by Ogre to ask the node
138	to update it's complete transformation based on it's parents
139	derived transform.
140	*/
141	virtual void _updateFromParent(void) const;
142
143	/** Internal method for creating a new child node - must be overridden per subclass. */
144	virtual Node* createChildImpl(void) = 0;
145
146	/** Internal method for creating a new child node - must be overridden per subclass. */
147	virtual Node* createChildImpl(const String& name) = 0;
148
149	/** Internal method for building a Matrix4 from orientation / scale / position.
150	@remarks
151	Transform is performed in the order rotate, scale, translation, i.e. translation is independent
152	of orientation axes, scale does not affect size of translation, rotation and scaling are always
153	centered on the origin.
154	*/
155	void makeTransform(
156	const Vector3& position,
157	const Vector3& scale,
158	const Quaternion& orientation,
159	Matrix4& destMatrix ) const;
160
161	/** Internal method for building an inverse Matrix4 from orientation / scale / position.
162	@remarks
163	As makeTransform except it build the inverse given the same data as makeTransform, so
164	performing -translation, 1/scale, -rotate in that order.
165	*/
166	void makeInverseTransform(
167	const Vector3& position,
168	const Vector3& scale,
169	const Quaternion& orientation,
170	Matrix4& destMatrix );
171
172	/// The position to use as a base for keyframe animation
173	Vector3 mInitialPosition;
174	/// The orientation to use as a base for keyframe animation
175	Quaternion mInitialOrientation;
176	/// The scale to use as a base for keyframe animation
177	Vector3 mInitialScale;
178
179	// Weight of applied animations so far, used for blending
180	Real mAccumAnimWeight;
181	// The total weighted translation from the initial state so far
182	Vector3 mTransFromInitial;
183	// The total weighted rotation from the initial state so far
184	Quaternion mRotFromInitial;
185	// The total weighted scale from the initial state so far
186	Vector3 mScaleFromInitial;
187
188	/// Cached derived transform as a 4x4 matrix
189	mutable Matrix4 mCachedTransform;
190	mutable bool mCachedTransformOutOfDate;
191
192
193	public:
194	/** Constructor, should only be called by parent, not directly.
195	@remarks
196	Generates a name.
197	*/
198	Node();
199	/** Constructor, should only be called by parent, not directly.
200	@remarks
201	Assigned a name.
202	*/
203	Node(const String& name);
204
205	virtual ~Node();
206
207	/** Returns the name of the node. */
208	const String& getName(void) const;
209
210	/** Gets this node's parent (NULL if this is the root).
211	*/
212	virtual Node* getParent(void) const;
213
214	/** Returns a quaternion representing the nodes orientation.
215	*/
216	virtual const Quaternion & getOrientation() const;
217
218	/** Sets the orientation of this node via a quaternion.
219	*/
220	virtual void setOrientation( const Quaternion& q );
221
222	/** Sets the orientation of this node via quaternion parameters.
223	*/
224	virtual void setOrientation( Real w, Real x, Real y, Real z);
225
226	/** Resets the nodes orientation (local axes as world axes, no rotation).
227	*/
228	virtual void resetOrientation(void);
229
230	/** Sets the position of the node relative to it's parent.
231	*/
232	virtual void setPosition(const Vector3& pos);
233
234	/** Sets the position of the node relative to it's parent.
235	*/
236	virtual void setPosition(Real x, Real y, Real z);
237
238	/** Gets the position of the node relative to it's parent.
239	*/
240	virtual const Vector3 & getPosition(void) const;
241
242	/** Sets the scaling factor applied to this node.
243	@remarks
244	Scaling factors, unlike other transforms, are not always inherited by child nodes.
245	Whether or not scalings affect both the size and position of the child nodes depends on
246	the setInheritScale option of the child. In some cases you want a scaling factor of a parent node
247	to apply to a child node (e.g. where the child node is a part of the same object, so you
248	want it to be the same relative size and position based on the parent's size), but
249	not in other cases (e.g. where the child node is just for positioning another object,
250	you want it to maintain it's own size and relative position). The default is to inherit
251	as with other transforms.
252	@par
253	Note that like rotations, scalings are oriented around the node's origin.
254	*/
255	virtual void setScale(const Vector3& scale);
256
257	/** Sets the scaling factor applied to this node.
258	@remarks
259	Scaling factors, unlike other transforms, are not always inherited by child nodes.
260	Whether or not scalings affect both the size and position of the child nodes depends on
261	the setInheritScale option of the child. In some cases you want a scaling factor of a parent node
262	to apply to a child node (e.g. where the child node is a part of the same object, so you
263	want it to be the same relative size and position based on the parent's size), but
264	not in other cases (e.g. where the child node is just for positioning another object,
265	you want it to maintain it's own size and relative position). The default is to inherit
266	as with other transforms.
267	@par
268	Note that like rotations, scalings are oriented around the node's origin.
269	*/
270	virtual void setScale(Real x, Real y, Real z);
271
272	/** Gets the scaling factor of this node.
273	*/
274	virtual const Vector3 & getScale(void) const;
275
276	/** Tells the node whether it should inherit scaling factors from it's parent node.
277	@remarks
278	Scaling factors, unlike other transforms, are not always inherited by child nodes.
279	Whether or not scalings affect both the size and position of the child nodes depends on
280	the setInheritScale option of the child. In some cases you want a scaling factor of a parent node
281	to apply to a child node (e.g. where the child node is a part of the same object, so you
282	want it to be the same relative size and position based on the parent's size), but
283	not in other cases (e.g. where the child node is just for positioning another object,
284	you want it to maintain it's own size and relative position). The default is to inherit
285	as with other transforms.
286	@param inherit If true, this node's scale and position will be affected by its parent's scale. If false,
287	it will not be affected.
288	*/
289	virtual void setInheritScale(bool inherit);
290
291	/** Returns true if this node is affected by scaling factors applied to the parent node.
292	@remarks
293	See setInheritScale for more info.
294	*/
295	virtual bool getInheritScale(void) const;
296
297	/** Scales the node, combining it's current scale with the passed in scaling factor.
298	@remarks
299	This method applies an extra scaling factor to the node's existing scale, (unlike setScale
300	which overwrites it) combining it's current scale with the new one. E.g. calling this
301	method twice with Vector3(2,2,2) would have the same effect as setScale(Vector3(4,4,4)) if
302	the existing scale was 1.
303	@par
304	Note that like rotations, scalings are oriented around the node's origin.
305	*/
306	virtual void scale(const Vector3& scale);
307
308	/** Scales the node, combining it's current scale with the passed in scaling factor.
309	@remarks
310	This method applies an extra scaling factor to the node's existing scale, (unlike setScale
311	which overwrites it) combining it's current scale with the new one. E.g. calling this
312	method twice with Vector3(2,2,2) would have the same effect as setScale(Vector3(4,4,4)) if
313	the existing scale was 1.
314	@par
315	Note that like rotations, scalings are oriented around the node's origin.
316	*/
317	virtual void scale(Real x, Real y, Real z);
318
319	/** Moves the node along the cartesian axes.
320	@par
321	This method moves the node by the supplied vector along the
322	world cartesian axes, i.e. along world x,y,z
323	@param
324	d Vector with x,y,z values representing the translation.
325	@param
326	relativeTo The space which this transform is relative to.
327	*/
328	virtual void translate(const Vector3& d, TransformSpace relativeTo = TS_PARENT);
329	/** Moves the node along the cartesian axes.
330	@par
331	This method moves the node by the supplied vector along the
332	world cartesian axes, i.e. along world x,y,z
333	@param
334	x
335	@param
336	y
337	@param
338	z Real x, y and z values representing the translation.
339	@param
340	relativeTo The space which this transform is relative to.
341	*/
342	virtual void translate(Real x, Real y, Real z, TransformSpace relativeTo = TS_PARENT);
343	/** Moves the node along arbitrary axes.
344	@remarks
345	This method translates the node by a vector which is relative to
346	a custom set of axes.
347	@param
348	axes A 3x3 Matrix containg 3 column vectors each representing the
349	axes X, Y and Z respectively. In this format the standard cartesian
350	axes would be expressed as:
351	<pre>
352	1 0 0
353	0 1 0
354	0 0 1
355	</pre>
356	i.e. the identity matrix.
357	@param
358	move Vector relative to the axes above.
359	@param
360	relativeTo The space which this transform is relative to.
361	*/
362	virtual void translate(const Matrix3& axes, const Vector3& move, TransformSpace relativeTo = TS_PARENT);
363	/** Moves the node along arbitrary axes.
364	@remarks
365	This method translates the node by a vector which is relative to
366	a custom set of axes.
367	@param
368	axes A 3x3 Matrix containg 3 column vectors each representing the
369	axes X, Y and Z respectively. In this format the standard cartesian
370	axes would be expressed as
371	<pre>
372	1 0 0
373	0 1 0
374	0 0 1
375	</pre>
376	i.e. the identity matrix.
377	@param
378	x,y,z Translation components relative to the axes above.
379	@param
380	relativeTo The space which this transform is relative to.
381	*/
382	virtual void translate(const Matrix3& axes, Real x, Real y, Real z, TransformSpace relativeTo = TS_PARENT);
383
384	/** Rotate the node around the Z-axis.
385	*/
386	virtual void roll(const Radian& angle, TransformSpace relativeTo = TS_LOCAL);
387	#ifndef OGRE_FORCE_ANGLE_TYPES
388	inline void roll(Real degrees, TransformSpace relativeTo = TS_LOCAL) {
389	roll ( Angle(degrees), relativeTo );
390	}
391	#endif//OGRE_FORCE_ANGLE_TYPES
392
393	/** Rotate the node around the X-axis.
394	*/
395	virtual void pitch(const Radian& angle, TransformSpace relativeTo = TS_LOCAL);
396	#ifndef OGRE_FORCE_ANGLE_TYPES
397	inline void pitch(Real degrees, TransformSpace relativeTo = TS_LOCAL) {
398	pitch ( Angle(degrees), relativeTo );
399	}
400	#endif//OGRE_FORCE_ANGLE_TYPES
401
402	/** Rotate the node around the Y-axis.
403	*/
404	virtual void yaw(const Radian& angle, TransformSpace relativeTo = TS_LOCAL);
405	#ifndef OGRE_FORCE_ANGLE_TYPES
406	inline void yaw(Real degrees, TransformSpace relativeTo = TS_LOCAL) {
407	yaw ( Angle(degrees), relativeTo );
408	}
409	#endif//OGRE_FORCE_ANGLE_TYPES
410
411	/** Rotate the node around an arbitrary axis.
412	*/
413	virtual void rotate(const Vector3& axis, const Radian& angle, TransformSpace relativeTo = TS_LOCAL);
414	#ifndef OGRE_FORCE_ANGLE_TYPES
415	inline void rotate(const Vector3& axis, Real degrees, TransformSpace relativeTo = TS_LOCAL) {
416	rotate ( axis, Angle(degrees), relativeTo );
417	}
418	#endif//OGRE_FORCE_ANGLE_TYPES
419
420	/** Rotate the node around an aritrary axis using a Quarternion.
421	*/
422	virtual void rotate(const Quaternion& q, TransformSpace relativeTo = TS_LOCAL);
423
424	/** Gets a matrix whose columns are the local axes based on
425	the nodes orientation relative to it's parent. */
426	virtual Matrix3 getLocalAxes(void) const;
427
428	/** Creates an unnamed new Node as a child of this node.
429	@param
430	translate Initial translation offset of child relative to parent
431	@param
432	rotate Initial rotation relative to parent
433	*/
434	virtual Node* createChild(
435	const Vector3& translate = Vector3::ZERO,
436	const Quaternion& rotate = Quaternion::IDENTITY );
437
438	/** Creates a new named Node as a child of this node.
439	@remarks
440	This creates a child node with a given name, which allows you to look the node up from
441	the parent which holds this collection of nodes.
442	@param
443	translate Initial translation offset of child relative to parent
444	@param
445	rotate Initial rotation relative to parent
446	*/
447	virtual Node* createChild(const String& name, const Vector3& translate = Vector3::ZERO, const Quaternion& rotate = Quaternion::IDENTITY);
448
449	/** Adds a (precreated) child scene node to this node. If it is attached to another node,
450	it must be detached first.
451	@param child The Node which is to become a child node of this one
452	*/
453	virtual void addChild(Node* child);
454
455	/** Reports the number of child nodes under this one.
456	*/
457	virtual unsigned short numChildren(void) const;
458
459	/** Gets a pointer to a child node.
460	@remarks
461	There is an alternate getChild method which returns a named child.
462	*/
463	virtual Node* getChild(unsigned short index) const;
464
465	/** Gets a pointer to a named child node.
466	*/
467	virtual Node* getChild(const String& name) const;
468
469	/** Retrieves an iterator for efficiently looping through all children of this node.
470	@remarks
471	Using this is faster than repeatedly calling getChild if you want to go through
472	all (or most of) the children of this node.
473	Note that the returned iterator is only valid whilst no children are added or
474	removed from this node. Thus you should not store this returned iterator for
475	later use, nor should you add / remove children whilst iterating through it;
476	store up changes for later. Note that calling methods on returned items in
477	the iterator IS allowed and does not invalidate the iterator.
478	*/
479	virtual ChildNodeIterator getChildIterator(void);
480
481	/** Retrieves an iterator for efficiently looping through all children of this node.
482	@remarks
483	Using this is faster than repeatedly calling getChild if you want to go through
484	all (or most of) the children of this node.
485	Note that the returned iterator is only valid whilst no children are added or
486	removed from this node. Thus you should not store this returned iterator for
487	later use, nor should you add / remove children whilst iterating through it;
488	store up changes for later. Note that calling methods on returned items in
489	the iterator IS allowed and does not invalidate the iterator.
490	*/
491	virtual ConstChildNodeIterator getChildIterator(void) const;
492
493	/** Drops the specified child from this node.
494	@remarks
495	Does not delete the node, just detaches it from
496	this parent, potentially to be reattached elsewhere.
497	There is also an alternate version which drops a named
498	child from this node.
499	*/
500	virtual Node* removeChild(unsigned short index);
501	/** Drops the specified child from this node.
502	@remarks
503	Does not delete the node, just detaches it from
504	this parent, potentially to be reattached elsewhere.
505	There is also an alternate version which drops a named
506	child from this node.
507	*/
508	virtual Node* removeChild(Node* child);
509
510	/** Drops the named child from this node.
511	@remarks
512	Does not delete the node, just detaches it from
513	this parent, potentially to be reattached elsewhere.
514	*/
515	virtual Node* removeChild(const String& name);
516	/** Removes all child Nodes attached to this node. Does not delete the nodes, just detaches them from
517	this parent, potentially to be reattached elsewhere.
518	*/
519	virtual void removeAllChildren(void);
520
521	/** Gets the orientation of the node as derived from all parents.
522	*/
523	virtual const Quaternion & _getDerivedOrientation(void) const;
524
525	/** Gets the position of the node as derived from all parents.
526	*/
527	virtual const Vector3 & _getDerivedPosition(void) const;
528
529	/** Gets the scaling factor of the node as derived from all parents.
530	*/
531	virtual const Vector3 & _getDerivedScale(void) const;
532
533	/** Gets the full transformation matrix for this node.
534	@remarks
535	This method returns the full transformation matrix
536	for this node, including the effect of any parent node
537	transformations, provided they have been updated using the Node::_update method.
538	This should only be called by a SceneManager which knows the
539	derived transforms have been updated before calling this method.
540	Applications using Ogre should just use the relative transforms.
541	*/
542	virtual Matrix4 _getFullTransform(void) const;
543
544	/** Internal method to update the Node.
545	@note
546	Updates this node and any relevant children to incorporate transforms etc.
547	Don't call this yourself unless you are writing a SceneManager implementation.
548	@param
549	updateChildren If true, the update cascades down to all children. Specify false if you wish to
550	update children separately, e.g. because of a more selective SceneManager implementation.
551	@param
552	parentHasChanged This flag indicates that the parent xform has changed,
553	so the child should retrieve the parent's xform and combine it with its own
554	even if it hasn't changed itself.
555	*/
556	virtual void _update(bool updateChildren, bool parentHasChanged);
557
558	/** Overridden from Renderable.
559	@remarks
560	This is only used if the SceneManager chooses to render the node. This option can be set
561	for SceneNodes at SceneManager::setDisplaySceneNodes, and for entities based on skeletal
562	models using Entity::setDisplayBones()
563	*/
564	const MaterialPtr& getMaterial(void) const;
565	/** Overridden from Renderable.
566	@remarks
567	This is only used if the SceneManager chooses to render the node. This option can be set
568	for SceneNodes at SceneManager::setDisplaySceneNodes, and for entities based on skeletal
569	models using Entity::setDisplaySkeleton()
570	*/
571	void getRenderOperation(RenderOperation& op);
572	/** Overridden from Renderable.
573	@remarks
574	This is only used if the SceneManager chooses to render the node. This option can be set
575	for SceneNodes at SceneManager::setDisplaySceneNodes, and for entities based on skeletal
576	models using Entity::setDisplaySkeleton()
577	*/
578	void getWorldTransforms(Matrix4* xform) const;
579	/** @copydoc Renderable::getWorldOrientation */
580	const Quaternion& getWorldOrientation(void) const;
581	/** @copydoc Renderable::getWorldPosition */
582	const Vector3& getWorldPosition(void) const;
583
584	/** Sets the current transform of this node to be the 'initial state' ie that
585	position / orientation / scale to be used as a basis for delta values used
586	in keyframe animation.
587	@remarks
588	You never need to call this method unless you plan to animate this node. If you do
589	plan to animate it, call this method once you've loaded the node with it's base state,
590	ie the state on which all keyframes are based.
591	@par
592	If you never call this method, the initial state is the identity transform, ie do nothing.
593	*/
594	virtual void setInitialState(void);
595
596	/** Resets the position / orientation / scale of this node to it's initial state, see setInitialState for more info. */
597	virtual void resetToInitialState(void);
598
599	/** Gets the initial position of this node, see setInitialState for more info.
600	@remarks
601	Also resets the cumulative animation weight used for blending.
602	*/
603	virtual const Vector3& getInitialPosition(void) const;
604
605	/** Gets the initial orientation of this node, see setInitialState for more info. */
606	virtual const Quaternion& getInitialOrientation(void) const;
607
608	/** Gets the initial position of this node, see setInitialState for more info. */
609	virtual const Vector3& getInitialScale(void) const;
610
611	/** Internal weighted transform method.
612	@remarks
613	This method transforms a Node by a weighted amount from it's
614	initial state. If weighted transforms have already been applied,
615	the previous transforms and this one are blended together based
616	on their relative weight. This method should not be used in
617	combination with the unweighted rotate, translate etc methods.
618	*/
619	virtual void _weightedTransform(Real weight, const Vector3& translate,
620	const Quaternion& rotate, const Vector3& scale);
621
622	/** Overridden, see Renderable */
623	Real getSquaredViewDepth(const Camera* cam) const;
624
625	/** To be called in the event of transform changes to this node that require it's recalculation.
626	@remarks
627	This not only tags the node state as being 'dirty', it also requests it's parent to
628	know about it's dirtiness so it will get an update next time.
629	*/
630	virtual void needUpdate();
631	/** Called by children to notify their parent that they need an update. */
632	virtual void requestUpdate(Node* child);
633	/** Called by children to notify their parent that they no longer need an update. */
634	virtual void cancelUpdate(Node* child);
635
636	/** @copydoc Renderable::getLights */
637	const LightList& getLights(void) const;
638
639
640
641	};
642
643	} //namespace
644
645	#endif

Note: See TracBrowser for help on using the repository browser.

Download in other formats: