Version: 2022.2
言語: 日本語
Use Vector API to create a radial progress indicator
エディター UI のサポート

Mesh API を使って放射状の進捗インジケーターを作成する

バージョン: 2021.3 以降

この例では、Mesh API を使用してビジュアル要素にビジュアルコンテンツを描画する方法を示します。

ノート: Mesh API は上級者向けのツールです。バージョン 2022.1 以降では、単純なジオメトリのみを生成したい場合は、代わりに Vector API を使用してください。詳細については、Vector API を使って放射状の進捗インジケーターを作成する を参照してください。

例の概要

この例では、ローディングバーの代わりに進行状況を表示するカスタムコントロールを作成します。進捗インジケーターは、パーセンテージを表示するラベルの周囲に、部分的に塗りつぶされた輪で進捗値を表示します。0 から 100 までの値で表示され、それにより輪がどの程度塗りつぶされるかが決定されます。

この例で作成するすべてのファイルは、GitHub リポジトリ にあります。

要件

このガイドは、Unity エディター、UI Toolkit、および C# スクリプトに精通している開発者を対象としています。始める前に、以下をよく理解してください。

放射状の進捗インジケーターとそのカスタムメッシュを作成する

RadialProgress クラスを定義する C# ファイルとカスタムメッシュを定義する 2 つの C# ファイルを作成します。RadialProgress クラスを定義する C# ファイルで、コントロールを UXML と UI Builder に公開する Factory クラスを作成します。

  1. 任意のテンプレートで Unity プロジェクトを作成します。

  2. radial-progress というフォルダーを作成し、ファイルを保存します。

  3. radial-progress フォルダーに、以下のコンテンツを含む RadialProgress.cs という C# スクリプトを作成します。

    using Unity.Collections;
    using UnityEngine;
    using UnityEngine.UIElements;
    
    namespace MyUILibrary
    {
    
        // An element that displays progress inside a partially filled circle
        public class RadialProgress : VisualElement
        {
            public new class UxmlTraits : VisualElement.UxmlTraits
            {
                // The progress property is exposed to UXML.
                UxmlFloatAttributeDescription m_ProgressAttribute = new UxmlFloatAttributeDescription()
                {
                    name = "progress"
                };
    
                // Use the Init method to assign the value of the progress UXML attribute to the C# progress property.
                public override void Init(VisualElement ve, IUxmlAttributes bag, CreationContext cc)
                {
                    base.Init(ve, bag, cc);
    
                    (ve as RadialProgress).progress = m_ProgressAttribute.GetValueFromBag(bag, cc);
                }
            }
    
            // Define a factory class to expose this control to UXML.
            public new class UxmlFactory : UxmlFactory<RadialProgress, UxmlTraits> { }
    
            // These are USS class names for the control overall and the label.
            public static readonly string ussClassName = "radial-progress";
            public static readonly string ussLabelClassName = "radial-progress__label";
    
            // These objects allow C# code to access custom USS properties.
            static CustomStyleProperty<Color> s_TrackColor = new CustomStyleProperty<Color>("--track-color");
            static CustomStyleProperty<Color> s_ProgressColor = new CustomStyleProperty<Color>("--progress-color");
    
            // These are the meshes this control uses.
            EllipseMesh m_TrackMesh;
            EllipseMesh m_ProgressMesh;
    
            // This is the label that displays the percentage.
            Label m_Label;
    
            // This is the number of outer vertices to generate the circle.
            const int k_NumSteps = 200;
    
            // This is the number that the Label displays as a percentage.
            float m_Progress;
    
            // A value between 0 and 100
    
            public float progress
            {
                // The progress property is exposed in C#.
                get => m_Progress;
                set
                {
                    // Whenever the progress property changes, MarkDirtyRepaint() is named. This causes a call to the
                    // generateVisualContents callback.
                    m_Progress = value;
                    m_Label.text = Mathf.Clamp(Mathf.Round(value), 0, 100) + "%";
                    MarkDirtyRepaint();
                }
            }
    
            // This default constructor is RadialProgress's only constructor.
            public RadialProgress()
            {
                // Create a Label, add a USS class name, and add it to this visual tree.
                m_Label = new Label();
                m_Label.AddToClassList(ussLabelClassName);
                Add(m_Label);
    
                // Create meshes for the track and the progress.
                m_ProgressMesh = new EllipseMesh(k_NumSteps);
                m_TrackMesh = new EllipseMesh(k_NumSteps);
    
                // Add the USS class name for the overall control.
                AddToClassList(ussClassName);
    
                // Register a callback after custom style resolution.
                RegisterCallback<CustomStyleResolvedEvent>(evt => CustomStylesResolved(evt));
    
                // Register a callback to generate the visual content of the control.
                generateVisualContent += context => GenerateVisualContent(context);
    
                progress = 0.0f;
            }
    
            static void CustomStylesResolved(CustomStyleResolvedEvent evt)
            {
                RadialProgress element = (RadialProgress)evt.currentTarget;
                element.UpdateCustomStyles();
            }
    
            // After the custom colors are resolved, this method uses them to color the meshes and (if necessary) repaint
            // the control.
            void UpdateCustomStyles()
            {
                if (customStyle.TryGetValue(s_ProgressColor, out var progressColor))
                {
                    m_ProgressMesh.color = progressColor;
                }
    
                if (customStyle.TryGetValue(s_TrackColor, out var trackColor))
                {
                    m_TrackMesh.color = trackColor;
                }
    
                if (m_ProgressMesh.isDirty || m_TrackMesh.isDirty)
                    MarkDirtyRepaint();
            }
    
            // The GenerateVisualContent() callback method calls DrawMeshes().
            static void GenerateVisualContent(MeshGenerationContext context)
            {
                RadialProgress element = (RadialProgress)context.visualElement;
                element.DrawMeshes(context);
            }
    
            // DrawMeshes() uses the EllipseMesh utility class to generate an array of vertices and indices, for both the
            // "track" ring (in grey) and the progress ring (in green). It then passes the geometry to the MeshWriteData
            // object, as returned by the MeshGenerationContext.Allocate() method. For the "progress" mesh, only a slice of
            // the index arrays is used to progressively reveal parts of the mesh.
            void DrawMeshes(MeshGenerationContext context)
            {
                float halfWidth = contentRect.width * 0.5f;
                float halfHeight = contentRect.height * 0.5f;
    
                if (halfWidth < 2.0f || halfHeight < 2.0f)
                    return;
    
                m_ProgressMesh.width = halfWidth;
                m_ProgressMesh.height = halfHeight;
                m_ProgressMesh.borderSize = 10;
                m_ProgressMesh.UpdateMesh();
    
                m_TrackMesh.width = halfWidth;
                m_TrackMesh.height = halfHeight;
                m_TrackMesh.borderSize = 10;
                m_TrackMesh.UpdateMesh();
    
                // Draw track mesh first
                var trackMeshWriteData = context.Allocate(m_TrackMesh.vertices.Length, m_TrackMesh.indices.Length);
                trackMeshWriteData.SetAllVertices(m_TrackMesh.vertices);
                trackMeshWriteData.SetAllIndices(m_TrackMesh.indices);
    
                // Keep progress between 0 and 100
                float clampedProgress = Mathf.Clamp(m_Progress, 0.0f, 100.0f);
    
                // Determine how many triangles are used to depending on progress, to achieve a partially filled circle
                int sliceSize = Mathf.FloorToInt((k_NumSteps * clampedProgress) / 100.0f);
    
                if (sliceSize == 0)
                    return;
    
                // Every step is 6 indices in the corresponding array
                sliceSize *= 6;
    
                var progressMeshWriteData = context.Allocate(m_ProgressMesh.vertices.Length, sliceSize);
                progressMeshWriteData.SetAllVertices(m_ProgressMesh.vertices);
    
                var tempIndicesArray = new NativeArray<ushort>(m_ProgressMesh.indices, Allocator.Temp);
                progressMeshWriteData.SetAllIndices(tempIndicesArray.Slice(0, sliceSize));
                tempIndicesArray.Dispose();
            }
    
        }
    }
    
  4. 以下のコンテンツで EllipseMesh.cs という C# スクリプトを作成します。

    using UnityEngine;
    using UnityEngine.UIElements;
    
    namespace MyUILibrary
    {
        public class EllipseMesh
        {
            int m_NumSteps;
            float m_Width;
            float m_Height;
            Color m_Color;
            float m_BorderSize;
            bool m_IsDirty;
            public Vertex[] vertices { get; private set; }
            public ushort[] indices { get; private set; }
    
            public EllipseMesh(int numSteps)
            {
                m_NumSteps = numSteps;
                m_IsDirty = true;
            }
    
            public void UpdateMesh()
            {
                if (!m_IsDirty)
                    return;
    
                int numVertices = numSteps * 2;
                int numIndices = numVertices * 6;
    
                if (vertices == null || vertices.Length != numVertices)
                    vertices = new Vertex[numVertices];
    
                if (indices == null || indices.Length != numIndices)
                    indices = new ushort[numIndices];
    
                float stepSize = 360.0f / (float)numSteps;
                float angle = -180.0f;
    
                for (int i = 0; i < numSteps; ++i)
                {
                    angle -= stepSize;
                    float radians = Mathf.Deg2Rad * angle;
    
                    float outerX = Mathf.Sin(radians) * width;
                    float outerY = Mathf.Cos(radians) * height;
                    Vertex outerVertex = new Vertex();
                    outerVertex.position = new Vector3(width + outerX, height + outerY, Vertex.nearZ);
                    outerVertex.tint = color;
                    vertices[i * 2] = outerVertex;
    
                    float innerX = Mathf.Sin(radians) * (width - borderSize);
                    float innerY = Mathf.Cos(radians) * (height - borderSize);
                    Vertex innerVertex = new Vertex();
                    innerVertex.position = new Vector3(width + innerX, height + innerY, Vertex.nearZ);
                    innerVertex.tint = color;
                    vertices[i * 2 + 1] = innerVertex;
    
                    indices[i * 6] = (ushort)((i == 0) ? vertices.Length - 2 : (i - 1) * 2); // previous outer vertex
                    indices[i * 6 + 1] = (ushort)(i * 2); // current outer vertex
                    indices[i * 6 + 2] = (ushort)(i * 2 + 1); // current inner vertex
    
                    indices[i * 6 + 3] = (ushort)((i == 0) ? vertices.Length - 2 : (i - 1) * 2); // previous outer vertex
                    indices[i * 6 + 4] = (ushort)(i * 2 + 1); // current inner vertex
                    indices[i * 6 + 5] = (ushort)((i == 0) ? vertices.Length - 1 : (i - 1) * 2 + 1); // previous inner vertex
                }
    
                m_IsDirty = false;
            }
    
            public bool isDirty => m_IsDirty;
    
            void CompareAndWrite(ref float field, float newValue)
            {
                if (Mathf.Abs(field - newValue) > float.Epsilon)
                {
                    m_IsDirty = true;
                    field = newValue;
                }
            }
    
            public int numSteps
            {
                get => m_NumSteps;
                set
                {
                    m_IsDirty = value != m_NumSteps;
                    m_NumSteps = value;
                }
            }
    
            public float width
            {
                get => m_Width;
                set => CompareAndWrite(ref m_Width, value);
            }
    
            public float height
            {
                get => m_Height;
                set => CompareAndWrite(ref m_Height, value);
            }
    
            public Color color
            {
                get => m_Color;
                set
                {
                    m_IsDirty = value != m_Color;
                    m_Color = value;
                }
            }
    
            public float borderSize
            {
                get => m_BorderSize;
                set => CompareAndWrite(ref m_BorderSize, value);
            }
    
        }
    }
    

UI Document でカスタムコントロールを使用しテストする

放射状進捗インジケーターカスタムコントロールのスタイルを設定するための USS ファイルを作成します。UI Builder を使用してコントロールを加え、USS スタイルシートを適用します。さまざまな Progress 値でコントロールをテストします。

  1. 以下のコンテンツで RadialProgress.uss という名の USS ファイルを作成します。

    .radial-progress {
        min-width: 26px;
        min-height: 20px;
        --track-color: rgb(130, 130, 130);
        --progress-color: rgb(46, 132, 24);
        --percentage-color: white;
        margin-left: 5px;
        margin-right: 5px;
        margin-top: 5px;
        margin-bottom: 5px;
        flex-direction: row;
        justify-content: center;
        width: 100px; 
        height: 100px;
    }
    
    .radial-progress__label {
        -unity-text-align: middle-left;
        color: var(--percentage-color);
    }
    
  2. RadialProgressExample.uxml という名前の UI Document を作成します。

  3. RadialProgressExample.uxml をダブルクリックして UI Builder で開きます。

  4. Library ウィンドウで、Project > Custom Controls > MyUILibrary を選択します。

  5. RadialProgress を Hierarchy ウィンドウにドラッグします。

  6. UI Builder の StyleSheets セクションに、既存の USS としてRadialProgress.uss を加えます。

  7. Hierarchy ウィンドウで、RadialProgress を選択します。

  8. Inspector ウィンドウの Name フィールドに radial-progress と入力します。

  9. Inspector ウィンドウで、Progress フィールドにさまざまな値を入力します。Viewport のパーセンテージが変わり、緑色の進捗リングのサイズが変化します。

ランタイムに進捗インジケーターを使用する

シーンで UI Document を使用し、デモ用にコントロールのProgress プロパティを動的な値で更新する C# MonoBehaviour スクリプトを作成します。

  1. radial-progress フォルダーに、以下のコンテンツを含む RadialProgressComponent.cs という C# スクリプトを作成します。

    using System.Collections;
    using System.Collections.Generic;
    using UnityEngine;
    using UnityEngine.UIElements;
    using MyUILibrary;
    
    [RequireComponent(typeof(UIDocument))]
    public class RadialProgressComponent : MonoBehaviour
    {
    
        RadialProgress m_RadialProgress;
    
        void Start()
        {
            var root = GetComponent<UIDocument>().rootVisualElement;
    
            m_RadialProgress = new RadialProgress() {
                style = {
                    position = Position.Absolute,
                    left = 20, top = 20, width = 200, height = 200
                }
            };
    
            root.Add(m_RadialProgress);
        }
    
        void Update()
        {
            // For demo purpose, give the progress property dynamic values.
            m_RadialProgress.progress = ((Mathf.Sin(Time.time) + 1.0f) / 2.0f) * 60.0f + 10.0f;
        }
    }
    
  2. Unity で、GameObject > UI Toolkit > UI Document を選択します。

  3. Hierarchy ウィンドウで UIDocument を選択します。

  4. UIDocument ゲームオブジェクトのコンポーネントとして RadialProgressComponent.cs を加えます。

  5. 再生モードに入ります。シーンに進捗インジケーターが表示され、進捗リングと値が動的に変化します。

その他の参考資料

Use Vector API to create a radial progress indicator
エディター UI のサポート