Skip to main content

图片加载

图片加载允许您在 VRChat 世界中显示来自互联网的图片。当用户访问您的世界时，可以从互联网下载图片并用作材质中的纹理。以下是一些图片加载的使用示例：

  • 无需重新上传即可更新世界中的纹理。
  • 在世界中创建海报，为季节活动或派对进行更新。
  • 在多个世界中重复使用相同的纹理并一次性更新。

SDK 包含一个易于使用的 ImageDownload 脚本，或者您可以使用新的 VRCImageDownloader 对象制作自己的脚本。

tip

您可以查看我们的图片加载器示例快速入门。

开始前须知​

您应该了解一些图片加载器的限制和参数：

  • 最大分辨率为 2048 × 2048 像素。尝试下载更大的图片将导致错误。
  • 每五秒只能下载一张图片。
    • 如果超过此限制，图片下载将排队并按随机顺序下载。
    • 此限制适用于整个场景，无论使用了多少 VRCImageDownload 组件。
  • URL 必须直接指向图片文件。不允许 URL 重定向，否则将导致错误。
  • 下载的图片自动解释为 RGBA、RGB 或 RG 图像。
    • 例如，带有 Alpha 通道的灰度图像被解释为 RG 图像。
  • 队列中最多 1000 个元素。
  • 输入和输出缓冲区均限制为最大 32MB，超过此限制的图片将导致错误。

并且只允许特定域名。如果域名不在列表中，除非用户已在设置中启用允许不受信任的 URL，否则图片不会下载。

  • 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 方法从内存中移除旧图片。如果不这样做并继续下载新图片，访问您世界的玩家在花费足够时间后可能耗尽内存并崩溃。

UdonGraph 节点​

VRCImageDownloader​

使用 VRCImageDownloader 的构造函数创建图片下载器，它可以在运行时从互联网下载图片。

DownloadImage​

下载图片，并调用指示成功或失败的事件（参见下面的'事件'）。 返回一个 IVRCImageDownload，可用于跟踪下载进度。

  • Instance：用于下载图片的 ImageDownloader 组件。
  • Url：要下载的纹理的 VRCURL。
  • Material（可选）：要自动应用下载图片作为主纹理的材质。
  • UdonBehavior（可选）：要向其发送 VRCImageDownloader 事件的 Udonbehavior。如果在 UdonGraph 中将 udonBehavior 留空，当前 UdonBehaviour 将接收所有事件。
    • 注意，除非指定 udonBehavior，否则 UdonSharp 不会收到任何事件。
  • TextureInfo（可选）：包含新创建纹理设置的 TextureInfo 对象。

Dispose​

清理 VRCImageDownloader。从内存中释放下载的纹理。

对 VRCImageDownloader 调用 Dispose 会使该对象失效，意味着它不能用于下载任何新图片。

关于释放和垃圾回收的说明：

  • 调用 Dispose 将使 VRCImageDownloader、所有关联的 IVRCImageDownload 对象以及这些下载关联的纹理失效。
    • 如果只想释放单个下载，请改为对 IVRCImageDownload 对象调用 Dispose。
  • 确保将对 VRCImageDownloader 的引用保存为变量，以防止它（以及任何下载的纹理）被随机垃圾回收。

TextureInfo​

包含要应用于下载纹理的设置。

  • GenerateMipMaps：启用 Mipmap 生成。（默认：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 函数的材质。
  • 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 自动选择下载图片的 纹理格式。

  • 带有 Alpha 通道的图片加载为 RGBA32、RGB64 等。
  • 不带 Alpha 通道的图片加载为 RGB24、RGB48 等。
  • 灰度图像加载为 R8、R16 等。

Dispose​

清理 IVRCImageDownload。卸载下载的纹理并释放其占用的内存。

与 VRCImageDownloader 的 dispose 方法不同，这只会释放单个下载及其关联的纹理，而保留其他下载及其纹理不变。

释放 IVRCImageDownload 后，其 State 将变为 Unloaded。

VRCImageDownloadState​

指示 IVRCImageDownload 中图片下载的状态：

  • Pending：尚未开始或仍在进行中。
  • Error：下载失败，出现错误（参见 VRCImageDownloadError）。
  • Complete：下载完成，纹理已可用。
  • Unloaded：在对 IVRCImageDownload 调用 Dispose 后等待垃圾回收。
  • Unknown：未知状态。

VRCImageDownloadError​

当图片下载失败时，会调用 OnImageLoadError。IVRCImageDownload 的 Error 字段将包含以下错误状态之一：

  • InvalidURL：DownloadImage 中使用的下载 URL 无效。
  • AccessDenied：访问 URL 被拒绝。
  • InvalidImage：下载的图片无效。
  • DownloadError：发生网络请求错误。
  • Unknown：未知错误状态。

事件​

  • OnImageLoadSuccess：返回 IVRCImageDownload。当 VRCImageDownloader 成功下载图片时调用。
  • OnImageLoadError：返回 IVRCImageDownload。当 VRCImageDownloader 下载图片失败时调用。