VRChat 非公式日本語ドキュメント

画像読み込み (Image Loading)

画像読み込み (Image Loading) を使用すると、インターネット上の画像を VRChat ワールド内に表示できます。ユーザーがワールドを訪れると、インターネットから画像がダウンロードされ、マテリアル内のテクスチャとして使用できるようになります。画像読み込みの活用例をいくつか紹介します。

  • ワールドを再アップロードせずにテクスチャを更新する。
  • ワールド内にポスターを作成し、季節のイベントやパーティーに合わせて更新する。
  • 同じテクスチャを複数のワールドで再利用し、それらを一括で更新する。

SDK には簡単に使える ImageDownload スクリプトが同梱されています。また、新しい VRCImageDownloader オブジェクトを使用して独自のスクリプトを作成することも可能です。

ヒント

手っ取り早く始めたい場合は、Image Loader のサンプルをご覧ください。

始める前に

Image Loader には、あらかじめ知っておくべき制限事項やパラメータがいくつかあります。

  • 最大解像度は 2048 × 2048 ピクセルです。これより大きな画像をダウンロードしようとするとエラーになります。
  • 画像は5秒ごとに1枚ダウンロードできます。
    • この制限を超えた場合、画像のダウンロードはキューに入れられ、ランダムな順序でダウンロードされます。
    • この制限は、使用されている VRCImageDownload コンポーネントの数に関係なく、シーン全体に適用されます。
  • URLは画像ファイルを直接指している必要があります。URLのリダイレクトは許可されておらず、エラーとなります。
  • ダウンロードされた画像は、自動的に RGBA、RGB、または RG として解釈されます。
    • 例えば、アルファチャンネルを持つグレースケール画像は、RG 画像として解釈されます。
  • キューに入れられる要素の上限は1000個です。
  • Input バッファと Output バッファはどちらも最大32MBに制限されており、これを超える画像はエラーとなります。

また、特定のドメインのみが許可されています。ドメインがリストにない場合、ユーザー設定で Allow Untrusted URLs が有効になっていない限り、画像はダウンロードされません。

  • DisBridge (*.disbridge.com)
  • Dropbox (dl.dropbox.com,dl.dropboxusercontent.com)
  • GitHub (*.github.io)
  • ImageBam (images4.imagebam.com)
  • ImgBB (i.ibb.co)
  • imgbox (images2.imgbox.com)
  • Imgur (i.imgur.com)
  • Postimages (i.postimg.cc)
  • Reddit (i.redd.it)
  • Twitter (pbs.twimg.com)
  • VRCDN (*.vrcdn.cloud)
  • VRChat (assets.vrchat.com)
  • Ytimg (i.ytimg.com)

メモリ管理

ダウンロードした画像は多くのメモリを消費します。画像の使用が終わったら、Udonを使って Dispose する必要があります。これにより、メモリが解放され、他の用途に使えるようになります。

例えば、新しい画像をダウンロードして、以前ダウンロードした画像と差し替える場合、以下に記載されている Dispose メソッドを使用して、古い画像をメモリから削除してください。これを行わずに新しい画像をダウンロードし続けると、ワールドの滞在時間が長くなった際に、訪問者のメモリが不足してクラッシュする可能性があります。

UdonGraph ノード

VRCImageDownloader

VRCImageDownloader のコンストラクターを使用してイメージダウンローダーを作成します。これを使うと、実行時にインターネットから画像をダウンロードできます。

DownloadImage

画像をダウンロードし、成功または失敗を示すイベントを呼び出します（以下の「Events」を参照）。
ダウンロードの進捗状況を追跡するために使用できる IVRCImageDownload を返します。

  • Instance: 画像のダウンロードに使用する ImageDownloader コンポーネント。
  • Url : ダウンロードするテクスチャの VRCURL。
  • Material (オプション): ダウンロードした画像をメインテクスチャとして自動的に適用する Material。
  • UdonBehavior (オプション): VRCImageDownloader のイベントを送信する UdonBehavior。UdonGraph で udonBehavior を空のままにした場合、現在の UdonBehavior がすべてのイベントを受け取ります。
    • udonBehavior を指定しない限り、UdonSharp はイベントを受け取らない点に注意してください。
  • TextureInfo (オプション): 新しく作成されるテクスチャの設定を含む TextureInfo オブジェクトです。

Dispose

VRCImageDownloader をクリーンアップします。ダウンロードされたテクスチャをメモリから解放します。

VRCImageDownloader に対して Dispose を呼び出すとオブジェクトが無効化されるため、新しい画像をダウンロードするために使用することはできなくなります。

破棄とガベージコレクションに関する注意点:

  • Dispose を呼び出すと、VRCImageDownloader、それに関連するすべての IVRCImageDownload オブジェクト、およびそれらのダウンロードに関連付けられたテクスチャが無効化されます。
    • 単一のダウンロードのみを破棄したい場合は、代わりに IVRCImageDownload オブジェクトに対して Dispose を呼び出してください。
  • VRCImageDownloader（およびダウンロードされたテクスチャ）が意図せずガベージコレクションされるのを防ぐため、必ず変数として参照を保持するようにしてください。

TextureInfo

ダウンロードしたテクスチャに適用する設定を格納します。

  • GenerateMipmaps: ミップマップの生成を有効にします。（デフォルト: false）
  • FilterMode: テクスチャの FilterMode を設定します。（デフォルト: Trilinear）
  • WrapModeU: U軸（水平方向）の TextureWrapMode です。（デフォルト: Repeat）
  • WrapModeV: V軸（垂直方向）の TextureWrapMode です。（デフォルト: Repeat）
  • WrapModeW: W軸（深度方向、Texture3Dでのみ有効）の TextureWrapMode です。（デフォルト: Repeat）
  • AnisoLevel: テクスチャの anisoLevel です。0を指定するとフィルタリングが無効になり、16で最大となります。（デフォルト: 9）
    • VRChatでは異方性フィルタリングが強制されます。anisoLevelの値が1から9の間にある場合、UnityはanisoLevelを9に設定します。値が9より大きい場合、Unityはその値を9から16の範囲に制限（クランプ）します。
  • MaterialProperty: DownloadImage で material が指定されている場合に、ダウンロードしたテクスチャを適用する MaterialProperty をオーバーライドします。（デフォルト: _MainTex）

IVRCImageDownload

ダウンロードした画像に関する情報が含まれています。VRCImageDownloader の DownloadImage 関数、OnImageLoadSuccess、および OnImageLoadError によって返されます。
これらのフィールドの多くは、ダウンロードが完了または失敗するまで無効であることに注意してください。

  • Get Error: イベントに関連付けられた VRCImageDownloadError を取得します。
  • Get Errormessage: エラーメッセージを string として取得します。
  • Get Material: DownloadImage 関数に送信された Material を取得します。
  • Get Progress: 画像ダウンロードの進捗状況を 0 から 1 の範囲の float で取得します。ダウンロードの進捗状況を追跡する場合（カスタム読み込みバーを作成する場合など）に使用してください。
  • Get Result: ダウンロードした画像の Texture2d です。
  • Get SizeInMemoryBytes: テクスチャのサイズをバイト単位の int として取得します。
  • Get State: 画像ダウンロードの状態を示す VRCImageDownloadState を取得します。
  • Get TextureInfo: DownloadImage 関数に指定されたテクスチャ情報（TextureInfo）です。
  • Get UdonBehavior: 画像ダウンロードのイベントの送信先である UdonBehavior を取得します。
  • Get URL: 画像ダウンロードの VRCURL を取得します。

VRChatは、ダウンロードした画像のテクスチャフォーマットを自動的に選択します。

  • アルファチャンネルを持つ画像は、RGBA32、RGB64などで読み込まれます。
  • アルファチャンネルを持たない画像は、RGB24、RGB48などで読み込まれます。
  • グレースケール画像は、R8、R16などで読み込まれます。

Dispose

IVRCImageDownload をクリーンアップします。ダウンロードしたテクスチャをアンロードし、使用していたメモリを解放します。

VRCImageDownloader の Dispose メソッドとは異なり、このメソッドは個別のダウンロードとその関連テクスチャのみを破棄し、他のダウンロードやテクスチャには影響を与えません。

IVRCImageDownload を Dispose すると、その State は Unloaded に変化します。

VRCImageDownloadState

IVRCImageDownload における画像ダウンロードの状態を示します：

  • Pending: 開始されていない、または現在進行中です。
  • Error: エラーによりダウンロードに失敗しました（VRCImageDownloadError を参照してください）。
  • Complete: ダウンロードが完了し、テクスチャを使用できる状態です。
  • Unloaded: IVRCImageDownload に対して Dispose が呼び出された後、ガベージコレクション待ちの状態です。
  • Unknown: 不明な状態です。

VRCImageDownloadError

画像ダウンロードが失敗すると OnImageLoadError が呼び出されます。IVRCImageDownload の Error フィールドには、以下のいずれかのエラー状態が格納されます：

  • InvalidURL: DownloadImage で使用されたダウンロードURLが無効です。
  • AccessDenied: URLへのアクセスが拒否されました。
  • InvalidImage: ダウンロードされた画像が無効です。
  • DownloadError: Webリクエストエラーが発生しました。
  • Unknown: 不明なエラー状態です。

Events

  • OnImageLoadSuccess: IVRCImageDownload を返します。VRCImageDownloader が画像のダウンロードに成功した際に呼び出されます。
  • OnImageLoadError: IVRCImageDownload を返します。VRCImageDownloader が画像のダウンロードに失敗したときに呼び出されます。

最終更新: