Stan/0ad
1
0
Fork 0
forked from 0ad/0ad
Code Pull Requests Activity

Corrects some Doxygen comments and adds a few others of interest.

Browse Source 
This was SVN commit r11209.
This commit is contained in:
historic_bruno 2012-03-01 03:55:05 +00:00
parent a247da1585
commit 7fa6afac37
18 changed files with 190 additions and 114 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
source/graphics/ColladaManager.h
View File

@ -50,9 +50,9 @@ public:
* Converts DAE to archive cached .pmd/psa and outputs the resulting path
* (used by archive builder)
*
* @param sourcePath[in] path of the .dae to load
* @param type[in] FileType, .pmd or .psa
* @param archiveCachePath[out] output path of the cached file
* @param[in] sourcePath path of the .dae to load
* @param[in] type FileType, .pmd or .psa
* @param[out] archiveCachePath output path of the cached file
*
* @return true if COLLADA converter completed successfully; or false if it failed
*/
@ -63,8 +63,8 @@ private:
* Creates MD5 hash key from skeletons.xml info and COLLADA converter version,
* used to invalidate cached .pmd/psas
*
* @param hash[out] resulting MD5 hash
* @param version[out] version passed to CCacheLoader, used if code change should force
* @param[out] hash resulting MD5 hash
* @param[out] version version passed to CCacheLoader, used if code change should force
* cache invalidation
*/
void PrepareCacheKey(MD5& hash, u32& version);

4
source/gui/scripting/ScriptFunctions.cpp
View File

@ -395,6 +395,10 @@ void CameraFollow(void* UNUSED(cbdata), entity_id_t entityid)
g_Game->GetView()->CameraFollow(entityid, false);
}
/**
* Start / stop first-person camera following mode
* @param entityid unit id to follow. If zero, stop following mode
*/
void CameraFollowFPS(void* UNUSED(cbdata), entity_id_t entityid)
{
if (g_Game && g_Game->GetView())

2
source/lib/file/archive/archive.h
View File

@ -91,7 +91,7 @@ struct IArchiveWriter
* @param pathname the actual file to add
* @param pathnameInArchive the name to store in the archive
**/
virtual Status AddFile(const OsPath& pathname, const Path& pathameInArchive) = 0;
virtual Status AddFile(const OsPath& pathname, const Path& pathnameInArchive) = 0;
/**
* add a file to the archive, when it is already in memory and not on disk.

2
source/lib/file/common/trace.h
View File

@ -110,7 +110,7 @@ struct ITrace
/**
* load entries from file.
*
* @param osPathname (native, absolute)
* @param pathname (native, absolute)
*
* replaces any existing entries.
**/

15
source/lib/res/sound/snd_mgr.cpp
View File

@ -139,12 +139,10 @@ static const char* alc_dev_name = 0;
/**
* tell OpenAL to use the specified device in future.
*
* @param alc_new_dev_name Device name.
* @param alc_new_dev_name Device name; if 0, it reverts to OpenAL's default
* choice, which will also be used if this routine is never called.
* @return Status
*
* name = 0 reverts to OpenAL's default choice, which will also
* be used if this routine is never called.
*
* the device name is typically taken from a config file at init-time;
* the snd_dev * enumeration routines below are used to present a list
* of choices to the user in the options screen.
@ -359,8 +357,8 @@ static int al_bufs_outstanding;
*
* @param data raw sound data buffer
* @param size size of buffer in bytes
* @param al_fmt AL_FORMAT_ * describing the sound data
* @param al_freq sampling frequency (typically 22050 Hz)
* @param fmt AL_FORMAT_ * describing the sound data
* @param freq sampling frequency (typically 22050 Hz)
* @return ALuint buffer name
*/
static ALuint al_buf_alloc(ALvoid* data, ALsizei size, ALenum fmt, ALsizei freq)
@ -1140,7 +1138,6 @@ static FadeRet fade(FadeInfo& fi, double cur_time, float& out_val)
/**
* Is the fade operation currently active?
*
* @param FadeInfo
* @return bool
*/
static bool fade_is_active(FadeInfo& fi)
@ -1319,7 +1316,7 @@ static Status VSrc_to_string(const VSrc* vs, wchar_t* buf)
/**
* open and return a handle to a sound instance.
*
* @param pathname. if a text file (extension ".txt"),
* @param pathname if a text file (extension ".txt"),
* it is assumed to be a definition file containing the
* sound file name and its gain (0.0 .. 1.0).
* otherwise, it is taken to be the sound file name and
@ -1473,7 +1470,6 @@ static Status list_free_all()
* Send the VSrc properties to OpenAL (when we actually have a source).
* called by snd_set * and vsrc_grant.
*
* @param VSrc*
*/
static void vsrc_latch(VSrc* vs)
{
@ -1535,7 +1531,6 @@ static void vsrc_latch(VSrc* vs)
/**
* Dequeue any of the VSrc's sound buffers that are finished playing.
*
* @param VSrc*
* @return int number of entries that were removed.
*/
static int vsrc_deque_finished_bufs(VSrc* vs)

18
source/maths/BoundingBoxAligned.h
View File

@ -43,7 +43,7 @@ public:
}
/**
* Transforms these bounds according to the specified transformation matrix @m, and writes the axis-aligned bounds
* Transforms these bounds according to the specified transformation matrix @p m, and writes the axis-aligned bounds
* of that result to @p result.
*/
void Transform(const CMatrix3D& m, CBoundingBoxAligned& result) const;
@ -86,15 +86,15 @@ public:
}
/**
* Returns true if the ray originating in @p origin and with unit direction vector @p dir intersects this AABB, false otherwise.
* Additionally, returns the distance in the positive direction from the origin of the ray to the entry and exit points in
* the bounding box in @p tmin and @p tmax. If the origin is inside the box, then this is counted as an intersection and one
* of @p tMin and @p tMax may be negative.
*
* Check if a given ray intersects this AABB.
* See also Real-Time Rendering, Third Edition by T. Akenine-Moller, p. 741--742.
*
* @param origin Origin of the ray.
* @param dir Direction vector of the ray, defining the positive direction of the ray. Must be of unit length.
*
* @param[in] origin Origin of the ray.
* @param[in] dir Direction vector of the ray, defining the positive direction of the ray. Must be of unit length.
* @param[out] tmin,tmax distance in the positive direction from the origin of the ray to the entry and exit points in
* the bounding box. If the origin is inside the box, then this is counted as an intersection and one of @p tMin and @p tMax may be negative.
*
* @return true if the ray originating in @p origin and with unit direction vector @p dir intersects this AABB, false otherwise.
*/
bool RayIntersect(const CVector3D& origin, const CVector3D& dir, float& tmin, float& tmax) const;

17
source/maths/BoundingBoxOriented.h
View File

@ -51,17 +51,16 @@ public:
explicit CBoundingBoxOriented(const CBoundingBoxAligned& bound);
/**
* Returns true if the ray originating in @p origin and with unit direction vector @p dir intersects this box, false otherwise.
* Additionally, returns the distance in the positive direction from the origin of the ray to the entry and exit points in the
* box in @p tMin and @p tMax. If the origin is inside the box, then this is counted as an intersection and one of @p tMin and
* @p tMax may be negative.
*
* Should not be used if IsEmpty() is true.
* Check if a given ray intersects this box.
* See also Real-Time Rendering, Third Edition by T. Akenine-Möller, p. 741--742.
*
* Should not be used if IsEmpty() is true.
*
* @param origin Origin of the ray.
* @param dir Direction vector of the ray, defining the positive direction of the ray. Must be of unit length.
* @param[in] origin Origin of the ray.
* @param[in] dir Direction vector of the ray, defining the positive direction of the ray. Must be of unit length.
* @param[out] tMin,tMax distance in the positive direction from the origin of the ray to the entry and exit points in the
* box. If the origin is inside the box, then this is counted as an intersection and one of @p tMin and @p tMax may be negative.
*
* @return true if the ray originating in @p origin and with unit direction vector @p dir intersects this box, false otherwise.
*/
bool RayIntersect(const CVector3D& origin, const CVector3D& dir, float& tMin, float& tMax) const;

30
source/ps/Preprocessor.h
View File

@ -46,18 +46,18 @@ THE SOFTWARE.
*
* Here's a list of supported features:
* <ul>
* <li>Fast memory allocation-less operation (mostly).
* <li>Line continuation (backslash-newline) is swallowed.
* <li>Fast memory allocation-less operation (mostly).</li>
* <li>Line continuation (backslash-newline) is swallowed.</li>
* <li>Line numeration is fully preserved by inserting empty lines where
* required. This is crucial if, say, GLSL compiler reports you an error
* with a line number.
* <li>#define: Parametrized and non-parametrized macros. Invoking a macro with
* less arguments than it takes assignes empty values to missing arguments.
* <li>#undef: Forget defined macros
* <li>#ifdef/#ifndef/#else/#endif: Conditional suppression of parts of code.
* <li>#if: Supports numeric expression of any complexity, also supports the
* defined() pseudo-function.
* <ul>
* with a line number.</li>
* <li>\#define: Parametrized and non-parametrized macros. Invoking a macro with
* less arguments than it takes assignes empty values to missing arguments.</li>
* <li>\#undef: Forget defined macros</li>
* <li>\#ifdef/\#ifndef/\#else/\#endif: Conditional suppression of parts of code.</li>
* <li>\#if: Supports numeric expression of any complexity, also supports the
* defined() pseudo-function.</li>
* </ul>
*/
class CPreprocessor
{
@ -243,7 +243,7 @@ class CPreprocessor
Token HandleDirective (Token &iToken, int iLine);
/**
* Handle a #define directive.
* Handle a \#define directive.
* @param iBody
* The body of the directive (everything after the directive
* until end of line).
@ -267,7 +267,7 @@ class CPreprocessor
bool HandleUnDef (Token &iBody, int iLine);
/**
* Handle an #ifdef directive.
* Handle an \#ifdef directive.
* @param iBody
* The body of the directive (everything after the directive
* until end of line).
@ -279,7 +279,7 @@ class CPreprocessor
bool HandleIfDef (Token &iBody, int iLine);
/**
* Handle an #if directive.
* Handle an \#if directive.
* @param iBody
* The body of the directive (everything after the directive
* until end of line).
@ -291,7 +291,7 @@ class CPreprocessor
bool HandleIf (Token &iBody, int iLine);
/**
* Handle an #else directive.
* Handle an \#else directive.
* @param iBody
* The body of the directive (everything after the directive
* until end of line).
@ -303,7 +303,7 @@ class CPreprocessor
bool HandleElse (Token &iBody, int iLine);
/**
* Handle an #endif directive.
* Handle an \#endif directive.
* @param iBody
* The body of the directive (everything after the directive
* until end of line).

3
source/ps/Profiler2.h
View File

@ -21,7 +21,8 @@
*/
/**
* @file New profiler (complementing the older CProfileManager)
* @file
* New profiler (complementing the older CProfileManager)
*
* The profiler is designed for analysing framerate fluctuations or glitches,
* and temporal relationships between threads.

3
source/renderer/HWLightingModelRenderer.h
View File

@ -37,9 +37,6 @@ class ShaderModelRenderer : public ModelVertexRenderer
public:
/**
* HWLightingModelRenderer: Constructor.
*
* @param colorIsDiffuseOnly if true, the primary color sent to the fragment stage
* contains only the diffuse term, and not the ambient
*/
ShaderModelRenderer();
~ShaderModelRenderer();

6
source/renderer/VertexBufferManager.h
View File

@ -34,8 +34,10 @@ public:
void Shutdown();
/**
* Try to allocate a buffer of given number of vertices (each of given size),
* and with the given type.
* Try to allocate a vertex buffer of the given size and type.
*
* @param vertexSize size of each vertex in the buffer
* @param numVertices number of vertices in the buffer
* @param usage typically GL_STATIC_DRAW or GL_DYNAMIC_DRAW
* @param target typically GL_ARRAY_BUFFER or GL_ELEMENT_ARRAY_BUFFER
* @return chunk, or NULL if no free chunks available

16
source/scriptinterface/ScriptInterface.cpp
View File

@ -47,8 +47,24 @@
#include "scriptinterface/ScriptExtraHeaders.h"
/**
* @file
* Abstractions of various SpiderMonkey features.
* Engine code should be using functions of these interfaces rather than
* directly accessing the underlying JS api.
*/
////////////////////////////////////////////////////////////////
/**
* Abstraction around a SpiderMonkey JSRuntime.
* Each ScriptRuntime can be used to initialize several ScriptInterface
* contexts which can then share data, but a single ScriptRuntime should
* only be used on a single thread.
*
* (One means to share data between threads and runtimes is to create
* a ScriptInterface::StructuredClone.)
*/
class ScriptRuntime
{
public:

2
source/scriptinterface/ScriptInterface.h
View File

@ -79,6 +79,8 @@ public:
* Constructor.
* @param nativeScopeName Name of global object that functions (via RegisterFunction) will
* be placed into, as a scoping mechanism; typically "Engine"
* @param debugName Name of this interface for CScriptStats purposes.
* @param runtime ScriptRuntime to use when initializing this interface.
*/
ScriptInterface(const char* nativeScopeName, const char* debugName, const shared_ptr<ScriptRuntime>& runtime);

11
source/simulation2/components/CCmpAIManager.cpp
View File

@ -42,8 +42,8 @@
#include "simulation2/serialization/SerializeTemplates.h"
/**
* @file Player AI interface.
*
* @file
* Player AI interface.
* AI is primarily scripted, and the CCmpAIManager component defined here
* takes care of managing all the scripts.
*
@ -66,6 +66,9 @@
* is designed to hopefully support threading when we want it.
*/
/**
* Implements worker thread for CCmpAIManager.
*/
class CAIWorker
{
private:
@ -515,7 +518,9 @@ private:
};
/**
* Implementation of ICmpAIManager.
*/
class CCmpAIManager : public ICmpAIManager
{
public:

13
source/simulation2/components/ICmpObstructionManager.h
View File

@ -94,25 +94,26 @@ public:
/**
* Register a static shape.
* @param ent entity ID associated with this shape (or INVALID_ENTITY if none)
* @param x X coordinate of center, in world space
* @param z Z coordinate of center, in world space
* @param x,z coordinates of center, in world space
* @param a angle of rotation (clockwise from +Z direction)
* @param w width (size along X axis)
* @param h height (size along Z axis)
* @param flags a set of EFlags values
* @return a valid tag for manipulating the shape
* @see StaticShape
*/
virtual tag_t AddStaticShape(entity_id_t ent, entity_pos_t x, entity_pos_t z, entity_angle_t a, entity_pos_t w, entity_pos_t h, flags_t flags) = 0;
/**
* Register a unit shape.
* @param ent entity ID associated with this shape (or INVALID_ENTITY if none)
* @param x X coordinate of center, in world space
* @param z Z coordinate of center, in world space
* @param r radius (half the unit's width/height)
* @param x,z coordinates of center, in world space
* @param r radius of circle or half the unit's width/height
* @param flags a set of EFlags values
* @param moving whether the unit is currently moving through the world or is stationary
* @param group control group (typically the owner entity, or a formation controller entity
* - units ignore collisions with others in the same group)
* @return a valid tag for manipulating the shape
* @see UnitShape
*/
virtual tag_t AddUnitShape(entity_id_t ent, entity_pos_t x, entity_pos_t z, entity_angle_t r, flags_t flags, entity_id_t group) = 0;

20
source/simulation2/helpers/Geometry.h
View File

@ -31,10 +31,9 @@ namespace Geometry
{
/**
* Returns true if @p point is inside the square with rotated X axis unit vector @p u and rotated Z axis unit vector @p v,
* and half dimensions specified by @p halfSizes. Currently assumes the @p u and @p v vectors are perpendicular. Can also
* be used for rectangles.
* Checks if a point is inside the given rotated square or rectangle.
*
* @note Currently assumes the @p u and @p v vectors are perpendicular.
* @param point point vector of the point that is to be tested relative to the origin (center) of the shape.
* @param u rotated X axis unit vector relative to the absolute XZ plane. Indicates the orientation of the rectangle. If not rotated,
* this value is the absolute X axis unit vector (1,0). If rotated by angle theta, this should be (cos theta, -sin theta), as
@ -42,7 +41,10 @@ namespace Geometry
* @param v rotated Z axis unit vector relative to the absolute XZ plane. Indicates the orientation of the rectangle. If not rotated,
* this value is the absolute Z axis unit vector (0,1). If rotated by angle theta, this should be (sin theta, cos theta), as
* the absolute Z axis points down in the unit circle.
* @param halfSizes Holds half the dimensions of the shape along the u and v vectors, respectively.
* @param halfSize Holds half the dimensions of the shape along the u and v vectors, respectively.
*
* @return true if @p point is inside the square with rotated X axis unit vector @p u and rotated Z axis unit vector @p v,
* and half dimensions specified by @p halfSizes.
*/
bool PointIsInSquare(CFixedVector2D point, CFixedVector2D u, CFixedVector2D v, CFixedVector2D halfSize);
@ -51,16 +53,18 @@ CFixedVector2D GetHalfBoundingBox(CFixedVector2D u, CFixedVector2D v, CFixedVect
fixed DistanceToSquare(CFixedVector2D point, CFixedVector2D u, CFixedVector2D v, CFixedVector2D halfSize);
/**
* Returns the point that is closest to @p point on the edge of the square specified by orientation unit vectors @p u and @p v and half
* dimensions @p halfSize, relative to the center of the square. Currently assumes the @p u and @p v vectors are perpendicular.
* Can also be used for rectangles.
* Find point closest to the given point on the edge of the given square or rectangle.
*
* @note Currently assumes the @p u and @p v vectors are perpendicular.
* @param point point vector of the point we want to get the nearest edge point for, relative to the origin (center) of the shape.
* @param u rotated X axis unit vector, relative to the absolute XZ plane. Indicates the orientation of the shape. If not rotated,
* this value is the absolute X axis unit vector (1,0). If rotated by angle theta, this should be (cos theta, -sin theta).
* @param v rotated Z axis unit vector, relative to the absolute XZ plane. Indicates the orientation of the shape. If not rotated,
* this value is the absolute Z axis unit vector (0,1). If rotated by angle theta, this should be (sin theta, cos theta).
* @param halfSizes Holds half the dimensions of the shape along the u and v vectors, respectively.
* @param halfSize Holds half the dimensions of the shape along the u and v vectors, respectively.
*
* @return point that is closest to @p point on the edge of the square specified by orientation unit vectors @p u and @p v and half
* dimensions @p halfSize, relative to the center of the square
*/
CFixedVector2D NearestPointOnSquare(CFixedVector2D point, CFixedVector2D u, CFixedVector2D v, CFixedVector2D halfSize);

79
source/simulation2/helpers/Render.h
View File

@ -57,23 +57,39 @@ namespace SimRender
{
/**
* Updates @p overlay so that it represents the given line (a list of x, z coordinate pairs),
* flattened on the terrain (or on the water if @p floating).
* Constructs overlay line from given points, conforming to terrain.
*
* @param[in] xz List of x,z coordinate pairs representing the line.
* @param[in,out] overlay Updated overlay line now conforming to terrain.
* @param[in] floating If true, the line conforms to water as well.
* @param[in] heightOffset Height above terrain to offset the line.
*/
void ConstructLineOnGround(const CSimContext& context, const std::vector<float>& xz,
SOverlayLine& overlay,
bool floating, float heightOffset = 0.25f);
/**
* Updates @p overlay so that it represents the given circle, flattened on the terrain.
* Constructs overlay line as a circle with given center and radius, conforming to terrain.
*
* @param[in] x,z Coordinates of center of circle.
* @param[in] radius Radius of circle to construct.
* @param[in,out] overlay Updated overlay line representing this circle.
* @param[in] floating If true, the circle conforms to water as well.
* @param[in] heightOffset Height above terrain to offset the circle.
*/
void ConstructCircleOnGround(const CSimContext& context, float x, float z, float radius,
SOverlayLine& overlay,
bool floating, float heightOffset = 0.25f);
/**
* Updates @p overlay so that it represents the given square, flattened on the terrain.
* @p x and @p z are position of center, @p w and @p h are size of rectangle, @p a is clockwise angle.
* Constructs overlay line as rectangle with given center and dimensions, conforming to terrain.
*
* @param[in] x,z Coordinates of center of rectangle.
* @param[in] w,h Width/height dimensions of the rectangle.
* @param[in] a Clockwise angle to orient the rectangle.
* @param[in,out] overlay Updated overlay line representing this rectangle.
* @param[in] floating If true, the rectangle conforms to water as well.
* @param[in] heightOffset Height above terrain to offset the rectangle.
*/
void ConstructSquareOnGround(const CSimContext& context, float x, float z, float w, float h, float a,
SOverlayLine& overlay,
@ -81,53 +97,70 @@ void ConstructSquareOnGround(const CSimContext& context, float x, float z, float
/**
* Constructs a solid outline of an arbitrarily-aligned box.
*
* @param[in] box
* @param[in,out] overlayLine Updated overlay line representing the oriented box.
*/
void ConstructBoxOutline(const CBoundingBoxOriented& box, SOverlayLine& overlayLine);
/**
* Constructs a solid outline of an axis-aligned bounding box.
*
* @param[in] bound
* @param[in,out] overlayLine Updated overlay line representing the AABB.
*/
void ConstructBoxOutline(const CBoundingBoxAligned& bound, SOverlayLine& overlayLine);
/**
* Constructs a simple gimbal outline of radius @p radius at @p center in @p out.
* @param numSteps The amount of steps to trace a circle's complete outline. Must be a (strictly) positive multiple of four.
* Constructs a simple gimbal outline with the given radius and center.
*
* @param[in] center
* @param[in] radius
* @param[in,out] out Updated overlay line representing the gimbal.
* @param[in] numSteps The amount of steps to trace a circle's complete outline. Must be a (strictly) positive multiple of four.
* For small radii, you can get away with small values; setting this to 4 will create a diamond shape.
*/
void ConstructGimbal(const CVector3D& center, float radius, SOverlayLine& out, size_t numSteps = 16);
/**
* Constructs XYZ axis marker overlay lines for the coordinate system specified by @p coordSystem and writes them to @p outX,
* @p outY and @p outZ. The overlay lines are colored RGB for the XYZ axes, respectively.
* Constructs 3D axis marker overlay lines for the given coordinate system.
* The overlay lines are colored RGB for the XYZ axes, respectively.
*
* @param[in] coordSystem Specifies the coordinate system.
* @param[out] outX,outY,outZ Constructed overlay lines for each axes.
*/
void ConstructAxesMarker(const CMatrix3D& coordSystem, SOverlayLine& outX, SOverlayLine& outY, SOverlayLine& outZ);
/**
* Updates @p points so each point is averaged with its neighbours, resulting in
* Updates the given points so each point is averaged with its neighbours, resulting in
* a somewhat smoother curve, assuming the points are roughly equally spaced.
* If @p closed then the points are treated as a closed path (the last is connected
* to the first).
*
* @param[in,out] points List of points to smooth.
* @param[in] closed if true, then the points are treated as a closed path (the last is connected
* to the first).
*/
void SmoothPointsAverage(std::vector<CVector2D>& points, bool closed);
/**
* Updates @p points to include intermediate points interpolating between the original
* Updates the given points to include intermediate points interpolating between the original
* control points, using a rounded nonuniform spline.
* The points are also shifted by @p offset in a direction 90 degrees clockwise from
* the direction of the curve.
* If @p closed then the points are treated as a closed path (the last is connected
* to the first).
* @param segmentSamples Amount of intermediate points to sample between every two control points.
*
* @param[in,out] points List of points to interpolate.
* @param[in] closed if true, then the points are treated as a closed path (the last is connected
* to the first).
* @param[in] offset The points are shifted by this distance in a direction 90 degrees clockwise from
* the direction of the curve.
* @param[in] segmentSamples Amount of intermediate points to sample between every two control points.
*/
void InterpolatePointsRNS(std::vector<CVector2D>& points, bool closed, float offset, int segmentSamples = 4);
/**
* Creates a dashed line from the line specified by @points so that each dash is of length
* @p dashLength, and each blank inbetween is of length @p blankLength. The dashed line returned as a list of smaller lines
* in @p dashedLineOut.
* Creates a dashed line from the given line, dash length, and blank space between.
*
* @param dashLength Length of a single dash. Must be strictly positive.
* @param blankLength Length of a single blank between dashes. Must be strictly positive.
* @param[in] linePoints List of points specifying the input line.
* @param[out] dashedLineOut The dashed line returned as a list of smaller lines
* @param[in] dashLength Length of a single dash. Must be strictly positive.
* @param[in] blankLength Length of a single blank between dashes. Must be strictly positive.
*/
void ConstructDashedLine(const std::vector<CVector2D>& linePoints, SDashedLine& dashedLineOut, const float dashLength, const float blankLength);

53
source/simulation2/helpers/Selection.h
View File

@ -36,33 +36,50 @@ namespace EntitySelection
/**
* Finds all selectable entities under the given screen coordinates.
* Returns list ordered by closeness of picking, closest first.
* Restricted to entities in the LOS of @p player, but with any owner.
* (For Atlas selections this value is ignored as the whole map is revealed).
* If @p allowEditorSelectables then all entities with the IID_Selectable interface
* will be selected, else only selectable entities without the EditorOnly flag set.
*
* @param camera use this view to convert screen to world coordinates.
* @param screenX,screenY 2D screen coordinates.
* @param player player whose LOS will be used when selecting entities. In Atlas
* this value is ignored as the whole map is revealed.
* @param allowEditorSelectables if true, all entities with the ICmpSelectable interface
* will be selected (including decorative actors), else only those selectable ingame.
*
* @return ordered list of selected entities with the closest first.
*/
std::vector<entity_id_t> PickEntitiesAtPoint(CSimulation2& simulation, const CCamera& camera, int screenX, int screenY, player_id_t player, bool allowEditorSelectables);
/**
* Finds all selectable entities within the given screen coordinate rectangle,
* that belong to player @p owner.
* If @p owner is INVALID_PLAYER then ownership is ignored.
* If @p allowEditorSelectables then all entities with the IID_Selectable interface
* will be selected, else only selectable entities without the EditorOnly flag set.
* Returns unordered list.
* belonging to the given player. Used for bandboxing.
*
* @param camera use this view to convert screen to world coordinates.
* @param sx0,sy0,sx1,sy1 diagonally opposite corners of the rectangle in 2D screen coordinates.
* @param owner player whose entities we are selecting. Ownership is ignored if
* INVALID_PLAYER is used.
* @param allowEditorSelectables if true, all entities with the ICmpSelectable interface
* will be selected (including decorative actors), else only those selectable ingame.
*
* @return unordered list of selected entities.
*/
std::vector<entity_id_t> PickEntitiesInRect(CSimulation2& simulation, const CCamera& camera, int sx0, int sy0, int sx1, int sy1, player_id_t owner, bool allowEditorSelectables);
/**
* Finds all entities with the given entity template name, that belong to player @p owner.
* If @p owner is INVALID_PLAYER then ownership is ignored.
* If @p includeOffScreen then all entities visible in the world will be selected,
* else only entities visible on the screen will be selected.
* If @p matchRank then only entities that exactly match @p templateName will be selected,
* else entities with matching SelectionGroupName will be selected.
* If @p allowEditorSelectables then all entities with the IID_Selectable interface
* will be selected, else only selectable entities without the EditorOnly flag set.
* Finds all entities with the given entity template name, belonging to the given player.
*
* @param camera use this view to convert screen to world coordinates.
* @param templateName the name of the template to match, or the selection group name
* for similar matching.
* @param owner player whose entities we are selecting. Ownership is ignored if
* INVALID_PLAYER is used.
* @param includeOffScreen if true, then all entities visible in the world will be selected,
* else only entities visible to the camera will be selected.
* @param matchRank if true, only entities that exactly match templateName will be selected,
* else entities with matching SelectionGroupName will be selected.
* @param allowEditorSelectables if true, all entities with the ICmpSelectable interface
* will be selected (including decorative actors), else only those selectable ingame.
*
* @return unordered list of selected entities.
* @see ICmpIdentity
*/
std::vector<entity_id_t> PickSimilarEntities(CSimulation2& simulation, const CCamera& camera, const std::string& templateName, player_id_t owner, bool includeOffScreen, bool matchRank, bool allowEditorSelectables);