[unity] Added example component `SkeletonRenderTextureFadeout` and improved example scene and documentation. See #1337.

CHANGELOG.md

@@ -164,6 +164,7 @@
   * Timeline naming improvements: `Spine AnimationState Clip` Inspector parameter `Custom Duration` changed and inverted to `Default Mix Duration` for more clarity. Shortened all Timeline add track menu entries from: `Spine.Unity.Playables - <track type>` to `Spine - <track type>`, `Spine Animation State Track` to `SkeletonAnimation Track`, `Spine AnimationState Graphic Track` to `SkeletonGraphic Track`, and `Spine Skeleton Flip Track` to `Skeleton Flip Track`.
   * Timeline track appearance and Inspector: Tracks now show icons and track colors to make them easier to distinguish. When a Track is selected, the Inspector now shows an editable track name which was previously only editable at the Timeline asset.
   * Added example component `SkeletonRenderTexture` to render a `SkeletonRenderer` to a `RenderTexture`, mainly for proper transparency. Added an example scene named `RenderTexture FadeOut Transparency` that demonstrates usage for a fadeout transparency effect.
+  * Added another fadeout example component named `SkeletonRenderTextureFadeout` which takes over transparency fadeout when enabled. You can use this component as-is, attach it in disabled state and enable it to start a fadeout effect.
 
 * **Changes of default values**
 

spine-unity/Assets/Spine Examples/Other Examples/RenderTexture FadeOut Transparency.unity

@@ -392,8 +392,10 @@ MonoBehaviour:
     m_HorizontalOverflow: 1
     m_VerticalOverflow: 1
     m_LineSpacing: 1
-  m_Text: "Enter play mode to see the problem of conventional alpha transparency\n
-    fadeout and how this can be fixed by using a RenderTexture."
+  m_Text: 'Enter play mode to see the problem of conventional alpha transparency
+
+    fadeout
+    and how this can be fixed by using a RenderTexture.'
 --- !u!222 &541830409
 CanvasRenderer:
   m_ObjectHideFlags: 0
@@ -529,7 +531,7 @@ MonoBehaviour:
   m_Script: {fileID: 11500000, guid: a4cc2b5fcffcac846aacb02b6dad0440, type: 3}
   m_Name: 
   m_EditorClassIdentifier: 
-  skeletonRenderTexture: {fileID: 1786065614}
+  renderTextureFadeout: {fileID: 1786065619}
   normalSkeletonRenderer: {fileID: 334034153}
 --- !u!1 &1369381599
 GameObject:
@@ -872,6 +874,7 @@ GameObject:
   - component: {fileID: 1786065616}
   - component: {fileID: 1786065615}
   - component: {fileID: 1786065614}
+  - component: {fileID: 1786065619}
   m_Layer: 0
   m_Name: Spineboy CorrectFadeout
   m_TagString: Untagged
@@ -886,7 +889,7 @@ MonoBehaviour:
   m_PrefabInstance: {fileID: 0}
   m_PrefabAsset: {fileID: 0}
   m_GameObject: {fileID: 1786065613}
-  m_Enabled: 1
+  m_Enabled: 0
   m_EditorHideFlags: 0
   m_Script: {fileID: 11500000, guid: 25e6ceb271c9af848ae53f2af1073d0d, type: 3}
   m_Name: 
@@ -998,6 +1001,19 @@ Transform:
   m_Father: {fileID: 0}
   m_RootOrder: 3
   m_LocalEulerAnglesHint: {x: 0, y: 0, z: 0}
+--- !u!114 &1786065619
+MonoBehaviour:
+  m_ObjectHideFlags: 0
+  m_CorrespondingSourceObject: {fileID: 0}
+  m_PrefabInstance: {fileID: 0}
+  m_PrefabAsset: {fileID: 0}
+  m_GameObject: {fileID: 1786065613}
+  m_Enabled: 0
+  m_EditorHideFlags: 0
+  m_Script: {fileID: 11500000, guid: 5fc94f89310427643babb41e000a8462, type: 3}
+  m_Name: 
+  m_EditorClassIdentifier: 
+  fadeoutSeconds: 2
 --- !u!1 &1799507977
 GameObject:
   m_ObjectHideFlags: 0

spine-unity/Assets/Spine Examples/Scripts/RenderTextureFadeoutExample.cs

@@ -31,30 +31,60 @@
 #define HAS_VECTOR_INT
 #endif
 
+using System.Collections;
 using UnityEngine;
 using UnityEngine.Events;
 
 namespace Spine.Unity.Examples {
 	public class RenderTextureFadeoutExample : MonoBehaviour {
 
-		public SkeletonRenderTexture skeletonRenderTexture;
+		public SkeletonRenderTextureFadeout renderTextureFadeout;
 		public SkeletonRenderer normalSkeletonRenderer;
 
-		public void Update () {
-			float fadeoutAlpha = 1.0f - ((0.5f * Time.time) % 1.0f);
+		float fadeoutSeconds = 2.0f;
+		float fadeoutSecondsRemaining;
 
-			// changing transpacency at a MeshRenderer does not yield the desired effect
+		IEnumerator Start () {
+			while (true) {
+				StartFadeoutBad();
+				StartFadeoutGood();
+				yield return new WaitForSeconds(5.0f);
+			}
+		}
+		void Update () {
+			UpdateBadFadeOutAlpha();
+		}
+
+		void UpdateBadFadeOutAlpha () {
+			if (fadeoutSecondsRemaining == 0)
+				return;
+
+			fadeoutSecondsRemaining -= Time.deltaTime;
+			if (fadeoutSecondsRemaining <= 0) {
+				fadeoutSecondsRemaining = 0;
+				return;
+			}
+			float fadeoutAlpha = fadeoutSecondsRemaining / fadeoutSeconds;
+
+			// changing transparency at a MeshRenderer does not yield the desired effect
 			// due to overlapping attachment meshes.
 			normalSkeletonRenderer.Skeleton.SetColor(new Color(1, 1, 1, fadeoutAlpha));
+		}
 
-#if HAS_VECTOR_INT
-			// Thus we render the whole skeleton to a RenderTexture first using the 
-			// SkeletonRenderTexture component.
-			// Changing transparency at a single quad with a RenderTexture works as desired.
-			skeletonRenderTexture.color.a = fadeoutAlpha;
-#else
-			Debug.LogError("The SkeletonRenderTexture component requires Unity 2017.2 or newer.");
-#endif
+		void StartFadeoutBad () {
+			fadeoutSecondsRemaining = fadeoutSeconds;
+		}
+
+		void StartFadeoutGood () {
+			renderTextureFadeout.gameObject.SetActive(true);
+			// enabling the SkeletonRenderTextureFadeout component starts the fadeout.
+			renderTextureFadeout.enabled = true;
+			renderTextureFadeout.OnFadeoutComplete -= DisableGameObject;
+			renderTextureFadeout.OnFadeoutComplete += DisableGameObject;
+		}
+
+		void DisableGameObject (SkeletonRenderTextureFadeout target) {
+			target.gameObject.SetActive(false);
 		}
 	}
 }

spine-unity/Assets/Spine Examples/Scripts/Sample Components/SkeletonRenderTexture/SkeletonRenderTexture.cs

@@ -41,6 +41,14 @@ using UnityEngine.Rendering;
 
 namespace Spine.Unity.Examples {
 
+	/// <summary>
+	/// When enabled, this component renders a skeleton to a RenderTexture and
+	/// then draws this RenderTexture at a quad of the same size.
+	/// This allows changing transparency at a single quad, which produces a more
+	/// natural fadeout effect.
+	/// Note: It is recommended to keep this component disabled as much as possible
+	/// because of the additional rendering overhead. Only enable it when alpha blending is required.
+	/// </summary>
 	[RequireComponent(typeof(SkeletonRenderer))]
 	public class SkeletonRenderTexture : MonoBehaviour {
 #if HAS_VECTOR_INT

spine-unity/Assets/Spine Examples/Scripts/Sample Components/SkeletonRenderTexture/SkeletonRenderTextureFadeout.cs

@@ -0,0 +1,88 @@
+/******************************************************************************
+ * Spine Runtimes License Agreement
+ * Last updated January 1, 2020. Replaces all prior versions.
+ *
+ * Copyright (c) 2013-2022, Esoteric Software LLC
+ *
+ * Integration of the Spine Runtimes into software or otherwise creating
+ * derivative works of the Spine Runtimes is permitted under the terms and
+ * conditions of Section 2 of the Spine Editor License Agreement:
+ * http://esotericsoftware.com/spine-editor-license
+ *
+ * Otherwise, it is permitted to integrate the Spine Runtimes into software
+ * or otherwise create derivative works of the Spine Runtimes (collectively,
+ * "Products"), provided that each user of the Products must obtain their own
+ * Spine Editor license and redistribution of the Products in any form must
+ * include this license and copyright notice.
+ *
+ * THE SPINE RUNTIMES ARE PROVIDED BY ESOTERIC SOFTWARE LLC "AS IS" AND ANY
+ * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+ * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED. IN NO EVENT SHALL ESOTERIC SOFTWARE LLC BE LIABLE FOR ANY
+ * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES,
+ * BUSINESS INTERRUPTION, OR LOSS OF USE, DATA, OR PROFITS) HOWEVER CAUSED AND
+ * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+ * THE SPINE RUNTIMES, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *****************************************************************************/
+
+#if UNITY_2019_3_OR_NEWER
+#define HAS_FORCE_RENDER_OFF
+#endif
+
+#if UNITY_2017_2_OR_NEWER
+#define HAS_VECTOR_INT
+#endif
+
+using UnityEngine;
+
+namespace Spine.Unity.Examples {
+
+	/// <summary>
+	/// A simple fadeout component that uses a <see cref="SkeletonRenderTexture"/> for transparency fadeout.
+	/// Attach a <see cref="SkeletonRenderTexture"/> and this component to a skeleton GameObject and disable both
+	/// components initially and keep them disabled during normal gameplay. When you need to start fadeout,
+	/// enable this component.
+	/// At the end of the fadeout, the event delegate <c>OnFadeoutComplete</c> is called, to which you can bind e.g.
+	/// a method that disables or destroys the entire GameObject.
+	/// </summary>
+	[RequireComponent(typeof(SkeletonRenderTexture))]
+	public class SkeletonRenderTextureFadeout : MonoBehaviour {
+		SkeletonRenderTexture skeletonRenderTexture;
+
+		public float fadeoutSeconds = 2.0f;
+		protected float fadeoutSecondsRemaining;
+
+		public delegate void FadeoutCallback (SkeletonRenderTextureFadeout skeleton);
+		public event FadeoutCallback OnFadeoutComplete;
+
+		protected void Awake () {
+			skeletonRenderTexture = this.GetComponent<SkeletonRenderTexture>();
+		}
+
+		protected void OnEnable () {
+			fadeoutSecondsRemaining = fadeoutSeconds;
+			skeletonRenderTexture.enabled = true;
+		}
+
+		protected void Update () {
+			if (fadeoutSecondsRemaining == 0)
+				return;
+
+			fadeoutSecondsRemaining -= Time.deltaTime;
+			if (fadeoutSecondsRemaining <= 0) {
+				fadeoutSecondsRemaining = 0;
+				if (OnFadeoutComplete != null)
+					OnFadeoutComplete(this);
+				return;
+			}
+			float fadeoutAlpha = fadeoutSecondsRemaining / fadeoutSeconds;
+#if HAS_VECTOR_INT
+			skeletonRenderTexture.color.a = fadeoutAlpha;
+#else
+			Debug.LogError("The SkeletonRenderTexture component requires Unity 2017.2 or newer.");
+#endif
+		}
+	}
+}

spine-unity/Assets/Spine Examples/Scripts/Sample Components/SkeletonRenderTexture/SkeletonRenderTextureFadeout.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 5fc94f89310427643babb41e000a8462
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: