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     /// By default, the loaded mesh has its own size and <see cref="PivotPoint"/> inferred from position of vertices.
  39     /// If user set size property, the mesh will be scaled to the input size.
  40     /// Default value of <see cref="ParentOrigin"/> of the Model is Center.
  41     ///
  42     /// The model starts to be loaded synchronously when the Model object is on Window.
  43     /// So, <see cref="GetAnimation(uint)"/> and <see cref="GetAnimation(string)"/> methods should be called after the Model object is added on Window.
  44     /// </remarks>
  45     ///
  46     /// <example>
  47     /// <code>
  48     /// Model model = new Model(modelUrl)
  49     /// {
  50     ///     Size = new Size(width, height),
  51     /// };
  52     /// model.SetImageBasedLightSource(diffuseUrl, specularUrl, scaleFactor);
  53     /// window.Add(model);
  54     ///
  55     /// int animationCount = model.GetAnimationCount();
  56     /// if(animationCount > 0)
  57     /// {
  58     ///     // Play an Animation of index 0.
  59     ///     model.GetAnimation(0).Play();
  60     /// }
  61     /// </code>
  62     /// </example>
  63     /// <since_tizen> 10 </since_tizen>
  64     public class Model : View
  65     {
  66         internal Model(global::System.IntPtr cPtr, bool cMemoryOwn) : base(cPtr, cMemoryOwn)
  67         {
  68         }
  69
  70         /// <summary>
  71         /// Create an initialized Model.
  72         /// </summary>
  73         /// <param name="modelUrl">model file url.(e.g. glTF, and DLI).</param>
  74         /// <param name="resourceDirectoryUrl"> The url to derectory containing resources: binary, image etc.</param>
  75         /// <remarks>
  76         /// If resourceDirectoryUrl is empty, the parent directory url of modelUrl is used for resource url.
  77         ///
  78         /// http://tizen.org/privilege/mediastorage for local files in media storage.
  79         /// http://tizen.org/privilege/externalstorage for local files in external storage.
  80         /// </remarks>
  81         /// <since_tizen> 10 </since_tizen>
  82         public Model(string modelUrl, string resourceDirectoryUrl = "") : this(Interop.Model.ModelNew(modelUrl, resourceDirectoryUrl), true)
  83         {
  84             if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
  85             this.PositionUsesAnchorPoint = true;
  86         }
  87
  88         /// <summary>
  89         /// Copy constructor.
  90         /// </summary>
  91         /// <param name="model">Source object to copy.</param>
  92         /// <since_tizen> 10 </since_tizen>
  93         public Model(Model model) : this(Interop.Model.NewModel(Model.getCPtr(model)), true)
  94         {
  95             if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
  96         }
  97
  98         /// <summary>
  99         /// Assignment operator.
 100         /// </summary>
 101         /// <param name="model">Source object to be assigned.</param>
 102         /// <returns>Reference to this.</returns>
 103         internal Model Assign(Model model)
 104         {
 105             Model ret = new Model(Interop.Model.ModelAssign(SwigCPtr, Model.getCPtr(model)), false);
 106             if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
 107             return ret;
 108         }
 109
 110         /// <summary>
 111         /// Changes Image Based Light according to the given input textures.
 112         /// </summary>
 113         /// <param name="diffuseUrl">The path of Cube map image that will be used as a diffuse IBL source.</param>
 114         /// <param name="specularUrl">The path of Cube map image that will be used as a specular IBL source.</param>
 115         /// <param name="scaleFactor">Scale factor that controls light source intensity in [0.0f, 1.0f]. Default value is 1.0f.</param>
 116         /// <remarks>
 117         /// http://tizen.org/privilege/mediastorage for local files in media storage.
 118         /// http://tizen.org/privilege/externalstorage for local files in external storage.
 119         /// </remarks>
 120         /// <since_tizen> 10 </since_tizen>
 121         public void SetImageBasedLightSource(string diffuseUrl, string specularUrl, float scaleFactor = 1.0f)
 122         {
 123             Interop.Model.SetImageBasedLightSource(SwigCPtr, diffuseUrl, specularUrl, scaleFactor);
 124             if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
 125         }
 126
 127         /// <summary>
 128         /// Gets number of animations that has been loaded from model file.
 129         /// </summary>
 130         /// <remarks>
 131         /// This method should be called after Model load has been finished.
 132         /// </remarks>
 133         /// <returns>The number of loaded animations.</returns>
 134         /// <since_tizen> 10 </since_tizen>
 135         public uint GetAnimationCount()
 136         {
 137             uint ret = Interop.Model.GetAnimationCount(SwigCPtr);
 138             if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
 139             return ret;
 140         }
 141
 142         /// <summary>
 143         /// Gets animation at the index.
 144         /// </summary>
 145         /// <remarks>
 146         /// This method should be called after Model load has been finished.
 147         /// </remarks>
 148         /// <param name="index">Index of animation to be retrieved.</param>
 149         /// <returns>Animation at the index.</returns>
 150         /// <since_tizen> 10 </since_tizen>
 151         public Animation GetAnimation(uint index)
 152         {
 153             Animation ret = new Animation(Interop.Model.GetAnimation(SwigCPtr, index), false);
 154             if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
 155             return ret;
 156         }
 157
 158         /// <summary>
 159         /// Retrieves animation with the given name.
 160         /// Note: This method should be called after Model load finished.
 161         /// </summary>
 162         /// <param name="name">String name of animation to be retrieved.</param>
 163         /// <returns>Animation that has the given name.</returns>
 164         /// <since_tizen> 10 </since_tizen>
 165         public Animation GetAnimation(string name)
 166         {
 167             Animation ret = new Animation(Interop.Model.GetAnimation(SwigCPtr, name), false);
 168             if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
 169             return ret;
 170         }
 171
 172         /// <summary>
 173         /// Retrieves model root Actor.
 174         /// </summary>
 175         /// <returns>Root View of the model.</returns>
 176         // This will be public opened after ACR done. (Before ACR, need to be hidden as Inhouse API)
 177         [EditorBrowsable(EditorBrowsableState.Never)]
 178         private View GetModelRoot()
 179         {
 180             View ret = new View(Interop.Model.GetModelRoot(SwigCPtr), false);
 181             if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
 182             return ret;
 183         }
 184
 185         /// <summary>
 186         /// Release swigCPtr.
 187         /// </summary>
 188         // This will be public opened after ACR done. (Before ACR, need to be hidden as Inhouse API)
 189         [EditorBrowsable(EditorBrowsableState.Never)]
 190         protected override void ReleaseSwigCPtr(global::System.Runtime.InteropServices.HandleRef swigCPtr)
 191         {
 192             Interop.Model.DeleteModel(swigCPtr);
 193         }
 194     }
 195 }