Создание DownloadHandlers

Руководство Unity 2020.3 (LTS)
Мультиплеер и сеть
UnityWebRequest
Расширенные операции: использование LLAPI
Создание DownloadHandlers


Важно: UNet — это устаревшее решение, а также новая многопользовательская и сетьсистема Unity, которая обеспечивает многопользовательскую игру. игры через компьютерную сеть. Подробнее См. в Словарь Решение (Netcode для GameObjects) находится в разработке. Дополнительную информацию и дальнейшие действия см. на веб-сайте Unity Netcode for GameObjects.

Важно: UNet — это устаревшее решение, а также новая многопользовательская и Решение (Netcode для GameObjects) находится в разработке. Дополнительную информацию и дальнейшие действия см. на веб-сайте Unity Netcode for GameObjects.

Существует несколько типов DownloadHandlers:

DownloadHandlerBuffer используется для простого хранения данных.
DownloadHandlerFile используется для загрузки и сохранения файла на диск с небольшим объемом памяти.
DownloadHandlerTexture используется для загрузки изображений.
DownloadHandlerAssetBundle используется для получения пакетов AssetBundle.
DownloadHandlerAudioClip используется для загрузки аудиофайлов.
DownloadHandlerMovieTexture используется для загрузки видеофайлов. Рекомендуется использовать VideoPlayer для загрузки видео и воспроизведения фильмов, поскольку MovieTexture устарела.
DownloadHandlerScript — это специальный класс. Сам по себе он ничего не делает. Однако этот класс может быть унаследован пользовательским классом. Этот класс получает обратные вызовы от системы UnityWebRequest, которые затем можно использовать для выполнения полностью настраиваемой обработки данных по мере их поступления из сети.

API аналогичны интерфейсу DownloadHandlerTexture.

UnityWebRequest имеет свойство disposeDownloadHandlerOnDispose, значение которого по умолчанию равно true. Если это свойство имеет значение true, то при удалении объекта UnityWebRequest функция Dispose() также будет вызываться для прикрепленного обработчика загрузки рендерингапроцесса рисование графики на экране (или в текстуре рендеринга). По умолчанию основная камера в Unity отображает изображение на экране. Подробнее
Посмотреть в Словарь это бесполезно. Если вы храните ссылку на обработчик загрузки длиннее, чем ссылку на UnityWebRequest, вы должны установить для disposeDownloadHandlerOnDispose значение false.

СкачатьHandlerBuffer

Этот обработчик загрузки является самым простым и подходит для большинства случаев использования. Он сохраняет полученные данные в собственном буфере кода. Когда загрузка будет завершена, вы сможете получить доступ к буферизованным данным либо в виде массива байтов, либо в виде текстовой строки.

Пример

using UnityEngine;
using UnityEngine.Networking;
using System.Collections;


public class MyBehaviour : MonoBehaviour {
    void Start() {
        StartCoroutine(GetText());
    }

    IEnumerator GetText() {
        UnityWebRequest www = new UnityWebRequest("https://www.my-server.com");
        www.downloadHandler = new DownloadHandlerBuffer();
        yield return www.SendWebRequest();

        if (www.result != UnityWebRequest.Result.Success) {
            Debug.Log(www.error);
        }
        else {
            // Show results as text
            Debug.Log(www.downloadHandler.text);

            // Or retrieve results as binary data
            byte[] results = www.downloadHandler.data;
        }
    }
}

Скачать файл обработчика

Это специальный обработчик загрузки больших файлов. Он записывает загруженные байты непосредственно в файл, поэтому использование памяти невелико независимо от размера загружаемого файла. Отличие от других обработчиков загрузки в том, что вы не можете получить данные из этого, все данные сохраняются в файл.

Пример

using System.Collections;
using System.IO;
using UnityEngine;
using UnityEngine.Networking;

public class FileDownloader : MonoBehaviour {

    void Start () {
        StartCoroutine(DownloadFile());
    }

    IEnumerator DownloadFile() {
        var uwr = new UnityWebRequest("https://unity3d.com/", UnityWebRequest.kHttpVerbGET);
        string path = Path.Combine(Application.persistentDataPath, "unity3d");
        uwr.downloadHandler = new DownloadHandlerFile(path);
        yield return uwr.SendWebRequest();
        if (uwr.result != UnityWebRequest.Result.Success)
            Debug.LogError(uwr.error);
        else
            Debug.Log("File successfully downloaded and saved to " + path);
    }
}

Скачать текстуру обработчика

Вместо использования DownloadHandlerBuffer для загрузки файла изображения и последующего создания текстуры из необработанных байтов с помощью Texture.LoadImage , более эффективно использовать DownloadHandlerTexture.

Этот обработчик загрузки сохраняет полученные данные в UnityEngine.Texture. По завершении загрузки он декодирует файлы JPEG и PNG в действительные объекты UnityEngine.Texture. Для каждого объекта DownloadHandlerTexture создается только одна копия UnityEngine.Texture. Это уменьшает снижение производительности при сборке мусора. Обработчик выполняет буферизацию, распаковку и создание текстур в собственном коде. Кроме того, распаковка и создание текстуры выполняются в рабочем потоке, а не в основном потоке, что может сократить время кадра при загрузке больших текстур.

Наконец, DownloadHandlerTexture выделяет управляемую память только при окончательном создании самой текстуры, что устраняет накладные расходы на сбор мусора, связанные с выполнением преобразования байта в текстуру в сценарии.

Пример

В следующем примере файл PNG загружается из Интернета и преобразуется в Spriteдвухмерные графические объекты. Если вы привыкли работать в 3D, спрайты — это, по сути, просто стандартные текстуры, но существуют специальные приемы комбинирования текстур спрайтов и управления ими для повышения эффективности и удобства во время разработки. Подробнее
См. в Словарь и присваивает его изображение:

using UnityEngine;
using UnityEngine.UI;
using UnityEngine.Networking;
using System.Collections;

[RequireComponent(typeof(Image))]
public class ImageDownloader : MonoBehaviour {
    Image _img;

    void Start () {
        _img = GetComponent();
        Download("https://www.mysite.com/myimage.png");
    }

    public void Download(string url) {
        StartCoroutine(LoadFromWeb(url));
    }

    IEnumerator LoadFromWeb(string url)
    {
        UnityWebRequest wr = new UnityWebRequest(url);
        DownloadHandlerTexture texDl = new DownloadHandlerTexture(true);
        wr.downloadHandler = texDl;
        yield return wr.SendWebRequest();
        if (wr.result == UnityWebRequest.Result.Success) {
            Texture2D t = texDl.texture;
            Sprite s = Sprite.Create(t, new Rect(0, 0, t.width, t.height),
                Vector2.zero, 1f);
            _img.sprite = s;
        }
    }
}

СкачатьHandlerAssetBundle

Преимущество этого специализированного обработчика загрузки заключается в том, что он может передавать данные в систему Unity AssetBundle. Как только система AssetBundle получит достаточно данных, AssetBundle станет доступен как объект UnityEngine.AssetBundle. Создается только одна копия объекта UnityEngine.AssetBundle. Это значительно уменьшает выделение памяти во время выполнения, а также влияние памяти на загрузку вашего AssetBundle. Это также позволяет частично использовать AssetBundles, пока они не загружены полностью, поэтому вы можете транслировать активы.

Вся загрузка и распаковка происходят в рабочих потоках.

AssetBundle загружаются через объект DownloadHandlerAssetBundle, который имеет специальное свойство assetBundle для извлечения AssetBundle.

Из-за того, как работает система AssetBundle, все AssetBundle должны иметь связанный с ними адрес. Как правило, это номинальный URL-адрес, по которому они расположены (имеется в виду URL-адрес до любых перенаправлений). Почти во всех случаях вы должны передавать тот же URL-адрес, который вы передали в UnityWebRequest. При использовании API высокого уровняСистема создания многопользовательских возможностей для игр Unity. Он построен поверх нижнего уровня транспортного уровня связи в реальном времени и выполняет многие общие задачи, необходимые для многопользовательских игр. Дополнительная информация
См. Словарь (HLAPI), это сделано за вас.

Пример

using UnityEngine;
using UnityEngine.Networking;
using System.Collections;

public class MyBehaviour : MonoBehaviour {
    void Start() {
        StartCoroutine(GetAssetBundle());
    }

    IEnumerator GetAssetBundle() {
        UnityWebRequest www = new UnityWebRequest("https://www.my-server.com");
        DownloadHandlerAssetBundle handler = new DownloadHandlerAssetBundle(www.url, uint.MaxValue);
        www.downloadHandler = handler;
        yield return www.SendWebRequest();

        if (www.result != UnityWebRequest.Result.Success) {
            Debug.Log(www.error);
        }
        else {
            // Extracts AssetBundle
            AssetBundle bundle = handler.assetBundle;
        }
    }
}

СкачатьHandlerAudioClip

Этот обработчик загрузки оптимизирован для загрузки аудиофайлов. Вместо того, чтобы загружать необработанные байты с помощью DownloadHandlerBuffer и затем создавать из них AudioClip, вы можете использовать этот обработчик загрузки, чтобы сделать это в более удобный способ.

Пример

using System.Collections;
using UnityEngine;
using UnityEngine.Networking;

public class AudioDownloader : MonoBehaviour {

    void Start () {
        StartCoroutine(GetAudioClip());
    }

    IEnumerator GetAudioClip() {
        using (var uwr = UnityWebRequestMultimedia.GetAudioClip("https://myserver.com/mysound.ogg", AudioType.OGGVORBIS)) {
            yield return uwr.SendWebRequest();
            if (uwr.result != UnityWebRequest.Result.Success) {
                Debug.LogError(uwr.error);
                yield break;
            }

            AudioClip clip = DownloadHandlerAudioClip.GetContent(uwr);
            // use audio clip
        }
    }
}

СкачатьHandlerScript

Для пользователей, которым требуется полный контроль над обработкой загружаемых данных, Unity предоставляет класс DownloadHandlerScript.

По умолчанию экземпляры этого класса ничего не делают. Однако если вы наследуете свои собственные классы от DownloadHandlerScript, вы можете переопределить определенные функции и использовать их для получения обратных вызовов по мере поступления данных из сети.

Примечание. Фактические загрузки происходят в рабочем потоке, но все обратные вызовы DownloadHandlerScript работают в основном потоке. Избегайте выполнения ресурсоемких операций во время этих обратных вызовов.

Функции для переопределения

ReceiveContentLength()

protected void ReceiveContentLength(long contentLength);

Эта функция вызывается при получении заголовка Content-Length. Обратите внимание, что этот обратный вызов может выполняться несколько раз, если ваш сервер отправляет один или несколько ответов перенаправления в ходе обработки вашего UnityWebRequest.

При завершении содержимого()

protected void OnContentComplete();

Эта функция вызывается, когда UnityWebRequest полностью загрузил все данные с сервера и перенаправил все полученные данные обратному вызову ReceiveData.

ПолучитьДанные()

protected bool ReceiveData(byte[] data, long dataLength);

Эта функция вызывается после получения данных с удаленного сервера и вызывается один раз для каждого кадра. Аргумент data содержит необработанные байты, полученные от удаленного сервера, а dataLength указывает длину новых данных в массиве данных.

Если предварительно выделенные буферы данных не используются, система создает новый массив байтов каждый раз, когда вызывает этот обратный вызов, а dataLength всегда равно данные.Длина. При использовании предварительно выделенных буферов данных буфер данных используется повторно, и для определения количества обновленных байтов необходимо использовать dataLength.

Эта функция требует возвращаемого значения true или false. Если вы возвращаете false, система немедленно прерывает UnityWebRequest. Если вы вернете true, обработка продолжится в обычном режиме.

Избегание накладных расходов на сборку мусора

Многие опытные пользователи Unity обеспокоены снижением пиковых нагрузок ЦП из-за сборки мусора. Для этих пользователей система UnityWebRequest позволяет предварительно выделить массив байтов управляемого кода, который используется для доставки загруженных данных обратному вызову ReceiveData DownloadHandlerScript.

Использование этой функции полностью устраняет выделение памяти управляемым кодом при использовании классов, производных от DownloadHandlerScript, для захвата загружаемых данных.

Чтобы заставить DownloadHandlerScript работать с предварительно выделенным управляемым буфером, укажите массив байтов в конструкторе DownloadHandlerScript.

Примечание. Размер массива байтов ограничивает количество данных, доставляемых в обратный вызов ReceiveData в каждом кадре. Если ваши данные поступают медленно, в течение многих кадров, возможно, вы предоставили слишком маленький массив байтов.

Пример

using UnityEngine;
using UnityEngine.Networking;

public class LoggingDownloadHandler : DownloadHandlerScript {

    // Standard scripted download handler - allocates memory on each ReceiveData callback

    public LoggingDownloadHandler(): base() {
    }

    // Pre-allocated scripted download handler
    // reuses the supplied byte array to deliver data.
    // Eliminates memory allocation.

    public LoggingDownloadHandler(byte[] buffer): base(buffer) {
    }

    // Required by DownloadHandler base class. Called when you address the 'bytes' property.

    protected override byte[] GetData() { return null; }

    // Called once per frame when data has been received from the network.

    protected override bool ReceiveData(byte[] data, int dataLength) {
        if(data == null || data.Length < 1) {
            Debug.Log("LoggingDownloadHandler :: ReceiveData - received a null/empty buffer");
            return false;
        }

        Debug.Log(string.Format("LoggingDownloadHandler :: ReceiveData - received {0} bytes", dataLength));
        return true;
    }

    // Called when all data has been received from the server and delivered via ReceiveData.

    protected override void CompleteContent() {
        Debug.Log("LoggingDownloadHandler :: CompleteContent - DOWNLOAD COMPLETE!");
    }

    // Called when a Content-Length header is received from the server.

    protected override void ReceiveContentLengthHeader(ulong contentLength) {
        Debug.Log(string.Format("LoggingDownloadHandler :: ReceiveContentLength - length {0}", contentLength));
    }
}

Вы можете отблагодарить автора, за перевод документации на русский язык. ₽ Спасибо