src/Tizen.NUI.Scene3D/src/public/Controls/Model.cs

   1 /*
   2  * Copyright(c) 2022 Samsung Electronics Co., Ltd.
   3  *
   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
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  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.
  15  *
  16  */
  17
  18 using System;
  19 using System.Runtime.InteropServices;
  20 using System.ComponentModel;
  21 using Tizen.NUI;
  22 using Tizen.NUI.Binding;
  23 using Tizen.NUI.BaseComponents;
  24
  25 namespace Tizen.NUI.Scene3D
  26 {
  27     /// <summary>
  28     /// Model is a Class to show 3D mesh objects.
  29     /// Model supports glTF 2.0 and DLI model formats.
  30     /// Physically Based Rendering with Image Based Lighting is also supported.
  31     /// </summary>
  32     ///
  33     /// <remarks>
  34     /// Since NUI uses a left-handed coordinate system, loaded models are transformed into a left-handed coordinate system with Y pointing down.
  35     /// The Animations defined in the glTF or DLI are also loaded and can be retrieved by using <see cref="GetAnimation(uint)"/> and <see cref="GetAnimation(string)"/> methods.
  36     /// The number of animation is also retrieved by GetAnimationCount() method.
  37     ///
  38     /// Model also supports Physically Based Rendering(PBR) with Image Based Lighting(IBL).
  39     /// For the IBL, two cube map textures(diffuse and specular) are required.
  40     /// Model supports 4 types layout for Cube Map: Vertical/Horizontal Cross layouts, and Vertical/Horizontal Array layouts.
  41     /// And also, ktx format with cube map is supported.
  42     ///
  43     /// The model and IBL textures start to be loaded asynchronously when the Model object is on Window.
  44     /// ResourcesLoaded signal notifies that the loading of the model and IBL resources have been completed.
  45     /// If Model or IBL is requested to be loaded before the other loading is completed, the ResourcesLoaded signal is called after all resources are loaded.
  46     /// <see cref="GetAnimation(uint)"/> and <see cref="GetAnimation(string)"/> methods can be used after the model loading is finished.
  47     ///
  48     /// By default, the loaded mesh has its own size and <see cref="PivotPoint"/> inferred from position of vertices.
  49     /// The <see cref="PivotPoint"/> can be modified after model loading is finished.
  50     /// If user set size property, the mesh will be scaled to the input size.
  51     /// Default value of <see cref="ParentOrigin"/> of the Model is Center.
  52     /// </remarks>
  53     ///
  54     /// <example>
  55     /// <code>
  56     /// Model model = new Model(modelUrl)
  57     /// {
  58     ///     Size = new Size(width, height),
  59     /// };
  60     /// model.ResourcesLoaded += (s, e) =>
  61     /// {
  62     ///     model.PivotPoint = new Vector3(0.5f, 0.5f, 0.5f); // Use center as a Pivot.
  63     ///
  64     ///     int animationCount = model.GetAnimationCount();
  65     ///     if(animationCount > 0)
  66     ///     {
  67     ///         // Play an Animation of index 0.
  68     ///         model.GetAnimation(0).Play();
  69     ///     }
  70     /// };
  71     /// model.SetImageBasedLightSource(diffuseUrl, specularUrl, scaleFactor);
  72     /// window.Add(model);
  73     ///
  74     /// </code>
  75     /// </example>
  76     /// <since_tizen> 10 </since_tizen>
  77     public class Model : View
  78     {
  79         internal Model(global::System.IntPtr cPtr, bool cMemoryOwn) : base(cPtr, cMemoryOwn)
  80         {
  81         }
  82
  83         /// <summary>
  84         /// Create an initialized Model.
  85         /// </summary>
  86         /// <param name="modelUrl">model file url.(e.g. glTF, and DLI).</param>
  87         /// <param name="resourceDirectoryUrl"> The url to derectory containing resources: binary, image etc.</param>
  88         /// <remarks>
  89         /// If resourceDirectoryUrl is empty, the parent directory url of modelUrl is used for resource url.
  90         ///
  91         /// http://tizen.org/privilege/mediastorage for local files in media storage.
  92         /// http://tizen.org/privilege/externalstorage for local files in external storage.
  93         /// </remarks>
  94         /// <since_tizen> 10 </since_tizen>
  95         public Model(string modelUrl, string resourceDirectoryUrl = "") : this(Interop.Model.ModelNew(modelUrl, resourceDirectoryUrl), true)
  96         {
  97             if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
  98             this.PositionUsesAnchorPoint = true;
  99         }
 100
 101         /// <summary>
 102         /// Copy constructor.
 103         /// </summary>
 104         /// <param name="model">Source object to copy.</param>
 105         /// <since_tizen> 10 </since_tizen>
 106         public Model(Model model) : this(Interop.Model.NewModel(Model.getCPtr(model)), true)
 107         {
 108             if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
 109         }
 110
 111         /// <summary>
 112         /// Assignment operator.
 113         /// </summary>
 114         /// <param name="model">Source object to be assigned.</param>
 115         /// <returns>Reference to this.</returns>
 116         internal Model Assign(Model model)
 117         {
 118             Model ret = new Model(Interop.Model.ModelAssign(SwigCPtr, Model.getCPtr(model)), false);
 119             if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
 120             return ret;
 121         }
 122
 123         /// <summary>
 124         /// Set/Get the ImageBasedLight ScaleFactor.
 125         /// Scale factor controls light source intensity in [0.0f, 1.0f]
 126         /// </summary>
 127         // This will be public opened after ACR done. (Before ACR, need to be hidden as Inhouse API)
 128         [EditorBrowsable(EditorBrowsableState.Never)]
 129         public float ImageBasedLightScaleFactor
 130         {
 131             set
 132             {
 133                 SetImageBasedLightScaleFactor(value);
 134             }
 135             get
 136             {
 137                 return GetImageBasedLightScaleFactor();
 138             }
 139         }
 140
 141         /// <summary>
 142         /// Changes Image Based Light according to the given input textures.
 143         /// </summary>
 144         /// <param name="diffuseUrl">The path of Cube map image that will be used as a diffuse IBL source.</param>
 145         /// <param name="specularUrl">The path of Cube map image that will be used as a specular IBL source.</param>
 146         /// <param name="scaleFactor">Scale factor that controls light source intensity in [0.0f, 1.0f]. Default value is 1.0f.</param>
 147         /// <remarks>
 148         /// http://tizen.org/privilege/mediastorage for local files in media storage.
 149         /// http://tizen.org/privilege/externalstorage for local files in external storage.
 150         /// </remarks>
 151         /// <since_tizen> 10 </since_tizen>
 152         public void SetImageBasedLightSource(string diffuseUrl, string specularUrl, float scaleFactor = 1.0f)
 153         {
 154             Interop.Model.SetImageBasedLightSource(SwigCPtr, diffuseUrl, specularUrl, scaleFactor);
 155             if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
 156         }
 157
 158         /// <summary>
 159         /// Gets number of animations that has been loaded from model file.
 160         /// </summary>
 161         /// <remarks>
 162         /// This method should be called after Model load has been finished.
 163         /// </remarks>
 164         /// <returns>The number of loaded animations.</returns>
 165         /// <since_tizen> 10 </since_tizen>
 166         public uint GetAnimationCount()
 167         {
 168             uint ret = Interop.Model.GetAnimationCount(SwigCPtr);
 169             if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
 170             return ret;
 171         }
 172
 173         /// <summary>
 174         /// Gets animation at the index.
 175         /// </summary>
 176         /// <remarks>
 177         /// This method should be called after Model load has been finished.
 178         /// </remarks>
 179         /// <param name="index">Index of animation to be retrieved.</param>
 180         /// <returns>Animation at the index.</returns>
 181         /// <since_tizen> 10 </since_tizen>
 182         public Animation GetAnimation(uint index)
 183         {
 184             Animation ret = new Animation(Interop.Model.GetAnimation(SwigCPtr, index), false);
 185             if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
 186             return ret;
 187         }
 188
 189         /// <summary>
 190         /// Retrieves animation with the given name.
 191         /// Note: This method should be called after Model load finished.
 192         /// </summary>
 193         /// <param name="name">String name of animation to be retrieved.</param>
 194         /// <returns>Animation that has the given name.</returns>
 195         /// <since_tizen> 10 </since_tizen>
 196         public Animation GetAnimation(string name)
 197         {
 198             Animation ret = new Animation(Interop.Model.GetAnimation(SwigCPtr, name), false);
 199             if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
 200             return ret;
 201         }
 202
 203         /// <summary>
 204         /// Retrieves model root Actor.
 205         /// </summary>
 206         /// <returns>Root View of the model.</returns>
 207         // This will be public opened after ACR done. (Before ACR, need to be hidden as Inhouse API)
 208         [EditorBrowsable(EditorBrowsableState.Never)]
 209         private View GetModelRoot()
 210         {
 211             View ret = new View(Interop.Model.GetModelRoot(SwigCPtr), false);
 212             if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
 213             return ret;
 214         }
 215
 216         /// <summary>
 217         /// Set the ImageBasedLight ScaleFactor.
 218         /// </summary>
 219         /// <param name="scaleFactor">Scale factor that controls light source intensity in [0.0f, 1.0f].</param>
 220         private void SetImageBasedLightScaleFactor(float scaleFactor)
 221         {
 222             Interop.Model.SetImageBasedLightScaleFactor(SwigCPtr, scaleFactor);
 223             if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
 224         }
 225
 226         /// <summary>
 227         /// Get the ImageBasedLight ScaleFactor.
 228         /// </summary>
 229         /// <returns>ImageBasedLightScaleFactor that controls light source intensity.</returns>
 230         private float GetImageBasedLightScaleFactor()
 231         {
 232             float scaleFactor = Interop.Model.GetImageBasedLightScaleFactor(SwigCPtr);
 233             if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
 234             return scaleFactor;
 235         }
 236
 237         /// <summary>
 238         /// Release swigCPtr.
 239         /// </summary>
 240         // This will be public opened after ACR done. (Before ACR, need to be hidden as Inhouse API)
 241         [EditorBrowsable(EditorBrowsableState.Never)]
 242         protected override void ReleaseSwigCPtr(global::System.Runtime.InteropServices.HandleRef swigCPtr)
 243         {
 244             Interop.Model.DeleteModel(swigCPtr);
 245         }
 246     }
 247 }