-#ifndef __DALI_CAMERA_ACTOR_H__
-#define __DALI_CAMERA_ACTOR_H__
+#ifndef DALI_CAMERA_ACTOR_H
+#define DALI_CAMERA_ACTOR_H
/*
- * Copyright (c) 2014 Samsung Electronics Co., Ltd.
+ * Copyright (c) 2023 Samsung Electronics Co., Ltd.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
namespace Dali
{
+/**
+ * @addtogroup dali_core_actors
+ * @{
+ */
namespace Internal DALI_INTERNAL
{
class CameraActor;
}
-
+/**
+ * @brief Enumeration for camera.
+ * @SINCE_1_0.0
+ */
namespace Camera
{
/**
- * @brief Type determines how camera operates.
+ * @brief Enumeration for type determination of how camera operates.
+ * @SINCE_1_0.0
*/
enum Type
{
- FREE_LOOK, ///< Camera orientation is taken from CameraActor
- LOOK_AT_TARGET, ///< Camera is oriented to always look at a target
+ FREE_LOOK, ///< Camera orientation is taken from CameraActor @SINCE_1_0.0
+ LOOK_AT_TARGET, ///< Camera is oriented to always look at a target @SINCE_1_0.0
};
/**
- * @brief Projection modes.
+ * @brief Enumeration for projection modes.
+ * @SINCE_1_0.0
*/
enum ProjectionMode
{
- PERSPECTIVE_PROJECTION, ///< Distance causes foreshortening; objects further from the camera appear smaller
- ORTHOGRAPHIC_PROJECTION, ///< Relative distance from the camera does not affect the size of objects
+ PERSPECTIVE_PROJECTION, ///< Distance causes foreshortening; objects further from the camera appear smaller @SINCE_1_0.0
+ ORTHOGRAPHIC_PROJECTION, ///< Relative distance from the camera does not affect the size of objects @SINCE_1_0.0
};
} // namespace Camera
/**
- * @brief Controls a camera.
+ * @brief CameraActor controls a camera.
*
* Allows the developer to use actor semantics to control a camera.
*
- * There are two types of camera actor, FREE_LOOK and LOOK_AT_TARGET. By default
+ * DALi has a concept of a camera to display its virtual 3D world to a 2D screen.
+ * There are 2 ways of using the camera in DALi:
+ *
+ * - For 2D applications, you do not need to care about the camera at all. The default camera is already best suited for 2D applications
+ * (configured to have the origin of the coordinate system at the top-left corner of the screen, and unit 1 as 1 pixel of the screen).
+ * This is a typical way.
+ *
+ * - For 3D applications, you can change the view by manipulating the camera. If you config some camera properties,
+ * or create camera by @see New3DCamera(), you can translate or rotate the camera whatever you want.
+ * Note that the top-left corner of the screen and unit 1 no longer are (0,0,0) and 1 pixel after manipulating the camera.
+ *
+ * There are two types of camera actor, FREE_LOOK and LOOK_AT_TARGET. By default,
* the camera actor will be FREE_LOOK.
*
- * A FREE_LOOK camera uses actor's rotation to control where the camera is looking.
- * If no additional rotations are specified, the camera looks in the negative Z direction.
+ * - A FREE_LOOK camera uses actor's orientation to control where the camera is looking.
+ * If no additional rotations are specified, the camera looks in the negative Z direction.
*
- * For LOOK_AT_TARGET the actor's rotation is ignored, instead the camera looks at TARGET_POSITION
- * in world coordinates.
+ * - For LOOK_AT_TARGET, the actor's orientation is ignored, instead the camera looks at TARGET_POSITION
+ * in world coordinates.
*
+ * @SINCE_1_0.0
*/
-class DALI_IMPORT_API CameraActor : public Actor
+class DALI_CORE_API CameraActor : public Actor
{
public:
-
/**
- * @brief An enumeration of properties belonging to the CameraActor class.
+ * @brief Enumeration for the instance of properties belonging to the CameraActor class.
+ *
* Properties additional to Actor.
+ * @SINCE_1_0.0
*/
struct Property
{
+ /**
+ * @brief Enumeration for the instance of properties belonging to the CameraActor class.
+ *
+ * Properties additional to Actor.
+ * @SINCE_1_0.0
+ */
enum
{
- Type = DEFAULT_DERIVED_ACTOR_PROPERTY_START_INDEX, ///< name "type", type String
- ProjectionMode, ///< name "projection-mode", type String
- FieldOfView, ///< name "field-of-view", type Float
- AspectRatio, ///< name "aspect-ratio", type Float
- NearPlaneDistance, ///< name "near-plane-distance", type Float
- FarPlaneDistance, ///< name "far-plane-distance", type Float
- LeftPlaneDistance, ///< name "left-plane-distance", type Float
- RightPlaneDistance, ///< name "right-plane-distance", type Float
- TopPlaneDistance, ///< name "top-plane-distance", type Float
- BottomPlaneDistance, ///< name "bottom-plane-distance", type Float
- TargetPosition, ///< name "target-position", type Vector3
- ProjectionMatrix, ///< name "projection-matrix", type Matrix
- ViewMatrix, ///< name "view-matrix", type Matrix
- InvertYAxis, ///< name "invert-y-axis", type Boolean
+ TYPE = DEFAULT_DERIVED_ACTOR_PROPERTY_START_INDEX, ///< name "type", type std::string @SINCE_1_0.0
+ PROJECTION_MODE, ///< name "projectionMode", type std::string @SINCE_1_0.0
+ FIELD_OF_VIEW, ///< name "fieldOfView", type float @SINCE_1_0.0
+ ASPECT_RATIO, ///< name "aspectRatio", type float @SINCE_1_0.0
+ NEAR_PLANE_DISTANCE, ///< name "nearPlaneDistance", type float @SINCE_1_0.0
+ FAR_PLANE_DISTANCE, ///< name "farPlaneDistance", type float @SINCE_1_0.0
+ LEFT_PLANE_DISTANCE, ///< name "leftPlaneDistance", type float @SINCE_1_0.0
+ RIGHT_PLANE_DISTANCE, ///< name "rightPlaneDistance", type float @SINCE_1_0.0
+ TOP_PLANE_DISTANCE, ///< name "topPlaneDistance", type float @SINCE_1_0.0
+ BOTTOM_PLANE_DISTANCE, ///< name "bottomPlaneDistance", type float @SINCE_1_0.0
+ TARGET_POSITION, ///< name "targetPosition", type Vector3 @SINCE_1_0.0
+ PROJECTION_MATRIX, ///< name "projectionMatrix", type Matrix @SINCE_1_0.0
+ VIEW_MATRIX, ///< name "viewMatrix", type Matrix @SINCE_1_0.0
+ INVERT_Y_AXIS, ///< name "invertYAxis", type bool @SINCE_1_0.0
};
};
/**
- * @brief Create an uninitialized CameraActor handle.
+ * @brief Creates an uninitialized CameraActor handle.
*
- * Initialise it using CameraActor::New(). Calling member functions
- * with an uninitialized Dali::Object is not allowed.
+ * Initialize it using CameraActor::New().
+ * Calling member functions with an uninitialized CameraActor handle is not allowed.
+ * @SINCE_1_0.0
*/
CameraActor();
/**
- * @brief Create a CameraActor object.
+ * @brief Creates a CameraActor object.
+ *
+ * @note Sets the default camera perspective projection for the size of the scene this is added to. @see SetPerspectiveProjection().
+ * @note When this actor gets added to a scene, then it's Z position will be modified according to the required perspective projection.
+ * After modified Z position, 1-world-unit become 1-pixel.
*
- * Sets the default camera perspective projection for the stage's size. @see SetPerspectiveProjection().
- * @return the newly created camera actor.
+ * @SINCE_1_0.0
+ * @return The newly created camera actor
*/
static CameraActor New();
/**
- * @brief Create a CameraActor object.
+ * @brief Creates a CameraActor object.
*
* Sets the default camera perspective projection for the given canvas size. @see SetPerspectiveProjection().
*
- * @param[in] size The canvas size.
- * @return the newly created camera actor.
+ * @SINCE_1_0.0
+ * @param[in] size The canvas size
+ * @return The newly created camera actor
+ */
+ static CameraActor New(const Size& size);
+
+ /**
+ * @brief Creates a CameraActor object initialize by 3D parameter.
+ *
+ * Intialize default perspective camera s.t. properties as good to be used on 3D app case.
+ * Default camera positioned at +Z axis, and fit to see 1-world-unit sized cube on world origin.
+ *
+ * @SINCE_2_2.15
+ * @return The newly created camera actor
*/
- static CameraActor New( const Size& size );
+ static CameraActor New3DCamera();
/**
- * @brief Downcast an Object handle to CameraActor.
+ * @brief Downcasts a handle to CameraActor handle.
*
- * If handle points to a CameraActor the downcast produces valid
- * handle. If not the returned handle is left uninitialized.
+ * If handle points to a CameraActor, the downcast produces valid handle.
+ * If not, the returned handle is left uninitialized.
+ * @SINCE_1_0.0
* @param[in] handle to An object
- * @return handle to a CameraActor or an uninitialized handle
+ * @return Handle to a CameraActor or an uninitialized handle
*/
- static CameraActor DownCast( BaseHandle handle );
+ static CameraActor DownCast(BaseHandle handle);
/**
- * @brief Destructor
+ * @brief Destructor.
*
- * This is non-virtual since derived Handle types must not contain data or virtual methods.
+ * This is non-virtual, since derived Handle types must not contain data or virtual methods.
+ * @SINCE_1_0.0
*/
~CameraActor();
/**
- * @brief Copy constructor
+ * @brief Copy constructor.
*
- * @param [in] copy The actor to copy.
+ * @SINCE_1_0.0
+ * @param[in] copy The actor to copy
*/
CameraActor(const CameraActor& copy);
/**
- * @brief Assignment operator
+ * @brief Assignment operator.
*
- * @param [in] rhs The actor to copy.
+ * @SINCE_1_0.0
+ * @param[in] rhs The actor to copy
+ * @return A reference to this
*/
CameraActor& operator=(const CameraActor& rhs);
/**
- * @brief Set the camera type.
+ * @brief Move constructor.
+ *
+ * @SINCE_2_2.4
+ * @param[in] rhs A reference to the actor to move
+ */
+ CameraActor(CameraActor&& rhs);
+
+ /**
+ * @brief Move assignment operator.
+ *
+ * @SINCE_2_2.4
+ * @param[in] rhs A reference to the actor to move
+ * @return A reference to this
+ */
+ CameraActor& operator=(CameraActor&& rhs);
+
+ /**
+ * @brief Sets the camera type.
* The default type is Dali::Camera::FREE_LOOK
+ * @SINCE_1_0.0
* @param[in] type The camera type
*/
- void SetType( Dali::Camera::Type type );
+ void SetType(Dali::Camera::Type type);
/**
- * @brief Get the type of the camera.
+ * @brief Gets the type of the camera.
*
- * @return the type of camera
+ * @SINCE_1_0.0
+ * @return The type of camera
*/
Dali::Camera::Type GetType() const;
/**
- * @brief Set the projection mode.
+ * @brief Sets the projection mode.
*
+ * @SINCE_1_0.0
* @param[in] mode One of PERSPECTIVE_PROJECTION or ORTHOGRAPHIC_PROJECTION
*/
- void SetProjectionMode( Dali::Camera::ProjectionMode mode );
+ void SetProjectionMode(Dali::Camera::ProjectionMode mode);
/**
- * @brief Get the projection mode.
+ * @brief Gets the projection mode.
*
+ * @SINCE_1_0.0
* @return One of PERSPECTIVE_PROJECTION or ORTHOGRAPHIC_PROJECTION
*/
Dali::Camera::ProjectionMode GetProjectionMode() const;
/**
- * @brief Set the field of view.
+ * @brief Sets the field of view.
+ * Field of view will be used when ProjectionMode is PERSPECTIVE_PROJECTION.
*
+ * @SINCE_1_0.0
* @param[in] fieldOfView The field of view in radians
*/
- void SetFieldOfView( float fieldOfView );
+ void SetFieldOfView(float fieldOfView);
/**
- * @brief Get the field of view in Radians.
+ * @brief Gets the field of view in Radians.
*
- * The default field of view is 45 degrees
+ * The default field of view is 45 degrees.
+ * @SINCE_1_0.0
* @return The field of view in radians
*/
- float GetFieldOfView( );
+ float GetFieldOfView();
/**
- * @brief Set the aspect ratio.
+ * @brief Sets the aspect ratio.
*
+ * @SINCE_1_0.0
* @param[in] aspectRatio The aspect ratio
*/
- void SetAspectRatio( float aspectRatio );
+ void SetAspectRatio(float aspectRatio);
/**
- * @brief Get the aspect ratio of the camera.
+ * @brief Gets the aspect ratio of the camera.
*
- * The default aspect ratio is 4.0f/3.0f
- * @return the aspect ratio
+ * The default aspect ratio is 4.0f/3.0f.
+ * @SINCE_1_0.0
+ * @return The aspect ratio
*/
- float GetAspectRatio( );
+ float GetAspectRatio();
/**
* @brief Sets the near clipping plane distance.
*
- * @param[in] nearClippingPlane distance of the near clipping plane
+ * @SINCE_1_0.0
+ * @param[in] nearClippingPlane Distance of the near clipping plane
*/
- void SetNearClippingPlane( float nearClippingPlane );
+ void SetNearClippingPlane(float nearClippingPlane);
/**
- * @brief Get the near clipping plane distance.
+ * @brief Gets the near clipping plane distance.
*
- * The default near clipping plane is 800.0f, to match the default screen height
- * Reduce this value to see objects closer to the camera
- * @return the near clipping plane value
+ * The default near clipping plane is 800.0f, to match the default screen height.
+ * Reduce this value to see objects closer to the camera.
+ * @SINCE_1_0.0
+ * @return The near clipping plane value
*/
- float GetNearClippingPlane( );
+ float GetNearClippingPlane();
/**
* @brief Sets the far clipping plane distance.
*
- * @param[in] farClippingPlane distance of the far clipping plane
+ * @SINCE_1_0.0
+ * @param[in] farClippingPlane Distance of the far clipping plane
*/
- void SetFarClippingPlane( float farClippingPlane );
+ void SetFarClippingPlane(float farClippingPlane);
/**
- * @brief Get the far clipping plane distance.
+ * @brief Gets the far clipping plane distance.
*
- * The default value is the default near clipping plane + (0xFFFF>>4)
- * @return the far clipping plane value
+ * The default value is the default near clipping plane + (0xFFFF>>4).
+ * @SINCE_1_0.0
+ * @return The far clipping plane value
*/
- float GetFarClippingPlane( );
+ float GetFarClippingPlane();
/**
- * @brief Set the target position of the camera.
+ * @brief Sets the target position of the camera.
*
- * @pre Camera type is LOOK_AT_TARGET
+ * @SINCE_1_0.0
* @param[in] targetPosition The position of the target to look at
+ * @pre Camera type is LOOK_AT_TARGET.
*/
- void SetTargetPosition( const Vector3& targetPosition );
+ void SetTargetPosition(const Vector3& targetPosition);
/**
- * @brief Get Camera Target position.
+ * @brief Gets the Camera Target position.
*
- * The target position is Vector3::ZERO
- * @pre Camera type is LOOK_AT_TARGET
+ * The default target position is Vector3::ZERO.
+ * @SINCE_1_0.0
* @return The target position of the camera
+ * @pre Camera type is LOOK_AT_TARGET.
*/
Vector3 GetTargetPosition() const;
/**
- * @brief Request for an inversion on the Y axis on the projection calculation.
+ * @brief Requests for an inversion on the Y axis on the projection calculation.
*
* The default value is not inverted.
+ * @SINCE_1_0.0
* @param[in] invertYAxis True if the Y axis should be inverted
*/
void SetInvertYAxis(bool invertYAxis);
/**
- * @brief Get whether the Y axis is inverted.
+ * @brief Gets whether the Y axis is inverted.
*
- * @return True if the Y axis is inverted, false otherwise
+ * @SINCE_1_0.0
+ * @return @c True if the Y axis is inverted, @c false otherwise
*/
bool GetInvertYAxis();
/**
* @brief Sets the default camera perspective projection for the given canvas size.
*
- * Sets the near and far clipping planes, the field of view, the aspect ratio
+ * Sets the near and far clipping planes, the field of view, the aspect ratio,
* and the Z position of the actor based on the canvas size so that 1 unit in
* XY (z=0) plane is 1 pixel on screen.
+ * Also, It will set orthographic size be fitted as XY plane.
*
- * If the canvas size is ZERO, it sets the default camera perspective
- * projection for the stage's size.
- *
- * @pre If size is non ZERO, \e width and \e height must be greater than zero.
- *
- * @param[in] size The canvas size.
+ * @SINCE_1_0.0
+ * @param[in] size The canvas size
+ * @pre The canvas size must be greater than zero.
+ * @note If either of the values of size is 0.0f, then we use the default perspective projection for the size of the scene this actor is added to.
+ * @note This modifies the Z position property of this actor as well.
*/
- void SetPerspectiveProjection( const Size& size );
+ void SetPerspectiveProjection(const Size& size);
/**
* @brief Sets the camera projection to use orthographic projection.
* bounding box match those that would be created by using
* SetPerspectiveProjection with the same size.
*
+ * @SINCE_1_0.0
* @param[in] size Size of XY plane (normal to camera axis)
*/
- void SetOrthographicProjection( const Size& size );
-
- /**
- * @brief Sets the camera projection to use orthographic projection with the given clip planes.
- *
- * This does not change the Z value of the camera actor.
- *
- * @param[in] left Distance to left clip plane (normal to camera axis)
- * @param[in] right Distance to right clip plane (normal to camera axis)
- * @param[in] top Distance to top clip plane (normal to camera axis)
- * @param[in] bottom Distance to bottom clip plane (normal to camera axis)
- * @param[in] near Distance to the near clip plane (along camera axis)
- * @param[in] far Distance to the far clip plane (along camera axis)
- */
- void SetOrthographicProjection( float left, float right, float top, float bottom, float near, float far );
+ void SetOrthographicProjection(const Size& size);
public: // Not intended for use by Application developers
+ /// @cond internal
/**
- * @brief This constructor is used by Dali New() methods.
+ * @brief This constructor is used by CameraActor::New() methods.
*
- * @param [in] actor A pointer to a newly allocated Dali resource
+ * @SINCE_1_0.0
+ * @param[in] actor A pointer to a newly allocated Dali resource
*/
explicit DALI_INTERNAL CameraActor(Internal::CameraActor* actor);
+ /// @endcond
};
+/**
+ * @}
+ */
} // namespace Dali
-#endif // __DALI_CAMERA_ACTOR_H__
+#endif // DALI_CAMERA_ACTOR_H
projects / platform / core / uifw / dali-core.git / blobdiff