dali-scene3d/public-api/algorithm/path-finder.h

   1 #ifndef DALI_SCENE3D_PATH_FINDER_H
   2 #define DALI_SCENE3D_PATH_FINDER_H
   3
   4 /*
   5  * Copyright (c) 2023 Samsung Electronics Co., Ltd.
   6
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  */
  19
  20 // INTERNAL INCLUDES
  21 #include <dali-scene3d/public-api/api.h>
  22 #include <dali-scene3d/public-api/algorithm/navigation-mesh.h>
  23 #include <dali-scene3d/public-api/algorithm/path-finder-waypoint.h>
  24
  25 namespace Dali::Scene3D::Algorithm
  26 {
  27
  28 using WayPointList = std::vector<Scene3D::Algorithm::WayPoint>;
  29
  30 /**
  31  * List of enums to be used when not using custom implementation
  32  * of path finding.
  33  */
  34 enum class PathFinderAlgorithm
  35 {
  36   DJIKSTRA_SHORTEST_PATH, ///< Using A* variant (Djikstra) finding a shortest path
  37   DEFAULT = DJIKSTRA_SHORTEST_PATH, ///< Default algorithm to use
  38 };
  39
  40 /**
  41  * @class PathFinderBase
  42  *
  43  * Base class for implementation of pathfinding algorithms.
  44  */
  45 class DALI_SCENE3D_API PathFinderBase
  46 {
  47 public:
  48
  49   /**
  50    * @brief Destructor
  51    */
  52   virtual ~PathFinderBase() = default;
  53
  54   /**
  55    * @brief Looks for a path from point A to point B.
  56    *
  57    * @param[in] positionFrom source position in NavigationMesh parent space
  58    * @param[in] positionTo target position in NavigationMesh parent space
  59    * @return List of waypoints for path or empty vector if no success
  60    */
  61   virtual WayPointList FindPath(const Dali::Vector3& positionFrom, const Dali::Vector3& positionTo) = 0;
  62
  63   /**
  64    * @brief Finds path between NavigationMesh faces
  65    *
  66    * @param[in] polyIndexFrom Index of start polygon
  67    * @param[in] polyIndexTo Index of end polygon
  68    * @return List of waypoints for path or empty vector if no success
  69    */
  70   virtual WayPointList FindPath(uint32_t polyIndexFrom, uint32_t polyIndexTo) = 0;
  71 };
  72
  73 /**
  74  * @class PathFinder
  75  *
  76  * PathFinder runs path finding algorithm on associated NavigationMesh
  77  * and returns a list of waypoints.
  78  */
  79 class DALI_SCENE3D_API PathFinder
  80 {
  81 public:
  82
  83   /**
  84    * @brief Creates new instance of path finder
  85    * @param[in] navigationMesh Navigation mesh to associate with
  86    * @param[in] algorithm algorithm to use
  87    * @return Valid pointer to PathFinder object or nullptr
  88    */
  89   static std::unique_ptr<PathFinder> New( NavigationMesh& navigationMesh, PathFinderAlgorithm algorithm );
  90
  91   /**
  92    * @brief Looks for a path from point A to point B.
  93    *
  94    * The function looks for the path between point A (positionFrom) and B (positionTo). It runs
  95    * the algorithm on the associated NavigationMesh and automatically looks for the floor point.
  96    *
  97    * It will fail if:
  98    * - Any point is outside the navigation mesh
  99    * - The path doesn't exist
 100    *
 101    * Both points should be defined in the same space as is used by the NavigationMesh.
 102    *
 103    * @param[in] positionFrom Source position
 104    * @param[in] positionTo Target position
 105    * @return List of waypoints for path or empty list on failure
 106    */
 107   WayPointList FindPath(const Dali::Vector3& positionFrom, const Dali::Vector3& positionTo);
 108
 109   /**
 110    * @brief Looks for a path between specified NavigationMesh faces
 111    *
 112    * The function looks for the path between given faces (provided as indices).
 113    *
 114    * It will fail if:
 115    * - index < 0 or index > NavigationMesh::GetFaceCount()
 116    * - The path doesn't exist
 117    *
 118    * @param[in] faceIndexFrom Source face index
 119    * @param[in] faceIndexTo Target face index
 120    * @return List of waypoints for path or empty list on failure
 121    */
 122   WayPointList FindPath(uint32_t faceIndexFrom, uint32_t faceIndexTo);
 123
 124 private:
 125
 126   PathFinder() = delete;
 127
 128   DALI_INTERNAL explicit PathFinder(std::unique_ptr<PathFinderBase>&& baseImpl);
 129
 130   std::unique_ptr<PathFinderBase> mImpl;
 131 };
 132
 133 }
 134
 135 #endif // DALI_SCENE3D_PATH_FINDER_H