2 * Copyright(c) 2022 Samsung Electronics Co., Ltd.
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
19 using System.Runtime.InteropServices;
20 using System.ComponentModel;
22 using Tizen.NUI.Binding;
23 using Tizen.NUI.BaseComponents;
25 namespace Tizen.NUI.Scene3D
28 /// SceneView is a Class to show multiple 3D objects in a single 2D screen.
29 /// Each SceneView has its own 3D space, and 3D objects added to SceneView are positioned in the space.
30 /// SceneView uses left-handed coordinate system same as NUI. X as right, Y as down, and Z as forward.
32 /// SceneView has internal root container to control inner rendering process like depth test.
33 /// When a View is added to the SceneView with <see cref="View.Add(View)"/> method, it is actually added on the root container.
34 /// Therefore, the added Views exist in the sub tree of SceneView, but are not direct children.
35 /// The sub tree of Views will be rendered with the SceneView's own Camera.
37 /// SceneView has one built-in camera by default.
38 /// The default Camera is not removed by using <see cref="RemoveCamera(Camera)"/> method.
39 /// <see cref="GetCamera(uint)"/> method with index "0" returns the default camera,
40 /// and the minimum value returned by <see cref="GetCameraCount()"/> method is 1.
42 /// SceneView also provides multiple Camera and one of them can be used to render multiple objects.
43 /// <see cref="AddCamera(Camera)"/>, <see cref="RemoveCamera(Camera)"/>, <see cref="GetCamera(uint)"/>,
44 /// and <see cref="SelectCamera(uint)"/> are methods to manage Cameras of the SceneView.
45 /// User can place multiple cameras in a scene to display the entire scene or to display individual objects.
46 /// User can use the <see cref="SelectCamera(uint)"/> method to select the currently required camera.
48 /// When the SceneView's size changes, some camera properties that depend on its size may also change.
49 /// The changing properties are as follows: AspectRatio, LeftPlaneDistance, RightPlaneDistance, TopPlaneDistance, and BottomPlaneDistance.
50 /// The Camera's FieldOfView is vertical fov. The horizontal fov is updated internally according to the SceneView size.
52 /// The <see cref="SetImageBasedLightSource(string, string, float)"/> method sets the same IBL to all Model objects added to the SceneView.
53 /// For the IBL, two cube map textures(diffuse and specular) are required.
54 /// SceneView supports 4 types layout for Cube Map: Vertical/Horizontal Cross layouts, and Vertical/Horizontal Array layouts.
55 /// And also, ktx format with cube map is supported.
56 /// If a model already has an IBL, it is batch overridden with the IBL of the SceneView.
57 /// If the SceneView has IBL, the IBL of newly added models is also overridden.
59 /// The IBL textures start to be loaded asynchronously when <see cref="SetImageBasedLightSource(string, string, float)"/> method is called.
60 /// ResourcesLoaded signal notifies that the loading of the IBL resources have been completed.
62 /// If FBO is used, the rendering result of SceneView is drawn on the FBO and it is mapped on the plane of the SceneView.
63 /// It could decreases performance slightly, but it is useful to show SceneView according to the rendering order with other Views.
65 /// And since SceneView is a View, it can be placed together with other 2D UI components in the NUI window.
67 /// <since_tizen> 10 </since_tizen>
68 public class SceneView : View
70 private bool inCameraTransition = false;
71 private Animation cameraTransition;
72 private string skyboxUrl;
74 internal SceneView(global::System.IntPtr cPtr, bool cMemoryOwn) : base(cPtr, cMemoryOwn)
79 /// Create an initialized SceneView.
81 /// <since_tizen> 10 </since_tizen>
82 public SceneView() : this(Interop.SceneView.SceneNew(), true)
84 if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
90 /// <param name="sceneView">The source object.</param>
91 /// <since_tizen> 10 </since_tizen>
92 public SceneView(SceneView sceneView) : this(Interop.SceneView.NewScene(SceneView.getCPtr(sceneView)), true)
94 if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
98 /// Assignment operator.
100 /// <param name="sceneView">Handle to an object.</param>
101 /// <returns>Reference to this.</returns>
102 internal SceneView Assign(SceneView sceneView)
104 SceneView ret = new SceneView(Interop.SceneView.SceneAssign(SwigCPtr, SceneView.getCPtr(sceneView)), false);
105 if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
110 /// An event emitted when Camera Transition is finished.
112 // This will be public opened after ACR done. (Before ACR, need to be hidden as Inhouse API)
113 [EditorBrowsable(EditorBrowsableState.Never)]
114 public event EventHandler CameraTransitionFinished;
117 /// Set/Get the ImageBasedLight ScaleFactor.
118 /// Scale factor controls light source intensity in [0.0f, 1.0f]
120 /// <since_tizen> 10 </since_tizen>
121 public float ImageBasedLightScaleFactor
125 SetImageBasedLightScaleFactor(value);
129 return GetImageBasedLightScaleFactor();
134 /// Set/Get the UseFramebuffer.
135 /// If this property is true, rendering result of SceneView is drawn on FBO and it is mapping on this SceneView plane.
136 /// If this property is false, each item in SceneView is rendered on window directly.
137 /// Default is false.
140 /// If UseFramebuffer is true, it could decrease performance but entire rendering order is satisfied.
141 /// If UseFramebuffer is false, the performance becomes better but SceneView is rendered on the top of the other 2D components regardless tree order.
143 // This will be public opened after ACR done. (Before ACR, need to be hidden as Inhouse API)
144 [EditorBrowsable(EditorBrowsableState.Never)]
145 public bool UseFramebuffer
149 SetUseFramebuffer(value);
153 return IsUsingFramebuffer();
158 /// Set/Get SkyboxUrl.
159 /// If SkyboxUrl is set, the cube map image is loaded and skybox is attached on scene.
160 /// Skybox texture is asynchronously loaded. When loading is finished, ResourcesLoaded is emitted.
162 // This will be public opened after ACR done. (Before ACR, need to be hidden as Inhouse API)
163 [EditorBrowsable(EditorBrowsableState.Never)]
164 public string SkyboxUrl
177 /// Set/Get Skybox intensity.
178 /// The skybox intensity is multiplied to the color of skybox texture.
179 /// Default value is 1.0f.
181 // This will be public opened after ACR done. (Before ACR, need to be hidden as Inhouse API)
182 [EditorBrowsable(EditorBrowsableState.Never)]
183 public float SkyboxIntensity
187 SetSkyboxIntensity(value);
191 return GetSkyboxIntensity();
196 /// Set/Get angle of orientation of the skybox.
197 /// If orientation is set, the skybox will be rotate by the Radian orientation along YAxis.
198 /// Default value is 0.0f.
200 // This will be public opened after ACR done. (Before ACR, need to be hidden as Inhouse API)
201 [EditorBrowsable(EditorBrowsableState.Never)]
202 public Rotation SkyboxOrientation
206 SetSkyboxOrientation(value);
210 return GetSkyboxOrientation();
215 /// Adds a Camera to the SceneView at the end of the camera list of SceneView.
216 /// The Camera can be used as a selected camera to render the scene by using <see cref="SelectCamera(uint)"/> or <see cref="SelectCamera(string)"/>
218 /// <param name="camera">Camera added on this SceneView.</param>
220 /// Some properties of the Camera will be change depending on the Size of this SceneView.
221 /// Those properties are as follows:
222 /// AspectRatio, LeftPlaneDistance, RightPlaneDistance, TopPlaneDistance, and BottomPlaneDistance.
224 /// The FieldOfView of Camera is for vertical fov.
225 /// When the size of the SceneView is changed, the vertical fov is maintained
226 /// and the horizontal fov is automatically calculated according to the SceneView's AspectRatio.
228 /// <since_tizen> 10 </since_tizen>
229 public void AddCamera(Camera camera)
233 Interop.SceneView.AddCamera(SwigCPtr, camera.SwigCPtr);
234 if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
239 /// Removes a Camera from this SceneView.
240 /// If removed Camera is selected Camera,
241 /// first camera in the list becomes the selected Camera.
243 /// <param name="camera"> camera Camera to be removed from this Camera.</param>
245 /// When Camera.Dispose() is called, the NUI object is disposed, but camera information is maintained internally.
246 /// Therefore, even if Camera.Dispose() is called, RemoveCamera() or RemoveCamera() methods can be used.
247 /// If RemoveCamera() is called too, all information is deleted together.
249 /// <since_tizen> 10 </since_tizen>
250 public void RemoveCamera(Camera camera)
254 Interop.SceneView.RemoveCamera(SwigCPtr, camera.SwigCPtr);
255 if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
260 /// Retrieves the number of cameras.
262 /// <returns>The number of Cameras.</returns>
263 /// <since_tizen> 10 </since_tizen>
264 public uint GetCameraCount()
266 uint count = Interop.SceneView.GetCameraCount(SwigCPtr);
267 if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
272 /// Retrieves a Camera of the index.
274 /// <param name="index"> Index of Camera to be retrieved.</param>
275 /// <returns>Camera of the index.</returns>
276 /// <since_tizen> 10 </since_tizen>
277 public Camera GetCamera(uint index)
279 global::System.IntPtr cPtr = Interop.SceneView.GetCamera(SwigCPtr, index);
280 Camera camera = Registry.GetManagedBaseHandleFromNativePtr(cPtr) as Camera;
283 // Register new camera into Registry.
284 camera = new Camera(cPtr, true);
288 // We found matched NUI camera. Reduce cPtr reference count.
289 HandleRef handle = new HandleRef(this, cPtr);
290 Interop.Camera.DeleteCameraProperty(handle);
291 handle = new HandleRef(null, IntPtr.Zero);
293 if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
298 /// Retrieves a Camera of the input name.
300 /// <param name="name"> string keyword of Camera to be retrieved.</param>
301 /// <returns>Camera that has the name as a View.Name property</returns>
302 /// <since_tizen> 10 </since_tizen>
303 public Camera GetCamera(string name)
305 global::System.IntPtr cPtr = Interop.SceneView.GetCamera(SwigCPtr, name);
306 Camera camera = Registry.GetManagedBaseHandleFromNativePtr(cPtr) as Camera;
309 // Register new camera into Registry.
310 camera = new Camera(cPtr, true);
314 // We found matched NUI camera. Reduce cPtr reference count.
315 HandleRef handle = new HandleRef(this, cPtr);
316 Interop.Camera.DeleteCameraProperty(handle);
317 handle = new HandleRef(null, IntPtr.Zero);
319 if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
324 /// Makes SceneView use a Camera of index as a selected camera.
326 /// <param name="index"> Index of Camera to be used as a selected camera.</param>
327 /// <since_tizen> 10 </since_tizen>
328 public void SelectCamera(uint index)
330 if(inCameraTransition)
334 Interop.SceneView.SelectCamera(SwigCPtr, index);
335 if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
339 /// Makes SceneView use a Camera of a name as a selected camera.
341 /// <param name="name"> string keyword of Camera to be used as a selected camera.</param>
342 /// <since_tizen> 10 </since_tizen>
343 public void SelectCamera(string name)
345 if(inCameraTransition)
349 Interop.SceneView.SelectCamera(SwigCPtr, name);
350 if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
354 /// Starts camera transition from currently selected camera to a camera of index.
355 /// Camera Position, Orientation and FieldOfView are smoothly animated.
358 /// The selected camera is switched when the transition is started.
359 /// During camera transition, Selected Camera cannot be changed by using SelectCamera() or CameraTransition() method.
361 /// <param name="index"> Index of destination Camera of Camera transition.</param>
362 /// <param name="durationMilliSeconds">The duration in milliseconds.</param>
363 /// <param name="alphaFunction">The alpha function to apply.</param>
364 /// <since_tizen> 10 </since_tizen>
365 public void CameraTransition(uint index, int durationMilliSeconds, AlphaFunction alphaFunction = null)
367 if(inCameraTransition)
371 Camera source = GetSelectedCamera();
373 Camera destination = GetSelectedCamera();
374 CameraTransition(source, destination, durationMilliSeconds, alphaFunction);
376 destination.Dispose();
380 /// Starts camera transition from currently selected camera to a camera of input name.
381 /// Camera Position, Orientation and FieldOfView are smoothly animated.
384 /// The selected camera is switched when the transition is started.
385 /// During camera transition, Selected Camera cannot be changed by using SelectCamera() or CameraTransition() method.
387 /// <param name="name"> string keyword of destination Camera of Camera transition.</param>
388 /// <param name="durationMilliSeconds">The duration in milliseconds.</param>
389 /// <param name="alphaFunction">The alpha function to apply.</param>
390 /// <since_tizen> 10 </since_tizen>
391 public void CameraTransition(string name, int durationMilliSeconds, AlphaFunction alphaFunction = null)
393 if(inCameraTransition)
397 Camera source = GetSelectedCamera();
399 Camera destination = GetSelectedCamera();
400 CameraTransition(source, destination, durationMilliSeconds, alphaFunction);
402 destination.Dispose();
406 /// Retrieves selected Camera.
408 /// <returns> Camera currently used in SceneView as a selected Camera.</returns>
409 /// <since_tizen> 10 </since_tizen>
410 public Camera GetSelectedCamera()
412 global::System.IntPtr cPtr = Interop.SceneView.GetSelectedCamera(SwigCPtr);
413 Camera camera = Registry.GetManagedBaseHandleFromNativePtr(cPtr) as Camera;
416 // Register new camera into Registry.
417 camera = new Camera(cPtr, true);
421 // We found matched NUI camera. Reduce cPtr reference count.
422 HandleRef handle = new HandleRef(this, cPtr);
423 Interop.Camera.DeleteCameraProperty(handle);
424 handle = new HandleRef(null, IntPtr.Zero);
426 if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
431 /// Changes Image Based Light as the input textures.
433 /// <param name="diffuseUrl">The path of Cube map image that can be used as a diffuse IBL source.</param>
434 /// <param name="specularUrl">The path of Cube map image that can be used as a specular IBL source.</param>
435 /// <param name="scaleFactor">Scale factor that controls light source intensity in [0.0f, 1.0f]. Default value is 1.0f.</param>
437 /// http://tizen.org/privilege/mediastorage for local files in media storage.
438 /// http://tizen.org/privilege/externalstorage for local files in external storage.
440 /// <since_tizen> 10 </since_tizen>
441 public void SetImageBasedLightSource(string diffuseUrl, string specularUrl, float scaleFactor = 1.0f)
443 Interop.SceneView.SetImageBasedLightSource(SwigCPtr, diffuseUrl, specularUrl, scaleFactor);
444 if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
447 internal void SetUseFramebuffer(bool useFramebuffer)
449 Interop.SceneView.UseFramebuffer(SwigCPtr, useFramebuffer);
450 if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
453 internal bool IsUsingFramebuffer()
455 bool result = Interop.SceneView.IsUsingFramebuffer(SwigCPtr);
456 if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
461 /// Set the ImageBasedLight ScaleFactor.
463 /// <param name="scaleFactor">Scale factor that controls light source intensity in [0.0f, 1.0f].</param>
464 private void SetImageBasedLightScaleFactor(float scaleFactor)
466 Interop.SceneView.SetImageBasedLightScaleFactor(SwigCPtr, scaleFactor);
467 if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
471 /// Get the ImageBasedLight ScaleFactor.
473 /// <returns>ImageBasedLightScaleFactor that controls light source intensity.</returns>
474 private float GetImageBasedLightScaleFactor()
476 float scaleFactor = Interop.SceneView.GetImageBasedLightScaleFactor(SwigCPtr);
477 if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
482 /// Set the Skybox from cube map image.
483 /// Skybox texture is asynchronously loaded. When loading is finished, ResourcesLoaded is emitted.
485 /// <param name="skyboxUrl">Cube map image url for skybox.</param>
486 private void SetSkybox(string skyboxUrl)
488 this.skyboxUrl = skyboxUrl;
489 Interop.SceneView.SetSkybox(SwigCPtr, skyboxUrl);
490 if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
494 /// Sets Skybox intensity.
495 /// The skybox intensity is multiplied to the color of skybox texture.
496 /// Default value is 1.0f.
498 /// <param name="intensity">Intensity value to be multiplied to the cube map color.</param>
499 private void SetSkyboxIntensity(float intensity)
501 Interop.SceneView.SetSkyboxIntensity(SwigCPtr, intensity);
502 if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
506 /// Gets Skybox intensity.
507 /// Default value is 1.0f.
509 /// <returns>skybox intensity.</returns>
510 private float GetSkyboxIntensity()
512 float intensity = Interop.SceneView.GetSkyboxIntensity(SwigCPtr);
513 if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
518 /// Sets orientation of the skybox.
520 /// <param name="orientation">Rotation angle of the skybox along YAxis.</param>
521 private void SetSkyboxOrientation(Rotation orientation)
523 Interop.SceneView.SetSkyboxOrientation(SwigCPtr, Rotation.getCPtr(orientation));
524 if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
528 /// Gets Skybox orientation.
530 /// <returns>skybox orientation.</returns>
531 private Rotation GetSkyboxOrientation()
533 global::System.IntPtr cPtr = Interop.SceneView.GetSkyboxOrientation(SwigCPtr);
534 Rotation ret = (cPtr == global::System.IntPtr.Zero) ? null : new Rotation(cPtr, false);
535 if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
539 private void CameraTransition(Camera sourceCamera, Camera destinationCamera, int durationMilliSeconds, AlphaFunction alphaFunction)
541 inCameraTransition = true;
543 Position sourcePosition = sourceCamera.Position;
544 Rotation sourceOrientation = sourceCamera.Orientation;
546 Position destinationPosition = destinationCamera.Position;
547 Rotation destinationOrientation = destinationCamera.Orientation;
549 cameraTransition = new Animation(durationMilliSeconds);
551 KeyFrames positionKeyFrames = new KeyFrames();
552 positionKeyFrames.Add(0.0f, sourcePosition);
553 positionKeyFrames.Add(1.0f, destinationPosition);
555 KeyFrames orientationKeyFrames = new KeyFrames();
556 orientationKeyFrames.Add(0.0f, sourceOrientation);
557 orientationKeyFrames.Add(1.0f, destinationOrientation);
559 cameraTransition.AnimateBetween(destinationCamera, "Position", positionKeyFrames, Animation.Interpolation.Linear, alphaFunction);
560 cameraTransition.AnimateBetween(destinationCamera, "Orientation", orientationKeyFrames, Animation.Interpolation.Linear, alphaFunction);
562 if(destinationCamera.ProjectionMode == Camera.ProjectionModeType.Perspective)
564 Radian sourceFieldOfView = sourceCamera.FieldOfView;
565 Radian destinationFieldOfView = destinationCamera.FieldOfView;
567 // If ProjectionDirection is not equal, match the value.
568 if (sourceCamera.ProjectionDirection != destinationCamera.ProjectionDirection)
570 float aspect = destinationCamera.AspectRatio;
571 if (destinationCamera.ProjectionDirection == Camera.ProjectionDirectionType.Vertical)
573 sourceFieldOfView = Camera.ConvertFovFromHorizontalToVertical(aspect, sourceFieldOfView);
577 sourceFieldOfView = Camera.ConvertFovFromVerticalToHorizontal(aspect, sourceFieldOfView);
581 KeyFrames fieldOfViewKeyFrames = new KeyFrames();
582 fieldOfViewKeyFrames.Add(0.0f, sourceFieldOfView.ConvertToFloat());
583 fieldOfViewKeyFrames.Add(1.0f, destinationFieldOfView.ConvertToFloat());
584 cameraTransition.AnimateBetween(destinationCamera, "FieldOfView", fieldOfViewKeyFrames, Animation.Interpolation.Linear, alphaFunction);
586 sourceFieldOfView.Dispose();
587 destinationFieldOfView.Dispose();
588 fieldOfViewKeyFrames.Dispose();
592 float sourceOrthographicSize = sourceCamera.OrthographicSize;
593 float destinationOrthographicSize = destinationCamera.OrthographicSize;
595 // If ProjectionDirection is not equal, match the value.
596 if (sourceCamera.ProjectionDirection != destinationCamera.ProjectionDirection)
598 float aspect = destinationCamera.AspectRatio;
599 if (destinationCamera.ProjectionDirection == Camera.ProjectionDirectionType.Vertical)
601 sourceOrthographicSize = sourceOrthographicSize / aspect;
605 sourceOrthographicSize = sourceOrthographicSize * aspect;
609 KeyFrames orthographicSizeKeyFrames = new KeyFrames();
610 orthographicSizeKeyFrames.Add(0.0f, sourceOrthographicSize);
611 orthographicSizeKeyFrames.Add(1.0f, destinationOrthographicSize);
612 cameraTransition.AnimateBetween(destinationCamera, "OrthographicSize", orthographicSizeKeyFrames, Animation.Interpolation.Linear, alphaFunction);
614 orthographicSizeKeyFrames.Dispose();
617 cameraTransition.Finished += (s, e) =>
619 inCameraTransition = false;
620 CameraTransitionFinished?.Invoke(this, EventArgs.Empty);
622 cameraTransition.Play();
624 positionKeyFrames.Dispose();
625 orientationKeyFrames.Dispose();
629 /// Release swigCPtr.
631 // This will be public opened after ACR done. (Before ACR, need to be hidden as Inhouse API)
632 [EditorBrowsable(EditorBrowsableState.Never)]
633 protected override void ReleaseSwigCPtr(global::System.Runtime.InteropServices.HandleRef swigCPtr)
635 Interop.SceneView.DeleteScene(swigCPtr);