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   PhysicsActor();
  57   ~PhysicsActor();
  58   PhysicsActor(const PhysicsActor& handle);
  59   PhysicsActor(PhysicsActor&& rhs) noexcept;
  60   PhysicsActor& operator=(const PhysicsActor& handle);
  61   PhysicsActor& operator=(PhysicsActor&& handle) noexcept;
  62
  63   /**
  64    * New method.
  65    * @SINCE_2.2.40
  66    *
  67    * Binds the actor to the given body. This should be a body that has
  68    * been added to the physics world, and has physical postion and
  69    * rotation in that space. The Actor is used to render that object in
  70    * DALi space.
  71    *
  72    * @note This object only stores the actor ID, which is used
  73    * internally in the FrameCallback. It is up to the caller to ensure
  74    * there is a reference to the actor (e.g. by parenting into the scene)
  75    *
  76    * @note This API is used internally, and is of little benefit to the developer.
  77    *
  78    * @param[in] actor The DALi actor used to render this object
  79    * @param[in] body The physics body used in the physics simulation
  80    * @param[in] adaptor The physics adaptor to use. @todo remove?
  81    */
  82   static PhysicsActor New(Dali::Actor actor, Dali::Any body, PhysicsAdaptor adaptor);
  83
  84   /**
  85    * @brief Downcasts a handle to PhysicsActor handle.
  86    *
  87    * If handle points to an PhysicsActor object, the downcast produces valid handle.
  88    * If not, the returned handle is left uninitialized.
  89    *
  90    * @SINCE_2.2.40
  91    * @param[in] handle to an object
  92    * @return handle to a PhysicsActor object or an uninitialized handle
  93    */
  94   static PhysicsActor DownCast(BaseHandle handle);
  95
  96   /**
  97    * @brief Get the actor ID of the associated actor.
  98    */
  99   uint32_t GetId() const;
 100
 101   /**
 102    * Using ANY wrapper to enable this interface to be used for any
 103    * types of physics bodies from either 2d or 3d physics.
 104    * @return The physics body. It can be cast to an appropriate type,
 105    * for example:
 106    *   btRigidBody* body = actor.GetBody().Get<btRigidBody*>();
 107    *
 108    * @note Please ensure to get a scoped accessor first to avoid modifying
 109    * physics properties during integration step, or use the Async methods
 110    * or the Queue.
 111    */
 112   Dali::Any GetBody() const;
 113
 114   /**
 115    * Queue a method to set the position on the associated physics body
 116    * in the update thread before the next integration.
 117    * @param[in] actorPosition The position of the actor in DALi space
 118    */
 119   void AsyncSetPhysicsPosition(Dali::Vector3 actorPosition);
 120
 121   /**
 122    * Queue a method to set the rotation of the associated physics body
 123    * in the update thread before the next integration.
 124    * @param[in] actorRotation The orientation of the actor in DALi space
 125    */
 126   void AsyncSetPhysicsRotation(Dali::Quaternion actorRotation);
 127
 128   /**
 129    * Get the current position of the physics body in Physics space.
 130    * @return the current position of the physics body in Physics space.
 131    */
 132   Dali::Vector3 GetPhysicsPosition() const;
 133
 134   /**
 135    * Get the current rotation of the physics body in Physics space.
 136    * @return the current rotation of the physics body in Physics space.
 137    */
 138   Dali::Quaternion GetPhysicsRotation() const;
 139
 140   /**
 141    * Get the current position of the physics body in DALi space.
 142    * @return the current position of the physics body in DALi space.
 143    */
 144   Dali::Vector3 GetActorPosition() const;
 145
 146   /**
 147    * Get the current rotation of the physics body in DALi space.
 148    * @return the current rotation of the physics body in DALi space.
 149    */
 150   Dali::Quaternion GetActorRotation() const;
 151
 152 public: // Not intended for developer use
 153   /// @cond internal
 154   /**
 155    * @note Not intented for application developers
 156    */
 157   explicit DALI_INTERNAL PhysicsActor(Internal::PhysicsActor* impl);
 158   /// @endcond
 159 };
 160
 161 } // namespace Dali::Toolkit::Physics
 162
 163 #endif //DALI_TOOLKIT_PHYSICS_ACTOR_H