1. 插件介绍

Flutter外部纹理首帧定制插件是专门为OpenHarmony平台开发的功能扩展，通过flutterRenderer.setTextureBackGroundColor和flutterRenderer.setTextureBackGroundPixelMap方法，允许开发者在视频加载或播放前自定义纹理的背景颜色和内容。这一功能确保了用户在等待视频渲染时能看到合适的背景，有效提升了应用的用户体验。

主要功能特点：

• 支持设置纹理背景颜色
• 支持设置纹理背景图像（如视频首帧）
• 兼容Flutter 3.7/3.22/3.27版本
• 适用于相机预览、视频播放等场景

2. 环境准备

在开始使用Flutter外部纹理首帧定制功能之前，请确保已完成以下环境配置：

• 安装DevEco Studio 4.0及以上版本
• 配置JDK 17环境
• 下载并安装支持OpenHarmony的Flutter SDK 3.7或以上版本
• 配置环境变量：

  # Flutter SDK路径（请替换为实际路径）
  export PATH=/path/to/flutter_flutter/bin:$PATH
  
  # OpenHarmony SDK工具
  export TOOL_HOME=/Applications/DevEco-Studio.app/Contents # mac环境
  export DEVECO_SDK_HOME=$TOOL_HOME/sdk
  export PATH=$TOOL_HOME/tools/ohpm/bin:$PATH
  export PATH=$TOOL_HOME/tools/hvigor/bin:$PATH
  export PATH=$TOOL_HOME/tools/node/bin:$PATH
  

3. 以Git形式引入插件

由于此插件为自定义修改版本，需要通过AtomGit以git形式引入。在项目的pubspec.yaml文件中添加以下依赖配置：

dependencies:
  external_texture_customization:
    git:
      url: "https://atomgit.com/your-username/external_texture_customization.git"
      path: "packages/external_texture_customization"

4. FlutterRenderer介绍

flutterRenderer是TextureRegistry的实例，通过FlutterState类获取。FlutterState类包含两个重要成员：

• binaryMessenger (BinaryMessenger): 用于Flutter与引擎之间的消息传递
• textureRegistry (TextureRegistry): 用于管理纹理和注册新纹理

FlutterState类定义

export class FlutterState {
  private binaryMessenger: BinaryMessenger;
  private textureRegistry: TextureRegistry;

  constructor(binaryMessenger: BinaryMessenger, textureRegistry: TextureRegistry) {
    this.binaryMessenger = binaryMessenger;
    this.textureRegistry = textureRegistry;
  }

  getBinaryMessenger(): BinaryMessenger {
    return this.binaryMessenger;
  }

  getTextureRegistry(): TextureRegistry {
    return this.textureRegistry;
  }
}

通过FlutterState.getTextureRegistry()方法，您可以访问flutterRenderer实例，用于管理和注册视频播放器纹理。

5. API调用指南

5.1 设置背景颜色

flutterRenderer.setTextureBackGroundColor(textureId, color)

参数说明：

• textureId (int): 纹理ID，用于标识要设置背景颜色的纹理
• color (int): 背景颜色值，使用32位十六进制格式0xAABBGGRR

示例：设置红色背景

// 设置完全不透明的红色背景 (0xAABBGGRR)
flutterRenderer.setTextureBackGroundColor(textureId, 0xFF0000FF);

颜色值解析：

• FF: Alpha通道，完全不透明
• 00: 蓝色分量，无蓝色
• 00: 绿色分量，无绿色
• FF: 红色分量，最大红色

5.2 设置背景图像

flutterRenderer.setTextureBackGroundPixelMap(textureId, pixelMap)

参数说明：

• textureId (int): 纹理ID，用于标识要设置背景图像的纹理
• pixelMap (PixelMap): 包含图像数据的PixelMap对象，用于作为纹理的背景图像

示例：设置视频首帧为背景

// 创建AVImageGenerator实例
let avImageGenerator = await media.createAVImageGenerator();

// 获取视频第一帧图像
let pixelMap = await avImageGenerator.fetchFrameByTime(
  0,
  media.AVImageQueryOptions.AV_IMAGE_QUERY_NEXT_SYNC,
  {
    width: -1,  // 使用原始宽度
    height: -1  // 使用原始高度
  }
);

// 设置为纹理背景
flutterRenderer.setTextureBackGroundPixelMap(textureId, pixelMap);

6. 完整使用示例

以下是在视频播放器插件中综合使用背景颜色和背景图像设置的完整示例：

// 创建视频播放器时设置纹理背景
if (asset != null) {
  // 处理资源文件
  let avMetaExtractor = await media.createAVMetadataExtractor();
  avMetaExtractor.fdSrc = await this.getContext().resourceManager.getRawFd("flutter_assets/" + asset);
  let mateData = await avMetaExtractor.fetchMetadata();

  if (mateData.hasVideo == CommonConstants.YES) {
    // 提取视频首帧
    let avImageGenerator = await media.createAVImageGenerator();
    avImageGenerator.fdSrc = await this.getContext().resourceManager.getRawFd("flutter_assets/" + asset);
    let pixelMap = await avImageGenerator.fetchFrameByTime(0, media.AVImageQueryOptions.AV_IMAGE_QUERY_NEXT_SYNC, {
      width: -1,
      height: -1
    });

    // 设置视频首帧为纹理背景
    flutterRenderer.setTextureBackGroundPixelMap(textureId, pixelMap);

    // 释放资源
    avImageGenerator.release();
  }
  avMetaExtractor.release();
} else if (uri != null && uri.startsWith("fd://")) {
  // 处理本地文件
  let avMetaExtractor = await media.createAVMetadataExtractor();
  avMetaExtractor.fdSrc = {
    fd: Number.parseInt(uri.replace("fd://", ""))
  };
  let mateData = await avMetaExtractor.fetchMetadata();

  if (mateData.hasVideo == CommonConstants.YES) {
    // 提取视频首帧
    let avImageGenerator = await media.createAVImageGenerator();
    avImageGenerator.fdSrc = {
      fd: Number.parseInt(uri.replace("fd://", ""))
    };
    let pixelMap = await avImageGenerator.fetchFrameByTime(0, media.AVImageQueryOptions.AV_IMAGE_QUERY_NEXT_SYNC, {
      width: -1,
      height: -1
    });

    // 设置视频首帧为纹理背景
    flutterRenderer.setTextureBackGroundPixelMap(textureId, pixelMap);

    // 释放资源
    avImageGenerator.release();
  }
  avMetaExtractor.release();
}

// 设置纹理背景颜色为红色（作为默认后备）
flutterRenderer.setTextureBackGroundColor(textureId, 0xFF0000FF);

7. 常见用例

7.1 视频加载前的占位背景

在视频加载过程中，使用背景颜色或图像填充纹理，确保用户不会看到空白屏幕。

7.2 显示加载状态

在等待视频加载和渲染时，使用预设的背景颜色或图像指示加载状态，提升用户体验。

7.3 自定义视频背景

通过使用背景图像或颜色自定义播放器外观，增强视觉效果。

8. 注意事项

1. 纹理ID有效性：在调用这些方法之前，确保纹理具有有效的textureId。

2. 内存管理：使用setTextureBackGroundPixelMap设置图像后，确保适当管理内存以避免内存泄漏。

3. 视频资源路径：确保资源路径（如资产或本地路径）正确，并且视频文件可以成功加载和提取。

4. 版本兼容性：

   • Flutter 3.7：外部纹理默认背景色为白色，可自定义
   • Flutter 3.22/3.27：外部纹理无默认背景色，可通过相同方法设置

9. 总结

Flutter外部纹理首帧定制功能为OpenHarmony平台上的视频播放应用提供了强大的背景定制能力。通过flutterRenderer.setTextureBackGroundColor和flutterRenderer.setTextureBackGroundPixelMap方法，开发者可以：

• 在视频加载前设置合适的背景颜色
• 使用视频首帧作为纹理背景
• 提升应用的视觉体验和用户交互

这一功能解决了默认白色背景无法满足所有业务场景的问题，为开发者提供了更大的灵活性，使应用能够更好地适应不同的设计需求和用户偏好。

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net