Yükleme süresi kaydetme işlevleri ekleme

Oyununuzun yükleme etkinlikleri gerçekleştirdiği zamanları kaydetmeniz iki nedenden dolayı önemlidir:

1. Yükleme sırasında kare süresi verilerinizin bozulmasını önlemek için.
2. Yükleme sürelerinin ne zaman ve nerede kabul edilebilir süreden daha uzun olduğunu görmek için yükleme sürelerini analiz etme.

Yükleme etkinliğiyle ilişkili meta veriler olabilir:

public class LoadingTimeMetadata
{
    public enum LoadingState
    {
        Unknown = 0,

        /// <summary>
        ///     The first time the game is run.
        /// </summary>
        FirstRun = 1,

        /// <summary>
        ///     App is not backgrounded.
        /// </summary>
        ColdStart = 2,

        /// <summary>
        ///     App is backgrounded.
        /// </summary>
        WarmStart = 3,

        /// <summary>
        ///     App is backgrounded, least work needed.
        /// </summary>
        HotStart = 4,

        /// <summary>
        ///     Asset loading between levels.
        /// </summary>
        InterLevel = 5
    }

    public LoadingState state;

    public enum LoadingSource
    {
        UnknownSource = 0,

        /// <summary>
        ///     Uncompressing data.
        /// </summary>
        Memory = 1,

        /// <summary>
        ///     Reading assets from APK bundle.
        /// </summary>
        Apk = 2,

        /// <summary>
        ///     Reading assets from device storage.
        /// </summary>
        DeviceStorage = 3,

        /// <summary>
        ///     Reading assets from external storage, e.g. SD card.
        /// </summary>
        ExternalStorage = 4,

        /// <summary>
        ///     Loading assets from the network.
        /// </summary>
        Network = 5,

        /// <summary>
        ///     Shader compilation.
        /// </summary>
        ShaderCompilation = 6,

        /// <summary>
        ///     Time spent between process starting and onCreate.
        /// </summary>
        PreActivity = 7,

        /// <summary>
        ///     Total time spent between process starting and first render frame.
        /// </summary>
        FirstTouchToFirstFrame = 8,

        /// <summary>
        ///     Time from start to end of a group of events.
        /// </summary>
        TotalUserWaitForGroup = 9
    }

    public LoadingSource source;

    /// <summary>
    ///     0 = no compression, 100 = max compression
    /// </summary>
    public int compression_level;

    public enum NetworkConnectivity
    {
        Unknown = 0,
        Wifi = 1,
        CellularNetwork = 2
    }

    public NetworkConnectivity network_connectivity;

    /// <summary>
    ///     Bandwidth in bits per second.
    /// </summary>
    public ulong network_transfer_speed_bps;

    /// <summary>
    ///     Latency in nanoseconds.
    /// </summary>
    public ulong network_latency_ns;
}

İhtiyaçlarınızla alakalı olmayan alanlar sıfır olabilir.

Yükleme etkinliğine ilişkili bir açıklama da eklenebilir. Annotation iletisindeki bir veya daha fazla alanı kullanarak çerçeve zamanı ek açıklamalarıyla aynı şekilde tanımlayabilirsiniz.

Result<ulong> StartRecordingLoadingTime(LoadingTimeMetadata eventMetadata, TAnnotation annotation);

Bu işlev, belirtilen meta veriler ve ek açıklamalarla ilişkili bir yükleme süresi etkinliğini kaydetmeye başlar ve StopRecordingLoadingTime() işlevinde kullanılacak bir Result<ulong>.value değerini doldurur.

ErrorCode StopRecordingLoadingTime(ulong handle);

Bu işlev, daha önce StartRecordingLoadingTime() tarafından başlatılan bir etkinliğin kaydını durdurur. Etkinlik, bir sonraki oturum temizleme işleminde yüklenir.

Grup işlevleri yükleniyor

Uyarı: Tüm yükleme etkinlikleri bir yükleme grubunun parçası olmalıdır. Grup işlevlerini yükleme hakkında kod örneğine bakın.

Oyununuzda, kullanıcı tarafından görülen tek bir yükleme dönemi için birden fazla yükleme etkinliği kaydedebilirsiniz. Örneğin, dosya yükleme, sahne yükleme, sıkıştırmayı açma ve gölgelendirici derleme işlemleri bu kapsamdadır.

Android Performance Tuner'ın daha iyi analizler sunabilmesi için yükleme etkinliklerinin bu tür bir grubun parçası olduğunu bildirmek önemlidir. Bunu yapmak için yükleme etkinliklerinizi aşağıdaki başlangıç ve durdurma işlevleriyle sınırlayın.

Not: Aynı anda yalnızca bir yükleme grubu etkin olabilir.

Result<ulong> StartLoadingGroup(LoadingTimeMetadata eventMetadata, TAnnotation annotation);

Bu işlev, belirtilen meta veriler ve ek açıklamalarla ilişkili bir yükleme grubunu başlatır ve StopLoadingGroup() işlevinde kullanılacak bir Result<ulong>.value doldurur. Üst veriler ve ek açıklamalar şu anda Play arka ucu tarafından kullanılmamaktadır. Ancak yalnızca ek açıklama null olarak ayarlanabilir. Sonraki tüm yükleme etkinlikleri benzersiz bir grup kimliğiyle etiketlenir.

ErrorCode StopLoadingGroup(ulong handle);

Bu işlev, daha önce StartLoadingGroup() tarafından başlatılan bir yükleme grubunu durdurur. StartLoadingGroup() tekrar çağrılana kadar sonraki yükleme etkinliklerinde grup kimliği olmaz.

1. Şekil. Yükleme grubu örneği.

Örnekler

Oyununuza yükleme süresi işlevlerini ekleme yöntemleriyle ilgili bazı örnekleri aşağıda bulabilirsiniz.

Dosya yükleme etkinlikleri

Aşağıdaki kod örneğinde, dosya yükleme etkinliklerinin oyununuza nasıl kaydedileceği gösterilmektedir.

public RawImage image;

IEnumerator LoadImageFromStreamingAssets(string imageName)
{
    string imagePath = "file://" + Path.Combine(Application.streamingAssetsPath, imageName);
    using (var r = UnityWebRequestTexture.GetTexture(imagePath))
    {
        LoadingTimeMetadata fileLoadingMetadata = new LoadingTimeMetadata()
        {
            state = LoadingTimeMetadata.LoadingState.InterLevel,
            source = LoadingTimeMetadata.LoadingSource.DeviceStorage,
            // Fields are zero by default but they could be set as follows
            compression_level = 0,
            network_connectivity = 0,
            network_transfer_speed_bps = 0,
            network_latency_ns = 0
        };
        Annotation annotation = new Annotation()
        {
            Scene = Scene.MagicalForest
        };
        // Start recording loading time.
        Result<ulong> result = performanceTuner.StartRecordingLoadingTime(fileLoadingMetadata, annotation);
        yield return r.SendWebRequest();
        // Stop recording loading time.
        performanceTuner.StopRecordingLoadingTime(result.value);
        if (r.isNetworkError || r.isHttpError)
        {
            Debug.Log(r.error);
        }
        else
        {
            Texture2D tex = DownloadHandlerTexture.GetContent(r);
            image.texture = tex;
        }
    }
}

Sahne yükleme etkinlikleri

Aşağıdaki kod örneğinde, oyununuzda sahne yükleme etkinliklerinin nasıl kaydedileceği gösterilmektedir.

IEnumerator LoadScene(int sceneIndex)
{
    LoadingTimeMetadata metadata = new LoadingTimeMetadata()
        {state = LoadingTimeMetadata.LoadingState.InterLevel};
    Annotation annotation = new Annotation() {Scene = (Scene) (sceneIndex + 1)};
    Result<ulong> result = performanceTuner.StartRecordingLoadingTime(metadata, annotation);
    AsyncOperation asyncSceneLoad = SceneManager.LoadSceneAsync(sceneIndex, LoadSceneMode.Single);
    while (!asyncSceneLoad.isDone)
    {
        yield return null;
    }

    performanceTuner.StopRecordingLoadingTime(result.value);
}

Grup işlevleri yükleniyor

Aşağıdaki kod örneğinde, oyununuza yükleme grubu işlevlerinin nasıl ekleneceği gösterilmektedir.

IEnumerator LoadImages()
{
    LoadingTimeMetadata groupMetadata = new LoadingTimeMetadata()
    {
        state = LoadingTimeMetadata.LoadingState.InterLevel,
        source = LoadingTimeMetadata.LoadingSource.DeviceStorage,
    };
    Result<ulong> result = performanceTuner.StartLoadingGroup(groupMetadata, null);
    yield return StartCoroutine(LoadImageFromStreamingAssets("image1.jpeg"));
    yield return StartCoroutine(LoadImageFromStreamingAssets("image2.jpeg"));
    yield return StartCoroutine(LoadImageFromStreamingAssets("image3.jpeg"));
    yield return StartCoroutine(LoadImageFromStreamingAssets("image4.jpeg"));
    var stopErrorCode = performanceTuner.StopLoadingGroup(0);
}