DownloadHandler の作成

Note: UNet is deprecated, and will be removed in the future. A new system is under development. For more information and next steps see this blog post and the FAQ

DownloadHandlersにはさまざまなタイプがあります。

• DownloadHandlerBuffer は簡易なデータストレージとして使用されます。
• DownloadHandlerFile は少ないメモリフットプリントでファイルをダウンロードし、ディスクに保存するために使用されます。
• DownloadHandlerTexture は画像をダウンロードするために使用されます。
• DownloadHandlerAssetBundle はアセットバンドルをフェッチするために使用されます。
• DownloadHandlerTexture はオーディオ ファイルをダウンロードするために使用されます。
• DownloadHandlerMovieTexture is used for downloading video files. It is recommended that you use VideoPlayer for video download and movie playback since MovieTexture is deprecated.
• DownloadHandlerScript は特殊クラスです。それ自体では何も行いません。ただし、このクラスはユーザー定義のクラスによって継承が可能です。 このクラスは UnityWebRequest システムからコールバックを受け取り、ネットワークからデータを取得したときに完全にカスタム処理するために使用します。

API は DownloadHandlerTexture のインターフェースに似ています。

UnityWebRequest には disposeDownloadHandlerOnDispose というプロパティがあります。このデフォルトは true です。このプロパティが true の場合、UnityWebRequest オブジェクトが破棄されると、添付されたダウンロードハンドラーで Dispose() も呼び出され、レンダリングを無効にします。ダウンロードハンドラーへの参照を UnityWebRequest への参照より長く保持している場合は、disposeDownloadHandlerOnDispose を false に設定する必要があります。

DownloadHandlerBuffer

このダウンロードハンドラーは最も簡単で、たいていのケースを処理できます。このハンドラーは受け取ったデータをネイティブコードバッファーに格納します。ダウンロードが終了すると、バイト配列またはテキスト文字列で、バッファーされたデータにアクセスできます。

例

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

 
public class MyBehaviour : MonoBehaviour {
    void Start() {
        StartCoroutine(GetText());
    }
 
    IEnumerator GetText() {
        UnityWebRequest www = new UnityWebRequest("http://www.my-server.com");
        www.downloadHandler = new DownloadHandlerBuffer();
        yield return www.SendWebRequest();
 
        if(www.isNetworkError || www.isHttpError) {
            Debug.Log(www.error);
        }
        else {
            // テキストで結果を表示
            Debug.Log(www.downloadHandler.text);
 
            // または、バイナリデータで結果を表示
            byte[] results = www.downloadHandler.data;
        }
    }
}

DownloadHandlerFile

これは大きなファイル用の特別なダウンロードハンドラです。ダウンロードされたバイトを直接ファイルに書き込むので、ダウンロードするファイルのサイズに関係なくメモリの使用量は少なくなります。他のダウンロードハンドラとの違いは、このデータは取り出すことができず、すべてのデータはファイルに保存されます。

例

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.html");
        uwr.downloadHandler = new DownloadHandlerFile(path);
        yield return uwr.SendWebRequest();
        if (uwr.isNetworkError || uwr.isHttpError)
            Debug.LogError(uwr.error);
        else
            Debug.Log("File successfully downloaded and saved to " + path);
    }
}

DownloadHandlerTexture

DownloadHandlerBuffer を使用して画像ファイルをダウンロードし、それから Texture.LoadImage を使用して生のバイトからテクスチャを作成する代わりに、DownloadHandlerTexture を使用する方が効率的です。

このダウンロードハンドラーは、受信したデータを UnityEngine.Texture に格納します。ダウンロードが完了すると、JPEG と PNG を有効な UnityEngine.Texture オブジェクトにデコードします。各 DownloadHandlerTexture オブジェクトごとに 1 つのUnityEngine.Texture だけしか作成されません。ですから、ガベージコレクションによるパフォーマンスの低下を軽減します。ハンドラーは、バッファリング、解凍、テクスチャの作成をネイティブコードで実行します。さらに、解凍とテクスチャの作成を、メインスレッドでなくワーカースレッドで実行するため、大きなテクスチャを読み込むときにフレーム時間を向上させます。

最後に、DownloadHandlerTexture は、最終的にテクスチャ自体を作成するときにのみマネージドのメモリを割り当てます。このため、スクリプトでバイトからテクスチャへの変換を実行する際のガベージコレクションのオーバーヘッドを排除します。

例

以下の例では、PNG ファイルをインターネットからダウンロードし、スプライトに変換し、画像 に割り当てます。

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

[RequireComponent(typeof(UnityEngine.UI.Image))]
public class ImageDownloader : MonoBehaviour {
    UnityEngine.UI.Image _img;
 
    void Start () {
        _img = GetComponent<UnityEngine.UI.Image>();
        Download("http://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.isNetworkError || wr.isHttpError)) {
            Texture2D t = texDl.texture;
            Sprite s = Sprite.Create(t, new Rect(0, 0, t.width, t.height),
                                     Vector2.zero, 1f);
            _img.sprite = s;
        }
    }
}

DownloadHandlerAssetBundle

この特化したダウンロードハンドラーの利点は、Unity のアセットバンドルシステムにデータをストリーミングできることです。アセットバンドルシステムが十分なデータを受け取ると、アセットバンドルはUnityEngine.AssetBundle オブジェクトとして利用できます。UnityEngine.AssetBundle オブジェクトのコピーは 1 つだけ作成されます。これにより、ランタイムメモリの割り当てと、アセットバンドルの読み込みによるメモリへの影響が大幅に軽減されます。また、完全にダウンロードされていないときにアセットバンドルを部分的に使用することができます。ですから、アセットをストリーミングすることができます。

すべてのダウンロードと解凍はワーカースレッドで行われます。

アセットバンドルは、DownloadHandlerAssetBundle オブジェクトをとおしてダウンロードされます。このオブジェクトには、アセットバンドルを取得する特別な assetBundle プロパティがあります。

アセットバンドルシステムの仕組みにより、すべてのアセットバンドルには関連付けられたアドレスが必要です。一般的には、これはアセットバンドルが位置する名目上の URL (リダイレクト前のURL ) です。ほとんどの場合、UnityWebRequest に渡したのと同じ URL を渡す必要があります。高レベル API (HLAPI) を使用する場合、これは本人の判断で行ってください。

例

using UnityEngine;
using UnityEngine.Networking; 
using System.Collections;
 
public class MyBehaviour : MonoBehaviour {
    void Start() {
        StartCoroutine(GetAssetBundle());
    }
 
    IEnumerator GetAssetBundle() {
        UnityWebRequest www = new UnityWebRequest("http://www.my-server.com");
        DownloadHandlerAssetBundle handler = new DownloadHandlerAssetBundle(www.url, uint.MaxValue);
        www.downloadHandler = handler;
        yield return www.SendWebRequest();
 
        if(www.isNetworkError || www.isHttpError) {
            Debug.Log(www.error);
        }
        else {
            // AssetBundle を抽出
            AssetBundle bundle = handler.assetBundle;
        }
    }
}

DownloadHandlerAudioClip

このダウンロードハンドラーは、オーディオファイルをダウンロードするために最適化されています。 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("http://myserver.com/mysound.ogg", AudioType.OGGVORBIS)) {
            yield return uwr.SendWebRequest();
            if (uwr.isNetworkError || uwr.isHttpError) {
                Debug.LogError(uwr.error);
                yield break;
            }

            AudioClip clip = DownloadHandlerAudioClip.GetContent(uwr);
            // オーディオクリップを使う
        }
    }   
}

DownloadHandlerTexture

ノート MovieTexture (ムービーテクスチャ) は廃止、または非推奨となる予定です。動画のダウンロードとムービー再生には、VideoPlayer を使用してください。

このダウンロードハンドラーは、ビデオファイルをダウンロードするために最適化されています。 DownloadHandlerBuffer を使用して生のバイトをダウンロードしてから MovieTexture を作成する代わりに、このダウンロードハンドラーを使用してより便利に処理できます。

例

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

public class MovieDownloader : MonoBehaviour {

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

    IEnumerator GetAudioClip() {
        using (var uwr = UnityWebRequestMultimedia.GetMovieTexture("http://myserver.com/mysound.ogg")) {
            yield return uwr.SendWebRequest();
            if (uwr.isNetworkError || uwr.isHttpError) {
                Debug.LogError(uwr.error);
                yield break;
            }

            MovieTexture movie = DownloadHandlerMovieTexture.GetContent(uwr);
            // ムービーテクスチャを使う
        }
    }   
}

DownloadHandlerScript

ダウンロードしたデータの処理を完全に制御する必要があるユーザのために、Unity はDownloadHandlerScript クラスを提供します。

デフォルトでは、このクラスのインスタンスは何も行いません。ただし、DownloadHandlerScript から独自のクラスを派生させる場合、特定の関数をオーバーライドして、ネットワークからデータが到着するときコールバックを受け取るためにその関数を使用します。

注意 実際のダウンロードはワーカースレッド上で行われますが、すべての DownloadHandlerScript コールバックはメインスレッド上で動作します。 これらのコールバック中に負荷の高い計算操作を行なわないでください。

オーバーライドする関数

ReceiveContentLength()

protected void ReceiveContentLength(long contentLength);

この関数は、Content Length ヘッダーが受信されたときに呼び出されます。UnityWebRequest の処理中にサーバーが 1つ以上のリダイレクト応答を送信すると、このコールバックは複数回発生することがあります。

OnContentComplete()

protected void OnContentComplete();

この関数は UnityWebRequest がサーバーからすべてのデータを完全にダウンロードし、それを ReceiveData コールバックに転送したときに呼び出されます。

ReceiveData()

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

この関数は、リモートサーバーからデータを受領した後に、フレームごとに 1 回呼び出されます。 data 引数には、リモートサーバーから受信した生のバイトが含まれます。また、 dataLength はデータ配列内の新しいデータの長さを示します。

事前に割り当てられたデータバッファを使用しない場合、システムはこのコールバックを呼び出すたびに新しいバイト配列を作成し、dataLength は常に data.Length　と等しくなります。 事前に割り当てられたデータバッファを使用する場合は、データバッファが再利用され、更新されたバイト数を見つけるために dataLength を使用する必要があります。

この関数には、true または false のいずれかの戻り値が必要です。false を返すと、システムは直ちに UnityWebRequest を中止します。true を返すと、処理は正常に続行されます。

ガーベージコレクションオーバーヘッドの回避

もっと上級レベルの Unity ユーザーの多くは、ガベージコレクションのために CPU スパイクを減らすことを気にかけています。これらのユーザのために、UnityWebRequest システムは、ダウンロードされたデータを DownloadHandlerScript のReceiveData コールバックに配信するために使用されるマネージドのコードのバイト配列の事前割り当てを許可します。

この関数を使用すると、DownloadHandlerScript 派生クラスを使用してダウンロードしたデータを取得するときに、マネージドのコードのメモリ割り当てを完全に排除します。

DownloadHandlerScript をあらかじめ割り当てられたマネージバッファで動作させるには、バイト配列を DownloadHandlerScript のコンストラクタに渡します。

注意 バイト配列のサイズは、各フレームで ReceiveData コールバックに渡されるデータ量を制限します。データがゆっくりと、多くのフレームにわたって到着した場合、バイト配列が小さすぎる可能性があります。

例

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

public class LoggingDownloadHandler : DownloadHandlerScript {

    // 標準のスクリプトされたダウンロードハンドラー - メモリを各 ReceiveData コールバックに割り当てます
   
    public LoggingDownloadHandler(): base() {
    }

    // 事前割り当てされたスクリプト化されたダウンロードハンドラーは
    //データを送信するために用意された配列を再利用します。
    // メモリアロケーションを削除します。
    
    public LoggingDownloadHandler(byte[] buffer): base(buffer) {
    }

    // DownloadHandler 基本クラスに必須。'bytes' プロパティを表すときに呼び出されます。
    
    protected override byte[] GetData() { return null; }

    // ネットワークからデータを受け取った後、フレームごとに 1 回呼び出されます。
    
    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;
    }

    // サーバーからすべてのデータを受け取った後、ReceiveData 経由で送信されます。
    
    protected override void CompleteContent() {
        Debug.Log("LoggingDownloadHandler :: CompleteContent - DOWNLOAD COMPLETE!");
    }

    // サーバーから Content-Length ヘッダーを受け取ったときに呼び出されます。
    
    protected override void ReceiveContentLength(int contentLength) {
        Debug.Log(string.Format("LoggingDownloadHandler :: ReceiveContentLength - length {0}", contentLength));
    }
}