dali-physics/public-api/physics-actor.h

   1 #ifndef DALI_TOOLKIT_PHYSICS_ACTOR_H
   2 #define DALI_TOOLKIT_PHYSICS_ACTOR_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 // EXTERNAL INCLUDES
  21 #include <dali/public-api/actors/actor.h>
  22 #include <dali/public-api/object/any.h>
  23 #include <dali/public-api/object/base-handle.h>
  24
  25 // INTERNAL INCLUDES
  26 #include <dali-toolkit/public-api/dali-toolkit-common.h>
  27
  28 namespace Dali::Toolkit::Physics
  29 {
  30 class PhysicsAdaptor;
  31
  32 namespace Internal
  33 {
  34 class PhysicsActor;
  35 }
  36
  37 /**
  38  * Class to associate a physics body (such as btRigidBody*) with a DALi
  39  * actor for rendering.
  40  *
  41  * This object offers methods to modify basic physics properties
  42  * asynchronously, that is, on the Update thread. It is also possible
  43  * for the developer to queue other physics functions on the body by
  44  * using PhysicsWorld::Queue() and passing in a lambda that captures the
  45  * body.
  46  *
  47  * For example:
  48  *   btRigidBody* body = physicsActor.GetBody().Get<btRigidBody*>();
  49  *   mPhysicsImpl.Queue([body](){ body->clearForces(); });
  50  * This enables the developer to synchronize setting physics properties
  51  * and setting DALi actor properties.
  52  */
  53 class DALI_TOOLKIT_API PhysicsActor : public Dali::BaseHandle
  54 {
  55 public:
  56   /**
  57    * @brief Constructor
  58    *
  59    * @SINCE_2_2.43
  60    */
  61   PhysicsActor();
  62
  63   /**
  64    * @brief Destructor.
  65    *
  66    * @SINCE_2_2.43
  67    * This is non-virtual since derived Handle types must not contain data or virtual methods
  68    */
  69   ~PhysicsActor();
  70
  71   /**
  72    * @brief Copy Constructor.
  73    *
  74    * @SINCE_2_2.43
  75    * @param[in] handle The handle to copy
  76    * @note This creates a new handle, but does not create a new implementation object.
  77    */
  78   PhysicsActor(const PhysicsActor& handle);
  79
  80   /**
  81    * @brief Move Constructor.
  82    *
  83    * @SINCE_2_2.43
  84    * @param[in] handle A reference to the handle to move
  85    */
  86   PhysicsActor(PhysicsActor&& rhs) noexcept;
  87
  88   /**
  89    * @brief Assignment operator.
  90    *
  91    * @SINCE_2_2.43
  92    * @param[in] handle A reference to the handle to move
  93    * @return a reference to this handle
  94    */
  95   PhysicsActor& operator=(const PhysicsActor& handle);
  96
  97   /**
  98    * @brief Move Assignment operator.
  99    *
 100    * @SINCE_2_2.43
 101    * @param[in] handle A reference to the handle to move
 102    * @return a reference to this handle
 103    */
 104   PhysicsActor& operator=(PhysicsActor&& handle) noexcept;
 105
 106   /**
 107    * New method.
 108    * @SINCE_2_2.43
 109    *
 110    * Binds the actor to the given body. This should be a body that has
 111    * been added to the physics world, and has physical postion and
 112    * rotation in that space. The Actor is used to render that object in
 113    * DALi space.
 114    *
 115    * @note This object only stores the actor ID, which is used
 116    * internally in the FrameCallback. It is up to the caller to ensure
 117    * there is a reference to the actor (e.g. by parenting into the scene)
 118    *
 119    * @note This API is used internally, and is of little benefit to the developer.
 120    *
 121    * @param[in] actor The DALi actor used to render this object
 122    * @param[in] body The physics body used in the physics simulation
 123    * @param[in] adaptor The physics adaptor to use. @todo remove?
 124    */
 125   static PhysicsActor New(Dali::Actor actor, Dali::Any body, PhysicsAdaptor adaptor);
 126
 127   /**
 128    * @brief Downcasts a handle to PhysicsActor handle.
 129    *
 130    * If handle points to an PhysicsActor object, the downcast produces valid handle.
 131    * If not, the returned handle is left uninitialized.
 132    *
 133    * @SINCE_2_2.43
 134    * @param[in] handle to an object
 135    * @return handle to a PhysicsActor object or an uninitialized handle
 136    */
 137   static PhysicsActor DownCast(BaseHandle handle);
 138
 139   /**
 140    * @brief Get the actor ID of the associated actor.
 141    *
 142    * @SINCE_2_2.43
 143    */
 144   uint32_t GetId() const;
 145
 146   /**
 147    * @brief Get the actual physics body of this object.
 148    *
 149    * @SINCE_2_2.43
 150    * Using ANY wrapper to enable this interface to be used for any
 151    * types of physics bodies from either 2d or 3d physics.
 152    * @return The physics body. It can be cast to an appropriate type,
 153    * for example:
 154    *   btRigidBody* body = actor.GetBody().Get<btRigidBody*>();
 155    *
 156    * @note Please ensure to get a scoped accessor first to avoid modifying
 157    * physics properties during integration step, or use the Async methods
 158    * or the Queue.
 159    */
 160   Dali::Any GetBody() const;
 161
 162   /**
 163    * @brief Queue a method to set the position on the associated physics body
 164    * in the update thread before the next integration.
 165    *
 166    * @SINCE_2_2.43
 167    * @param[in] actorPosition The position of the actor in DALi space
 168    */
 169   void AsyncSetPhysicsPosition(Dali::Vector3 actorPosition);
 170
 171   /**
 172    * @brief Queue a method to set the rotation of the associated physics body
 173    * in the update thread before the next integration.
 174    *
 175    * @SINCE_2_2.43
 176    * @param[in] actorRotation The orientation of the actor in DALi space
 177    */
 178   void AsyncSetPhysicsRotation(Dali::Quaternion actorRotation);
 179
 180   /**
 181    * @brief Get the current position of the physics body in Physics space.
 182    *
 183    * @SINCE_2_2.43
 184    * @return the current position of the physics body in Physics space.
 185    */
 186   Dali::Vector3 GetPhysicsPosition() const;
 187
 188   /**
 189    * @brief Get the current rotation of the physics body in Physics space.
 190    *
 191    * @SINCE_2_2.43
 192    * @return the current rotation of the physics body in Physics space.
 193    */
 194   Dali::Quaternion GetPhysicsRotation() const;
 195
 196   /**
 197    * @brief Get the current position of the physics body in DALi space.
 198    *
 199    * @SINCE_2_2.43
 200    * @return the current position of the physics body in DALi space.
 201    */
 202   Dali::Vector3 GetActorPosition() const;
 203
 204   /**
 205    * @brief Get the current rotation of the physics body in DALi space.
 206    *
 207    * @SINCE_2_2.43
 208    * @return the current rotation of the physics body in DALi space.
 209    */
 210   Dali::Quaternion GetActorRotation() const;
 211
 212 public: // Not intended for developer use
 213   /// @cond internal
 214   /**
 215    * @brief This constructor is used by PhysicsActor::New() methods.
 216    *
 217    * @SINCE_2_2.43
 218    * @param[in] impl A pointer to a newly allocated Dali resource.
 219    * @note Not intended for application developers
 220    */
 221   explicit DALI_INTERNAL PhysicsActor(Internal::PhysicsActor* impl);
 222   /// @endcond
 223 };
 224
 225 } // namespace Dali::Toolkit::Physics
 226
 227 #endif //DALI_TOOLKIT_PHYSICS_ACTOR_H