@hxa-rn/react-native-gcanvas 6.0.25 → 6.0.26

package/harmony/gcanvas/src/main/ets/GCanvasModuleTurboModule.ts

@@ -1,448 +1,448 @@
-import { UITurboModule, UITurboModuleContext } from '@rnoh/react-native-openharmony/ts';
-import { TM } from './generated/ts';
-import { image } from '@kit.ImageKit';
-import { http } from '@kit.NetworkKit';
-import util from '@ohos.util';
-import fs from '@ohos.file.fs';
-import hilog from '@ohos.hilog';
-import { GCanvasNativeEngine } from './GCanvasNativeEngine';
-
-const TAG = 'GCanvasModule';
-const DOMAIN = 0x0001;
-
-/**
- * GCanvasModule TurboModule（鸿蒙 ArkTS 侧实现）。
- *
- * 本模块是 C++ OpenGL ES Canvas/WebGL 引擎（GCanvas）的鸿蒙适配：
- *  - 同步方法（enable/extendCallNative/setContextType/toDataURL/字体等）：透传至
- *    C++ 原生引擎 GCanvasNativeEngine（单例），由其内部 GL 线程执行命令并同步返回。
- *    同步语义复刻 Android GCanvasJNI.render() 的 waitUtilTimeout/QueueProc。
- *  - 异步方法（图片解码/网络下载/生命周期）：在 ArkTS 侧用 image kit / net.http 实现，
- *    解码出的 RGBA 像素交 C++ 引擎上传纹理（对齐 Android texImage2D 命令 '102,9,...'）。
- *
- * 方法名、签名、返回类型与 JS 桥（packages/gcanvas/src/bridge/react-native.js）及
- * Spec（src/specs/v1/NativeGCanvasModule.ts）完全一致。TurboModuleRegistry 名称固定 'GCanvasModule'。
- *
- * 错误处理约定：异步方法用 Promise.reject()；同步方法不抛异常（GL 调用失败由 C++ 内部记录），
- * 仅在 ArkTS 入口参数非法时记录日志并返回安全默认值，避免原生崩溃导致 RN 应用闪退。
- */
-export class GCanvasModuleTurboModule extends UITurboModule implements TM.GCanvasModule.Spec {
-  private engine: GCanvasNativeEngine = GCanvasNativeEngine.getInstance();
-  // GImage.preloadImage currently passes the legacy placeholder id 0 and assigns
-  // the real image id in JS afterwards. Android therefore resolves textures by
-  // path (fetchLoadImage(path)); keep the same source-keyed cache on Harmony.
-  private decodedImagesBySource: Map<string, RgbaPixels> = new Map();
-
-  constructor(ctx: UITurboModuleContext) {
-    super(ctx);
-  }
-
-  /**
-   * 启用画布（同步）。返回前需让 GL 表面就绪。
-   * config 是上游渲染器选项数组；尺寸和像素比分别来自 XComponent 与 setDevicePixelRatio。
-   */
-  enable(args: { componentId: string, config: number[] }): void {
-    try {
-      this.engine.enable(args.componentId, args.config);
-    } catch (e) {
-      hilogError(`enable failed: componentId=${args.componentId}`, e);
-    }
-  }
-
-  /** 禁用画布（异步）。 */
-  disable(refId: string): Promise<void> {
-    try {
-      this.engine.disable(refId);
-      return Promise.resolve();
-    } catch (e) {
-      hilogError(`disable failed: refId=${refId}`);
-      return Promise.reject(new Error(`disable failed: ${refId}`));
-    }
-  }
-
-  /**
-   * 异步执行命令字符串（type 含 32-bit 编码：2d=0x00 / webgl=0x40，async）。
-   * 命令投递到 GL 线程后立即返回，不等待结果。
-   */
-  render(canvasId: string, cmd: string, type: number): Promise<void> {
-    try {
-      this.engine.render(canvasId, cmd, type);
-      return Promise.resolve();
-    } catch (e) {
-      hilogError(`render failed: canvasId=${canvasId}`, e);
-      return Promise.reject(new Error(`render failed: ${canvasId}`));
-    }
-  }
-
-  /**
-   * 【核心】同步执行命令字符串并返回结果。
-   * 32-bit type = ContextType[31:30](0=2d/1=webgl) | MethodType[29](1=sync) | OptionType[28:0]。
-   * 命令在 GL 线程执行并阻塞等待结果，对齐 Android GCanvasJNI.render() 的同步语义。
-   */
-  extendCallNative(args: { contextId: string, args: string, type: number }): { result: string } {
-    let result: string = '';
-    try {
-      result = this.engine.extendCallNative(args.contextId, args.args, args.type);
-    } catch (e) {
-      hilogError(`extendCallNative failed: contextId=${args.contextId}`, e);
-    }
-    let ret: ExtendCallNativeResult = { result };
-    return ret;
-  }
-
-  /** 设置上下文类型（同步）。0=2d, 1=webgl。 */
-  setContextType(contextType: number, refId: string): void {
-    try {
-      this.engine.setContextType(contextType, refId);
-    } catch (e) {
-      hilogError(`setContextType failed: refId=${refId}`);
-    }
-  }
-
-  /** 设置设备像素比（同步）。 */
-  setDevicePixelRatio(refId: string, ratio: number): void {
-    try {
-      this.engine.setDevicePixelRatio(refId, ratio);
-    } catch (e) {
-      hilogError(`setDevicePixelRatio failed: refId=${refId}`);
-    }
-  }
-
-  /** 重置 GL viewport（同步）。 */
-  resetGlViewport(refId: string): void {
-    try {
-      this.engine.resetGlViewport(refId);
-    } catch (e) {
-      hilogError(`resetGlViewport failed: refId=${refId}`);
-    }
-  }
-
-  /**
-   * 同步导出画布为 data URL（glReadPixels → PNG → base64）。
-   * 返回形如 data:image/png;base64,xxxx；失败返回空字符串。
-   */
-  toDataURL(refId: string, mimeType: string, quality: number): string {
-    try {
-      return this.engine.toDataURL(refId, mimeType, quality);
-    } catch (e) {
-      hilogError(`toDataURL failed: refId=${refId}`);
-      return '';
-    }
-  }
-
-  /** 将一个画布内容绘制到另一画布（同步）。 */
-  drawCanvas2Canvas(map: DrawCanvas2CanvasMap): void {
-    try {
-      this.engine.drawCanvas2Canvas(map);
-    } catch (e) {
-      hilogError(`drawCanvas2Canvas failed: src=${map.srcComponentId} dst=${map.dstComponentId}`);
-    }
-  }
-
-  /**
-   * 图片解码后绑定纹理（异步）。src=图片路径，imageId=纹理 id。
-   * 鸿蒙用 image kit 解码为 RGBA_8888，再交 C++ 引擎上传纹理。
-   */
-  bindImageTexture(args: { src: string, imageId: number }, refId: string): Promise<void> {
-    if (this.engine.bindCachedImageTexture(refId, args.imageId)) {
-      return Promise.resolve();
-    }
-    const cached = this.decodedImagesBySource.get(args.src);
-    if (cached) {
-      this.engine.bindImageTexture(refId, args.imageId, cached.buffer, cached.width, cached.height);
-      return Promise.resolve();
-    }
-    return decodeImageToRGBA(args.src).then((rgba: RgbaPixels) => {
-      this.decodedImagesBySource.set(args.src, rgba);
-      this.engine.bindImageTexture(refId, args.imageId, rgba.buffer, rgba.width, rgba.height);
-    }).catch((e: Error) => {
-      hilogError(`bindImageTexture failed: src=${args.src} err=${e.message}`);
-      return Promise.reject(new Error(`bindImageTexture failed: ${e.message}`));
-    });
-  }
-
-  /**
-   * 预加载图片（异步）。url=图片地址，id=图片 id，返回尺寸/错误信息。
-   * 远程 URL 经 @ohos.net.http 下载为 ArrayBuffer 后再解码（image kit 不支持 http URL）。
-   */
-  preLoadImage(args: { url: string, id: number }): Promise<ImageInfo> {
-    return decodeImageToRGBA(args.url).then((rgba: RgbaPixels) => {
-      // 缓存解码结果，供后续 bindImageTexture/texImage2D 复用
-      this.decodedImagesBySource.set(args.url, rgba);
-      this.engine.cacheImage(args.id, rgba.buffer, rgba.width, rgba.height);
-      let info: ImageInfo = { width: rgba.width, height: rgba.height };
-      return info;
-    }).catch((e: Error) => {
-      hilogError(`preLoadImage failed: url=${args.url} err=${e.message}`);
-      let info: ImageInfo = { width: 0, height: 0, error: e.message };
-      return info;
-    });
-  }
-
-  /** 获取设备信息（异步）。返回 JSON 字符串。 */
-  getDeviceInfo(args: string): Promise<DeviceInfoRet> {
-    try {
-      const data = this.engine.getDeviceInfo(args);
-      let ret: DeviceInfoRet = { data };
-      return Promise.resolve(ret);
-    } catch (e) {
-      hilogError(`getDeviceInfo failed: args=${args}`);
-      let ret: DeviceInfoRet = { data: '' };
-      return Promise.resolve(ret);
-    }
-  }
-
-  /** 注册自定义字体族（同步）。fontNames 与 fontFiles 一一对应。 */
-  addFontFamily(fontNames: string[], fontFiles: string[]): void {
-    try {
-      this.engine.addFontFamily(fontNames, fontFiles);
-    } catch (e) {
-      hilogError('addFontFamily failed');
-    }
-  }
-
-  /** 枚举系统字体族名（同步）。 */
-  getFontNames(): string[] {
-    try {
-      return this.engine.getFontNames();
-    } catch (e) {
-      hilogError('getFontNames failed');
-      return [];
-    }
-  }
-
-  /** 设置额外字体目录（同步）。 */
-  setExtraFontLocation(location: string): void {
-    try {
-      this.engine.setExtraFontLocation(location);
-    } catch (e) {
-      hilogError(`setExtraFontLocation failed: location=${location}`);
-    }
-  }
-
-  /** 设置日志级别（异步）。 */
-  setLogLevel(level: number): Promise<void> {
-    try {
-      this.engine.setLogLevel(level);
-      return Promise.resolve();
-    } catch (e) {
-      hilogError(`setLogLevel failed: level=${level}`);
-      return Promise.reject(new Error('setLogLevel failed'));
-    }
-  }
-
-  /** 重置组件（异步）。 */
-  resetComponent(refId: string): Promise<void> {
-    try {
-      this.engine.resetComponent(refId);
-      return Promise.resolve();
-    } catch (e) {
-      hilogError(`resetComponent failed: refId=${refId}`);
-      return Promise.reject(new Error(`resetComponent failed: ${refId}`));
-    }
-  }
-
-  /** WebGL 纹理上传（同步）。图片须先由 GImage/preLoadImage 解码并按 src 缓存。 */
-  texImage2D(refId: string, target: number, level: number, internalformat: number, format: number,
-    type: number, src: string): void {
-    try {
-      const rgba = this.decodedImagesBySource.get(src);
-      if (!rgba) {
-        hilogError(`texImage2D image is not preloaded: src=${src}`);
-        return;
-      }
-      this.engine.texImage2D(refId, target, level, internalformat, format, type,
-        rgba.buffer, rgba.width, rgba.height);
-    } catch (e) {
-      hilogError(`texImage2D failed: refId=${refId}`);
-    }
-  }
-
-  /** WebGL 纹理子图上传（同步，鸿蒙新增分支）。命令 '105,9,...'。 */
-  texSubImage2D(refId: string, target: number, level: number, xoffset: number, yoffset: number,
-    format: number, type: number, src: string): void {
-    try {
-      const rgba = this.decodedImagesBySource.get(src);
-      if (!rgba) {
-        hilogError(`texSubImage2D image is not preloaded: src=${src}`);
-        return;
-      }
-      this.engine.texSubImage2D(refId, target, level, xoffset, yoffset, format, type,
-        rgba.buffer, rgba.width, rgba.height);
-    } catch (e) {
-      hilogError(`texSubImage2D failed: refId=${refId}`);
-    }
-  }
-
-  /** 设置组件 alpha（异步，原实现为空壳，鸿蒙同样空实现）。 */
-  setAlpha(refId: string, alpha: number): Promise<void> {
-    // 原生 Android/iOS 端 setAlpha 即为空实现，鸿蒙保持一致。
-    return Promise.resolve();
-  }
-}
-
-/**
- * 解码图片为 RGBA 像素缓冲。
- * 支持：沙箱/资源/$rawfile 路径、http(s) 远程 URL、data: URL。
- * 远程 URL 先经 @ohos.net.http 下载为 ArrayBuffer（image.createImageSource 不支持 http）。
- */
-async function decodeImageToRGBA(src: string): Promise<RgbaPixels> {
-  let buf: ArrayBuffer;
-  if (src.startsWith('http://') || src.startsWith('https://')) {
-    buf = await downloadToBuffer(src);
-  } else if (src.startsWith('data:')) {
-    buf = dataUrlToBuffer(src);
-  } else {
-    buf = await readLocalToBuffer(src);
-  }
-  let imageSource: image.ImageSource | null = null;
-  let pixelMap: image.PixelMap | null = null;
-  try {
-    imageSource = image.createImageSource(buf);
-    pixelMap = await imageSource.createPixelMap({ desiredPixelFormat: image.PixelMapFormat.RGBA_8888 });
-    const info = await pixelMap.getImageInfo();
-    const width: number = info.size.width;
-    const height: number = info.size.height;
-    const byteCount: number = pixelMap.getPixelBytesNumber();
-    const pixels: ArrayBuffer = new ArrayBuffer(byteCount);
-    await pixelMap.readPixelsToBuffer(pixels);
-    let ret: RgbaPixels = { buffer: pixels, width, height };
-    return ret;
-  } catch (e) {
-    hilog.error(DOMAIN, TAG, `decodeImageToRGBA failed: src=${src} err=${(e as Error).message}`);
-    throw e instanceof Error ? e : new Error(String(e));
-  } finally {
-    releaseDecodedImage(pixelMap, imageSource);
-  }
-}
-
-function releaseDecodedImage(pixelMap: image.PixelMap | null, imageSource: image.ImageSource | null): void {
-  if (pixelMap) {
-    try {
-      pixelMap.release();
-    } catch (e) {
-      hilog.error(DOMAIN, TAG, `release PixelMap failed: ${(e as Error).message}`);
-    }
-  }
-  if (imageSource) {
-    try {
-      imageSource.release();
-    } catch (e) {
-      hilog.error(DOMAIN, TAG, `release ImageSource failed: ${(e as Error).message}`);
-    }
-  }
-}
-
-/** 远程图片下载为 ArrayBuffer。 */
-async function downloadToBuffer(url: string): Promise<ArrayBuffer> {
-  let httpReq: http.HttpRequest | null = null;
-  try {
-    httpReq = http.createHttp();
-    const resp = await httpReq.request(url, {
-      method: http.RequestMethod.GET,
-      expectDataType: http.HttpDataType.ARRAY_BUFFER,
-    });
-    httpReq.destroy();
-    return resp.result as ArrayBuffer;
-  } catch (e) {
-    if (httpReq) {
-      httpReq.destroy();
-    }
-    hilog.error(DOMAIN, TAG, `downloadToBuffer failed: url=${url} err=${(e as Error).message}`);
-    throw e instanceof Error ? e : new Error(String(e));
-  }
-}
-
-/** data URL（base64）转 ArrayBuffer。 */
-function dataUrlToBuffer(dataUrl: string): ArrayBuffer {
-  try {
-    const base64Helper = new util.Base64Helper();
-    const commaIdx = dataUrl.indexOf(',');
-    const base64 = commaIdx >= 0 ? dataUrl.substring(commaIdx + 1) : dataUrl;
-    const bytes = base64Helper.decodeSync(base64);
-    return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
-  } catch (e) {
-    hilog.error(DOMAIN, TAG, `dataUrlToBuffer failed: err=${(e as Error).message}`);
-    throw e instanceof Error ? e : new Error(String(e));
-  }
-}
-
-/** 本地/资源文件读取为 ArrayBuffer。 */
-async function readLocalToBuffer(path: string): Promise<ArrayBuffer> {
-  let file: fs.File | null = null;
-  try {
-    file = fs.openSync(path, fs.OpenMode.READ_ONLY);
-    const stat = fs.statSync(path);
-    const buf: ArrayBuffer = new ArrayBuffer(stat.size);
-    await fs.read(file.fd, buf);
-    fs.closeSync(file);
-    return buf;
-  } catch (e) {
-    // 关闭文件也可能抛异常，且门禁要求 @kit 调用必须在 try/catch 内并用 hilog 记录。
-    if (file) {
-      try {
-        fs.closeSync(file);
-      } catch (ce) {
-        hilog.error(DOMAIN, TAG, `readLocalToBuffer close failed: path=${path} err=${(ce as Error).message}`);
-      }
-    }
-    hilog.error(DOMAIN, TAG, `readLocalToBuffer failed: path=${path} err=${(e as Error).message}`);
-    throw e instanceof Error ? e : new Error(String(e));
-  }
-}
-
-function errorMessage(e: Object): string {
-  try {
-    return e instanceof Error ? e.message : String(e);
-  } catch (_ignored) {
-    return 'unknown';
-  }
-}
-
-function hilogError(msg: string, e?: Object): void {
-  if (e === undefined) {
-    hilog.error(DOMAIN, TAG, msg);
-    return;
-  }
-  hilog.error(DOMAIN, TAG, `${msg} err=${errorMessage(e)}`);
-}
-
-/** extendCallNative 同步返回值。 */
-interface ExtendCallNativeResult {
-  result: string;
-}
-
-/** drawCanvas2Canvas 参数。 */
-interface DrawCanvas2CanvasMap {
-  srcComponentId: string;
-  dstComponentId: string;
-  tw: number;
-  th: number;
-  sx: number;
-  sy: number;
-  sw: number;
-  sh: number;
-  dx: number;
-  dy: number;
-  dw: number;
-  dh: number;
-}
-
-/** RGBA 像素解码结果。 */
-interface RgbaPixels {
-  buffer: ArrayBuffer;
-  width: number;
-  height: number;
-}
-
-/** preLoadImage 返回的图片信息。 */
-interface ImageInfo {
-  width: number;
-  height: number;
-  error?: string;
-}
-
-/** getDeviceInfo 返回。 */
-interface DeviceInfoRet {
-  data: string;
-}
+import { UITurboModule, UITurboModuleContext } from '@rnoh/react-native-openharmony/ts';
+import { TM } from './generated/ts';
+import { image } from '@kit.ImageKit';
+import { http } from '@kit.NetworkKit';
+import util from '@ohos.util';
+import fs from '@ohos.file.fs';
+import hilog from '@ohos.hilog';
+import { GCanvasNativeEngine } from './GCanvasNativeEngine';
+
+const TAG = 'GCanvasModule';
+const DOMAIN = 0x0001;
+
+/**
+ * GCanvasModule TurboModule（鸿蒙 ArkTS 侧实现）。
+ *
+ * 本模块是 C++ OpenGL ES Canvas/WebGL 引擎（GCanvas）的鸿蒙适配：
+ *  - 同步方法（enable/extendCallNative/setContextType/toDataURL/字体等）：透传至
+ *    C++ 原生引擎 GCanvasNativeEngine（单例），由其内部 GL 线程执行命令并同步返回。
+ *    同步语义复刻 Android GCanvasJNI.render() 的 waitUtilTimeout/QueueProc。
+ *  - 异步方法（图片解码/网络下载/生命周期）：在 ArkTS 侧用 image kit / net.http 实现，
+ *    解码出的 RGBA 像素交 C++ 引擎上传纹理（对齐 Android texImage2D 命令 '102,9,...'）。
+ *
+ * 方法名、签名、返回类型与 JS 桥（packages/gcanvas/src/bridge/react-native.js）及
+ * Spec（src/specs/v1/NativeGCanvasModule.ts）完全一致。TurboModuleRegistry 名称固定 'GCanvasModule'。
+ *
+ * 错误处理约定：异步方法用 Promise.reject()；同步方法不抛异常（GL 调用失败由 C++ 内部记录），
+ * 仅在 ArkTS 入口参数非法时记录日志并返回安全默认值，避免原生崩溃导致 RN 应用闪退。
+ */
+export class GCanvasModuleTurboModule extends UITurboModule implements TM.GCanvasModule.Spec {
+  private engine: GCanvasNativeEngine = GCanvasNativeEngine.getInstance();
+  // GImage.preloadImage currently passes the legacy placeholder id 0 and assigns
+  // the real image id in JS afterwards. Android therefore resolves textures by
+  // path (fetchLoadImage(path)); keep the same source-keyed cache on Harmony.
+  private decodedImagesBySource: Map<string, RgbaPixels> = new Map();
+
+  constructor(ctx: UITurboModuleContext) {
+    super(ctx);
+  }
+
+  /**
+   * 启用画布（同步）。返回前需让 GL 表面就绪。
+   * config 是上游渲染器选项数组；尺寸和像素比分别来自 XComponent 与 setDevicePixelRatio。
+   */
+  enable(args: { componentId: string, config: number[] }): void {
+    try {
+      this.engine.enable(args.componentId, args.config);
+    } catch (e) {
+      hilogError(`enable failed: componentId=${args.componentId}`, e);
+    }
+  }
+
+  /** 禁用画布（异步）。 */
+  disable(refId: string): Promise<void> {
+    try {
+      this.engine.disable(refId);
+      return Promise.resolve();
+    } catch (e) {
+      hilogError(`disable failed: refId=${refId}`);
+      return Promise.reject(new Error(`disable failed: ${refId}`));
+    }
+  }
+
+  /**
+   * 异步执行命令字符串（type 含 32-bit 编码：2d=0x00 / webgl=0x40，async）。
+   * 命令投递到 GL 线程后立即返回，不等待结果。
+   */
+  render(canvasId: string, cmd: string, type: number): Promise<void> {
+    try {
+      this.engine.render(canvasId, cmd, type);
+      return Promise.resolve();
+    } catch (e) {
+      hilogError(`render failed: canvasId=${canvasId}`, e);
+      return Promise.reject(new Error(`render failed: ${canvasId}`));
+    }
+  }
+
+  /**
+   * 【核心】同步执行命令字符串并返回结果。
+   * 32-bit type = ContextType[31:30](0=2d/1=webgl) | MethodType[29](1=sync) | OptionType[28:0]。
+   * 命令在 GL 线程执行并阻塞等待结果，对齐 Android GCanvasJNI.render() 的同步语义。
+   */
+  extendCallNative(args: { contextId: string, args: string, type: number }): { result: string } {
+    let result: string = '';
+    try {
+      result = this.engine.extendCallNative(args.contextId, args.args, args.type);
+    } catch (e) {
+      hilogError(`extendCallNative failed: contextId=${args.contextId}`, e);
+    }
+    let ret: ExtendCallNativeResult = { result };
+    return ret;
+  }
+
+  /** 设置上下文类型（同步）。0=2d, 1=webgl。 */
+  setContextType(contextType: number, refId: string): void {
+    try {
+      this.engine.setContextType(contextType, refId);
+    } catch (e) {
+      hilogError(`setContextType failed: refId=${refId}`);
+    }
+  }
+
+  /** 设置设备像素比（同步）。 */
+  setDevicePixelRatio(refId: string, ratio: number): void {
+    try {
+      this.engine.setDevicePixelRatio(refId, ratio);
+    } catch (e) {
+      hilogError(`setDevicePixelRatio failed: refId=${refId}`);
+    }
+  }
+
+  /** 重置 GL viewport（同步）。 */
+  resetGlViewport(refId: string): void {
+    try {
+      this.engine.resetGlViewport(refId);
+    } catch (e) {
+      hilogError(`resetGlViewport failed: refId=${refId}`);
+    }
+  }
+
+  /**
+   * 同步导出画布为 data URL（glReadPixels → PNG → base64）。
+   * 返回形如 data:image/png;base64,xxxx；失败返回空字符串。
+   */
+  toDataURL(refId: string, mimeType: string, quality: number): string {
+    try {
+      return this.engine.toDataURL(refId, mimeType, quality);
+    } catch (e) {
+      hilogError(`toDataURL failed: refId=${refId}`);
+      return '';
+    }
+  }
+
+  /** 将一个画布内容绘制到另一画布（同步）。 */
+  drawCanvas2Canvas(map: DrawCanvas2CanvasMap): void {
+    try {
+      this.engine.drawCanvas2Canvas(map);
+    } catch (e) {
+      hilogError(`drawCanvas2Canvas failed: src=${map.srcComponentId} dst=${map.dstComponentId}`);
+    }
+  }
+
+  /**
+   * 图片解码后绑定纹理（异步）。src=图片路径，imageId=纹理 id。
+   * 鸿蒙用 image kit 解码为 RGBA_8888，再交 C++ 引擎上传纹理。
+   */
+  bindImageTexture(args: { src: string, imageId: number }, refId: string): Promise<void> {
+    if (this.engine.bindCachedImageTexture(refId, args.imageId)) {
+      return Promise.resolve();
+    }
+    const cached = this.decodedImagesBySource.get(args.src);
+    if (cached) {
+      this.engine.bindImageTexture(refId, args.imageId, cached.buffer, cached.width, cached.height);
+      return Promise.resolve();
+    }
+    return decodeImageToRGBA(args.src).then((rgba: RgbaPixels) => {
+      this.decodedImagesBySource.set(args.src, rgba);
+      this.engine.bindImageTexture(refId, args.imageId, rgba.buffer, rgba.width, rgba.height);
+    }).catch((e: Error) => {
+      hilogError(`bindImageTexture failed: src=${args.src} err=${e.message}`);
+      return Promise.reject(new Error(`bindImageTexture failed: ${e.message}`));
+    });
+  }
+
+  /**
+   * 预加载图片（异步）。url=图片地址，id=图片 id，返回尺寸/错误信息。
+   * 远程 URL 经 @ohos.net.http 下载为 ArrayBuffer 后再解码（image kit 不支持 http URL）。
+   */
+  preLoadImage(args: { url: string, id: number }): Promise<ImageInfo> {
+    return decodeImageToRGBA(args.url).then((rgba: RgbaPixels) => {
+      // 缓存解码结果，供后续 bindImageTexture/texImage2D 复用
+      this.decodedImagesBySource.set(args.url, rgba);
+      this.engine.cacheImage(args.id, rgba.buffer, rgba.width, rgba.height);
+      let info: ImageInfo = { width: rgba.width, height: rgba.height };
+      return info;
+    }).catch((e: Error) => {
+      hilogError(`preLoadImage failed: url=${args.url} err=${e.message}`);
+      let info: ImageInfo = { width: 0, height: 0, error: e.message };
+      return info;
+    });
+  }
+
+  /** 获取设备信息（异步）。返回 JSON 字符串。 */
+  getDeviceInfo(args: string): Promise<DeviceInfoRet> {
+    try {
+      const data = this.engine.getDeviceInfo(args);
+      let ret: DeviceInfoRet = { data };
+      return Promise.resolve(ret);
+    } catch (e) {
+      hilogError(`getDeviceInfo failed: args=${args}`);
+      let ret: DeviceInfoRet = { data: '' };
+      return Promise.resolve(ret);
+    }
+  }
+
+  /** 注册自定义字体族（同步）。fontNames 与 fontFiles 一一对应。 */
+  addFontFamily(fontNames: string[], fontFiles: string[]): void {
+    try {
+      this.engine.addFontFamily(fontNames, fontFiles);
+    } catch (e) {
+      hilogError('addFontFamily failed');
+    }
+  }
+
+  /** 枚举系统字体族名（同步）。 */
+  getFontNames(): string[] {
+    try {
+      return this.engine.getFontNames();
+    } catch (e) {
+      hilogError('getFontNames failed');
+      return [];
+    }
+  }
+
+  /** 设置额外字体目录（同步）。 */
+  setExtraFontLocation(location: string): void {
+    try {
+      this.engine.setExtraFontLocation(location);
+    } catch (e) {
+      hilogError(`setExtraFontLocation failed: location=${location}`);
+    }
+  }
+
+  /** 设置日志级别（异步）。 */
+  setLogLevel(level: number): Promise<void> {
+    try {
+      this.engine.setLogLevel(level);
+      return Promise.resolve();
+    } catch (e) {
+      hilogError(`setLogLevel failed: level=${level}`);
+      return Promise.reject(new Error('setLogLevel failed'));
+    }
+  }
+
+  /** 重置组件（异步）。 */
+  resetComponent(refId: string): Promise<void> {
+    try {
+      this.engine.resetComponent(refId);
+      return Promise.resolve();
+    } catch (e) {
+      hilogError(`resetComponent failed: refId=${refId}`);
+      return Promise.reject(new Error(`resetComponent failed: ${refId}`));
+    }
+  }
+
+  /** WebGL 纹理上传（同步）。图片须先由 GImage/preLoadImage 解码并按 src 缓存。 */
+  texImage2D(refId: string, target: number, level: number, internalformat: number, format: number,
+    type: number, src: string): void {
+    try {
+      const rgba = this.decodedImagesBySource.get(src);
+      if (!rgba) {
+        hilogError(`texImage2D image is not preloaded: src=${src}`);
+        return;
+      }
+      this.engine.texImage2D(refId, target, level, internalformat, format, type,
+        rgba.buffer, rgba.width, rgba.height);
+    } catch (e) {
+      hilogError(`texImage2D failed: refId=${refId}`);
+    }
+  }
+
+  /** WebGL 纹理子图上传（同步，鸿蒙新增分支）。命令 '105,9,...'。 */
+  texSubImage2D(refId: string, target: number, level: number, xoffset: number, yoffset: number,
+    format: number, type: number, src: string): void {
+    try {
+      const rgba = this.decodedImagesBySource.get(src);
+      if (!rgba) {
+        hilogError(`texSubImage2D image is not preloaded: src=${src}`);
+        return;
+      }
+      this.engine.texSubImage2D(refId, target, level, xoffset, yoffset, format, type,
+        rgba.buffer, rgba.width, rgba.height);
+    } catch (e) {
+      hilogError(`texSubImage2D failed: refId=${refId}`);
+    }
+  }
+
+  /** 设置组件 alpha（异步，原实现为空壳，鸿蒙同样空实现）。 */
+  setAlpha(refId: string, alpha: number): Promise<void> {
+    // 原生 Android/iOS 端 setAlpha 即为空实现，鸿蒙保持一致。
+    return Promise.resolve();
+  }
+}
+
+/**
+ * 解码图片为 RGBA 像素缓冲。
+ * 支持：沙箱/资源/$rawfile 路径、http(s) 远程 URL、data: URL。
+ * 远程 URL 先经 @ohos.net.http 下载为 ArrayBuffer（image.createImageSource 不支持 http）。
+ */
+async function decodeImageToRGBA(src: string): Promise<RgbaPixels> {
+  let buf: ArrayBuffer;
+  if (src.startsWith('http://') || src.startsWith('https://')) {
+    buf = await downloadToBuffer(src);
+  } else if (src.startsWith('data:')) {
+    buf = dataUrlToBuffer(src);
+  } else {
+    buf = await readLocalToBuffer(src);
+  }
+  let imageSource: image.ImageSource | null = null;
+  let pixelMap: image.PixelMap | null = null;
+  try {
+    imageSource = image.createImageSource(buf);
+    pixelMap = await imageSource.createPixelMap({ desiredPixelFormat: image.PixelMapFormat.RGBA_8888 });
+    const info = await pixelMap.getImageInfo();
+    const width: number = info.size.width;
+    const height: number = info.size.height;
+    const byteCount: number = pixelMap.getPixelBytesNumber();
+    const pixels: ArrayBuffer = new ArrayBuffer(byteCount);
+    await pixelMap.readPixelsToBuffer(pixels);
+    let ret: RgbaPixels = { buffer: pixels, width, height };
+    return ret;
+  } catch (e) {
+    hilog.error(DOMAIN, TAG, `decodeImageToRGBA failed: src=${src} err=${(e as Error).message}`);
+    throw e instanceof Error ? e : new Error(String(e));
+  } finally {
+    releaseDecodedImage(pixelMap, imageSource);
+  }
+}
+
+function releaseDecodedImage(pixelMap: image.PixelMap | null, imageSource: image.ImageSource | null): void {
+  if (pixelMap) {
+    try {
+      pixelMap.release();
+    } catch (e) {
+      hilog.error(DOMAIN, TAG, `release PixelMap failed: ${(e as Error).message}`);
+    }
+  }
+  if (imageSource) {
+    try {
+      imageSource.release();
+    } catch (e) {
+      hilog.error(DOMAIN, TAG, `release ImageSource failed: ${(e as Error).message}`);
+    }
+  }
+}
+
+/** 远程图片下载为 ArrayBuffer。 */
+async function downloadToBuffer(url: string): Promise<ArrayBuffer> {
+  let httpReq: http.HttpRequest | null = null;
+  try {
+    httpReq = http.createHttp();
+    const resp = await httpReq.request(url, {
+      method: http.RequestMethod.GET,
+      expectDataType: http.HttpDataType.ARRAY_BUFFER,
+    });
+    httpReq.destroy();
+    return resp.result as ArrayBuffer;
+  } catch (e) {
+    if (httpReq) {
+      httpReq.destroy();
+    }
+    hilog.error(DOMAIN, TAG, `downloadToBuffer failed: url=${url} err=${(e as Error).message}`);
+    throw e instanceof Error ? e : new Error(String(e));
+  }
+}
+
+/** data URL（base64）转 ArrayBuffer。 */
+function dataUrlToBuffer(dataUrl: string): ArrayBuffer {
+  try {
+    const base64Helper = new util.Base64Helper();
+    const commaIdx = dataUrl.indexOf(',');
+    const base64 = commaIdx >= 0 ? dataUrl.substring(commaIdx + 1) : dataUrl;
+    const bytes = base64Helper.decodeSync(base64);
+    return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
+  } catch (e) {
+    hilog.error(DOMAIN, TAG, `dataUrlToBuffer failed: err=${(e as Error).message}`);
+    throw e instanceof Error ? e : new Error(String(e));
+  }
+}
+
+/** 本地/资源文件读取为 ArrayBuffer。 */
+async function readLocalToBuffer(path: string): Promise<ArrayBuffer> {
+  let file: fs.File | null = null;
+  try {
+    file = fs.openSync(path, fs.OpenMode.READ_ONLY);
+    const stat = fs.statSync(path);
+    const buf: ArrayBuffer = new ArrayBuffer(stat.size);
+    await fs.read(file.fd, buf);
+    fs.closeSync(file);
+    return buf;
+  } catch (e) {
+    // 关闭文件也可能抛异常，且门禁要求 @kit 调用必须在 try/catch 内并用 hilog 记录。
+    if (file) {
+      try {
+        fs.closeSync(file);
+      } catch (ce) {
+        hilog.error(DOMAIN, TAG, `readLocalToBuffer close failed: path=${path} err=${(ce as Error).message}`);
+      }
+    }
+    hilog.error(DOMAIN, TAG, `readLocalToBuffer failed: path=${path} err=${(e as Error).message}`);
+    throw e instanceof Error ? e : new Error(String(e));
+  }
+}
+
+function errorMessage(e: Object): string {
+  try {
+    return e instanceof Error ? e.message : String(e);
+  } catch (_ignored) {
+    return 'unknown';
+  }
+}
+
+function hilogError(msg: string, e?: Object): void {
+  if (e === undefined) {
+    hilog.error(DOMAIN, TAG, msg);
+    return;
+  }
+  hilog.error(DOMAIN, TAG, `${msg} err=${errorMessage(e)}`);
+}
+
+/** extendCallNative 同步返回值。 */
+interface ExtendCallNativeResult {
+  result: string;
+}
+
+/** drawCanvas2Canvas 参数。 */
+interface DrawCanvas2CanvasMap {
+  srcComponentId: string;
+  dstComponentId: string;
+  tw: number;
+  th: number;
+  sx: number;
+  sy: number;
+  sw: number;
+  sh: number;
+  dx: number;
+  dy: number;
+  dw: number;
+  dh: number;
+}
+
+/** RGBA 像素解码结果。 */
+interface RgbaPixels {
+  buffer: ArrayBuffer;
+  width: number;
+  height: number;
+}
+
+/** preLoadImage 返回的图片信息。 */
+interface ImageInfo {
+  width: number;
+  height: number;
+  error?: string;
+}
+
+/** getDeviceInfo 返回。 */
+interface DeviceInfoRet {
+  data: string;
+}