Skip to main content

纹理

¥Textures

纹理是 PixiJS 渲染管道中最重要的组件之一。它们定义了精灵、网格和其他可渲染对象所使用的视觉内容。本指南介绍如何加载、创建和使用纹理，以及 PixiJS 支持的各种数据源类型。

¥Textures are one of the most essential components in the PixiJS rendering pipeline. They define the visual content used by Sprites, Meshes, and other renderable objects. This guide covers how textures are loaded, created, and used, along with the various types of data sources PixiJS supports.

纹理生命周期​

¥Texture Lifecycle

纹理系统基于两个主要类构建：

¥The texture system is built around two major classes:

  • TextureSource：表示像素源，例如图片、画布或视频。

    ¥TextureSource: Represents a pixel source, such as an image, canvas, or video.

  • Texture：将视图定义为 TextureSource，包括子矩形、修剪和变换。

    ¥Texture: Defines a view into a TextureSource, including sub-rectangles, trims, and transformations.

生命周期流程​

¥Lifecycle Flow

Source File/Image -> TextureSource -> Texture -> Sprite (or other display object)

加载纹理​

¥Loading Textures

可以使用 Assets 系统异步加载纹理：

¥Textures can be loaded asynchronously using the Assets system:

const texture = await Assets.load('myTexture.png');

const sprite = new Sprite(texture);

准备纹理​

¥Preparing Textures

即使在加载纹理之后，图片仍然需要被推送到 GPU 并进行解码。对大量源图片执行此操作可能会很慢，并且在项目首次加载时会导致延迟峰值。为了解决这个问题，你可以使用 准备 插件，它允许你在显示项目之前的最后一步中预加载纹理。

¥Even after you've loaded your textures, the images still need to be pushed to the GPU and decoded. Doing this for a large number of source images can be slow and cause lag spikes when your project first loads. To solve this, you can use the Prepare plugin, which allows you to pre-load textures in a final step before displaying your project.

纹理 vs. 纹理源​

¥Texture vs. TextureSource

TextureSource 类处理原始像素数据和 GPU 上传。Texture 是该源的轻量级视图，包含修剪、矩形框、UV 映射等元数据。多个 Texture 实例可以共享一个 TextureSource，例如在精灵图中。

¥The TextureSource handles the raw pixel data and GPU upload. A Texture is a lightweight view on that source, with metadata such as trimming, frame rectangle, UV mapping, etc. Multiple Texture instances can share a single TextureSource, such as in a sprite sheet.

const sheet = await Assets.load('spritesheet.json');
const heroTexture = sheet.textures['hero.png'];

纹理创建​

¥Texture Creation

你可以使用构造函数手动创建纹理：

¥You can manually create textures using the constructor:

const mySource = new TextureSource({ resource: myImage });
const texture = new Texture({ source: mySource });

如果你计划在运行时修改其 frame、trim 或 source，请在 Texture 选项中设置 dynamic: true。

¥Set dynamic: true in the Texture options if you plan to modify its frame, trim, or source at runtime.

销毁纹理​

¥Destroying Textures

使用完纹理后，你可能希望释放它使用的内存（WebGL 管理的缓冲区和基于浏览器的缓冲区）。为此，你应该调用 Assets.unload('texture.png')；如果你在 Assets 之外创建了纹理，则应调用 texture.destroy()。

¥Once you're done with a Texture, you may wish to free up the memory (both WebGL-managed buffers and browser-based) that it uses. To do so, you should call Assets.unload('texture.png'), or texture.destroy() if you have created the texture outside of Assets.

对于短暂的图片（例如大型且仅使用一次的过场动画）来说，这是一个特别好的主意。如果通过 Assets 加载的纹理被破坏，则资源类将自动为你将其从缓存中删除。

¥This is a particularly good idea for short-lived imagery like cut-scenes that are large and will only be used once. If a texture is destroyed that was loaded via Assets then the assets class will automatically remove it from the cache for you.

从 GPU 卸载纹理​

¥Unload Texture from GPU

如果你想从 GPU 卸载纹理但将其保留在内存中，可以调用 texture.source.unload()。这将从 GPU 中移除纹理，但将源保留在内存中。

¥If you want to unload a texture from the GPU but keep it in memory, you can call texture.source.unload(). This will remove the texture from the GPU but keep the source in memory.

// Load the texture
const texture = await Assets.load('myTexture.png');

// ... Use the texture

// Unload the texture from the GPU
texture.source.unload();

纹理类型​

¥Texture Types

PixiJS 支持多种 TextureSource 类型，具体取决于输入数据类型：

¥PixiJS supports multiple TextureSource types, depending on the kind of input data:

纹理类型描述
ImageSourceHTMLImageElement、ImageBitmap、SVG、VideoFrame 等
CanvasSourceHTMLCanvasElement 或 OffscreenCanvas
VideoSourceHTMLVideoElement 可选自动播放和更新 FPS
BufferImageSource具有明确宽度、高度和格式的 TypedArray 或 ArrayBuffer
CompressedSource压缩 mipmap 数组 (Uint8Array[])

常用纹理属性​

¥Common Texture Properties

以下是 Texture 类的一些重要属性：

¥Here are some important properties of the Texture class:

  • frame：定义源中可见部分的矩形。

    ¥frame: Rectangle defining the visible portion within the source.

  • orig：原始未裁剪尺寸。

    ¥orig: Original untrimmed dimensions.

  • trim：定义修剪区域以排除透明空间。

    ¥trim: Defines trimmed regions to exclude transparent space.

  • uvs：由 frame 和 rotate 生成的 UV 坐标。

    ¥uvs: UV coordinates generated from frame and rotate.

  • rotate：GroupD8 旋转值用于图集兼容性。

    ¥rotate: GroupD8 rotation value for atlas compatibility.

  • defaultAnchor：用于精灵图时的默认锚点。

    ¥defaultAnchor: Default anchor when used in Sprites.

  • defaultBorders：用于 9 切片缩放。

    ¥defaultBorders: Used for 9-slice scaling.

  • source：TextureSource 实例。

    ¥source: The TextureSource instance.

常用 TextureSource 属性​

¥Common TextureSource Properties

以下是 TextureSource 类的一些重要属性：

¥Here are some important properties of the TextureSource class:

  • resolution：影响相对于实际像素大小的渲染大小。

    ¥resolution: Affects render size relative to actual pixel size.

  • format：纹理格式（例如 rgba8unorm、bgra8unorm 等）

    ¥format: Texture format (e.g., rgba8unorm, bgra8unorm, etc.)

  • alphaMode：控制上传时如何解释 Alpha 值。

    ¥alphaMode: Controls how alpha is interpreted on upload.

  • wrapMode / scaleMode:控制如何在边界外或缩放时对纹理进行采样。

    ¥wrapMode / scaleMode: Controls how texture is sampled outside of bounds or when scaled.

  • autoGenerateMipmaps：上传时是否生成 mipmap。

    ¥autoGenerateMipmaps: Whether to generate mipmaps on upload.

你可以在创建 TextureSource 时设置以下属性：

¥You can set these properties when creating a TextureSource:

texture.source.scaleMode = 'linear';
texture.source.wrapMode = 'repeat';

API 参考​

¥API Reference