1 #ifndef DALI_CAMERA_ACTOR_H
2 #define DALI_CAMERA_ACTOR_H
5 * Copyright (c) 2023 Samsung Electronics Co., Ltd.
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
21 #include <dali/public-api/actors/actor.h>
26 * @addtogroup dali_core_actors
30 namespace Internal DALI_INTERNAL
36 * @brief Enumeration for camera.
42 * @brief Enumeration for type determination of how camera operates.
47 FREE_LOOK, ///< Camera orientation is taken from CameraActor @SINCE_1_0.0
48 LOOK_AT_TARGET, ///< Camera is oriented to always look at a target @SINCE_1_0.0
52 * @brief Enumeration for projection modes.
57 PERSPECTIVE_PROJECTION, ///< Distance causes foreshortening; objects further from the camera appear smaller @SINCE_1_0.0
58 ORTHOGRAPHIC_PROJECTION, ///< Relative distance from the camera does not affect the size of objects @SINCE_1_0.0
64 * @brief CameraActor controls a camera.
66 * Allows the developer to use actor semantics to control a camera.
68 * DALi has a concept of a camera to display its virtual 3D world to a 2D screen.
69 * There are 2 ways of using the camera in DALi:
71 * - For 2D applications, you do not need to care about the camera at all. The default camera is already best suited for 2D applications
72 * (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).
73 * This is a typical way.
75 * - For 3D applications, you can change the view by manipulating the camera. If you config some camera properties,
76 * or create camera by @see New3DCamera(), you can translate or rotate the camera whatever you want.
77 * 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.
79 * There are two types of camera actor, FREE_LOOK and LOOK_AT_TARGET. By default,
80 * the camera actor will be FREE_LOOK.
82 * - A FREE_LOOK camera uses actor's orientation to control where the camera is looking.
83 * If no additional rotations are specified, the camera looks in the negative Z direction.
85 * - For LOOK_AT_TARGET, the actor's orientation is ignored, instead the camera looks at TARGET_POSITION
86 * in world coordinates.
90 class DALI_CORE_API CameraActor : public Actor
94 * @brief Enumeration for the instance of properties belonging to the CameraActor class.
96 * Properties additional to Actor.
102 * @brief Enumeration for the instance of properties belonging to the CameraActor class.
104 * Properties additional to Actor.
109 TYPE = DEFAULT_DERIVED_ACTOR_PROPERTY_START_INDEX, ///< name "type", type int @SINCE_1_0.0
110 PROJECTION_MODE, ///< name "projectionMode", type int @SINCE_1_0.0
111 FIELD_OF_VIEW, ///< name "fieldOfView", type float @SINCE_1_0.0
112 ASPECT_RATIO, ///< name "aspectRatio", type float @SINCE_1_0.0
113 NEAR_PLANE_DISTANCE, ///< name "nearPlaneDistance", type float @SINCE_1_0.0
114 FAR_PLANE_DISTANCE, ///< name "farPlaneDistance", type float @SINCE_1_0.0
115 LEFT_PLANE_DISTANCE, ///< name "leftPlaneDistance", type float @SINCE_1_0.0
116 RIGHT_PLANE_DISTANCE, ///< name "rightPlaneDistance", type float @SINCE_1_0.0
117 TOP_PLANE_DISTANCE, ///< name "topPlaneDistance", type float @SINCE_1_0.0
118 BOTTOM_PLANE_DISTANCE, ///< name "bottomPlaneDistance", type float @SINCE_1_0.0
119 TARGET_POSITION, ///< name "targetPosition", type Vector3 @SINCE_1_0.0
120 PROJECTION_MATRIX, ///< name "projectionMatrix", type Matrix @SINCE_1_0.0
121 VIEW_MATRIX, ///< name "viewMatrix", type Matrix @SINCE_1_0.0
122 INVERT_Y_AXIS, ///< name "invertYAxis", type bool @SINCE_1_0.0
127 * @brief Creates an uninitialized CameraActor handle.
129 * Initialize it using CameraActor::New().
130 * Calling member functions with an uninitialized CameraActor handle is not allowed.
136 * @brief Creates a CameraActor object.
138 * @note Sets the default camera perspective projection for the size of the scene this is added to. @see SetPerspectiveProjection().
139 * @note When this actor gets added to a scene, then it's Z position will be modified according to the required perspective projection.
140 * After modified Z position, 1-world-unit become 1-pixel.
143 * @return The newly created camera actor
145 static CameraActor New();
148 * @brief Creates a CameraActor object.
150 * Sets the default camera perspective projection for the given canvas size. @see SetPerspectiveProjection().
153 * @param[in] size The canvas size
154 * @return The newly created camera actor
156 static CameraActor New(const Size& size);
159 * @brief Creates a CameraActor object initialize by 3D parameter.
161 * Intialize default perspective camera s.t. properties as good to be used on 3D app case.
162 * Default camera positioned at +Z axis, and fit to see 1-world-unit sized cube on world origin.
165 * @return The newly created camera actor
167 static CameraActor New3DCamera();
170 * @brief Downcasts a handle to CameraActor handle.
172 * If handle points to a CameraActor, the downcast produces valid handle.
173 * If not, the returned handle is left uninitialized.
175 * @param[in] handle to An object
176 * @return Handle to a CameraActor or an uninitialized handle
178 static CameraActor DownCast(BaseHandle handle);
183 * This is non-virtual, since derived Handle types must not contain data or virtual methods.
189 * @brief Copy constructor.
192 * @param[in] copy The actor to copy
194 CameraActor(const CameraActor& copy);
197 * @brief Assignment operator.
200 * @param[in] rhs The actor to copy
201 * @return A reference to this
203 CameraActor& operator=(const CameraActor& rhs);
206 * @brief Move constructor.
209 * @param[in] rhs A reference to the actor to move
211 CameraActor(CameraActor&& rhs) noexcept;
214 * @brief Move assignment operator.
217 * @param[in] rhs A reference to the actor to move
218 * @return A reference to this
220 CameraActor& operator=(CameraActor&& rhs) noexcept;
223 * @brief Sets the camera type.
224 * The default type is Dali::Camera::FREE_LOOK
226 * @param[in] type The camera type
228 void SetType(Dali::Camera::Type type);
231 * @brief Gets the type of the camera.
234 * @return The type of camera
236 Dali::Camera::Type GetType() const;
239 * @brief Sets the projection mode.
242 * @param[in] mode One of PERSPECTIVE_PROJECTION or ORTHOGRAPHIC_PROJECTION
244 void SetProjectionMode(Dali::Camera::ProjectionMode mode);
247 * @brief Gets the projection mode.
250 * @return One of PERSPECTIVE_PROJECTION or ORTHOGRAPHIC_PROJECTION
252 Dali::Camera::ProjectionMode GetProjectionMode() const;
255 * @brief Sets the field of view.
256 * Field of view will be used when ProjectionMode is PERSPECTIVE_PROJECTION.
259 * @param[in] fieldOfView The field of view in radians
261 void SetFieldOfView(float fieldOfView);
264 * @brief Gets the field of view in Radians.
266 * The default field of view is 45 degrees.
268 * @return The field of view in radians
270 float GetFieldOfView();
273 * @brief Sets the aspect ratio.
276 * @param[in] aspectRatio The aspect ratio
278 void SetAspectRatio(float aspectRatio);
281 * @brief Gets the aspect ratio of the camera.
283 * The default aspect ratio is 4.0f/3.0f.
285 * @return The aspect ratio
287 float GetAspectRatio();
290 * @brief Sets the near clipping plane distance.
293 * @param[in] nearClippingPlane Distance of the near clipping plane
295 void SetNearClippingPlane(float nearClippingPlane);
298 * @brief Gets the near clipping plane distance.
300 * The default near clipping plane is 800.0f, to match the default screen height.
301 * Reduce this value to see objects closer to the camera.
303 * @return The near clipping plane value
305 float GetNearClippingPlane();
308 * @brief Sets the far clipping plane distance.
311 * @param[in] farClippingPlane Distance of the far clipping plane
313 void SetFarClippingPlane(float farClippingPlane);
316 * @brief Gets the far clipping plane distance.
318 * The default value is the default near clipping plane + (0xFFFF>>4).
320 * @return The far clipping plane value
322 float GetFarClippingPlane();
325 * @brief Sets the target position of the camera.
328 * @param[in] targetPosition The position of the target to look at
329 * @pre Camera type is LOOK_AT_TARGET.
331 void SetTargetPosition(const Vector3& targetPosition);
334 * @brief Gets the Camera Target position.
336 * The default target position is Vector3::ZERO.
338 * @return The target position of the camera
339 * @pre Camera type is LOOK_AT_TARGET.
341 Vector3 GetTargetPosition() const;
344 * @brief Requests for an inversion on the Y axis on the projection calculation.
346 * The default value is not inverted.
348 * @param[in] invertYAxis True if the Y axis should be inverted
350 void SetInvertYAxis(bool invertYAxis);
353 * @brief Gets whether the Y axis is inverted.
356 * @return @c True if the Y axis is inverted, @c false otherwise
358 bool GetInvertYAxis();
361 * @brief Sets the default camera perspective projection for the given canvas size.
363 * Sets the near and far clipping planes, the field of view, the aspect ratio,
364 * and the Z position of the actor based on the canvas size so that 1 unit in
365 * XY (z=0) plane is 1 pixel on screen.
366 * Also, It will set orthographic size be fitted as XY plane.
369 * @param[in] size The canvas size
370 * @pre The canvas size must be greater than zero.
371 * @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.
372 * @note This modifies the Z position property of this actor as well.
374 void SetPerspectiveProjection(const Size& size);
377 * @brief Sets the camera projection to use orthographic projection.
379 * The XY plane is centered on the camera axis. The units in the X/Y
380 * plane directly equate to pixels on an equivalently sized
383 * The Z position of the actor, and the near and far clip planes of the
384 * bounding box match those that would be created by using
385 * SetPerspectiveProjection with the same size.
388 * @param[in] size Size of XY plane (normal to camera axis)
390 void SetOrthographicProjection(const Size& size);
392 public: // Not intended for use by Application developers
395 * @brief This constructor is used by CameraActor::New() methods.
398 * @param[in] actor A pointer to a newly allocated Dali resource
400 explicit DALI_INTERNAL CameraActor(Internal::CameraActor* actor);
409 #endif // DALI_CAMERA_ACTOR_H