Pyrogenesis  trunk
ICmpPosition.h
Go to the documentation of this file.
1 /* Copyright (C) 2017 Wildfire Games.
2  * This file is part of 0 A.D.
3  *
4  * 0 A.D. is free software: you can redistribute it and/or modify
5  * it under the terms of the GNU General Public License as published by
6  * the Free Software Foundation, either version 2 of the License, or
7  * (at your option) any later version.
8  *
9  * 0 A.D. is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12  * GNU General Public License for more details.
13  *
14  * You should have received a copy of the GNU General Public License
15  * along with 0 A.D. If not, see <http://www.gnu.org/licenses/>.
16  */
17 
18 #ifndef INCLUDED_ICMPPOSITION
19 #define INCLUDED_ICMPPOSITION
20 
22 
24 #include "maths/FixedVector3D.h"
25 #include "maths/FixedVector2D.h"
26 
27 #include <set>
28 
29 class CMatrix3D;
30 
31 /**
32  * Represents an entity's position in the world (plus its orientation).
33  *
34  * Entity positions are determined by the following:
35  * - X, Z coordinates (giving left/right and front/back coordinates on the map)
36  * - Y offset (height; entities always snap to the ground, then are offset by this amount)
37  * - 'Floating' flag (snap to surface of water instead of going underneath)
38  * As far as the simulation code is concerned, movements are instantaneous.
39  * The only exception is GetInterpolatedTransform, used for rendering, which may
40  * interpolate between the previous and current positions.
41  * (The "Jump" methods circumvent the interpolation, and should be used whenever immediate
42  * movement is needed.)
43  *
44  * Orientations consist of the following:
45  * - Rotation around upwards 'Y' axis (the common form of rotation)
46  * - Terrain conformance mode, one of:
47  * - Upright (upwards axis is always the world Y axis, e.g. for humans)
48  * - Pitch (rotates backwards and forwards to match the terrain, e.g. for horses)
49  * - Pitch-Roll (rotates in all directions to match the terrain, e.g. for carts)
50  * - Roll (rotates sideways to match the terrain)
51  * NOTE: terrain conformance is currently only a local, visual effect; it doesn't change
52  * the network synchronized rotation or the data returned by GetRotation
53  * - Rotation around relative X (pitch), Z (roll) axes (rare; used for special effects)
54  * NOTE: if XZ rotation is non-zero, it will override the terrain conformance mode
55  *
56  * Entities can also be 'outside the world' (e.g. hidden inside a building), in which
57  * case they have no position. Callers <b>must</b> check the entity is in the world, before
58  * querying its position.
59  */
60 class ICmpPosition : public IComponent
61 {
62 public:
63  /**
64  * Set this as a turret of an other entity
65  */
66  virtual void SetTurretParent(entity_id_t parent, const CFixedVector3D& offset) = 0;
67 
68  /**
69  * Get the turret parent of this entity
70  */
71  virtual entity_id_t GetTurretParent() const = 0;
72 
73  /**
74  * Has to be called to update the simulation position of the turret
75  */
76  virtual void UpdateTurretPosition() = 0;
77 
78  /**
79  * Get the list of turrets to read or edit
80  */
81  virtual std::set<entity_id_t>* GetTurrets() = 0;
82 
83  /**
84  * Returns true if the entity currently exists at a defined position in the world.
85  */
86  virtual bool IsInWorld() const = 0;
87 
88  /**
89  * Causes IsInWorld to return false. (Use MoveTo() or JumpTo() to move back into the world.)
90  */
91  virtual void MoveOutOfWorld() = 0;
92 
93  /**
94  * Move smoothly to the given location.
95  */
96  virtual void MoveTo(entity_pos_t x, entity_pos_t z) = 0;
97 
98  /**
99  * Combines MoveTo and TurnTo to avoid an uncessary "AdvertisePositionChange"
100  */
101  virtual void MoveAndTurnTo(entity_pos_t x, entity_pos_t z, entity_angle_t ry) = 0;
102 
103  /**
104  * Move immediately to the given location, with no interpolation.
105  */
106  virtual void JumpTo(entity_pos_t x, entity_pos_t z) = 0;
107 
108  /**
109  * Set the vertical offset above the terrain/water surface.
110  */
111  virtual void SetHeightOffset(entity_pos_t dy) = 0;
112 
113  /**
114  * Returns the current vertical offset above the terrain/water surface.
115  */
116  virtual entity_pos_t GetHeightOffset() const = 0;
117 
118  /**
119  * Set the vertical position above the map zero point
120  */
121  virtual void SetHeightFixed(entity_pos_t y) = 0;
122 
123  /**
124  * Returns the vertical offset above the map zero point
125  */
126  virtual entity_pos_t GetHeightFixed() const = 0;
127 
128  /**
129  * Returns true iff the entity will follow the terrain height (possibly with an offset)
130  */
131  virtual bool IsHeightRelative() const = 0;
132 
133  /**
134  * When set to true, the entity will follow the terrain height (possibly with an offset)
135  * When set to false, it's height won't change automatically
136  */
137  virtual void SetHeightRelative(bool flag) = 0;
138 
139  /**
140  * Returns whether the entity floats on water.
141  */
142  virtual bool IsFloating() const = 0;
143 
144  /**
145  * Set the entity to float on water
146  */
147  virtual void SetFloating(bool flag) = 0;
148 
149  /**
150  * Set the entity to float on water, in a non-network-synchronised visual-only way.
151  * (This is to support the 'floating' flag in actor XMLs.)
152  */
153  virtual void SetActorFloating(bool flag) = 0;
154 
155  /**
156  * Set construction progress of the model, this affects the rendered position of the model.
157  * 0.0 will be fully underground, 1.0 will be fully visible, 0.5 will be half underground.
158  */
159  virtual void SetConstructionProgress(fixed progress) = 0;
160 
161  /**
162  * Returns the current x,y,z position (no interpolation).
163  * Depends on the current terrain heightmap.
164  * Must not be called unless IsInWorld is true.
165  */
166  virtual CFixedVector3D GetPosition() const = 0;
167 
168  /**
169  * Returns the current x,z position (no interpolation).
170  * Must not be called unless IsInWorld is true.
171  */
172  virtual CFixedVector2D GetPosition2D() const = 0;
173 
174  /**
175  * Returns the previous turn's x,y,z position (no interpolation).
176  * Depends on the current terrain heightmap.
177  * Must not be called unless IsInWorld is true.
178  */
179  virtual CFixedVector3D GetPreviousPosition() const = 0;
180 
181  /**
182  * Returns the previous turn's x,z position (no interpolation).
183  * Must not be called unless IsInWorld is true.
184  */
185  virtual CFixedVector2D GetPreviousPosition2D() const = 0;
186 
187  /**
188  * Rotate smoothly to the given angle around the upwards axis.
189  * @param y clockwise radians from the +Z axis.
190  */
191  virtual void TurnTo(entity_angle_t y) = 0;
192 
193  /**
194  * Rotate immediately to the given angle around the upwards axis.
195  * @param y clockwise radians from the +Z axis.
196  */
197  virtual void SetYRotation(entity_angle_t y) = 0;
198 
199  /**
200  * Rotate immediately to the given angles around the X (pitch) and Z (roll) axes.
201  * @param x radians around the X axis. (TODO: in which direction?)
202  * @param z radians around the Z axis.
203  * @note if either x or z is non-zero, it will override terrain conformance mode
204  */
205  virtual void SetXZRotation(entity_angle_t x, entity_angle_t z) = 0;
206 
207  // NOTE: we separate Y from XZ because most code will only ever change Y;
208  // XZ are typically just used in the editor, and other code should never
209  // worry about them
210 
211  /**
212  * Returns the current rotation (relative to the upwards axis), as Euler
213  * angles with X=pitch, Y=yaw, Z=roll. (TODO: is that the right way round?)
214  */
215  virtual CFixedVector3D GetRotation() const = 0;
216 
217  /**
218  * Returns the distance that the unit will be interpolated over,
219  * i.e. the distance travelled since the start of the turn.
220  */
221  virtual fixed GetDistanceTravelled() const = 0;
222 
223  /**
224  * Get the current interpolated 2D position and orientation, for rendering.
225  * Must not be called unless IsInWorld is true.
226  */
227  virtual void GetInterpolatedPosition2D(float frameOffset, float& x, float& z, float& rotY) const = 0;
228 
229  /**
230  * Get the current interpolated transform matrix, for rendering.
231  * Must not be called unless IsInWorld is true.
232  */
233  virtual CMatrix3D GetInterpolatedTransform(float frameOffset) const = 0;
234 
235  DECLARE_INTERFACE_TYPE(Position)
236 };
237 
238 #endif // INCLUDED_ICMPPOSITION
Definition: IComponent.h:33
A simple fixed-point number class.
Definition: Fixed.h:115
Definition: FixedVector2D.h:24
virtual void GetInterpolatedPosition2D(float frameOffset, float &x, float &z, float &rotY) const =0
Get the current interpolated 2D position and orientation, for rendering.
virtual CFixedVector2D GetPosition2D() const =0
Returns the current x,z position (no interpolation).
virtual CMatrix3D GetInterpolatedTransform(float frameOffset) const =0
Get the current interpolated transform matrix, for rendering.
virtual fixed GetDistanceTravelled() const =0
Returns the distance that the unit will be interpolated over, i.e.
virtual bool IsHeightRelative() const =0
Returns true iff the entity will follow the terrain height (possibly with an offset) ...
Represents an entity&#39;s position in the world (plus its orientation).
Definition: ICmpPosition.h:60
virtual void MoveAndTurnTo(entity_pos_t x, entity_pos_t z, entity_angle_t ry)=0
Combines MoveTo and TurnTo to avoid an uncessary "AdvertisePositionChange".
virtual CFixedVector3D GetRotation() const =0
Returns the current rotation (relative to the upwards axis), as Euler angles with X=pitch...
virtual CFixedVector2D GetPreviousPosition2D() const =0
Returns the previous turn&#39;s x,z position (no interpolation).
virtual CFixedVector3D GetPosition() const =0
Returns the current x,y,z position (no interpolation).
virtual void SetTurretParent(entity_id_t parent, const CFixedVector3D &offset)=0
Set this as a turret of an other entity.
virtual void SetHeightRelative(bool flag)=0
When set to true, the entity will follow the terrain height (possibly with an offset) When set to fal...
virtual bool IsInWorld() const =0
Returns true if the entity currently exists at a defined position in the world.
virtual void SetConstructionProgress(fixed progress)=0
Set construction progress of the model, this affects the rendered position of the model...
virtual entity_pos_t GetHeightFixed() const =0
Returns the vertical offset above the map zero point.
virtual entity_id_t GetTurretParent() const =0
Get the turret parent of this entity.
Definition: Matrix3D.h:33
virtual void MoveOutOfWorld()=0
Causes IsInWorld to return false.
virtual bool IsFloating() const =0
Returns whether the entity floats on water.
virtual void SetYRotation(entity_angle_t y)=0
Rotate immediately to the given angle around the upwards axis.
virtual void SetActorFloating(bool flag)=0
Set the entity to float on water, in a non-network-synchronised visual-only way.
virtual void TurnTo(entity_angle_t y)=0
Rotate smoothly to the given angle around the upwards axis.
Definition: FixedVector3D.h:24
virtual void SetFloating(bool flag)=0
Set the entity to float on water.
#define DECLARE_INTERFACE_TYPE(iname)
Definition: Interface.h:23
virtual void MoveTo(entity_pos_t x, entity_pos_t z)=0
Move smoothly to the given location.
virtual CFixedVector3D GetPreviousPosition() const =0
Returns the previous turn&#39;s x,y,z position (no interpolation).
virtual void JumpTo(entity_pos_t x, entity_pos_t z)=0
Move immediately to the given location, with no interpolation.
virtual entity_pos_t GetHeightOffset() const =0
Returns the current vertical offset above the terrain/water surface.
virtual void UpdateTurretPosition()=0
Has to be called to update the simulation position of the turret.
Entity coordinate types.
u32 entity_id_t
Entity ID type.
Definition: Entity.h:23
virtual void SetHeightOffset(entity_pos_t dy)=0
Set the vertical offset above the terrain/water surface.
virtual std::set< entity_id_t > * GetTurrets()=0
Get the list of turrets to read or edit.
virtual void SetHeightFixed(entity_pos_t y)=0
Set the vertical position above the map zero point.
virtual void SetXZRotation(entity_angle_t x, entity_angle_t z)=0
Rotate immediately to the given angles around the X (pitch) and Z (roll) axes.