Utrecht University Crowd Simulation API
Classes | Macros | Typedefs | Enumerations | Functions
UUCS.h File Reference

Defines the Utrecht University Crowd Simulation (UUCS) API functions and related types. More...

#include "Environment/EnvironmentTypeDefinitions.h"
#include "Simulation/CharacterParameterInfo.h"
#include "Simulation/PathPlanning/PathPlanningManager.h"
#include "Simulation/PathFollowing/PathFollowingManager.h"
#include "Simulation/CollisionAvoidance/CollisionAvoidanceManager.h"
#include "Simulation/GroupForces/GroupForcesManager.h"
#include "Simulation/Character.h"
#include "Accessory_Tools/DensityMap_Grid.h"

Go to the source code of this file.

Classes

struct  CharacterStepData_Position
 A struct that stores the velocity and orientation of a character in the simulation at some point in time. More...
 
struct  CharacterStepData_Velocity
 A struct that stores the desired velocity and force of a character in the simulation at some point in time. More...
 
struct  CharacterGroupData
 A struct that stores the IDs of the members of a character group in the simulation at some point in time. More...
 
struct  VertexData
 A struct that represents a 2D position in the environment. More...
 
struct  VertexDataWithLayer
 A struct that represents a 2D position at a certain layer of the environment. More...
 
struct  VertexData3D
 A struct that stores the 3D position of a vertex in the environment. More...
 
struct  ConnectionData
 A struct that stores the endpoints of a connection, and the IDs of the layers to which this connection is associated. More...
 
struct  ObstacleData
 A struct that stores the list of vertices of an obstacle. More...
 
struct  WalkableAreaData
 A struct that stores the list of vertices of a walkable area. More...
 
struct  LayerData
 A struct that stores the list of obstacles and walkable areas of a layer. More...
 
struct  EnvironmentData
 A struct that stores the list of layers of an environment and the environment boundaries. More...
 
struct  DensityMapGrid
 A struct that stores the two dimensional array index, the corresponded positions in the environment, and the density in the grid It can be used to communicate the index, position, and density of each grid in the density map. More...
 

Macros

#define UUCSAPI   extern"C"
 
#define UUCS_CALLCONV
 
#define DEPRECATED_MESSAGE   "function is deprecated"
 
#define DEPRECATED   __declspec(deprecated(DEPRECATED_MESSAGE))
 

Typedefs

typedef CharacterParameterName CHARACTER_PARAMETER
 
typedef CharacterParameterType PARAMETER_TYPE
 
typedef Character::ControlMode CHARACTER_CONTROL_MODE
 
typedef DensityMapParameterName DENSITYMAP_PARAMETER
 
typedef DensityMapType DENSITYMAP_TYPE
 

Enumerations

enum  CharacterMovingState { Moving = 0, ReachedGoal = 1 }
 Indicates whether a Character reached its goal or is still moving. More...
 
enum  STATUS_CODE { SC_OK, SC_ERROR }
 Denotes a status code of the simulation. More...
 

Functions

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_Modelling_AddConnection (VertexData3D endpoint1, VertexData3D endpoint2, LayerIndex layerID1, LayerIndex layerID2, ConnectionIndex &connectionID)
 Adds a connection to the active modelling environment. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_Modelling_AddLayer (LayerIndex &layerID)
 Adds an empty layer to the active modelling environment. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_Modelling_AddObstacle (LayerIndex layerID, VertexData *vertices, int numVertices, PrimitiveIndex &obstacleID)
 Adds an obstacle on the specified layer of the active modelling environment. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_Modelling_AddWalkableArea (LayerIndex layerID, VertexData3D *vertices, int numVertices, PrimitiveIndex &walkableAreaID)
 Adds a walkable area on the specified layer of the active modelling environment. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_Modelling_Cleanup ()
 Cleans up all modelling-related objects managed by this DLL (i.e. the active modelling environment/layer/obstacle/walkable area/connection). More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_Modelling_CreateEnvironment (const char *name)
 Creates an empty modelling environment with the specified name and sets it as the active modelling environment. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_Modelling_LoadEnvironmentFromFile (const char *filename)
 Loads an environment (as an ENV or PRI file) into the program and sets it as the active modelling environment. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_Modelling_LoadEnvironmentFromMemory (EnvironmentData *environmentData)
 Loads an environment (as an EnvironmentData struct) into the program and sets it as the active modelling environment. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_Modelling_RemoveConnection (ConnectionIndex connectionID)
 Removes a connection from the active modelling environment. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_Modelling_RemoveLayer (LayerIndex layerID)
 Removes a layer from the active modelling environment. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_Modelling_RemoveObstacle (PrimitiveIndex obstacleID)
 Removes an obstacle from the active modelling environment. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_Modelling_RemoveWalkableArea (PrimitiveIndex walkableAreaID)
 Removes a walkable area from the active modelling environment. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_Modelling_SaveEnvironmentToMemory (EnvironmentData *&environmentData)
 Stores the active modelling environment to an EnvironmentData object. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_Modelling_SaveEnvironmentToFile (const char *filename)
 Saves the active modelling environment as an ENV or PRI file. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_Modelling_SimplifyPolygon (VertexData *originalVertices, int numVertices, float epsilon, VertexData *newVertices, int &numNewVertices)
 Simplify a obstacle polygon. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_Modelling_GetConvexHull (VertexData *originalVertices, int numVertices, VertexData *newVertices, int &numNewVertices)
 Get the convex hull of a polygon. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_Modelling_PolygonSubtract (VertexData *minuend, int numMiunendVertices, VertexData *subtrahend, int numSubtractPolygons, int *numSubtrahendVertices, VertexData *result, int &numResultVertices)
 Get the difference of a polygon and a list of polygons Can be used to operate obstacle polygons. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_Modelling_PolygonUnion (VertexData *addendList, int numAddPolygons, int *numaddendListVertices, VertexData *result, int &numResultVertices)
 Get the union of a polygon and a list of polygons Can be used to operate obstacle polygons. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_DoSimulationStep ()
 Performs a simulation step. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_ComputeNavigationMesh ()
 Computes the navigation mesh for the active simulation environment. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_PrepareSimulation (double timeStep, int seed, int nrThreads=0, CHARACTER_CONTROL_MODE defaultCharacterControlMode=CHARACTER_CONTROL_MODE::Internal)
 Initializes the simulation. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetSimulationTime (double &simulationTime)
 Stores the simulation time in the given memory address. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_ResetSimulation ()
 Resets the simulation: removes all characters and sets the simulation time back to 0. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_SaveEnvironmentToFile (const char *filename)
 Saves the active simulation environment as an ENV or PRI file. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_SaveEnvironmentToMemory (EnvironmentData *&environmentData)
 Stores the active simulation environment to an EnvironmentData object. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_SaveNavigationMeshToFile (const char *filename)
 Saves the navigation mesh of the active simulation environment as an ECMX or ECM file. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_LoadEnvironmentFromFile (const char *filename)
 Loads an environment (as an ENV or PRI file) into the program and sets it as the active simulation environment. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_LoadEnvironmentFromMemory (EnvironmentData *environmentData)
 Loads an environment (as an EnvironmentData struct) into the program and sets it as the active simulation environment. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_LoadNavigationMeshFromFile (const char *filename)
 Loads a precomputed navigation mesh (as an ECMX or ECM file) into the program. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_LoadCharacterProfiles (const char *filename)
 Loads character profiles from an XML file. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_Cleanup ()
 Cleans up all simulation-related objects managed by this DLL (i.e. the active simulation environment, its navigation mesh, the simulator, and its characters). More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_CreateDensityMap (LayerIndex layerIndex, int &id, double xMin=1.0, double yMin=1.0, double xMax=0.0, double yMax=0.0)
 Create a density to a layer, with a given range The grid width is default 0.3m, and the agent measure radius is default 1.5m. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_CalculateDensityMapWithCharacters (int id, const int *charactersID, int characterNumber)
 Performs a density map calculation step with a given character list. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_CalculateDensityMap (int id)
 Performs a density map calculation step. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetDensityMapParameter (int id, DENSITYMAP_PARAMETER parameter, double &value)
 Gets the value of a density map parameter. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetDensityMapSize (int id, int &width, int &height)
 Gets the width and the height of a density map. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_SetDensityMapParameter (int id, DENSITYMAP_PARAMETER parameter, double value)
 Updates a density map parameter to the specified value. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_ResetDensityMap (int id)
 Reset a density map, all of the data will be reset to their initial values. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetDensityMapResult (int id, DENSITYMAP_TYPE type, DensityMapGrid *densityMap)
 Get one of the three types of the density map, i.e. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_CleanUpDensityMap (int id)
 Cleans up a density map with ID. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_AddCharacter (double x, double y, LayerIndex layerID, int &id, const char *profileName="default", bool collisionFreePlacement=true, CHARACTER_CONTROL_MODE controlMode=CHARACTER_CONTROL_MODE::UseSimulationDefault)
 Adds a character to the simulation. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_RemoveCharacter (int characterID)
 Removes a character from the simulation. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_AddCharacterToGroup (int characterID, int &groupID)
 Adds an existing character as a member of a group. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetGroupID (int characterID, int &groupID)
 Retrieves the ID of the group that the specified character belongs to. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_RemoveCharacterFromGroup (int characterID)
 Removes a character from a group. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_SetCharacterGoal (int characterID, double x, double y, LayerIndex layerID, double radius)
 Sets the goal position of a character in the simulation, and lets the character plan a path towards it. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetCharacterGoal (int characterID, double &x, double &y, LayerIndex &layerID, double &radius)
 Retrieves the goal position of a character in the simulation, and lets the character plan a path towards it. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_SetCharacterIndicativeRoute (int characterID, VertexData *path, int length)
 Replaces the indactive route of the character by the given path. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetCharacterIndicativeRouteData (int characterID, int &length, double &score)
 Retrieves and returns the size of the character's indicative route and the score assigned to it. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetCharacterIndicativeRoute (int characterID, VertexDataWithLayer *path)
 Retrieves and returns the points of a character's indicative route. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_SetCharacterStepData (CharacterStepData_Position *stepData, int numEntries)
 Updates the position and orientation of externally controlled characters according to the specified settings. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetCharacterStepData (CharacterStepData_Position *&stepData_positions, int &numCharacters_positions, CharacterStepData_Velocity *&stepData_velocities, int &numCharacters_velocities)
 Stores the positions and orientations of all characters in the simulation in the given array pointer. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetCharacterStepDataInArea (double xMin, double yMin, double xMax, double yMax, LayerIndex layerID, CharacterStepData_Position *&stepData_positions, int &numCharacters_positions, CharacterStepData_Velocity *&stepData_velocities, int &numCharacters_velocities)
 Stores the positions and orientations of all characters in the specified area in the given array pointer. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetCharacterStepDataInRange (double xCenter, double yCenter, double radius, LayerIndex layerID, CharacterStepData_Position *&stepData_positions, int &numCharacters_positions, CharacterStepData_Velocity *&stepData_velocities, int &numCharacters_velocities)
 Stores the positions and orientations of all characters in the specified range in the given array pointer. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_SetCharacterControlMode (int characterID, CHARACTER_CONTROL_MODE newMode)
 Changes the control mode of a character. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetCharacterControlMode (int characterID, CHARACTER_CONTROL_MODE &result)
 Gets the current control mode of a character. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetCharacterParameterType (CHARACTER_PARAMETER parameter, PARAMETER_TYPE &type)
 Gets the type of a given character parameter. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetCharacterParameter_Double (int characterID, CHARACTER_PARAMETER parameter, double &value)
 Gets the value of a character parameter of type "double". More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetCharacterParameter_Int (int characterID, CHARACTER_PARAMETER parameter, int &value)
 Gets the value of a character parameter of type "int". More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetCharacterParameter_Bool (int characterID, CHARACTER_PARAMETER parameter, bool &value)
 Gets the value of a character parameter of type "bool". More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetCharacterParameter_PathPlanningMethod (int characterID, PathPlanningMethod::Type &value)
 Gets the type of a character's path planning method. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetCharacterParameter_PathFollowingMethod (int characterID, PathFollowingMethod::Type &value)
 Gets the type of a character's path following method. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetCharacterParameter_CollisionAvoidanceMethod (int characterID, CollisionAvoidanceMethod::Type &value)
 Gets the type of a character's collision avoidance method. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetCharacterParameter_GroupForcesMethod (int characterID, GroupForcesMethod::Type &value)
 Gets the type of a character's group forces method. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_SetCharacterParameter_Double (int characterID, CHARACTER_PARAMETER parameter, double value)
 Updates a character parameter of type "double" to the specified value. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_SetCharacterParameter_Int (int characterID, CHARACTER_PARAMETER parameter, int value)
 Updates a character parameter of type "int" to the specified value. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_SetCharacterParameter_Bool (int characterID, CHARACTER_PARAMETER parameter, bool value)
 Updates a character parameter of type "bool" to the specified value. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_SetCharacterParameter_PathPlanningMethod (int characterID, PathPlanningMethod::Type value)
 Updates a character's path planning method to the specified value. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_SetCharacterParameter_PathFollowingMethod (int characterID, PathFollowingMethod::Type value)
 Updates a character's path following method to the specified value. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_SetCharacterParameter_CollisionAvoidanceMethod (int characterID, CollisionAvoidanceMethod::Type value)
 Updates a character's collision avoidance method to the specified value. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_SetCharacterParameter_GroupForcesMethod (int characterID, GroupForcesMethod::Type value)
 Updates a character's group forces method to the specified value. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_AddActivityArea (LayerIndex layerID, VertexData *vertices, int numVertices, int &id)
 Adds an ActivityArea on the specified layer of the active simulation environment. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_RemoveActivityArea (int id)
 Removes an ActivityArea from the active simulation. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetActivityAreaArrayLengths (int id, int &enteredLength, int &insideLength, int &leftLength)
 
Retrieves the lengths of the arrays containing the CharacterID's for the characters that entered, left, or are inside the ActivityArea with the given ID. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetActivityAreaData (int id, int *characterIDsEntered, int *characterIDsInside, int *characterIDsLeft)
 Retrieves the CharacterIDs for the Characters that entered, or left the are or are inside of the ActivityArea. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_AddDynamicObstacle (LayerIndex layerID, VertexData *vertices, int numVertices, PrimitiveIndex &obstacleID)
 Adds a dynamic obstacle on the specified layer of the active simulation environment. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_RemoveDynamicObstacle (PrimitiveIndex obstacleID)
 Removes a dynamic obstacle from the active simulation environment. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetMajorVersion (int &verMajor)
 Retrieves the major version of the UUCS API. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetMinorVersion (int &verMinor)
 Retrieves the minor version of the UUCS API. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetPatchVersion (int &verPatch)
 Retrieves the patch version of the UUCS API. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetRandomFreePosition (LayerIndex layerID, double radius, double xMin, double yMin, double xMax, double yMax, double &x, double &y)
 Finds a random free position on a given layer of the active simulation environment, within the specified axis-aligned bounding box. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_IsDiscFreeOfObstacles (double x, double y, LayerIndex layerID, double radius, bool &free)
 Checks whether the specified disc does not intersect any obstacles within the active simulation environment. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_IsDiscFreeOfCharacters (double x, double y, LayerIndex layerID, double radius, bool &free)
 Checks whether the specified disc does not intersect any obstacles within the active simulation environment. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetCharacterGroupData (CharacterGroupData *&cGData, int &numCharacterGroups)
 Stores the IDs of the members of all character groups in the simulation in the given array pointer. More...
 
UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_PerformTest (int testID, int numCharacters)
 Performs a simple test scenario. More...
 

Detailed Description

Defines the Utrecht University Crowd Simulation (UUCS) API functions and related types.

Author
Angelos Kremyzas
Wouter van Toll

Macro Definition Documentation

◆ DEPRECATED

#define DEPRECATED   __declspec(deprecated(DEPRECATED_MESSAGE))

◆ DEPRECATED_MESSAGE

#define DEPRECATED_MESSAGE   "function is deprecated"

◆ UUCS_CALLCONV

#define UUCS_CALLCONV

◆ UUCSAPI

#define UUCSAPI   extern"C"

Typedef Documentation

◆ CHARACTER_CONTROL_MODE

typedef Character::ControlMode CHARACTER_CONTROL_MODE

◆ CHARACTER_PARAMETER

typedef CharacterParameterName CHARACTER_PARAMETER

◆ DENSITYMAP_PARAMETER

typedef DensityMapParameterName DENSITYMAP_PARAMETER

◆ DENSITYMAP_TYPE

typedef DensityMapType DENSITYMAP_TYPE

◆ PARAMETER_TYPE

typedef CharacterParameterType PARAMETER_TYPE

Enumeration Type Documentation

◆ CharacterMovingState

Indicates whether a Character reached its goal or is still moving.

Enumerator
Moving 

Indicates that a Character is still moving.

ReachedGoal 

Indicates that the Character reached its goal.

◆ STATUS_CODE

Denotes a status code of the simulation.

It is used to describe the success or failure of an API function call.

Enumerator
SC_OK 

Indicates that the called API function has been successfully executed.

SC_ERROR 

Indicates that there was an error while executing the called API function.

Function Documentation

◆ UUCS_AddActivityArea()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_AddActivityArea ( LayerIndex  layerID,
VertexData vertices,
int  numVertices,
int &  id 
)

Adds an ActivityArea on the specified layer of the active simulation environment.

Parameters
[in]layerIDThe ID of the layer at which the ActivityArea is added.
[in]verticesAn array that stores all vertices that define the ActivityArea to add. The vertices should be given in counterclockwise order.
[in]numVerticesThe number of vertices that define the ActivityArea to add. This parameter should be equal to the length of the vertices array.
[in,out]idThe desired ID of the ActivityArea to add is read from this parameter. The DLL will attempt to add the specified ActivityArea using the desired ID. If -1 is provided as a desired ID, then the DLL will automatically assign an ID to the added ActivityArea. Upon successfull addition of the ActivityArea, its assigned ID is written back to this parameter. If the ActivityArea could not be added this is set to -1. You can use this ID to remove the dynamic obstacle using UUCS_RemoveActivityArea().
Return values
SC_OKif the specified ActivityArea was successfully added to the active simulation environment.
SC_ERRORotherwise, i.e. if:
a) there exists no active simulation environment yet, or
b) no navigation mesh has been linked to the active simulation environment, or
c) the active simulation environment does not include a layer with the specified layer ID, or
d) another ActivityArea already exists in the active simulation environment with the specified ID, or
e) the 'vertices' parameter is nullptr, or
f) the 'numVertices' parameter is not positive, or
Precondition
1. There exists an active simulation environment, i.e. either UUCS_LoadEnvironmentFromFile() or UUCS_LoadEnvironmentFromMemory() has been previously called and returned SC_OK.
2. A navigation mesh has been linked to the active simulation environment, i.e. either UUCS_LoadNavigationMeshFromFile() or UUCS_ComputeNavigationMesh() has been previously called and returned SC_OK.
3. The active simulation environment includes a layer with layerID as its ID.
4. There exists no ActivityArea in the active simulation environment with obstacleID as its ID.
5. The 'numVertices' parameter equals the size of the 'vertices' array.
6. The 'vertices' array defines a point or a line segment or convex polygon whose vertices are provided in either clockwise or counterclockwise order.
Postcondition
1. The specified ActivityArea is added to the active simulation environment.

◆ UUCS_AddCharacter()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_AddCharacter ( double  x,
double  y,
LayerIndex  layerID,
int &  id,
const char *  profileName = "default",
bool  collisionFreePlacement = true,
CHARACTER_CONTROL_MODE  controlMode = CHARACTER_CONTROL_MODE::UseSimulationDefault 
)

Adds a character to the simulation.

Parameters
[in]xThe X coordinate of the character's position.
[in]yThe Y coordinate of the character's position.
[in]layerIDThe ID of the layer on which the character should be located.
[in,out]idA reference to the desired ID of the character. Use -1 to let the DLL generate a unique ID automatically. Use a non-negative value to force a certain ID to be used. This is useful if your external program is already managing character IDs on its own, and you want the IDs in both programs to be synchronized. If the character is successfully added, this variable now stores the ID that has been assigned to the added character.
[in]profileNameThe name of the character profile to use. This profile should have been loaded before, through UUCS_LoadCharacterProfiles().
[in]collisionFreePlacementWhether or not the character must be added in a position that is free of obstacles and other characters. Use 'true' to require collision free placement or 'false' otherwise.
[in]controlModeThe desired control mode for the character. Use CHARACTER_CONTROL_MODE::UseSimulationDefault to apply the default simulation setting.
Return values
SC_OKif the character was successfully added.
SC_ERRORotherwise, i.e. if:
a) the simulation has not been initialized yet, or
b) no profile with the given profileName has been loaded, or
c) a character with the given ID already exists in the simulation. d) collisionFreePlacement is set to 'true', while the given character's position and radius as specified in the character profile do not allow for collision free placement.
Precondition
1. UUCS_PrepareSimulation() has been previously called and returned SC_OK.
2. UUCS_LoadCharacterProfiles() has been previously called and returned SC_OK.
3. The loaded character profiles include a profile with the name specified.
4. There is no other character in the simulation with the id specified.
5. If collisionFreePlacement is set to 'true', then the specified position has a clearance of at least the radius of the specified profile from all obstacles and characters that exist in the active simulation environment.
Postcondition
The value of id equals the ID that has been assigned to the added character by the DLL.
See also
UUCS_PrepareSimulation()

◆ UUCS_AddCharacterToGroup()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_AddCharacterToGroup ( int  characterID,
int &  groupID 
)

Adds an existing character as a member of a group.

Warning
Calling this function will remove the specified character from any group that this character is a member of.
Parameters
[in]characterIDThe ID of the character to add as a member of the group.
[in,out]groupIDA reference to the ID of the group to which the character is added. If no group exists yet in the simulation with the specified group ID, then a new group is created. Use -1 to let the DLL create a new group and generate a unique ID automatically. If the character is successfully added to the group, this variable now stores the ID of the group.
Return values
SC_OKif the character was successfully added as a member of a group.
SC_ERRORotherwise, i.e. if:
a) the simulation has not been initialized yet, or
b) a character with the given ID does not exists in the simulation, or
Precondition
1. UUCS_PrepareSimulation() has been previously called and returned SC_OK.
2. A character with the specified id exists in the simulation.
Postcondition
The value of groupID equals the ID of the group to which the character has been added by the DLL.
If the specified group did not exist before in the simulation, then it has now been created.
If the character was a member of a different group before, then it is no longer a member of that group.
See also
UUCS_PrepareSimulation()

◆ UUCS_AddDynamicObstacle()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_AddDynamicObstacle ( LayerIndex  layerID,
VertexData vertices,
int  numVertices,
PrimitiveIndex &  obstacleID 
)

Adds a dynamic obstacle on the specified layer of the active simulation environment.

Warning
Dynamic obstacle updates is currently work in progress.
Note
1. It is only allowed to add a dynamic obstacle that is either a point or a line segment or a convex polygon.
2. It is only allowed to add a dynamic obstacle that does not intersect other obstacles within the active simulation environment.
Warning
Adding a dynamic obstacle sets any character that intersects that obstacle to be 'externally controlled' as well as any other member of the group that this character belongs to, if any.
Parameters
[in]layerIDThe ID of the layer at which the dynamic obstacle is added.
[in]verticesAn array that stores all vertices that define the dynamic obstacle to add. The vertices can be given in either clockwise or counterclockwise order.
[in]numVerticesThe number of vertices that define the dynamic obstacle to add. This parameter should be equal to the length of the vertices array.
[in,out]obstacleIDThe desired ID of the dynamic obstacle to add is read from this parameter. The DLL will attempt to add the specified dynamic obstacle using the desired ID. If -1 is provided as a desired ID, then the DLL will automatically assign an ID to the added dynamic obstacle. Upon successfull addition of the dynamic obstacle, its assigned ID is written back to this parameter. If the dynamic obstacle could not be added this is set to -1. You can use this ID to remove the dynamic obstacle using UUCS_RemoveDynamicObstacle().
Return values
SC_OKif the specified dynamic obstacle was successfully added to the active simulation environment.
SC_ERRORotherwise, i.e. if:
a) there exists no active simulation environment yet, or
b) no navigation mesh has been linked to the active simulation environment, or
c) the active simulation environment does not include a layer with the specified layer ID, or
d) another obstacle already exists in the active simulation environment with the specified obstacle ID, or
e) the 'vertices' parameter is nullptr, or
f) the 'numVertices' parameter is not positive, or
g) the specified dynamic obstacle is neither a point nor a line segment nor a convex polygon, or
h) the specified dynamic obstacle intersects another obstacle of the active simulation environment.
Precondition
1. There exists an active simulation environment, i.e. either UUCS_LoadEnvironmentFromFile() or UUCS_LoadEnvironmentFromMemory() has been previously called and returned SC_OK.
2. A navigation mesh has been linked to the active simulation environment, i.e. either UUCS_LoadNavigationMeshFromFile() or UUCS_ComputeNavigationMesh() has been previously called and returned SC_OK.
3. The active simulation environment includes a layer with layerID as its ID.
4. There exists no obstacle in the active simulation environment with obstacleID as its ID.
5. The 'numVertices' parameter equals the size of the 'vertices' array.
6. The 'vertices' array defines a point or a line segment or convex polygon whose vertices are provided in either clockwise or counterclockwise order.
7. The specified dynamic obstacle does not intersect another obstacle of the active simulation environment.
Postcondition
1. The specified dynamic obstacle is added to the active simulation environment.
2. The specified dynamic obstacle is added to the navigation mesh of the active simulation environment by the end of the next simulation step, i.e. after UUCS_DoSimulationStep() has been called again and returned SC_OK.
3. obstacleID contains the ID of the added dynamic obstacle.
4. Any character that intersects the added dynamic obstacle and any other member of that character's group, if any, is set to be 'externally controlled' by the end of the next simulation step, i.e. after UUCS_DoSimulationStep() has been called again and returned SC_OK.
See also
UUCS_RemoveDynamicObstacle()
ObstacleData
EnvironmentData
UUCS_LoadEnvironmentFromFile()
UUCS_LoadEnvironmentFromMemory()
UUCS_LoadNavigationMeshFromFile()
UUCS_ComputeNavigationMesh()
UUCS_SaveEnvironmentToMemory()
UUCS_SetCharacterStepData()
UUCS_DoSimulationStep()

◆ UUCS_CalculateDensityMap()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_CalculateDensityMap ( int  id)

Performs a density map calculation step.

Call this function after creating the density map

Parameters
[in]idThe ID of the density map which the user wants to update
Return values
SC_OKif the calculation is successful
SC_ERRORotherwise.
Precondition
UUCS_CreateDensityMap has been previously called and returned SC_OK.

◆ UUCS_CalculateDensityMapWithCharacters()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_CalculateDensityMapWithCharacters ( int  id,
const int *  charactersID,
int  characterNumber 
)

Performs a density map calculation step with a given character list.

Call this function after creating the density map

Parameters
[in]idThe ID of the density map which the user wants to update
[in]charactersIDan array of Characters' ID, representing the characters that the user wants to take into account
[in]characterNumberThe size of the given character array
Return values
SC_OKif the calculation is successful
SC_ERRORotherwise.
Precondition
UUCS_CreateDensityMap has been previously called and returned SC_OK.

◆ UUCS_Cleanup()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_Cleanup ( )

Cleans up all simulation-related objects managed by this DLL (i.e. the active simulation environment, its navigation mesh, the simulator, and its characters).

Call this function when you are about to stop using the program.

◆ UUCS_CleanUpDensityMap()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_CleanUpDensityMap ( int  id)

Cleans up a density map with ID.

◆ UUCS_ComputeNavigationMesh()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_ComputeNavigationMesh ( )

Computes the navigation mesh for the active simulation environment.

Therefore, you must call UUCS_LoadEnvironmentFromFile() or UUCS_LoadEnvironmentFromMemory() first. Use this function instead of UUCS_LoadNavigationMeshFromFile() if you don't have a precomputed navigation mesh yet.

Return values
SC_OKif an active simulation environment exists, and its navigation mesh was successfully computed.
SC_ERRORotherwise.
Precondition
There exists an active simulation environment, i.e. UUCS_LoadEnvironmentFromFile() or UUCS_LoadEnvironmentFromMemory() has been previously called and returned SC_OK.
Postcondition
The computed navigation mesh is linked to the active simulation environment.
See also
UUCS_LoadEnvironmentFromFile()
UUCS_LoadEnvironmentFromMemory()

◆ UUCS_CreateDensityMap()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_CreateDensityMap ( LayerIndex  layerIndex,
int &  id,
double  xMin = 1.0,
double  yMin = 1.0,
double  xMax = 0.0,
double  yMax = 0.0 
)

Create a density to a layer, with a given range The grid width is default 0.3m, and the agent measure radius is default 1.5m.

Call this function after preparing the simulation.

Parameters
[in]layerIndexThe ID of the layer in which the density map should create.
[in]xMin[optional] The minimum x coordinate of the axis-aligned bounding box in which the density map should create.
[in]yMin[optional] The minimum y coordinate of the axis-aligned bounding box in which the density map should create.
[in]xMax[optional] The maximum x coordinate of the axis-aligned bounding box in which the density map should create.
[in]yMax[optional] The maximum y coordinate of the axis-aligned bounding box in which the density map should create.
[in,out]idA reference to the desired ID of the character. If the density map is successfully added, this variable now stores the ID that has been assigned to the added density map.
Return values
SC_OKif the density is successfully created.
SC_ERRORotherwise.
Precondition
UUCS_PrepareSimulation() has been previously called and returned SC_OK.

◆ UUCS_DoSimulationStep()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_DoSimulationStep ( )

Performs a simulation step.

Return values
SC_OKif the simulation step was successfully performed.
SC_ERRORotherwise, i.e. if the simulation has not been initialized yet.
Precondition
UUCS_PrepareSimulation() has been previously called and returned SC_OK.
See also
UUCS_PrepareSimulation()

◆ UUCS_GetActivityAreaArrayLengths()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetActivityAreaArrayLengths ( int  id,
int &  enteredLength,
int &  insideLength,
int &  leftLength 
)


Retrieves the lengths of the arrays containing the CharacterID's for the characters that entered, left, or are inside the ActivityArea with the given ID.

Parameters
[in]idThe ID of the ActivityArea for which we want to know the lengths.
[out]enteredLengthThe length of the array containing CharacterID's that entered the Activity Area is stored in this variable.
[out]insideLengthThe length of the array containing CharacterID's that are inside the Activity Area is stored in this variable.
[out]leftLengthThe length of the array containing CharacterID's that left the Activity Area is stored in this variable.
Return values
SC_OKif the data was retrieved correctly.
SC_ERRORotherwise, i.e. if:
a) no ActivityArea with the given id is present in the simulation.

◆ UUCS_GetActivityAreaData()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetActivityAreaData ( int  id,
int *  characterIDsEntered,
int *  characterIDsInside,
int *  characterIDsLeft 
)

Retrieves the CharacterIDs for the Characters that entered, or left the are or are inside of the ActivityArea.

Parameters
[in]idThe ID of the ActivityArea for which we want to retrieve the data.
[out]characterIDsEnteredPointer to an array in which the IDs for the Characters are stored that entered the ActivityArea.
[out]characterIDsInsidePointer to an array in which the IDs for the Characters are stored that are inside the ActivityArea.
[out]characterIDsLeftPointer to an array in which the IDs for the Characters are stored that left the ActivityArea.
Return values
SC_OKif the data was retrieved correctly.
SC_ERRORotherwise, i.e. if:
a) no ActivityArea with the given id is present in the simulation.

◆ UUCS_GetCharacterControlMode()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetCharacterControlMode ( int  characterID,
CHARACTER_CONTROL_MODE result 
)

Gets the current control mode of a character.

Parameters
[in]characterIDThe ID of the character to check.
[out]resultWill store the current control mode of the character.
Return values
SC_OKif the control mode of the character has been successfully retrieved.
SC_ERRORotherwise, i.e. if the simulation has not been initialized yet or if the specified character ID does not exist.
Precondition
1. UUCS_PrepareSimulation() has been previously called and returned SC_OK.
2. There exists a character in the simulation with the ID specified.
Postcondition
The control mode of the given character is stored in the result parameter.
See also
CHARACTER_CONTROL_MODE
UUCS_PrepareSimulation()
UUCS_GetCharacterStepData()
UUCS_SetCharacterStepData()

◆ UUCS_GetCharacterGoal()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetCharacterGoal ( int  characterID,
double &  x,
double &  y,
LayerIndex &  layerID,
double &  radius 
)

Retrieves the goal position of a character in the simulation, and lets the character plan a path towards it.

Parameters
[in]characterIDThe ID of the character.
[out]xA reference to the X coordinate of the character's goal position.
[out]yA reference to the Y coordinate of the character's goal position.
[out]layerIDA reference to the ID of the layer on which the character's goal position is located.
[out]radiusA reference to the radius of the goal position, in meters.
Return values
SC_OKif the goal of the character has been successfully retrieved.
SC_ERRORotherwise, i.e. if:
a) the simulation has not been initialized yet, or
b) the character with the given ID does not exist, or
c) the character with the given ID has no goal specified.
Precondition
1. UUCS_PrepareSimulation() has been previously called and returned SC_OK.
2. There exists a character in the simulation with the ID specified.
3. A goal has been specified for the character with the given ID.
See also
UUCS_PrepareSimulation()
UUCS_SetCharacterGoal()

◆ UUCS_GetCharacterGroupData()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetCharacterGroupData ( CharacterGroupData *&  cGData,
int &  numCharacterGroups 
)

Stores the IDs of the members of all character groups in the simulation in the given array pointer.

Warning
Depending on the order of events, the simulation may contain character groups that do not yet exist in your external program.
Parameters
[out]cGDataA (reference to a) pointer to the beginning of a CharacterGroupData array (i.e. a memory address). This DLL will fill this array with CharacterGroupData for each character group in the simulation. Your own application will have to read these values and use them properly. The DLL is responsible for managing the memory of the CharacterGroupData array.
[out]numCharacterGroupsA reference to an integer that stores the number of character groups in the crowd.
Return values
SC_OKif the crowd information has been successfully written to the CharacterGroupData array. numCharacterGroups indicates the size of this array.
SC_ERRORotherwise, i.e. if the simulation has not been initialized yet.
Precondition
UUCS_PrepareSimulation() has been previously called and returned SC_OK.
See also
UUCS_PrepareSimulation()

◆ UUCS_GetCharacterIndicativeRoute()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetCharacterIndicativeRoute ( int  characterID,
VertexDataWithLayer path 
)

Retrieves and returns the points of a character's indicative route.

Parameters
[in]characterIDThe ID of the character whose data is to be retrieved.
[out]pathReference to the array in which we will store the VertexDataWithLayer containing the points of the indicative route.
Return values
SC_OKif the indicative route was retrieved succesfully.
SC_ERRORotherwise, i.e. if the simulation has not been initialized yet or if the given character does not exist.
Precondition

◆ UUCS_GetCharacterIndicativeRouteData()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetCharacterIndicativeRouteData ( int  characterID,
int &  length,
double &  score 
)

Retrieves and returns the size of the character's indicative route and the score assigned to it.

Parameters
[in]characterIDThe ID of the character whose data is to be retrieved.
[out]lengthAmount of vertices that define the character's indicative route.
[out]scoreThe score assigned to the character's indicative route.
Return values
SC_OKif the data was retrieved succesfully.
SC_ERRORotherwise, i.e. if the simulation has not been initialized yet or if the given character does not exist.

◆ UUCS_GetCharacterParameter_Bool()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetCharacterParameter_Bool ( int  characterID,
CHARACTER_PARAMETER  parameter,
bool &  value 
)

Gets the value of a character parameter of type "bool".

Parameters
[in]characterIDThe ID of the character whose parameter is to be queried.
[in]parameterThe CHARACTER_PARAMETER that describes the character parameter to be queried.
[out]valueWill store the value of the given parameter.
Return values
SC_OKif the value of the character parameter has been successfully retrieved (and stored in the "value" argument).
SC_ERRORotherwise, i.e. if the simulation has not been initialized yet, or if the character with the specified ID does not exist, or if the specified parameter does not have type "bool".
Precondition
1. UUCS_PrepareSimulation() has been previously called and returned SC_OK.
2. There exists a character in the simulation with the ID specified.
See also
UUCS_PrepareSimulation()

◆ UUCS_GetCharacterParameter_CollisionAvoidanceMethod()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetCharacterParameter_CollisionAvoidanceMethod ( int  characterID,
CollisionAvoidanceMethod::Type &  value 
)

Gets the type of a character's collision avoidance method.

Parameters
[in]characterIDThe ID of the character to be queried.
[out]valueWill store the collision avoidance method type of the associated character.
Return values
SC_OKif the value of the character parameter has been successfully retrieved (and stored in the "value" argument).
SC_ERRORotherwise, i.e. if the simulation has not been initialized yet, or if the character with the specified ID does not exist.
Precondition
1. UUCS_PrepareSimulation() has been previously called and returned SC_OK.
2. There exists a character in the simulation with the ID specified.
See also
UUCS_PrepareSimulation()

◆ UUCS_GetCharacterParameter_Double()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetCharacterParameter_Double ( int  characterID,
CHARACTER_PARAMETER  parameter,
double &  value 
)

Gets the value of a character parameter of type "double".

Parameters
[in]characterIDThe ID of the character whose parameter is to be queried.
[in]parameterThe CHARACTER_PARAMETER that describes the character parameter to be queried.
[out]valueWill store the value of the given parameter.
Return values
SC_OKif the value of the character parameter has been successfully retrieved (and stored in the "value" argument).
SC_ERRORotherwise, i.e. if the simulation has not been initialized yet, or if the character with the specified ID does not exist, or if the specified parameter does not have type "double".
Precondition
1. UUCS_PrepareSimulation() has been previously called and returned SC_OK.
2. There exists a character in the simulation with the ID specified.
See also
UUCS_PrepareSimulation()

◆ UUCS_GetCharacterParameter_GroupForcesMethod()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetCharacterParameter_GroupForcesMethod ( int  characterID,
GroupForcesMethod::Type &  value 
)

Gets the type of a character's group forces method.

Parameters
[in]characterIDThe ID of the character to be queried.
[out]valueWill store the group forces method type of the associated character.
Return values
SC_OKif the value of the character parameter has been successfully retrieved (and stored in the "value" argument).
SC_ERRORotherwise, i.e. if the simulation has not been initialized yet, or if the character with the specified ID does not exist.
Precondition
1. UUCS_PrepareSimulation() has been previously called and returned SC_OK.
2. There exists a character in the simulation with the ID specified.
See also
UUCS_PrepareSimulation()

◆ UUCS_GetCharacterParameter_Int()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetCharacterParameter_Int ( int  characterID,
CHARACTER_PARAMETER  parameter,
int &  value 
)

Gets the value of a character parameter of type "int".

Parameters
[in]characterIDThe ID of the character whose parameter is to be queried.
[in]parameterThe CHARACTER_PARAMETER that describes the character parameter to be queried.
[out]valueWill store the value of the given parameter.
Return values
SC_OKif the value of the character parameter has been successfully retrieved (and stored in the "value" argument).
SC_ERRORotherwise, i.e. if the simulation has not been initialized yet, or if the character with the specified ID does not exist, or if the specified parameter does not have type "int".
Precondition
1. UUCS_PrepareSimulation() has been previously called and returned SC_OK.
2. There exists a character in the simulation with the ID specified.
See also
UUCS_PrepareSimulation()

◆ UUCS_GetCharacterParameter_PathFollowingMethod()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetCharacterParameter_PathFollowingMethod ( int  characterID,
PathFollowingMethod::Type &  value 
)

Gets the type of a character's path following method.

Parameters
[in]characterIDThe ID of the character to be queried.
[out]valueWill store the path following method type of the associated character.
Return values
SC_OKif the value of the character parameter has been successfully retrieved (and stored in the "value" argument).
SC_ERRORotherwise, i.e. if the simulation has not been initialized yet, or if the character with the specified ID does not exist.
Precondition
1. UUCS_PrepareSimulation() has been previously called and returned SC_OK.
2. There exists a character in the simulation with the ID specified.
See also
UUCS_PrepareSimulation()

◆ UUCS_GetCharacterParameter_PathPlanningMethod()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetCharacterParameter_PathPlanningMethod ( int  characterID,
PathPlanningMethod::Type &  value 
)

Gets the type of a character's path planning method.

Parameters
[in]characterIDThe ID of the character to be queried.
[out]valueWill store the path planning method type of the associated character.
Return values
SC_OKif the value of the character parameter has been successfully retrieved (and stored in the "value" argument).
SC_ERRORotherwise, i.e. if the simulation has not been initialized yet, or if the character with the specified ID does not exist.
Precondition
1. UUCS_PrepareSimulation() has been previously called and returned SC_OK.
2. There exists a character in the simulation with the ID specified.
See also
UUCS_PrepareSimulation()

◆ UUCS_GetCharacterParameterType()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetCharacterParameterType ( CHARACTER_PARAMETER  parameter,
PARAMETER_TYPE type 
)

Gets the type of a given character parameter.

You can use this method if you are not sure which version of UUCS_GetCharacterParameter_...() or UUCS_SetCharacterParameter_...() you should use.

Parameters
[in]parameterThe CHARACTER_PARAMETER that describes the character parameter to be queried.
[out]typeWill store a PARAMETER_TYPE value that represents the type of the given parameter.
Return values
SC_OKif the type of the given parameter has been successfully retrieved and stored in the out-parameter 'type'.
SC_ERRORotherwise, i.e. if the simulation has not been initialized yet, or the given parameter was not known for any other reason (which should never occur).

◆ UUCS_GetCharacterStepData()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetCharacterStepData ( CharacterStepData_Position *&  stepData_positions,
int &  numCharacters_positions,
CharacterStepData_Velocity *&  stepData_velocities,
int &  numCharacters_velocities 
)

Stores the positions and orientations of all characters in the simulation in the given array pointer.

Warning
Depending on the order of events, the simulation may contain characters that do not yet exist in your external program.
Parameters
[out]stepData_positionsA (reference to a) pointer to the beginning of a CharacterStepData_Position array (i.e. a memory address). This DLL will fill this array with data for each applicable character in the simulation. Your own application will have to read these values and use them properly. For example, if you have a Unity application, you can assign the positions and orientations to the 3D character models. The DLL is responsible for managing the memory of this array.
[out]numCharacters_positionsA reference to an integer that stores the number of characters in the stepData_positions array.
[out]stepData_velocitiesA (reference to a) pointer to the beginning of a CharacterStepData_Velocity array (i.e. a memory address). This DLL will fill this array with data for each applicable character in the simulation. Your own application will have to read these values and use them properly. For example, if you have a Unity application, you can try to apply the given velocity and then add Unity physics on top of it. The DLL is responsible for managing the memory of this array. NOTE: The characters in this array have not yet received a new position within the DLL. Your own application should use UUCS_SetCharacterStepData() to notify the DLL about the positions that you have computed yourself.
[out]numCharacters_velocitiesA reference to an integer that stores the number of characters in the stepData_positions array.
Return values
SC_OKif the crowd information has been successfully written to the CharacterStepData array. numCharacters indicates the size of this array.
SC_ERRORotherwise, i.e. if the simulation has not been initialized yet.
Precondition
UUCS_PrepareSimulation() has been previously called and returned SC_OK.
See also
UUCS_PrepareSimulation()

◆ UUCS_GetCharacterStepDataInArea()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetCharacterStepDataInArea ( double  xMin,
double  yMin,
double  xMax,
double  yMax,
LayerIndex  layerID,
CharacterStepData_Position *&  stepData_positions,
int &  numCharacters_positions,
CharacterStepData_Velocity *&  stepData_velocities,
int &  numCharacters_velocities 
)

Stores the positions and orientations of all characters in the specified area in the given array pointer.

Warning
Depending on the order of events, the simulation may contain characters that do not yet exist in your external program.
Parameters
[in]xMin,yMin,xMax,yMaxThe minimum corner and the maximum corner of the area
[in]layerIDthe target layer's ID
[out]stepData_positionsA (reference to a) pointer to the beginning of a CharacterStepData_Position array (i.e. a memory address). This DLL will fill this array with data for each applicable character in the simulation. Your own application will have to read these values and use them properly. For example, if you have a Unity application, you can assign the positions and orientations to the 3D character models. The DLL is responsible for managing the memory of this array.
[out]numCharacters_positionsA reference to an integer that stores the number of characters in the stepData_positions array.
[out]stepData_velocitiesA (reference to a) pointer to the beginning of a CharacterStepData_Velocity array (i.e. a memory address). This DLL will fill this array with data for each applicable character in the simulation. Your own application will have to read these values and use them properly. For example, if you have a Unity application, you can try to apply the given velocity and then add Unity physics on top of it. The DLL is responsible for managing the memory of this array. NOTE: The characters in this array have not yet received a new position within the DLL. Your own application should use UUCS_SetCharacterStepData() to notify the DLL about the positions that you have computed yourself.
[out]numCharacters_velocitiesA reference to an integer that stores the number of characters in the stepData_positions array.
Return values
SC_OKif the crowd information has been successfully written to the CharacterStepData array. numCharacters indicates the size of this array.
SC_ERRORotherwise, i.e. if the simulation has not been initialized yet.
Precondition
UUCS_PrepareSimulation() has been previously called and returned SC_OK.
See also
UUCS_PrepareSimulation()

◆ UUCS_GetCharacterStepDataInRange()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetCharacterStepDataInRange ( double  xCenter,
double  yCenter,
double  radius,
LayerIndex  layerID,
CharacterStepData_Position *&  stepData_positions,
int &  numCharacters_positions,
CharacterStepData_Velocity *&  stepData_velocities,
int &  numCharacters_velocities 
)

Stores the positions and orientations of all characters in the specified range in the given array pointer.

Warning
Depending on the order of events, the simulation may contain characters that do not yet exist in your external program.
Parameters
[in]xCenter,yCenterThe center of the searching range
[in]radiusThe radius of the searching circle
[in]layerIDthe target layer's ID
[out]stepData_positionsA (reference to a) pointer to the beginning of a CharacterStepData_Position array (i.e. a memory address). This DLL will fill this array with data for each applicable character in the simulation. Your own application will have to read these values and use them properly. For example, if you have a Unity application, you can assign the positions and orientations to the 3D character models. The DLL is responsible for managing the memory of this array.
[out]numCharacters_positionsA reference to an integer that stores the number of characters in the stepData_positions array.
[out]stepData_velocitiesA (reference to a) pointer to the beginning of a CharacterStepData_Velocity array (i.e. a memory address). This DLL will fill this array with data for each applicable character in the simulation. Your own application will have to read these values and use them properly. For example, if you have a Unity application, you can try to apply the given velocity and then add Unity physics on top of it. The DLL is responsible for managing the memory of this array. NOTE: The characters in this array have not yet received a new position within the DLL. Your own application should use UUCS_SetCharacterStepData() to notify the DLL about the positions that you have computed yourself.
[out]numCharacters_velocitiesA reference to an integer that stores the number of characters in the stepData_positions array.
Return values
SC_OKif the crowd information has been successfully written to the CharacterStepData array. numCharacters indicates the size of this array.
SC_ERRORotherwise, i.e. if the simulation has not been initialized yet.
Precondition
UUCS_PrepareSimulation() has been previously called and returned SC_OK.
See also
UUCS_PrepareSimulation()

◆ UUCS_GetDensityMapParameter()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetDensityMapParameter ( int  id,
DENSITYMAP_PARAMETER  parameter,
double &  value 
)

Gets the value of a density map parameter.

Parameters
[in]idThe ID of the density map which the user wants to get a paramter
[in]parameterThe CHARACTER_PARAMETER that describes the character parameter to be queried.
[out]valueWill store the value of the given parameter.
Return values
SC_OKif the value of the density map parameter has been successfully retrieved (and stored in the "value" argument).
SC_ERRORotherwise
Precondition
UUCS_CreateDensityMap has been previously called and returned SC_OK.

◆ UUCS_GetDensityMapResult()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetDensityMapResult ( int  id,
DENSITYMAP_TYPE  type,
DensityMapGrid densityMap 
)

Get one of the three types of the density map, i.e.

low density map, high density map, average density map.

Parameters
[in]idThe ID of the density map which the user wants to get
[in]typeThe DENSITYMAP_TYPE that describes the density map's type to be queried.
[in,out]densityMapReference to the array in which we will store the DensityMapGrid containing the point and the density of a grid.
Return values
SC_OKif the density map successfully retrieved.
SC_ERRORotherwise
Precondition
UUCS_CreateDensityMap has been previously called and returned SC_OK.

◆ UUCS_GetDensityMapSize()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetDensityMapSize ( int  id,
int &  width,
int &  height 
)

Gets the width and the height of a density map.

Parameters
[in]idThe ID of the density map which the user wants to get a paramter
[out]widthWill store the value of the map's width
[out]heightWill store the value of the map's height
Return values
SC_OKif the size of the density map has been successfully retrieved.
SC_ERRORotherwise
Precondition
UUCS_CreateDensityMap has been previously called and returned SC_OK.

◆ UUCS_GetGroupID()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetGroupID ( int  characterID,
int &  groupID 
)

Retrieves the ID of the group that the specified character belongs to.

Parameters
[in]characterIDThe ID of the character whose group ID is requested.
[out]groupIDA reference to an integer that stores the group ID of the specified character. This DLL will store the current group ID to this integer.
Return values
SC_OKif the group ID of the specified character has been successfully written to the specified memory address.
SC_ERRORotherwise, i.e. if the simulation has not been initialized yet.
Precondition
1. UUCS_PrepareSimulation() has been previously called and returned SC_OK.
2. There exists a character in the simulation with the id specified.
3. The specified character is a group member.
See also
UUCS_PrepareSimulation()
UUCS_AddCharacter()
UUCS_AddCharacterToGroup()

◆ UUCS_GetMajorVersion()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetMajorVersion ( int &  verMajor)

Retrieves the major version of the UUCS API.

Parameters
[out]verMajorA reference to the major version of the UUCS API.
Return values
SC_OKif the major version of the UUCS API was retrieved successfully.
SC_ERRORotherwise.

◆ UUCS_GetMinorVersion()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetMinorVersion ( int &  verMinor)

Retrieves the minor version of the UUCS API.

Parameters
[out]verMinorA reference to the minor version of the UUCS API.
Return values
SC_OKif the minor version of the UUCS API was retrieved successfully.
SC_ERRORotherwise.

◆ UUCS_GetPatchVersion()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetPatchVersion ( int &  verPatch)

Retrieves the patch version of the UUCS API.

Parameters
[out]verPatchA reference to the patch version of the UUCS API.
Return values
SC_OKif the patch version of the UUCS API was retrieved successfully.
SC_ERRORotherwise.

◆ UUCS_GetRandomFreePosition()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetRandomFreePosition ( LayerIndex  layerID,
double  radius,
double  xMin,
double  yMin,
double  xMax,
double  yMax,
double &  x,
double &  y 
)

Finds a random free position on a given layer of the active simulation environment, within the specified axis-aligned bounding box.

Parameters
[in]layerIDThe ID of the layer on which a free position must be found.
[in]radiusThe radius of a disc for which we want to find a free position.
[in]xMinThe minimum x coordinate of the axis-aligned bounding box in which the point should lie.
[in]yMinThe minimum y coordinate of the axis-aligned bounding box in which the point should lie.
[in]xMaxThe maximum x coordinate of the axis-aligned bounding box in which the point should lie.
[in]yMaxThe maximum y coordinate of the axis-aligned bounding box in which the point should lie.
[out]xA reference to the X coordinate of a randomly sampled 2D point (on the specified layer, and in the specified bounding box) that lies at least 'radius' meters away from obstacles.
[out]yA reference to the Y coordinate of a randomly sampled 2D point (on the specified layer, and in the specified bounding box) that lies at least 'radius' meters away from obstacles.
Return values
SC_OKif a free position was successfully found.
SC_ERRORotherwise, i.e. if:
a) there exists no active simulation environment has been loaded yet, or
b) no navigation mesh has been linked to the active simulation environment yet, or
c) sampling on the specified layer and in the specified box bounding box did not detect a point that is at least 'radius' meters away from obstacles.
Precondition
1. Either UUCS_LoadEnvironmentFromFile() or UUCS_LoadEnvironmentFromMemory()has been previously called and returned SC_OK.
2. A navigation mesh has been linked to the active simulation environment, i.e. either UUCS_LoadNavigationMeshFromFile() or UUCS_ComputeNavigationMesh() has been previously called and returned SC_OK.
3. The active simulation environment includes a layer with the specified ID and a position in that layer that is at least 'radius' meters away from obstacles and is within the specified bounding box.

◆ UUCS_GetSimulationTime()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_GetSimulationTime ( double &  simulationTime)

Stores the simulation time in the given memory address.

Parameters
[out]simulationTimeA reference to a double that stores the simulation time. This DLL will store the current simulation time to this double. Your own application will have to read the value and use it properly.
Return values
SC_OKif the simulation time has been successfully written to the specified memory address.
SC_ERRORotherwise, i.e. if:
a) the simulation has not been initialized yet, or
b) a character with the given ID does not exist in the simulation, or
c) the specified character is not a group member
Precondition
UUCS_PrepareSimulation() has been previously called and returned SC_OK.
See also
UUCS_PrepareSimulation()

◆ UUCS_IsDiscFreeOfCharacters()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_IsDiscFreeOfCharacters ( double  x,
double  y,
LayerIndex  layerID,
double  radius,
bool &  free 
)

Checks whether the specified disc does not intersect any obstacles within the active simulation environment.

Parameters
[in]xThe X coordinate of the disc center.
[in]yThe Y coordinate of the disc center.
[in]layerIDThe ID of the layer at which the disc is located.
[in]radiusThe radius of the disc.
[out]freeA reference to a boolean that indicates whether the specified disc does not intersect any characters within the given layer. If the disc does not intersect with any of the characters, its value is set to true.
Return values
SC_OKif the disc was successfully checked for intersections against the characters of the same layer.
SC_ERRORotherwise, i.e. if either there exists no active simulation environment or no navigation mesh has been linked to the active simulation environment yet.

◆ UUCS_IsDiscFreeOfObstacles()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_IsDiscFreeOfObstacles ( double  x,
double  y,
LayerIndex  layerID,
double  radius,
bool &  free 
)

Checks whether the specified disc does not intersect any obstacles within the active simulation environment.

Parameters
[in]xThe X coordinate of the disc center.
[in]yThe Y coordinate of the disc center.
[in]layerIDThe ID of the layer at which the disc is located.
[in]radiusThe radius of the disc. Use 0 to check whether a point is 'free'.
[out]freeA reference to a boolean that indicates whether the specified disc does not intersect any obstacles within the active simulation environment. If the disc center is within the bounds of the active simulation environment and no obstacles intersect the disc, then this parameter is set to 'true'. Otherwise it is set to 'false'.
Return values
SC_OKif the disc was successfully checked for intersections against the obstacles of the active simulation environment.
SC_ERRORotherwise, i.e. if either there exists no active simulation environment or no navigation mesh has been linked to the active simulation environment yet.
Precondition
1. There exists an active simulation environment, i.e. either UUCS_LoadEnvironmentFromFile() or UUCS_LoadEnvironmentFromMemory() has been previously called and returned SC_OK.
2. A navigation mesh has been linked to the active simulation environment, i.e. either UUCS_LoadNavigationMeshFromFile() or UUCS_ComputeNavigationMesh() has been previously called and returned SC_OK.
Postcondition
1. If free was set to be 'true', then no obstacles intersect the specified disc within the active simulation environment.
2. If free was set to be 'false', then at least one obstacle within the active simulation environment intersects the specified disc or the specified disc center is not within the bounds of the active simulation environment.
See also
UUCS_LoadEnvironmentFromFile()
UUCS_LoadEnvironmentFromMemory()
UUCS_LoadNavigationMeshFromFile()
UUCS_ComputeNavigationMesh()

◆ UUCS_LoadCharacterProfiles()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_LoadCharacterProfiles ( const char *  filename)

Loads character profiles from an XML file.

A character profiles file contains one or more named character profiles; each profile contains settings such as the character's radius, preferred speed, and collision avoidance settings.

Call this function after preparing the simulation and before adding any characters. (When adding a character with a certain profile name, the profile with this name should have been loaded already.)

Parameters
[in]filenameThe name (with extension) of the file that stores the character profile(s).
Return values
SC_OKthe profile(s) were successfully loaded from the specified file.
SC_ERRORotherwise.
Precondition
UUCS_PrepareSimulation() has been previously called and returned SC_OK.
Postcondition
It is possible to call UUCS_AddCharacter() using a profile name that is included in the loaded character profiles.
See also
UUCS_AddCharacter()

◆ UUCS_LoadEnvironmentFromFile()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_LoadEnvironmentFromFile ( const char *  filename)

Loads an environment (as an ENV or PRI file) into the program and sets it as the active simulation environment.

Warning
There is only one active simulation environment at a time. If you call this function a second time or call UUCS_LoadEnvironmentFromMemory(), the active simulation environment will be replaced.
Parameters
[in]filenameThe name of the file to load. If the filename has no extension, then the program will try to find an ENV or PRI file (in that order) and accept the first file that was loaded successfully.
Return values
SC_OKif an environment was loaded successfully and was set as the active simulation environment.
SC_ERRORotherwise.
Postcondition
The loaded environment is set to be the active simulation environment.
See also
UUCS_LoadEnvironmentFromMemory()

◆ UUCS_LoadEnvironmentFromMemory()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_LoadEnvironmentFromMemory ( EnvironmentData environmentData)

Loads an environment (as an EnvironmentData struct) into the program and sets it as the active simulation environment.

Warning
There is only one active simulation environment at a time. If you call this function a second time or call UUCS_LoadEnvironmentFromFile(), the active simulation environment will be replaced.
Parameters
[in]environmentDataA pointer to the EnvironmentData to load.
Return values
SC_OKif an environment was loaded successfully and was set as the active simulation environment.
SC_ERRORotherwise.
Postcondition
The loaded environment is set to be the active modelling environment.
See also
UUCS_LoadEnvironmentFromFile()

◆ UUCS_LoadNavigationMeshFromFile()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_LoadNavigationMeshFromFile ( const char *  filename)

Loads a precomputed navigation mesh (as an ECMX or ECM file) into the program.

This navigation mesh will be linked to the active simulation environment. Therefore, you must call UUCS_LoadEnvironmentFromFile() or UUCS_LoadEnvironmentFromMemory() first.

Parameters
[in]filenameThe name of the file to load. If the filename has no extension, then the program will try to find an ECMX or ECM file (in that order) and accept the first file that was loaded successfully.
Return values
SC_OKif a navigation mesh was loaded successfully for the active simulation environment.
SC_ERRORotherwise.
Precondition
There exists an active simulation environment, i.e. UUCS_LoadEnvironmentFromFile() or UUCS_LoadEnvironmentFromMemory() has been previously called and returned SC_OK.
Postcondition
The loaded navigation mesh is linked to the active simulation environment.
See also
UUCS_LoadEnvironmentFromFile()
UUCS_LoadEnvironmentFromMemory()

◆ UUCS_Modelling_AddConnection()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_Modelling_AddConnection ( VertexData3D  endpoint1,
VertexData3D  endpoint2,
LayerIndex  layerID1,
LayerIndex  layerID2,
ConnectionIndex &  connectionID 
)

Adds a connection to the active modelling environment.

Parameters
[in]endpoint1A VertexData3D describing the first endpoint of the connection.
[in]endpoint2A VertexData3D describing the second endpoint of the connection.
[in]layerID1The ID of the first layer to which the connection is associated. This layer is assumed to lie immediately to the left of the line segment from endpoint1 to endpoint2.
[in]layerID2The ID of the second layer to which the connection is associated. This layer is assumed to lie immediately to the right of the line segment from endpoint1 to endpoint2.
[in,out]connectionIDThe desired ID of the connection to add is read from this parameter. The DLL will attempt to add the specified connection using the desired ID. If this parameter is negative, then the DLL will automatically assign a new non-negative ID to the added connection. Upon successfull addition of the connection, its assigned ID is written back to this parameter. If the connection could not be added, this parameter is set to -1. You can use this ID to remove the connection using UUCS_Modelling_RemoveConnection().
Return values
SC_OKif the specified connection was successfully added to the active modelling environment.
SC_ERRORotherwise, i.e. if:
a) there exists no active modelling environment yet, or
b) another connection already exists in the active modelling environment with the specified connection ID
Warning
This function does not check if the layers with IDs layerID1 and layerID2 actually exist. This is a deliberate design choice to give users more flexibility in modelling an environment. For example, you can add a connection between layers that have not yet been created, and removing a layer does not automatically remove the associated connections.
Precondition
1. There exists an active modelling environment, i.e. either UUCS_Modelling_CreateEnvironment() or UUCS_Modelling_LoadEnvironmentFromFile() or UUCS_Modelling_LoadEnvironmentFromMemory() has been previously called and returned SC_OK.
2. There exists no connection in the active modelling environment with connectionID as its ID.
Postcondition
1. The specified connection is added to the active modelling environment.
2. connectionID contains the ID of the added connection.
See also
ConnectionData
UUCS_Modelling_RemoveConnection()
UUCS_Modelling_GetConnection()
UUCS_Modelling_CreateEnvironment()
UUCS_Modelling_LoadEnvironmentFromFile()
UUCS_Modelling_LoadEnvironmentFromMemory()
UUCS_Modelling_SaveEnvironmentToMemory()

◆ UUCS_Modelling_AddLayer()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_Modelling_AddLayer ( LayerIndex &  layerID)

Adds an empty layer to the active modelling environment.

Parameters
[in,out]layerIDThe desired ID of the layer to add is read from this parameter. The DLL will attempt to add the specified layer using the desired ID. If this parameter is negative, then the DLL will automatically assign a new non-negative ID to the added layer. Upon successfull addition of the layer, its assigned ID is written back to this parameter. If the layer could not be added, this parameter is set to -1. You can use this ID to remove the layer using UUCS_Modelling_RemoveLayer().
Return values
SC_OKif the specified layer was successfully added to the active modelling environment.
SC_ERRORotherwise, i.e. if:
a) there exists no active modelling environment yet, or
b) another layer already exists in the active modelling environment with the specified layer ID
Precondition
1. There exists an active modelling environment, i.e. either UUCS_Modelling_CreateEnvironment() or UUCS_Modelling_LoadEnvironmentFromFile() or UUCS_Modelling_LoadEnvironmentFromMemory() has been previously called and returned SC_OK.
2. There exists no layer in the active modelling environment with layerID as its ID.
Postcondition
1. The specified layer is added to the active modelling environment.
2. layerID contains the ID of the added layer.
See also
UUCS_Modelling_RemoveLayer()
UUCS_Modelling_GetLayer()
UUCS_Modelling_CreateEnvironment()
UUCS_Modelling_LoadEnvironmentFromFile()
UUCS_Modelling_LoadEnvironmentFromMemory()
UUCS_Modelling_SaveEnvironmentToMemory()

◆ UUCS_Modelling_AddObstacle()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_Modelling_AddObstacle ( LayerIndex  layerID,
VertexData vertices,
int  numVertices,
PrimitiveIndex &  obstacleID 
)

Adds an obstacle on the specified layer of the active modelling environment.

Warning
Only points, line segments and simple polygons can be added as obstacles.
Parameters
[in]layerIDThe ID of the layer at which the obstacle is added.
[in]verticesAn array that stores all vertices that define the obstacle to add. The vertices can be given in either clockwise or counterclockwise order.
[in]numVerticesThe number of vertices that define the obstacle to add. This parameter should be equal to the length of the vertices array.
[in,out]obstacleIDThe desired ID of the obstacle to add is read from this parameter. The DLL will attempt to add the specified obstacle using the desired ID. If this parameter is negative, then the DLL will automatically assign a new non-negative ID to the added obstacle. Upon successfull addition of the obstacle, its assigned ID is written back to this parameter. If the obstacle could not be added this is set to -1. You can use this ID to remove the obstacle using UUCS_Modelling_RemoveObstacle().
Return values
SC_OKif the specified obstacle was successfully added to the active modelling environment.
SC_ERRORotherwise, i.e. if:
a) there exists no active modelling environment yet, or
b) there exists no layer in the active modelling environment with the specified layer ID, or
c) another obstacle already exists in the active modelling environment with the specified obstacle ID, or
d) the 'vertices' parameter is nullptr, or
e) the 'numVertices' parameter is not positive
Precondition
1. There exists an active modelling environment, i.e. either UUCS_Modelling_CreateEnvironment() or UUCS_Modelling_LoadEnvironmentFromFile() or UUCS_Modelling_LoadEnvironmentFromMemory() has been previously called and returned SC_OK.
2. The active modelling environment includes a layer with layerID as its ID.
3. There exists no obstacle in the active modelling environment with obstacleID as its ID.
4. The 'numVertices' parameter equals the size of the 'vertices' array.
5. The 'vertices' array defines a point or a line segment or a simple polygon whose vertices are provided in either clockwise or counterclockwise order.
Postcondition
1. The specified obstacle is added to the specified layer of the active modelling environment.
2. obstacleID contains the ID of the added obstacle.
3. The bounding box of the active modelling environment is updated to include the added obstacle.
See also
ObstacleData
UUCS_Modelling_RemoveObstacle()
UUCS_Modelling_GetObstacle()
UUCS_Modelling_CreateEnvironment()
UUCS_Modelling_LoadEnvironmentFromFile()
UUCS_Modelling_LoadEnvironmentFromMemory()
UUCS_Modelling_SaveEnvironmentToMemory()

◆ UUCS_Modelling_AddWalkableArea()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_Modelling_AddWalkableArea ( LayerIndex  layerID,
VertexData3D vertices,
int  numVertices,
PrimitiveIndex &  walkableAreaID 
)

Adds a walkable area on the specified layer of the active modelling environment.

Warning
Only simple polygons can be added as walkable areas.
Parameters
[in]layerIDThe ID of the layer at which the walkable area is added.
[in]verticesAn array that stores all vertices that define the walkable area to add. The vertices can be given in either clockwise or counterclockwise order.
[in]numVerticesThe number of vertices that define the walkable areas to add. This parameter should be equal to the length of the vertices array.
[in,out]walkableAreaIDThe desired ID of the walkable area to add is read from this parameter. The DLL will attempt to add the specified walkable area using the desired ID. If this parameter is negative, then the DLL will automatically assign a new non-negative ID to the added walkable area. Upon successfull addition of the walkable area, its assigned ID is written back to this parameter. If the walkable area could not be added this is set to -1. You can use this ID to remove the walkable area using UUCS_Modelling_RemoveWalkableArea().
Return values
SC_OKif the specified walkable area was successfully added to the active modelling environment.
SC_ERRORotherwise, i.e. if:
a) there exists no active modelling environment yet, or
b) there exists no layer in the active modelling environment with the specified layer ID, or
c) another walkable area already exists in the active modelling environment with the specified walkable area ID, or
d) the 'vertices' parameter is nullptr, or
e) the 'numVertices' parameter is not positive
Precondition
1. There exists an active modelling environment, i.e. either UUCS_Modelling_CreateEnvironment() or UUCS_Modelling_LoadEnvironmentFromFile() or UUCS_Modelling_LoadEnvironmentFromMemory() has been previously called and returned SC_OK.
2. The active modelling environment includes a layer with layerID as its ID.
3. There exists no walkable area in the active modelling environment with walkableAreaID as its ID.
4. The 'numVertices' parameter equals the size of the 'vertices' array.
5. The 'vertices' array defines a simple polygon whose vertices are provided in either clockwise or counterclockwise order.
Postcondition
1. The specified walkable area is added to the specified layer of the active modelling environment.
2. walkableAreaID contains the ID of the added walkable area.
3. The bounding box of the active modelling environment is updated to include the added walkable area.
See also
WalkableAreaData
UUCS_Modelling_RemoveWalkableArea()
UUCS_Modelling_GetWalkableArea()
UUCS_Modelling_CreateEnvironment()
UUCS_Modelling_LoadEnvironmentFromFile()
UUCS_Modelling_LoadEnvironmentFromMemory()
UUCS_Modelling_SaveEnvironmentToMemory()

◆ UUCS_Modelling_Cleanup()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_Modelling_Cleanup ( )

Cleans up all modelling-related objects managed by this DLL (i.e. the active modelling environment/layer/obstacle/walkable area/connection).

Call this function when you are about to stop using the program.

◆ UUCS_Modelling_CreateEnvironment()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_Modelling_CreateEnvironment ( const char *  name)

Creates an empty modelling environment with the specified name and sets it as the active modelling environment.

Warning
There is only one active modelling environment at a time. If you call this function a second time or call UUCS_Modelling_LoadEnvironmentFromFile() or UUCS_Modelling_LoadEnvironmentFromMemory(), the active modelling environment will be replaced.
Parameters
[in]nameThe name of the environment to create.
Return values
SC_OKif a modelling environment with the specified name was successfully created.
SC_ERRORotherwise.
Postcondition
The created environment is set to be the active modelling environment.
See also
UUCS_Modelling_LoadEnvironmentFromFile()
UUCS_Modelling_LoadEnvironmentFromMemory()

◆ UUCS_Modelling_GetConvexHull()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_Modelling_GetConvexHull ( VertexData originalVertices,
int  numVertices,
VertexData newVertices,
int &  numNewVertices 
)

Get the convex hull of a polygon.

Warning
You should call this function before adding the obsatcle
Parameters
[in]originalVerticesAn array that stores all original vertices that define the polygon. The vertices can be given in either clockwise or counterclockwise order.
[in]numVerticesThe number of vertices that the polygon has. This parameter should be equal to the length of the vertices array.
[in,out]newVerticesAn array that stores all vertices of the convex hull.
[in,out]numNewVerticesThe number of vertices that the convex hull has.
Return values
SC_OKif getting the convex hull successfully.
SC_ERRORotherwise.

◆ UUCS_Modelling_LoadEnvironmentFromFile()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_Modelling_LoadEnvironmentFromFile ( const char *  filename)

Loads an environment (as an ENV or PRI file) into the program and sets it as the active modelling environment.

Warning
There is only one active modelling environment at a time. If you call this function a second time or call UUCS_Modelling_LoadEnvironmentFromMemory() or UUCS_Modelling_CreateEnvironment(), the active modelling environment will be replaced.
Parameters
[in]filenameThe name of the file to load. If the filename has no extension, then the program will try to find an ENV or PRI file (in that order) and accept the first file that was loaded successfully.
Return values
SC_OKif an environment was loaded successfully and was set as the active modelling environment.
SC_ERRORotherwise.
Postcondition
The loaded environment is set to be the active modelling environment.
See also
UUCS_Modelling_LoadEnvironmentFromMemory()
UUCS_Modelling_CreateEnvironment()

◆ UUCS_Modelling_LoadEnvironmentFromMemory()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_Modelling_LoadEnvironmentFromMemory ( EnvironmentData environmentData)

Loads an environment (as an EnvironmentData struct) into the program and sets it as the active modelling environment.

Warning
There is only one active modelling environment at a time. If you call this function a second time or call UUCS_Modelling_LoadEnvironmentFromFile() or UUCS_Modelling_CreateEnvironment(), the active modelling environment will be replaced.
Parameters
[in]environmentDataA pointer to the EnvironmentData to load.
Return values
SC_OKif an environment was loaded successfully and was set as the active modelling environment.
SC_ERRORotherwise.
Postcondition
The loaded environment is set to be the active modelling environment.
See also
UUCS_Modelling_LoadEnvironmentFromFile()
UUCS_Modelling_CreateEnvironment()

◆ UUCS_Modelling_PolygonSubtract()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_Modelling_PolygonSubtract ( VertexData minuend,
int  numMiunendVertices,
VertexData subtrahend,
int  numSubtractPolygons,
int *  numSubtrahendVertices,
VertexData result,
int &  numResultVertices 
)

Get the difference of a polygon and a list of polygons Can be used to operate obstacle polygons.

Warning
You should call this function before adding the obsatcle
Parameters
[in]minuendAn array that stores all vertices of the minuend polygon.
[in]numMiunendVerticesThe number of vertices that the minuend polygon has. This parameter should be equal to the length of the vertices array.
[in]subtrahendA two-dimensional array that stores all vertices that the subtrahend polygons have.
[in]numSubtractPolygonsThe number of the subtrahend polygons This parameter times numSubtrahendVertices should be equal to the length of the subtrahend vertices array.
[in]numSubtrahendVerticesA list of numbers of vertices corresponding to each subtrahend polygon. This parameter times numSubtractPolygons should be equal to the length of the subtrahend vertices array.
[in,out]resultAn array that stores all vertices of the result triangles Notice: The result is given with triangles, not polygons
[in,out]numResultVerticesThe number of vertices that the result has
Return values
SC_OKif getting the subtraction successfully.
SC_ERRORotherwise.

◆ UUCS_Modelling_PolygonUnion()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_Modelling_PolygonUnion ( VertexData addendList,
int  numAddPolygons,
int *  numaddendListVertices,
VertexData result,
int &  numResultVertices 
)

Get the union of a polygon and a list of polygons Can be used to operate obstacle polygons.

Warning
You should call this function before adding the obsatcle
Parameters
[in]addendListA two-dimensional array that stores all vertices that the addend polygons have.
[in]numAddPolygonsThe number of the addend polygons This parameter times numaddendListVertices should be equal to the length of the addend vertices array.
[in]numaddendListVerticesA list of numbers of vertices corresponding to each addend polygon. This parameter times numAddPolygons should be equal to the length of the addend vertices array.
[in,out]resultAn array that stores all vertices of the result triangles Notice: The result is given with triangles, not polygons
[in,out]numResultVerticesThe number of vertices that the result has
Return values
SC_OKif getting the union successfully.
SC_ERRORotherwise.

◆ UUCS_Modelling_RemoveConnection()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_Modelling_RemoveConnection ( ConnectionIndex  connectionID)

Removes a connection from the active modelling environment.

Parameters
[in]connectionIDThe ID of the connection to remove.
Return values
SC_OKif the specified connection was successfully removed from the active modelling environment.
SC_ERRORotherwise, i.e. if:
a) there exists no active modelling environment yet, or
b) the active modelling environment does not include a connection with the specified connection ID.
Precondition
1. There exists an active modelling environment, i.e. either UUCS_Modelling_LoadEnvironmentFromFile() or UUCS_Modelling_LoadEnvironmentFromMemory() or UUCS_Modelling_CreateEnvironment() has been previously called and returned SC_OK.
2. The active modelling environment includes a connection with connectionID as its ID.
Postcondition
1. The specified connection is removed from the active modelling environment.
See also
ConnectionData
UUCS_Modelling_AddConnection()
UUCS_Modelling_GetConnection()
UUCS_Modelling_CreateEnvironment()
UUCS_Modelling_LoadEnvironmentFromFile()
UUCS_Modelling_LoadEnvironmentFromMemory()
UUCS_SaveEnvironmentToMemory()

◆ UUCS_Modelling_RemoveLayer()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_Modelling_RemoveLayer ( LayerIndex  layerID)

Removes a layer from the active modelling environment.

Parameters
[in]layerIDThe ID of the layer to remove.
Return values
SC_OKif the specified layer was successfully removed from the active modelling environment.
SC_ERRORotherwise, i.e. if:
a) there exists no active modelling environment yet, or
b) the active modelling environment does not include a layer with the specified layer ID.
Warning
Any connections associated to this layer will not be removed. If desired, please remove them by calling UUCS_Modelling_RemoveConnection().
Precondition
1. There exists an active modelling environment, i.e. either UUCS_Modelling_LoadEnvironmentFromFile() or UUCS_Modelling_LoadEnvironmentFromMemory() or UUCS_Modelling_CreateEnvironment() has been previously called and returned SC_OK.
2. The active modelling environment includes a layer with layerID as its ID.
Postcondition
1. The specified layer is removed from the active modelling environment.
2. The bounding box of the active modelling environment is updated to exclude the removed layer.
See also
LayerData
UUCS_Modelling_AddLayer()
UUCS_Modelling_CreateEnvironment()
UUCS_Modelling_LoadEnvironmentFromFile()
UUCS_Modelling_LoadEnvironmentFromMemory()
UUCS_SaveEnvironmentToMemory()

◆ UUCS_Modelling_RemoveObstacle()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_Modelling_RemoveObstacle ( PrimitiveIndex  obstacleID)

Removes an obstacle from the active modelling environment.

Parameters
[in]obstacleIDThe ID of the obstacle to remove.
Return values
SC_OKif the specified obstacle was successfully removed from the active modelling environment.
SC_ERRORotherwise, i.e. if:
a) there exists no active modelling environment yet, or
b) the active modelling environment does not include an obstacle with the specified obstacle ID.
Precondition
1. There exists an active modelling environment, i.e. either UUCS_Modelling_LoadEnvironmentFromFile() or UUCS_Modelling_LoadEnvironmentFromMemory() or UUCS_Modelling_CreateEnvironment() has been previously called and returned SC_OK.
2. The active modelling environment includes an obstacle with obstacleID as its ID.
Postcondition
1. The specified obstacle is removed from the active modelling environment.
2. The bounding box of the active modelling environment is updated to exclude the removed obstacle.
See also
ObstacleData
UUCS_Modelling_AddObstacle()
UUCS_Modelling_GetObstacle()
UUCS_Modelling_CreateEnvironment()
UUCS_Modelling_LoadEnvironmentFromFile()
UUCS_Modelling_LoadEnvironmentFromMemory()
UUCS_SaveEnvironmentToMemory()

◆ UUCS_Modelling_RemoveWalkableArea()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_Modelling_RemoveWalkableArea ( PrimitiveIndex  walkableAreaID)

Removes a walkable area from the active modelling environment.

Parameters
[in]walkableAreaIDThe ID of the walkable area to remove.
Return values
SC_OKif the specified walkable area was successfully removed from the active modelling environment.
SC_ERRORotherwise, i.e. if:
a) there exists no active modelling environment yet, or
b) the active modelling environment does not include an walkable area with the specified walkable area ID.
Precondition
1. There exists an active modelling environment, i.e. either UUCS_Modelling_LoadEnvironmentFromFile() or UUCS_Modelling_LoadEnvironmentFromMemory() or UUCS_Modelling_CreateEnvironment() has been previously called and returned SC_OK.
2. The active modelling environment includes a walkable area with walkableAreaID as its ID.
Postcondition
1. The specified walkable area is removed from the active modelling environment.
2. The bounding box of the active modelling environment is updated to exclude the removed walkable area.
See also
WalkableAreaData
UUCS_Modelling_AddWalkableArea()
UUCS_Modelling_GetWalkableArea()
UUCS_Modelling_CreateEnvironment()
UUCS_Modelling_LoadEnvironmentFromFile()
UUCS_Modelling_LoadEnvironmentFromMemory()
UUCS_Modelling_SaveEnvironmentToMemory()

◆ UUCS_Modelling_SaveEnvironmentToFile()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_Modelling_SaveEnvironmentToFile ( const char *  filename)

Saves the active modelling environment as an ENV or PRI file.

Warning
You should have an active modelling environment before calling this function.
Parameters
[in]filenameThe name of the environment file to create. If the filename has no extension, then the program will add an ENV extension instead.
Return values
SC_OKif the active simulation environment was saved successfully.
SC_ERRORotherwise.
Precondition
There exists an active modelling environment, i.e. UUCS_Modelling_CreateEnvironment() or UUCS_Modelling_LoadEnvironmentFromFile() or UUCS_Modelling_LoadEnvironmentFromMemory() has been previously called and returned SC_OK.
See also
UUCS_Modelling_LoadEnvironmentFromFile()
UUCS_Modelling_LoadEnvironmentFromMemory()

◆ UUCS_Modelling_SaveEnvironmentToMemory()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_Modelling_SaveEnvironmentToMemory ( EnvironmentData *&  environmentData)

Stores the active modelling environment to an EnvironmentData object.

Warning
An active modelling environment must be set before calling this function.
Parameters
[out]environmentDataA reference to an EnvironmentData pointer. Calling this function makes the pointer point to an EnvironmentData object that contains the active modelling environment. Your own application will have to read these values and use them properly. The DLL is responsible for managing the memory of the EnvironmentData object.
Return values
SC_OKif the active modelling environment is successfully pointed by the specified EnvironmentData pointer.
SC_ERRORotherwise, i.e. if there exists no active modelling environment.
Precondition
There exists an active modelling environment, i.e. UUCS_Modelling_CreateEnvironment() or UUCS_Modelling_LoadEnvironmentFromFile() or UUCS_Modelling_LoadEnvironmentFromMemory() has been previously called and returned SC_OK.
See also
UUCS_Modelling_CreateEnvironment()
UUCS_Modelling_LoadEnvironmentFromFile()
UUCS_Modelling_LoadEnvironmentFromMemory()

◆ UUCS_Modelling_SimplifyPolygon()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_Modelling_SimplifyPolygon ( VertexData originalVertices,
int  numVertices,
float  epsilon,
VertexData newVertices,
int &  numNewVertices 
)

Simplify a obstacle polygon.

Warning
You should call this function before adding the obsatcle
Parameters
[in]originalVerticesAn array that stores all original vertices that define the polygon. The vertices can be given in either clockwise or counterclockwise order.
[in]numVerticesThe number of vertices that the polygon has. This parameter should be equal to the length of the vertices array.
[in]epsilonIn Douglas-Peucker algorithm, it represents the maximum distance from a point to the line segment. This number should be bigger than 0.
[in,out]newVerticesAn array that stores all vertices after simplification.
[in,out]numNewVerticesThe number of vertices that the simplified polygon has.
Return values
SC_OKif the polygon is simplified successfully.
SC_ERRORotherwise.

◆ UUCS_PerformTest()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_PerformTest ( int  testID,
int  numCharacters 
)

Performs a simple test scenario.

Parameters
[in]testIDThe ID of the test to run. Possible values explained:
  • If testID is 0, this function adds characters with random start and goal positions. The minimum distance between a character's start and goal positions depends on the size of the active simulation environment.
  • If testID is 1, this function adds characters that move to opposite sides of a circle. The size of the circle depends on the size of the active simulation environment.
  • If testID is 2, this function adds characters that move to opposite sides of a rectangle. The size of the rectangle depends on the size of the active simulation environment.
  • If testID is 3, this function adds groups of characters with random start and goal positions. The distribution of the group sizes is based on the empirical observations of Moussaid et al. 2010.
[in]numCharactersThe number of characters to use in the test.
Warning
If testID is 1 or 2, then this function might add less than the requested number of characters to guarantee a collision free crowd initialization.
Return values
SC_OKif the test was successfully started.
SC_ERRORotherwise, i.e. if the simulation has not yet been initialized.
Precondition
UUCS_PrepareSimulation() has been previously called and returned SC_OK.
See also
UUCS_PrepareSimulation()

◆ UUCS_PrepareSimulation()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_PrepareSimulation ( double  timeStep,
int  seed,
int  nrThreads = 0,
CHARACTER_CONTROL_MODE  defaultCharacterControlMode = CHARACTER_CONTROL_MODE::Internal 
)

Initializes the simulation.

Call this function before performing simulation steps or adding/modifying characters. Also, this function will not work if there exists no active simulation environment or if there exists no navigation mesh linked to the active simulation environment.

Warning
The simulation will not run on its own. Instead, your external program should control when the actual simulation steps are performed, using UUCS_DoSimulationStep().
Parameters
[in]timeStepThe fixed size of a simulation time step (in seconds). A recommended value is 0.1. Every time you call UUCS_DoSimulationStep(), the simulation will advance by this value.
[in]seedA seed for random number generation. Use -1 to generate a different seed each time. Use a non-negative value to use that specific seed; this is useful for repeating experiments.
[in]nrThreadsThe number of parallel threads to use for the simulation. Use 1 to strictly disallow multithreading. Use 0 or less (default) to allow multithreading but to let the system decide how many threads to use.
[in]defaultCharacterControlModeThe default control mode to use for characters in the simulation.
Return values
SC_OKif an active simulation environment and its navigation mesh exist, and the simulation was successfully intialized.
SC_ERRORotherwise.
Precondition
1. There exists an active simulation environment, i.e. UUCS_LoadEnvironmentFromFile() or UUCS_LoadEnvironmentFromMemory() has been previously called and returned SC_OK.
2. A navigation mesh has been linked to the active simulation environment, i.e. either UUCS_LoadNavigationMeshFromFile() or UUCS_ComputeNavigationMesh() has been previously called and returned SC_OK.
See also
UUCS_LoadEnvironmentFromFile()
UUCS_LoadEnvironmentFromMemory()
UUCS_LoadNavigationMeshFromFile()
UUCS_ComputeNavigationMesh()

◆ UUCS_RemoveActivityArea()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_RemoveActivityArea ( int  id)

Removes an ActivityArea from the active simulation.

Parameters
[in]idThe ID of the ActivityArea to remove. This must be equal to the ID generated by UUCS_AddActivityArea(), when the ActivityArea to remove was initially added to the simulation.
Return values
SC_OKif the specified ActivityArea was successfully removed from the simulation.
SC_ERRORotherwise, i.e. if:
a) there exists no active simulation environment yet
Precondition
1. There exists an active simulation environment, i.e. either UUCS_LoadEnvironmentFromFile() or UUCS_LoadEnvironmentFromMemory() has been previously called and returned SC_OK.
2. A navigation mesh has been linked to the active simulation environment, i.e. either UUCS_LoadNavigationMeshFromFile() or UUCS_ComputeNavigationMesh() has been previously called and returned SC_OK.
3. The active simulation environment includes an ActivityArea with id as its ID.
Postcondition
1. The specified ActivityArea is removed from the simulation.

◆ UUCS_RemoveCharacter()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_RemoveCharacter ( int  characterID)

Removes a character from the simulation.

Parameters
[in]characterIDThe ID of the character to remove.
Return values
SC_OKif the character was successfully removed.
SC_ERRORotherwise, i.e. if:
a) the simulation has not been initialized yet, or
b) the character with the given ID does not exist.
Precondition
1. UUCS_PrepareSimulation() has been previously called and returned SC_OK.
2. There exists a character in the simulation with the ID specified.
See also
UUCS_PrepareSimulation()

◆ UUCS_RemoveCharacterFromGroup()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_RemoveCharacterFromGroup ( int  characterID)

Removes a character from a group.

Parameters
[in]characterIDThe ID of the character to remove as a member of a group.
Return values
SC_OKif the character was successfully removed from a group.
SC_ERRORotherwise, i.e. if:
a) the simulation has not been initialized yet, or
b) a character with the given ID does not exists in the simulation, or
c) the character with the given ID is not a member of a group
Precondition
1. UUCS_PrepareSimulation() has been previously called and returned SC_OK.
2. A character with the specified id exists in the simulation.
3. The character with the specified id is a member of a group.
Postcondition
The character with the specified id is no longer a member of the group it belonged to before this call.
See also
UUCS_PrepareSimulation()

◆ UUCS_RemoveDynamicObstacle()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_RemoveDynamicObstacle ( PrimitiveIndex  obstacleID)

Removes a dynamic obstacle from the active simulation environment.

Warning
Dynamic obstacle updates is currently work in progress.
Note
It is only allowed to remove a dynamic obstacle that has already been added to the active simulation environment using UUCS_AddDynamicObstacle().
Warning
Removing a dynamic obstacle stops 'external control' of any character that was set to be 'externally controlled' when that obstacle was added.
Parameters
[in]obstacleIDThe ID of the dynamic obstacle to remove. This must be equal to the obstacle ID generated by UUCS_AddDynamicObstacle(), when the dynamic obstacle to remove was initially added to the active simulation environment.
Return values
SC_OKif the specified dynamic obstacle was successfully removed from the active simulation environment.
SC_ERRORotherwise, i.e. if:
a) there exists no active simulation environment yet, or
b) no navigation mesh has been linked to the active simulation environment yet, or
c) the active simulation environment does not include a dynamic obstacle with the specified obstacle ID.
Precondition
1. There exists an active simulation environment, i.e. either UUCS_LoadEnvironmentFromFile() or UUCS_LoadEnvironmentFromMemory() has been previously called and returned SC_OK.
2. A navigation mesh has been linked to the active simulation environment, i.e. either UUCS_LoadNavigationMeshFromFile() or UUCS_ComputeNavigationMesh() has been previously called and returned SC_OK.
3. The active simulation environment includes a dynamic obstacle with obstacleID as its ID.
Postcondition
1. The specified dynamic obstacle is removed from the active simulation environment.
2. The specified dynamic obstacle is removed from the navigation mesh of the active simulation environment by the end of the next simulation step, i.e. after UUCS_DoSimulationStep() has been called again and returned SC_OK.
3. Any character that intersected the dynamic obstacle that was removed and any other member of that character's group, if any, is set to not be 'externally controlled' by the end of the next simulation step, i.e. after UUCS_DoSimulationStep() has been called again and returned SC_OK.
See also
UUCS_AddDynamicObstacle()
UUCS_LoadEnvironmentFromFile()
UUCS_LoadEnvironmentFromMemory()
UUCS_LoadNavigationMeshFromFile()
UUCS_ComputeNavigationMesh()
UUCS_SaveEnvironmentToMemory()
UUCS_DoSimulationStep()

◆ UUCS_ResetDensityMap()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_ResetDensityMap ( int  id)

Reset a density map, all of the data will be reset to their initial values.

Parameters
[in]idThe ID of the density map which the user wants to clean
Return values
SC_OKif the the density map has been successfully cleaned.
SC_ERRORotherwise,
Precondition
UUCS_CreateDensityMap has been previously called and returned SC_OK.

◆ UUCS_ResetSimulation()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_ResetSimulation ( )

Resets the simulation: removes all characters and sets the simulation time back to 0.

Return values
SC_OKif the simulation was successfully reset.
SC_ERRORotherwise, i.e. if the simulation has not been initialized yet.
Precondition
UUCS_PrepareSimulation() has been previously called and returned SC_OK.
See also
UUCS_PrepareSimulation()

◆ UUCS_SaveEnvironmentToFile()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_SaveEnvironmentToFile ( const char *  filename)

Saves the active simulation environment as an ENV or PRI file.

Warning
You should have an active simulation environment before calling this function.
Parameters
[in]filenameThe name of the environment file to create. If the filename has no extension, then the program will add an ENV extension instead.
Return values
SC_OKif the active simulation environment was saved successfully.
SC_ERRORotherwise.
Precondition
There exists an active simulation environment, i.e. UUCS_LoadEnvironmentFromFile() or UUCS_LoadEnvironmentFromMemory() has been previously called and returned SC_OK.
See also
UUCS_LoadEnvironmentFromFile()
UUCS_LoadEnvironmentFromMemory()

◆ UUCS_SaveEnvironmentToMemory()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_SaveEnvironmentToMemory ( EnvironmentData *&  environmentData)

Stores the active simulation environment to an EnvironmentData object.

Warning
An active simulation environment must be set before calling this function.
Parameters
[out]environmentDataA reference to an EnvironmentData pointer. Calling this function makes the pointer point to an EnvironmentData object that contains the active simulation environment. Your own application will have to read these values and use them properly. The DLL is responsible for managing the memory of the EnvironmentData object.
Return values
SC_OKif the active simulation environment is successfully pointed by the specified EnvironmentData pointer.
SC_ERRORotherwise, i.e. if there exists no active simulation environment.
Precondition
There exists an active simulation environment, i.e. UUCS_LoadEnvironmentFromFile() or UUCS_LoadEnvironmentFromMemory() has been previously called and returned SC_OK.
See also
UUCS_LoadEnvironmentFromFile()
UUCS_LoadEnvironmentFromMemory()

◆ UUCS_SaveNavigationMeshToFile()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_SaveNavigationMeshToFile ( const char *  filename)

Saves the navigation mesh of the active simulation environment as an ECMX or ECM file.

Once you've saved a navigation mesh to a file, you can re-use it the next time so you don't have to recompute it.

This function will not work if there is no active simulation environment, or if the active simulation environment does not yet have a navigation mesh linked to it.

Parameters
[in]filenameThe desired filename of the navigation mesh, in ECMX or ECM format. If the filename has no extension, then the default extension .ecmx will be added automatically.
Return values
SC_OKif an active simulation environment exists, and it has a navigation mesh linked to it, and this navigation mesh was successfully saved.
SC_ERRORotherwise.
Precondition
1. There exists an active simulation environment, i.e. UUCS_LoadEnvironmentFromFile() or UUCS_LoadEnvironmentFromMemory() has been previously called and returned SC_OK.
2. A navigation mesh has been linked to the active simulation environment, i.e. either UUCS_LoadNavigationMeshFromFile() or UUCS_ComputeNavigationMesh() has been previously called and returned SC_OK.
See also
UUCS_LoadEnvironmentFromFile()
UUCS_LoadEnvironmentFromMemory()
UUCS_LoadNavigationMeshFromFile()
UUCS_ComputeNavigationMesh()

◆ UUCS_SetCharacterControlMode()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_SetCharacterControlMode ( int  characterID,
CHARACTER_CONTROL_MODE  newMode 
)

Changes the control mode of a character.

This changes the way in which UUCS determines the character's behaviour. This change will be reflected in the use of UUCS_GetCharacterStepData() and UUCS_SetCharacterStepData().

Parameters
[in]characterIDThe ID of the character to change.
[in]newModeThe desired new control mode of the character.
Return values
SC_OKif the control mode of the character has been successfully changed.
SC_ERRORotherwise, i.e. if the simulation has not been initialized yet or if the specified character ID does not exist.
Precondition
1. UUCS_PrepareSimulation() has been previously called and returned SC_OK.
2. There exists a character in the simulation with the ID specified.
Postcondition
The control mode of the given character has been updated to the specified value.
See also
CHARACTER_CONTROL_MODE
UUCS_PrepareSimulation()
UUCS_GetCharacterStepData()
UUCS_SetCharacterStepData()

◆ UUCS_SetCharacterGoal()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_SetCharacterGoal ( int  characterID,
double  x,
double  y,
LayerIndex  layerID,
double  radius 
)

Sets the goal position of a character in the simulation, and lets the character plan a path towards it.

The character will then start traversing this path in the next simulation step.

Warning
If the character is a group member, then calling this function also updates the goal of the remaining group members.
Parameters
[in]characterIDThe ID of the character.
[in]xThe X coordinate of the character's new goal position.
[in]yThe Y coordinate of the character's new goal position.
[in]layerIDThe ID of the layer on which the character's new goal position is located.
[in]radiusThe radius of the goal position, in meters. The character will stop when it is "radius" meters away from the goal.
Return values
SC_OKif the character has successfully planned a path to the new goal.
SC_ERRORotherwise, i.e. if:
a) the simulation has not been initialized yet, or
b) the character with the given ID does not exist, or
c) there is no obstacle-free path from the character's current position to the specified goal.
Precondition
1. UUCS_PrepareSimulation() has been previously called and returned SC_OK.
2. There exists a character in the simulation with the id specified.
3. There exists an obstacle-free path from the character's current position to the specified goal.
See also
UUCS_PrepareSimulation()
UUCS_GetCharacterGoal()

◆ UUCS_SetCharacterIndicativeRoute()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_SetCharacterIndicativeRoute ( int  characterID,
VertexData path,
int  length 
)

Replaces the indactive route of the character by the given path.

The replanning time is set to 0 such that the given path is not overwritten by the engine. Note: This method takes a list of 2D positions as input, without layer IDs. It will automatically augment the indicative route with layer information.

Parameters
[in]characterIDThe ID of the character whose path will be replaced.
[in]pathReference to the array containing the new indicative route.
[in]lengthLength of the given indicative route.
Return values
SC_OKif the path was set successfully.
SC_ERRORotherwise, i.e. no character corresponds to the given character id.
Precondition

◆ UUCS_SetCharacterParameter_Bool()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_SetCharacterParameter_Bool ( int  characterID,
CHARACTER_PARAMETER  parameter,
bool  value 
)

Updates a character parameter of type "bool" to the specified value.

Parameters
[in]characterIDThe ID of the character whose parameter is to be set.
[in]parameterThe CHARACTER_PARAMETER that describes the character parameter to be updated.
[in]valueThe desired new value of the parameter.
Return values
SC_OKif the character parameter has been successfully updated to the specified value.
SC_ERRORotherwise, i.e. if the simulation has not been initialized yet, or if the character with the specified ID does not exist, or if the specified parameter does not have type "bool".
Precondition
1. UUCS_PrepareSimulation() has been previously called and returned SC_OK.
2. There exists a character in the simulation with the ID specified.
See also
UUCS_PrepareSimulation()

◆ UUCS_SetCharacterParameter_CollisionAvoidanceMethod()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_SetCharacterParameter_CollisionAvoidanceMethod ( int  characterID,
CollisionAvoidanceMethod::Type  value 
)

Updates a character's collision avoidance method to the specified value.

Parameters
[in]characterIDThe ID of the character whose parameter is to be set.
[in]valueThe type of the desired new collision avoidance method.
Return values
SC_OKif the character parameter has been successfully updated to the specified value.
SC_ERRORotherwise, i.e. if the simulation has not been initialized yet, or if the character with the specified ID does not exist.
Precondition
1. UUCS_PrepareSimulation() has been previously called and returned SC_OK.
2. There exists a character in the simulation with the ID specified.
See also
UUCS_PrepareSimulation()

◆ UUCS_SetCharacterParameter_Double()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_SetCharacterParameter_Double ( int  characterID,
CHARACTER_PARAMETER  parameter,
double  value 
)

Updates a character parameter of type "double" to the specified value.

Parameters
[in]characterIDThe ID of the character whose parameter is to be set.
[in]parameterThe CHARACTER_PARAMETER that describes the character parameter to be updated.
[in]valueThe desired new value of the parameter.
Return values
SC_OKif the character parameter has been successfully updated to the specified value.
SC_ERRORotherwise, i.e. if the simulation has not been initialized yet, or if the character with the specified ID does not exist, or if the specified parameter does not have type "double", or if the specified value is not within the allowed range for this parameter.
Precondition
1. UUCS_PrepareSimulation() has been previously called and returned SC_OK.
2. There exists a character in the simulation with the ID specified.
See also
UUCS_PrepareSimulation()

◆ UUCS_SetCharacterParameter_GroupForcesMethod()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_SetCharacterParameter_GroupForcesMethod ( int  characterID,
GroupForcesMethod::Type  value 
)

Updates a character's group forces method to the specified value.

Parameters
[in]characterIDThe ID of the character whose parameter is to be set.
[in]valueThe type of the desired new group forces method.
Return values
SC_OKif the character parameter has been successfully updated to the specified value.
SC_ERRORotherwise, i.e. if the simulation has not been initialized yet, or if the character with the specified ID does not exist.
Precondition
1. UUCS_PrepareSimulation() has been previously called and returned SC_OK.
2. There exists a character in the simulation with the ID specified.
See also
UUCS_PrepareSimulation()

◆ UUCS_SetCharacterParameter_Int()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_SetCharacterParameter_Int ( int  characterID,
CHARACTER_PARAMETER  parameter,
int  value 
)

Updates a character parameter of type "int" to the specified value.

Parameters
[in]characterIDThe ID of the character whose parameter is to be set.
[in]parameterThe CHARACTER_PARAMETER that describes the character parameter to be updated.
[in]valueThe desired new value of the parameter.
Return values
SC_OKif the character parameter has been successfully updated to the specified value.
SC_ERRORotherwise, i.e. if the simulation has not been initialized yet, or if the character with the specified ID does not exist, or if the specified parameter does not have type "int", or if the specified value is not within the allowed range for this parameter.
Precondition
1. UUCS_PrepareSimulation() has been previously called and returned SC_OK.
2. There exists a character in the simulation with the ID specified.
See also
UUCS_PrepareSimulation()

◆ UUCS_SetCharacterParameter_PathFollowingMethod()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_SetCharacterParameter_PathFollowingMethod ( int  characterID,
PathFollowingMethod::Type  value 
)

Updates a character's path following method to the specified value.

Parameters
[in]characterIDThe ID of the character whose parameter is to be set.
[in]valueThe type of the desired new path following method.
Return values
SC_OKif the character parameter has been successfully updated to the specified value.
SC_ERRORotherwise, i.e. if the simulation has not been initialized yet, or if the character with the specified ID does not exist.
Precondition
1. UUCS_PrepareSimulation() has been previously called and returned SC_OK.
2. There exists a character in the simulation with the ID specified.
See also
UUCS_PrepareSimulation()

◆ UUCS_SetCharacterParameter_PathPlanningMethod()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_SetCharacterParameter_PathPlanningMethod ( int  characterID,
PathPlanningMethod::Type  value 
)

Updates a character's path planning method to the specified value.

Parameters
[in]characterIDThe ID of the character whose parameter is to be set.
[in]valueThe type of the desired new path planning method.
Return values
SC_OKif the character parameter has been successfully updated to the specified value.
SC_ERRORotherwise, i.e. if the simulation has not been initialized yet, or if the character with the specified ID does not exist.
Precondition
1. UUCS_PrepareSimulation() has been previously called and returned SC_OK.
2. There exists a character in the simulation with the ID specified.
See also
UUCS_PrepareSimulation()

◆ UUCS_SetCharacterStepData()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_SetCharacterStepData ( CharacterStepData_Position stepData,
int  numEntries 
)

Updates the position and orientation of externally controlled characters according to the specified settings.

Parameters
[in]stepDataA pointer to the beginning of an array (i.e. a memory address) that stores all character positions and orientations that have been computed by the client application. The client application is in charge of managing the memory allocated for this array.
[in]numEntriesThe size of the stepData array, i.e. the number of characters that are described by it.
Note
While a character is 'externally controlled' no forces are applied to it and UUCS does not update its position on its own. Characters which are not externally controlled will try to avoid an externally controlled character and receive physical contact forces in case of a collision.
Warning
This function must be called before each UUCS_DoSimulationStep() call, to ensure that the next simulation step will use the latest details.
Return values
SC_OKif the position and orientation of the externally controlled characters has been successfully updated.
SC_ERRORotherwise, i.e. if the simulation has not been initialized yet or if any of the characters could not be found or is not externally controlled.
Precondition
1. UUCS_PrepareSimulation() has been previously called and returned SC_OK.
2. The characters represented in the stepData array are all externally controlled.
3. The numEntries parameter correctly reflects the number of entries in the stepData array.
Postcondition
1. The position and orientation of the characters represented in the stepData array are updated in the simulation.
2. All characters in the simulation that are not 'externally controlled' will now consider the new positions and orientations of these characters.
See also
UUCS_PrepareSimulation()
UUCS_SetCharacterControlMode()
UUCS_GetCharacterControlMode()

◆ UUCS_SetDensityMapParameter()

UUCSAPI STATUS_CODE UUCS_CALLCONV UUCS_SetDensityMapParameter ( int  id,
DENSITYMAP_PARAMETER  parameter,
double  value 
)

Updates a density map parameter to the specified value.

Parameters
[in]idThe ID of the density map which the user wants to set a parameter
[in]parameterThe DENSITYMAP_PARAMETER that describes the density map parameter to be updated.
[in]valueThe desired new value of the parameter.
Return values
SC_OKif the the density map parameter has been successfully updated to the specified value.
SC_ERRORotherwise,
Precondition
UUCS_CreateDensityMap has been previously called and returned SC_OK.