PixiJS 源码揭秘 - 8. 插件机制深度解析

// 内部标准化后的格式
interface StrictExtensionFormat {
  type: ExtensionType[] // 确保是数组
  name?: string
  priority: number // 提供默认值 0
  ref: any // 指向插件的实际实现（对象或类的实例）
}

// 开发者定义插件时使用的元数据接口
interface ExtensionMetadataDetails {
  type: ExtensionType | ExtensionType[] // 支持单个或多个类型
  name?: string // 插件唯一标识，强烈建议提供
  priority?: number // 处理优先级，默认为 ExtensionPriority.Normal (0)
}

// 示例：添加一个简单的文本加载器
const myTxtLoader = {
  extension: {
    type: ExtensionType.LoadParser,
    priority: 1, // 优先级略高于默认
    name: 'my-txt-loader',
  },

  test(url) {
    return url.endsWith('.mytxt')
  },

  async load(url) {
    const response = await fetch(url)
    const text = await response.text()
    // 可以进行一些预处理
    return `Processed: ${text}`
  },
}

extensions.add(myTxtLoader)

// 使用
Assets.load('path/to/data.mytxt').then((content) => {
  console.log(content) // 输出 "Processed: ..."
})

// 示例：一个简单的 WebGL 系统插件，用于计数渲染对象
class RenderCounterSystem implements ISystem {
  static extension = {
    type: ExtensionType.WebGLSystem,
    name: 'render-counter',
  }

  private _count = 0

  renderer: Renderer

  constructor(renderer: Renderer) {
    this.renderer = renderer
  }

  // 在每帧渲染前重置计数器
  preprerender() {
    this._count = 0
  }

  // 假设我们在某个 Pipe 中调用此方法
  incrementCount() {
    this._count++
  }

  // 在渲染后打印计数
  postrender() {
    console.log(`Rendered ${this._count} objects this frame.`)
  }

  destroy() {
    // 清理资源
  }
}

extensions.add(RenderCounterSystem)

// 在需要的地方获取系统实例并使用
// const counterSystem = renderer.systems.renderCounter;
// counterSystem.incrementCount();

// 示例：自定义一个简单的 "加亮" 混合模式
const lightenBlendMode = {
  extension: {
    type: ExtensionType.BlendMode,
    name: 'lighten-blend',
  },
  // WebGL 混合参数
  gl: {
    srcRGB: 'SRC_ALPHA', // 源颜色 * 源 Alpha
    dstRGB: 'ONE', // 目标颜色 * 1
    srcAlpha: 'ONE', // 源 Alpha * 1
    dstAlpha: 'ONE', // 目标 Alpha * 1
    // 公式: Result = SrcColor * SrcAlpha + DstColor
  },
  // Canvas 混合模式（可选）
  canvas: 'lighter', // 使用 Canvas 的 'lighter' 模式近似
}

extensions.add(lightenBlendMode)

// 使用
const sprite = new Sprite(texture)
sprite.blendMode = 'lighten-blend'

class MySystem implements ISystem {
  static extension = {
    type: ExtensionType.WebGLSystem,
    name: 'my-system',
  }

  private _shader: Shader

  constructor(renderer: Renderer) {
    /* ... */
  }

  init(options?: any): void {
    console.log('MySystem 初始化:', options)
    // 创建着色器、缓冲区等
    this._shader = createMyShader()
  }

  prerender(): void {
    // 绑定着色器、设置 Uniforms 等
  }

  postrender(): void {
    // 清理状态、执行后处理
  }

  destroy(): void {
    console.log('MySystem 销毁')
    this._shader?.destroy()
    // 释放其他资源
  }
}

extensions.add(MySystem)

// 概念示例：Spine Atlas 加载器
const spineAtlasParser = {
  extension: { type: ExtensionType.LoadParser, priority: LoaderParserPriority.High },
  testParse(asset, options) {
    // 检查是否为 .atlas 文件且可能有关联的 .json/.skel
    return Promise.resolve(isSpineAtlas(asset, options))
  },
  async parse(asset, options, loader) {
    // 异步加载和解析 .atlas 文件内容
    const atlasData = await fetch(asset.src).then((res) => res.text())
    // ... 解析 atlas 数据 ...
    // 可能需要加载关联的纹理
    const texture = await loader.load(textureUrl)
    return createSpineAtlas(atlasData, texture)
  },
}
extensions.add(spineAtlasParser)

// 概念示例：Spine 渲染管线 (简化)
class SpinePipe implements IPipe {
  static extension = { type: ExtensionType.WebGLPipes, name: 'spine' }

  constructor(renderer) {
    /* ... 初始化 WebGL 资源 ... */
  }

  addRenderable(renderable: Spine, instructionSet: InstructionSet): void {
    // 将 Spine 对象添加到渲染指令集
    // ... 准备顶点数据、Uniforms ...
    instructionSet.add(renderable)
  }

  execute(instructionSet: InstructionSet): void {
    // 遍历指令集中的 Spine 对象并渲染
    for (const renderable of instructionSet.renderables) {
      // 绑定着色器、设置 Uniforms、绑定顶点数据
      // ... renderer.shader.bind(spineShader) ...
      // ... renderer.geometry.bind(spineGeometry) ...
      // 发出绘制调用
      // ... renderer.geometry.draw(...) ...
    }
  }

  destroy() {
    /* ... 清理资源 ... */
  }
}
extensions.add(SpinePipe)

// 概念示例：Live2D Model3.json 加载器
const live2dModelParser = {
  extension: { type: ExtensionType.LoadParser, priority: LoaderParserPriority.Normal },
  testParse(asset, options) {
    // 检查是否为 .model3.json 文件
    return Promise.resolve(isLive2DModelJson(asset, options))
  },
  async parse(asset, options, loader) {
    // 加载并解析 model3.json
    const modelJson = await fetch(asset.src).then((res) => res.json())
    // 根据 json 内容，递归加载依赖的 moc3, 纹理, 物理, 动作等文件
    const dependencies = await Promise.all([
      loader.load(resolvePath(asset.src, modelJson.FileReferences.Moc)),
      loader.load(resolvePath(asset.src, modelJson.FileReferences.Textures)),
      // ... 加载其他依赖 ...
    ])
    // ... 组装 Live2D 模型实例 ...
    return createLive2DModel(modelJson, dependencies)
  },
}
extensions.add(live2dModelParser)

// 概念示例：Live2D 渲染系统 (简化)
class Live2DRenderSystem implements ISystem {
  static extension = { type: ExtensionType.WebGLSystem, name: 'live2d' }

  constructor(renderer) {
    /* ... 初始化 WebGL 状态，如模板缓冲 ... */
  }

  render(displayObject: Live2DModel): void {
    // 准备渲染 Live2D 模型
    const model = displayObject.internalModel
    // ... 更新模型状态（动画、物理） ...
    // ... 设置 WebGL 状态（混合模式、模板测试等）...
    // 遍历模型的 Drawable 对象
    for (const drawable of model.drawables) {
      if (!drawable.isVisible) continue
      // ... 绑定纹理、设置 Uniforms ...
      // ... 绑定顶点数据（包含蒙皮信息）...
      // ... 处理遮罩逻辑（可能涉及模板缓冲操作）...
      // ... 发出绘制调用 ...
    }
    // ... 恢复 WebGL 状态 ...
  }

  destroy() {
    /* ... 清理资源 ... */
  }
}
extensions.add(Live2DRenderSystem)

// 概念示例：继承 Filter 实现简单的灰度滤镜
import { Filter, GlProgram, GpuProgram } from 'pixi.js'

const grayscaleFrag = `
  varying vec2 vTextureCoord;
  uniform sampler2D uSampler;

  void main(void)
  {
      vec4 color = texture2D(uSampler, vTextureCoord);
      float gray = dot(color.rgb, vec3(0.299, 0.587, 0.114));
      gl_FragColor = vec4(vec3(gray), color.a);
  }
`

class GrayscaleFilter extends Filter {
  constructor() {
    const gpuProgram = GpuProgram.from({
      fragment: {
        source: grayscaleFrag,
        entryPoint: 'main',
      },
    })
    const glProgram = GlProgram.from({
      fragment: grayscaleFrag,
      vertex: Filter.defaultVertexSrc, // 使用默认顶点着色器
    })

    super({ gpuProgram, glProgram })
  }
}

// 使用
const sprite = new Sprite(texture)
const grayFilter = new GrayscaleFilter()
sprite.filters = [grayFilter]