Pyrogenesis  trunk
ICmpVisual.h
Go to the documentation of this file.
1 /* Copyright (C) 2021 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_ICMPVISUAL
19 #define INCLUDED_ICMPVISUAL
20 
22 
23 #include "ps/CStr.h"
26 #include "maths/Fixed.h"
27 #include "maths/FixedVector3D.h"
28 #include "lib/file/vfs/vfs_path.h"
29 
30 class CUnit;
31 
32 /**
33  * The visual representation of an entity (typically an actor).
34  */
35 class ICmpVisual : public IComponent
36 {
37 public:
38  /**
39  * Get the world-space bounding box of the object's visual representation.
40  * (Not safe for use in simulation code.)
41  */
42  virtual CBoundingBoxAligned GetBounds() const = 0;
43 
44  /**
45  * Get the oriented world-space bounding box of the object's visual representation, clipped at the Y=0 plane in object space
46  * to prevent it from extending into the terrain. The primary difference with GetBounds is that this bounding box is not aligned
47  * to the world axes, but arbitrarily rotated according to the model transform.
48  */
49  virtual CBoundingBoxOriented GetSelectionBox() const = 0;
50 
51  /**
52  * Get the world-space position of the base point of the object's visual representation.
53  * (Not safe for use in simulation code.)
54  */
55  virtual CVector3D GetPosition() const = 0;
56 
57  /**
58  * Return the filename of the actor to be used for projectiles from this unit, or the empty string if none.
59  * (Not safe for use in simulation code.)
60  */
61  virtual std::wstring GetProjectileActor() const = 0;
62 
63  /**
64  * Return the exact position where a projectile should be launched from (based on the actor's
65  * ammo prop points).
66  * Return type is CFixedVector3D because it is exposed to the JS interface.
67  * Returns (0,0,0) if no point can be found.
68  */
69  virtual CFixedVector3D GetProjectileLaunchPoint() const = 0;
70 
71  /**
72  * Returns the underlying unit of this visual actor. May return NULL to indicate that no unit exists (e.g. may happen if the
73  * game is started without graphics rendering).
74  * Originally intended for introspection purposes in Atlas; for other purposes, consider using a specialized getter first.
75  */
76  virtual CUnit* GetUnit() = 0;
77 
78  /**
79  * Set the variant selection of the actor for a certain key.
80  * This overrides a previous selection on that key, so every component
81  * should use unique keys.
82  */
83  virtual void SetVariant(const CStr& key, const CStr& selection) = 0;
84 
85  /**
86  * Returns the name of the currently played animation.
87  */
88  virtual std::string GetAnimationName() const = 0;
89 
90  /**
91  * Start playing the given animation. If there are multiple possible animations then it will
92  * pick one at random (not network-synchronised).
93  * @param name animation name (e.g. "idle", "walk", "melee"; the names are determined by actor XML files)
94  * @param once if true then the animation will play once and freeze at the final frame, else it will loop
95  * @param speed animation speed multiplier (typically 1.0 for the default speed)
96  */
97  virtual void SelectAnimation(const std::string& name, bool once, fixed speed) = 0;
98 
99  /**
100  * Start playing the given movement animation unless we are currently playing a non-movement animation.
101  * This is necessary so UnitMotion can set the movement animations without overwriting specific animations
102  * that might have been set by other components.
103  * TODO: Non-movement animations should probably be made into variants, defining "idle" (really "default"), "walk" and "run" as appropriate,
104  * and this would no longer be necessary.
105  * @param name animation name (i.e. one of "idle", "walk", "run").
106  * @param speed animation speed multiplier (typically 1.0 for the default speed)
107  */
108  virtual void SelectMovementAnimation(const std::string& name, fixed speed) = 0;
109 
110  /**
111  * Adjust the speed of the current animation, so it can match simulation events.
112  * @param repeattime time for complete loop of animation, in msec
113  */
114  virtual void SetAnimationSyncRepeat(fixed repeattime) = 0;
115 
116  /**
117  * Adjust the offset of the current animation, so it can match simulation events.
118  * @param actiontime time between now and when the 'action' event should occur, in msec
119  */
120  virtual void SetAnimationSyncOffset(fixed actiontime) = 0;
121 
122  /**
123  * Set the shading color that will be modulated with the model's textures.
124  * Default shading is (1, 1, 1, 1).
125  * Alpha should probably be 1 else it's unlikely to work properly.
126  * @param r red component, expected range [0, 1]
127  * @param g green component, expected range [0, 1]
128  * @param b blue component, expected range [0, 1]
129  * @param a alpha component, expected range [0, 1]
130  */
131  virtual void SetShadingColor(fixed r, fixed g, fixed b, fixed a) = 0;
132 
133  /**
134  * Set an arbitrarily-named variable that the model may use to alter its appearance
135  * (e.g. in particle emitter parameter computations).
136  */
137  virtual void SetVariable(const std::string& name, float value) = 0;
138 
139  /**
140  * Get actor seed used for random variations
141  */
142  virtual u32 GetActorSeed() const = 0;
143 
144  /**
145  * Set actor seed for random variations and reload model
146  */
147  virtual void SetActorSeed(u32 seed) = 0;
148 
149  /**
150  * Recalculate the actor name, applying modifiers.
151  */
152  virtual void RecomputeActorName() = 0;
153 
154  /**
155  * Returns true if this entity should have a construction preview
156  */
157  virtual bool HasConstructionPreview() const = 0;
158 
159  /**
160  * Called when an actor file has been modified and reloaded dynamically.
161  * If this component uses the named actor file, it should regenerate its actor
162  * to pick up the new definitions.
163  * If name is empty, this reloads all the time. This is used when global quality settings change.
164  */
165  virtual void Hotload(const VfsPath& name = L"") = 0;
166 
167  DECLARE_INTERFACE_TYPE(Visual)
168 };
169 
170 // TODO: rename this to VisualActor, because the interface is actor-specific, maybe?
171 
172 #endif // INCLUDED_ICMPVISUAL
Definition: IComponent.h:32
A simple fixed-point number class.
Definition: Fixed.h:119
virtual bool HasConstructionPreview() const =0
Returns true if this entity should have a construction preview.
virtual void SetVariant(const CStr &key, const CStr &selection)=0
Set the variant selection of the actor for a certain key.
virtual CUnit * GetUnit()=0
Returns the underlying unit of this visual actor.
virtual CFixedVector3D GetProjectileLaunchPoint() const =0
Return the exact position where a projectile should be launched from (based on the actor&#39;s ammo prop ...
Definition: Vector3D.h:30
virtual void SelectMovementAnimation(const std::string &name, fixed speed)=0
Start playing the given movement animation unless we are currently playing a non-movement animation...
virtual std::wstring GetProjectileActor() const =0
Return the filename of the actor to be used for projectiles from this unit, or the empty string if no...
Definition: Unit.h:36
virtual u32 GetActorSeed() const =0
Get actor seed used for random variations.
virtual void SelectAnimation(const std::string &name, bool once, fixed speed)=0
Start playing the given animation.
uint32_t u32
Definition: types.h:39
virtual void SetShadingColor(fixed r, fixed g, fixed b, fixed a)=0
Set the shading color that will be modulated with the model&#39;s textures.
Definition: path.h:79
Definition: FixedVector3D.h:24
pthread_key_t key
Definition: wpthread.cpp:140
virtual CBoundingBoxAligned GetBounds() const =0
Get the world-space bounding box of the object&#39;s visual representation.
#define DECLARE_INTERFACE_TYPE(iname)
Definition: Interface.h:23
virtual void SetVariable(const std::string &name, float value)=0
Set an arbitrarily-named variable that the model may use to alter its appearance (e.g.
virtual std::string GetAnimationName() const =0
Returns the name of the currently played animation.
virtual void SetAnimationSyncRepeat(fixed repeattime)=0
Adjust the speed of the current animation, so it can match simulation events.
Definition: BoundingBoxAligned.h:33
virtual void RecomputeActorName()=0
Recalculate the actor name, applying modifiers.
virtual void SetAnimationSyncOffset(fixed actiontime)=0
Adjust the offset of the current animation, so it can match simulation events.
Definition: BoundingBoxOriented.h:30
virtual CBoundingBoxOriented GetSelectionBox() const =0
Get the oriented world-space bounding box of the object&#39;s visual representation, clipped at the Y=0 p...
virtual void Hotload(const VfsPath &name=L"")=0
Called when an actor file has been modified and reloaded dynamically.
virtual CVector3D GetPosition() const =0
Get the world-space position of the base point of the object&#39;s visual representation.
virtual void SetActorSeed(u32 seed)=0
Set actor seed for random variations and reload model.
The visual representation of an entity (typically an actor).
Definition: ICmpVisual.h:35