1 #ifndef __DALI_CAMERA_ACTOR_H__
2 #define __DALI_CAMERA_ACTOR_H__
5 * Copyright (c) 2015 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
38 * @brief Type determines how camera operates.
42 FREE_LOOK, ///< Camera orientation is taken from CameraActor
43 LOOK_AT_TARGET, ///< Camera is oriented to always look at a target
47 * @brief Projection modes.
51 PERSPECTIVE_PROJECTION, ///< Distance causes foreshortening; objects further from the camera appear smaller
52 ORTHOGRAPHIC_PROJECTION, ///< Relative distance from the camera does not affect the size of objects
58 * @brief Controls a camera.
60 * Allows the developer to use actor semantics to control a camera.
62 * There are two types of camera actor, FREE_LOOK and LOOK_AT_TARGET. By default
63 * the camera actor will be FREE_LOOK.
65 * A FREE_LOOK camera uses actor's orientation to control where the camera is looking.
66 * If no additional rotations are specified, the camera looks in the negative Z direction.
68 * For LOOK_AT_TARGET the actor's orientation is ignored, instead the camera looks at TARGET_POSITION
69 * in world coordinates.
72 class DALI_IMPORT_API CameraActor : public Actor
77 * @brief An enumeration of properties belonging to the CameraActor class.
78 * Properties additional to Actor.
84 TYPE = DEFAULT_DERIVED_ACTOR_PROPERTY_START_INDEX, ///< name "type", type std::string
85 PROJECTION_MODE, ///< name "projection-mode", type std::string
86 FIELD_OF_VIEW, ///< name "field-of-view", type float
87 ASPECT_RATIO, ///< name "aspect-ratio", type float
88 NEAR_PLANE_DISTANCE, ///< name "near-plane-distance", type float
89 FAR_PLANE_DISTANCE, ///< name "far-plane-distance", type float
90 LEFT_PLANE_DISTANCE, ///< name "left-plane-distance", type float
91 RIGHT_PLANE_DISTANCE, ///< name "right-plane-distance", type float
92 TOP_PLANE_DISTANCE, ///< name "top-plane-distance", type float
93 BOTTOM_PLANE_DISTANCE, ///< name "bottom-plane-distance", type float
94 TARGET_POSITION, ///< name "target-position", type Vector3
95 PROJECTION_MATRIX, ///< name "projection-matrix", type Matrix
96 VIEW_MATRIX, ///< name "view-matrix", type Matrix
97 INVERT_Y_AXIS, ///< name "invert-y-axis", type bool
102 * @brief Create an uninitialized CameraActor handle.
104 * Initialise it using CameraActor::New(). Calling member functions
105 * with an uninitialized Dali::Object is not allowed.
110 * @brief Create a CameraActor object.
112 * Sets the default camera perspective projection for the stage's size. @see SetPerspectiveProjection().
113 * @return the newly created camera actor.
115 static CameraActor New();
118 * @brief Create a CameraActor object.
120 * Sets the default camera perspective projection for the given canvas size. @see SetPerspectiveProjection().
122 * @param[in] size The canvas size.
123 * @return the newly created camera actor.
125 static CameraActor New( const Size& size );
128 * @brief Downcast an Object handle to CameraActor.
130 * If handle points to a CameraActor the downcast produces valid
131 * handle. If not the returned handle is left uninitialized.
132 * @param[in] handle to An object
133 * @return handle to a CameraActor or an uninitialized handle
135 static CameraActor DownCast( BaseHandle handle );
140 * This is non-virtual since derived Handle types must not contain data or virtual methods.
145 * @brief Copy constructor
147 * @param [in] copy The actor to copy.
149 CameraActor(const CameraActor& copy);
152 * @brief Assignment operator
154 * @param [in] rhs The actor to copy.
156 CameraActor& operator=(const CameraActor& rhs);
159 * @brief Set the camera type.
160 * The default type is Dali::Camera::FREE_LOOK
161 * @param[in] type The camera type
163 void SetType( Dali::Camera::Type type );
166 * @brief Get the type of the camera.
168 * @return the type of camera
170 Dali::Camera::Type GetType() const;
173 * @brief Set the projection mode.
175 * @param[in] mode One of PERSPECTIVE_PROJECTION or ORTHOGRAPHIC_PROJECTION
177 void SetProjectionMode( Dali::Camera::ProjectionMode mode );
180 * @brief Get the projection mode.
182 * @return One of PERSPECTIVE_PROJECTION or ORTHOGRAPHIC_PROJECTION
184 Dali::Camera::ProjectionMode GetProjectionMode() const;
187 * @brief Set the field of view.
189 * @param[in] fieldOfView The field of view in radians
191 void SetFieldOfView( float fieldOfView );
194 * @brief Get the field of view in Radians.
196 * The default field of view is 45 degrees
197 * @return The field of view in radians
199 float GetFieldOfView( );
202 * @brief Set the aspect ratio.
204 * @param[in] aspectRatio The aspect ratio
206 void SetAspectRatio( float aspectRatio );
209 * @brief Get the aspect ratio of the camera.
211 * The default aspect ratio is 4.0f/3.0f
212 * @return the aspect ratio
214 float GetAspectRatio( );
217 * @brief Sets the near clipping plane distance.
219 * @param[in] nearClippingPlane distance of the near clipping plane
221 void SetNearClippingPlane( float nearClippingPlane );
224 * @brief Get the near clipping plane distance.
226 * The default near clipping plane is 800.0f, to match the default screen height
227 * Reduce this value to see objects closer to the camera
228 * @return the near clipping plane value
230 float GetNearClippingPlane( );
233 * @brief Sets the far clipping plane distance.
235 * @param[in] farClippingPlane distance of the far clipping plane
237 void SetFarClippingPlane( float farClippingPlane );
240 * @brief Get the far clipping plane distance.
242 * The default value is the default near clipping plane + (0xFFFF>>4)
243 * @return the far clipping plane value
245 float GetFarClippingPlane( );
248 * @brief Set the target position of the camera.
250 * @pre Camera type is LOOK_AT_TARGET
251 * @param[in] targetPosition The position of the target to look at
253 void SetTargetPosition( const Vector3& targetPosition );
256 * @brief Get Camera Target position.
258 * The target position is Vector3::ZERO
259 * @pre Camera type is LOOK_AT_TARGET
260 * @return The target position of the camera
262 Vector3 GetTargetPosition() const;
265 * @brief Request for an inversion on the Y axis on the projection calculation.
267 * The default value is not inverted.
268 * @param[in] invertYAxis True if the Y axis should be inverted
270 void SetInvertYAxis(bool invertYAxis);
273 * @brief Get whether the Y axis is inverted.
275 * @return True if the Y axis is inverted, false otherwise
277 bool GetInvertYAxis();
280 * @brief Sets the default camera perspective projection for the given canvas size.
282 * Sets the near and far clipping planes, the field of view, the aspect ratio
283 * and the Z position of the actor based on the canvas size so that 1 unit in
284 * XY (z=0) plane is 1 pixel on screen.
286 * If the canvas size is ZERO, it sets the default camera perspective
287 * projection for the stage's size.
289 * @pre If size is non ZERO, \e width and \e height must be greater than zero.
291 * @param[in] size The canvas size.
293 void SetPerspectiveProjection( const Size& size );
296 * @brief Sets the camera projection to use orthographic projection.
298 * The XY plane is centered on the camera axis. The units in the X/Y
299 * plane directly equate to pixels on an equivalently sized
302 * The Z position of the actor, and the near and far clip planes of the
303 * bounding box match those that would be created by using
304 * SetPerspectiveProjection with the same size.
306 * @param[in] size Size of XY plane (normal to camera axis)
308 void SetOrthographicProjection( const Size& size );
311 * @brief Sets the camera projection to use orthographic projection with the given clip planes.
313 * This does not change the Z value of the camera actor.
315 * @param[in] left Distance to left clip plane (normal to camera axis)
316 * @param[in] right Distance to right clip plane (normal to camera axis)
317 * @param[in] top Distance to top clip plane (normal to camera axis)
318 * @param[in] bottom Distance to bottom clip plane (normal to camera axis)
319 * @param[in] near Distance to the near clip plane (along camera axis)
320 * @param[in] far Distance to the far clip plane (along camera axis)
322 void SetOrthographicProjection( float left, float right, float top, float bottom, float near, float far );
324 public: // Not intended for use by Application developers
326 * @brief This constructor is used by Dali New() methods.
328 * @param [in] actor A pointer to a newly allocated Dali resource
330 explicit DALI_INTERNAL CameraActor(Internal::CameraActor* actor);
338 #endif // __DALI_CAMERA_ACTOR_H__