@hxa-rn/react-native-gcanvas 6.0.24-beta.1 → 6.0.26

package/harmony/gcanvas/src/main/cpp/GCanvasNapi.cpp

@@ -1,485 +1,485 @@
-/**
- * GCanvasNapi — 把 C++ GCanvasEngine 以 NAPI 模块 'libgcanvas.so' 暴露给 ArkTS。
- *
- * ArkTS 侧 `import nativeModule from 'libgcanvas.so'`（GCanvasNativeEngine.ts）调用本模块
- * 导出的函数。模块名 gcanvas 与 XComponent libraryname 一致，故本 .so 同时承担：
- *   1. XComponent native window 回调（GCanvasXComponent.cpp 的 RegisterGCanvasModule）；
- *   2. ArkTS 可调用的命令/字体/纹理 NAPI 函数（本文件）。
- *
- * 注意：ArkTS NAPI 互操作中，对象字面量（如 enable 的 args: {componentId, config}）经
- * napi_value 传入，此处逐一取出字段。ArrayBuffer（像素缓冲）经 napi_get_arraybuffer_info 取指针。
- */
-#include "GCanvasEngine.h"
-
-#include <hilog/log.h>
-#include <napi/native_api.h>
-
-#include <cstdint>
-#include <limits>
-#include <string>
-#include <vector>
-
-#define GC_LOGI(...) OH_LOG_INFO(LOG_APP, __VA_ARGS__)
-#define GC_LOGE(...) OH_LOG_ERROR(LOG_APP, __VA_ARGS__)
-
-namespace {
-
-using namespace gcanvas;
-
-std::string NapiToString(napi_env env, napi_value value) {
-    if (value == nullptr) {
-        return "";
-    }
-    size_t len = 0;
-    if (napi_get_value_string_utf8(env, value, nullptr, 0, &len) != napi_ok) {
-        return "";
-    }
-    std::vector<char> buffer(len + 1U, '\0');
-    if (napi_get_value_string_utf8(env, value, buffer.data(), buffer.size(), &len) != napi_ok) {
-        return "";
-    }
-    return std::string(buffer.data(), len);
-}
-
-std::vector<double> NapiToDoubleArray(napi_env env, napi_value configValue) {
-    std::vector<double> config;
-    if (configValue == nullptr) {
-        return config;
-    }
-    uint32_t length = 0;
-    if (napi_get_array_length(env, configValue, &length) != napi_ok) {
-        return config;
-    }
-    config.reserve(length);
-    for (uint32_t i = 0; i < length; ++i) {
-        napi_value elem = nullptr;
-        napi_get_element(env, configValue, i, &elem);
-        double v = 0;
-        if (napi_get_value_double(env, elem, &v) == napi_ok) {
-            config.push_back(v);
-        }
-    }
-    return config;
-}
-
-int32_t GetNamedInt32(napi_env env, napi_value object, const char *name) {
-    napi_value value = nullptr;
-    int32_t result = 0;
-    if (object != nullptr && napi_get_named_property(env, object, name, &value) == napi_ok) {
-        napi_get_value_int32(env, value, &result);
-    }
-    return result;
-}
-
-std::string GetNamedString(napi_env env, napi_value object, const char *name) {
-    napi_value value = nullptr;
-    if (object == nullptr || napi_get_named_property(env, object, name, &value) != napi_ok) {
-        return "";
-    }
-    return NapiToString(env, value);
-}
-
-DrawCanvas2CanvasArgs ParseDrawMap(napi_env env, napi_value mapValue) {
-    DrawCanvas2CanvasArgs result;
-    result.srcComponentId = GetNamedString(env, mapValue, "srcComponentId");
-    result.dstComponentId = GetNamedString(env, mapValue, "dstComponentId");
-    result.tw = GetNamedInt32(env, mapValue, "tw");
-    result.th = GetNamedInt32(env, mapValue, "th");
-    result.sx = GetNamedInt32(env, mapValue, "sx");
-    result.sy = GetNamedInt32(env, mapValue, "sy");
-    result.sw = GetNamedInt32(env, mapValue, "sw");
-    result.sh = GetNamedInt32(env, mapValue, "sh");
-    result.dx = GetNamedInt32(env, mapValue, "dx");
-    result.dy = GetNamedInt32(env, mapValue, "dy");
-    result.dw = GetNamedInt32(env, mapValue, "dw");
-    result.dh = GetNamedInt32(env, mapValue, "dh");
-    return result;
-}
-
-std::vector<std::string> NapiToStringArray(napi_env env, napi_value value) {
-    std::vector<std::string> result;
-    if (value == nullptr) {
-        return result;
-    }
-    uint32_t length = 0;
-    napi_get_array_length(env, value, &length);
-    for (uint32_t i = 0; i < length; ++i) {
-        napi_value elem = nullptr;
-        napi_get_element(env, value, i, &elem);
-        result.push_back(NapiToString(env, elem));
-    }
-    return result;
-}
-
-napi_value MakeString(napi_env env, const std::string &str) {
-    napi_value result = nullptr;
-    napi_create_string_utf8(env, str.c_str(), str.length(), &result);
-    return result;
-}
-
-using NapiCb = napi_value (*)(napi_env, napi_callback_info);
-
-napi_value CreateFunction(napi_env env, NapiCb cb) {
-    napi_value fn = nullptr;
-    napi_create_function(env, "fn", NAPI_AUTO_LENGTH, cb, nullptr, &fn);
-    return fn;
-}
-
-void *GetArrayBuffer(napi_env env, napi_value value, size_t *length) {
-    void *data = nullptr;
-    *length = 0;
-    bool isArrayBuffer = false;
-    napi_is_arraybuffer(env, value, &isArrayBuffer);
-    if (!isArrayBuffer) {
-        return nullptr;
-    }
-    napi_get_arraybuffer_info(env, value, &data, length);
-    return data;
-}
-
-bool HasRgbaBytes(size_t actualLength, int32_t width, int32_t height) {
-    if (width <= 0 || height <= 0) {
-        return false;
-    }
-    const size_t w = static_cast<size_t>(width);
-    const size_t h = static_cast<size_t>(height);
-    return w <= std::numeric_limits<size_t>::max() / h &&
-        w * h <= std::numeric_limits<size_t>::max() / 4U && actualLength >= w * h * 4U;
-}
-
-#define NAPI_EXPORT(name, fn) napi_set_named_property(env, exports, name, fn)
-
-napi_value BindSurface(napi_env env, napi_callback_info info) {
-    size_t argc = 4;
-    napi_value args[4] = {nullptr};
-    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
-    std::string componentId = NapiToString(env, argc > 0 ? args[0] : nullptr);
-    int64_t window = 0;
-    if (argc > 1) {
-        napi_get_value_int64(env, args[1], &window);
-    }
-    double w = 0, h = 0;
-    if (argc > 2) { napi_get_value_double(env, args[2], &w); }
-    if (argc > 3) { napi_get_value_double(env, args[3], &h); }
-    if (!componentId.empty() && window != 0 && w > 0 && h > 0) {
-        GCanvasEngine::Instance().OnSurfaceCreated(
-            componentId, reinterpret_cast<void *>(static_cast<uintptr_t>(window)),
-            static_cast<uint64_t>(w), static_cast<uint64_t>(h));
-    }
-    return nullptr;
-}
-
-napi_value Enable(napi_env env, napi_callback_info info) {
-    size_t argc = 2;
-    napi_value args[2] = {nullptr};
-    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
-    const std::string componentId = NapiToString(env, argc > 0 ? args[0] : nullptr);
-    const std::vector<double> config = NapiToDoubleArray(env, argc > 1 ? args[1] : nullptr);
-    GCanvasEngine::Instance().Enable(componentId, config);
-    return nullptr;
-}
-
-napi_value Disable(napi_env env, napi_callback_info info) {
-    size_t argc = 1;
-    napi_value argv[1] = {nullptr};
-    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
-    GCanvasEngine::Instance().Disable(NapiToString(env, argv[0]));
-    return nullptr;
-}
-
-napi_value Render(napi_env env, napi_callback_info info) {
-    size_t argc = 3;
-    napi_value argv[3] = {nullptr};
-    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
-    std::string canvasId = NapiToString(env, argc > 0 ? argv[0] : nullptr);
-    std::string cmd = NapiToString(env, argc > 1 ? argv[1] : nullptr);
-    int32_t type = 0;
-    if (argc > 2) { napi_get_value_int32(env, argv[2], &type); }
-    GCanvasEngine::Instance().Render(canvasId, cmd, type);
-    return nullptr;
-}
-
-napi_value ExtendCallNative(napi_env env, napi_callback_info info) {
-    size_t argc = 3;
-    napi_value argv[3] = {nullptr};
-    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
-    const std::string contextId = NapiToString(env, argc > 0 ? argv[0] : nullptr);
-    const std::string args = NapiToString(env, argc > 1 ? argv[1] : nullptr);
-    int32_t type = 0;
-    if (argc > 2) { napi_get_value_int32(env, argv[2], &type); }
-    std::string result = GCanvasEngine::Instance().ExtendCallNative(contextId, args, type);
-    return MakeString(env, result);
-}
-
-napi_value SetContextType(napi_env env, napi_callback_info info) {
-    size_t argc = 2;
-    napi_value argv[2] = {nullptr};
-    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
-    int32_t contextType = 0;
-    if (argc > 0) { napi_get_value_int32(env, argv[0], &contextType); }
-    std::string refId = NapiToString(env, argc > 1 ? argv[1] : nullptr);
-    GCanvasEngine::Instance().SetContextType(contextType, refId);
-    return nullptr;
-}
-
-napi_value SetDevicePixelRatio(napi_env env, napi_callback_info info) {
-    size_t argc = 2;
-    napi_value argv[2] = {nullptr};
-    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
-    std::string refId = NapiToString(env, argc > 0 ? argv[0] : nullptr);
-    double ratio = 1;
-    if (argc > 1) { napi_get_value_double(env, argv[1], &ratio); }
-    GCanvasEngine::Instance().SetDevicePixelRatio(refId, ratio);
-    return nullptr;
-}
-
-napi_value ResetGlViewport(napi_env env, napi_callback_info info) {
-    size_t argc = 1;
-    napi_value argv[1] = {nullptr};
-    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
-    GCanvasEngine::Instance().ResetGlViewport(NapiToString(env, argv[0]));
-    return nullptr;
-}
-
-napi_value ToDataURL(napi_env env, napi_callback_info info) {
-    size_t argc = 3;
-    napi_value argv[3] = {nullptr};
-    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
-    std::string refId = NapiToString(env, argc > 0 ? argv[0] : nullptr);
-    std::string mime = NapiToString(env, argc > 1 ? argv[1] : nullptr);
-    double quality = 1;
-    if (argc > 2) { napi_get_value_double(env, argv[2], &quality); }
-    std::string result = GCanvasEngine::Instance().ToDataURL(refId, mime, quality);
-    return MakeString(env, result);
-}
-
-napi_value DrawCanvas2Canvas(napi_env env, napi_callback_info info) {
-    size_t argc = 1;
-    napi_value argv[1] = {nullptr};
-    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
-    GCanvasEngine::Instance().DrawCanvas2Canvas(ParseDrawMap(env, argc > 0 ? argv[0] : nullptr));
-    return nullptr;
-}
-
-napi_value BindImageTexture(napi_env env, napi_callback_info info) {
-    size_t argc = 5;
-    napi_value argv[5] = {nullptr};
-    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
-    std::string refId = NapiToString(env, argc > 0 ? argv[0] : nullptr);
-    int32_t imageId = 0;
-    if (argc > 1) { napi_get_value_int32(env, argv[1], &imageId); }
-    size_t length = 0;
-    void *pixels = GetArrayBuffer(env, argc > 2 ? argv[2] : nullptr, &length);
-    int32_t width = 0, height = 0;
-    if (argc > 3) { napi_get_value_int32(env, argv[3], &width); }
-    if (argc > 4) { napi_get_value_int32(env, argv[4], &height); }
-    if (HasRgbaBytes(length, width, height)) {
-        GCanvasEngine::Instance().BindImageTexture(refId, imageId, pixels, width, height);
-    }
-    return nullptr;
-}
-
-napi_value BindCachedImageTexture(napi_env env, napi_callback_info info) {
-    size_t argc = 2;
-    napi_value argv[2] = {nullptr};
-    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
-    const std::string refId = NapiToString(env, argc > 0 ? argv[0] : nullptr);
-    int32_t imageId = 0;
-    if (argc > 1) { napi_get_value_int32(env, argv[1], &imageId); }
-    napi_value result = nullptr;
-    napi_get_boolean(env, GCanvasEngine::Instance().BindCachedImageTexture(refId, imageId), &result);
-    return result;
-}
-
-napi_value CacheImage(napi_env env, napi_callback_info info) {
-    size_t argc = 4;
-    napi_value argv[4] = {nullptr};
-    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
-    int32_t id = 0;
-    if (argc > 0) { napi_get_value_int32(env, argv[0], &id); }
-    size_t length = 0;
-    void *pixels = GetArrayBuffer(env, argc > 1 ? argv[1] : nullptr, &length);
-    int32_t width = 0, height = 0;
-    if (argc > 2) { napi_get_value_int32(env, argv[2], &width); }
-    if (argc > 3) { napi_get_value_int32(env, argv[3], &height); }
-    if (HasRgbaBytes(length, width, height)) {
-        GCanvasEngine::Instance().CacheImage(id, pixels, width, height);
-    }
-    return nullptr;
-}
-
-napi_value GetDeviceInfo(napi_env env, napi_callback_info info) {
-    size_t argc = 1;
-    napi_value argv[1] = {nullptr};
-    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
-    std::string args = NapiToString(env, argc > 0 ? argv[0] : nullptr);
-    return MakeString(env, GCanvasEngine::Instance().GetDeviceInfo(args));
-}
-
-napi_value AddFontFamily(napi_env env, napi_callback_info info) {
-    size_t argc = 2;
-    napi_value argv[2] = {nullptr};
-    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
-    auto names = NapiToStringArray(env, argc > 0 ? argv[0] : nullptr);
-    auto files = NapiToStringArray(env, argc > 1 ? argv[1] : nullptr);
-    GCanvasEngine::Instance().AddFontFamily(names, files);
-    return nullptr;
-}
-
-napi_value GetFontNames(napi_env env, napi_callback_info info) {
-    (void)info;
-    auto names = GCanvasEngine::Instance().GetFontNames();
-    napi_value result = nullptr;
-    napi_create_array_with_length(env, names.size(), &result);
-    for (size_t i = 0; i < names.size(); ++i) {
-        napi_set_element(env, result, static_cast<uint32_t>(i), MakeString(env, names[i]));
-    }
-    return result;
-}
-
-napi_value SetExtraFontLocation(napi_env env, napi_callback_info info) {
-    size_t argc = 1;
-    napi_value argv[1] = {nullptr};
-    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
-    GCanvasEngine::Instance().SetExtraFontLocation(NapiToString(env, argv[0]));
-    return nullptr;
-}
-
-napi_value SetLogLevel(napi_env env, napi_callback_info info) {
-    size_t argc = 1;
-    napi_value argv[1] = {nullptr};
-    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
-    int32_t level = 0;
-    if (argc > 0) { napi_get_value_int32(env, argv[0], &level); }
-    GCanvasEngine::Instance().SetLogLevel(level);
-    return nullptr;
-}
-
-napi_value ResetComponent(napi_env env, napi_callback_info info) {
-    size_t argc = 1;
-    napi_value argv[1] = {nullptr};
-    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
-    GCanvasEngine::Instance().ResetComponent(NapiToString(env, argv[0]));
-    return nullptr;
-}
-
-napi_value SurfaceChanged(napi_env env, napi_callback_info info) {
-    size_t argc = 3;
-    napi_value argv[3] = {nullptr};
-    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
-    const std::string componentId = NapiToString(env, argc > 0 ? argv[0] : nullptr);
-    double width = 0;
-    double height = 0;
-    if (argc > 1) { napi_get_value_double(env, argv[1], &width); }
-    if (argc > 2) { napi_get_value_double(env, argv[2], &height); }
-    if (!componentId.empty() && width > 0 && height > 0) {
-        GCanvasEngine::Instance().OnSurfaceChanged(componentId, nullptr,
-                                                    static_cast<uint64_t>(width),
-                                                    static_cast<uint64_t>(height));
-    }
-    return nullptr;
-}
-
-napi_value SurfaceDestroyed(napi_env env, napi_callback_info info) {
-    size_t argc = 1;
-    napi_value argv[1] = {nullptr};
-    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
-    const std::string componentId = NapiToString(env, argc > 0 ? argv[0] : nullptr);
-    if (!componentId.empty()) {
-        GCanvasEngine::Instance().OnSurfaceDestroyed(componentId);
-    }
-    return nullptr;
-}
-
-napi_value ConfigureView(napi_env env, napi_callback_info info) {
-    size_t argc = 2;
-    napi_value argv[2] = {nullptr};
-    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
-    const std::string refId = NapiToString(env, argc > 0 ? argv[0] : nullptr);
-    bool enableFboMsaa = false;
-    if (argc > 1) { napi_get_value_bool(env, argv[1], &enableFboMsaa); }
-    GCanvasEngine::Instance().ConfigureView(refId, enableFboMsaa);
-    return nullptr;
-}
-
-napi_value TexImage2D(napi_env env, napi_callback_info info) {
-    size_t argc = 9;
-    napi_value argv[9] = {nullptr};
-    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
-    std::string refId = NapiToString(env, argc > 0 ? argv[0] : nullptr);
-    int32_t target = 0, level = 0, internalformat = 0, format = 0, type = 0, width = 0, height = 0;
-    if (argc > 1) { napi_get_value_int32(env, argv[1], &target); }
-    if (argc > 2) { napi_get_value_int32(env, argv[2], &level); }
-    if (argc > 3) { napi_get_value_int32(env, argv[3], &internalformat); }
-    if (argc > 4) { napi_get_value_int32(env, argv[4], &format); }
-    if (argc > 5) { napi_get_value_int32(env, argv[5], &type); }
-    size_t length = 0;
-    void *pixels = GetArrayBuffer(env, argc > 6 ? argv[6] : nullptr, &length);
-    if (argc > 7) { napi_get_value_int32(env, argv[7], &width); }
-    if (argc > 8) { napi_get_value_int32(env, argv[8], &height); }
-    if (HasRgbaBytes(length, width, height)) {
-        GCanvasEngine::Instance().TexImage2D(refId, target, level, internalformat, format, type,
-                                             pixels, width, height);
-    }
-    return nullptr;
-}
-
-napi_value TexSubImage2D(napi_env env, napi_callback_info info) {
-    size_t argc = 10;
-    napi_value argv[10] = {nullptr};
-    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
-    std::string refId = NapiToString(env, argc > 0 ? argv[0] : nullptr);
-    int32_t target = 0, level = 0, xoffset = 0, yoffset = 0, format = 0, type = 0, width = 0, height = 0;
-    if (argc > 1) { napi_get_value_int32(env, argv[1], &target); }
-    if (argc > 2) { napi_get_value_int32(env, argv[2], &level); }
-    if (argc > 3) { napi_get_value_int32(env, argv[3], &xoffset); }
-    if (argc > 4) { napi_get_value_int32(env, argv[4], &yoffset); }
-    if (argc > 5) { napi_get_value_int32(env, argv[5], &format); }
-    if (argc > 6) { napi_get_value_int32(env, argv[6], &type); }
-    size_t length = 0;
-    void *pixels = GetArrayBuffer(env, argc > 7 ? argv[7] : nullptr, &length);
-    if (argc > 8) { napi_get_value_int32(env, argv[8], &width); }
-    if (argc > 9) { napi_get_value_int32(env, argv[9], &height); }
-    if (HasRgbaBytes(length, width, height)) {
-        GCanvasEngine::Instance().TexSubImage2D(refId, target, level, xoffset, yoffset, format, type,
-                                                pixels, width, height);
-    }
-    return nullptr;
-}
-
-napi_value InitExports(napi_env env, napi_value exports) {
-    NAPI_EXPORT("bindSurface", CreateFunction(env, BindSurface));
-    NAPI_EXPORT("surfaceChanged", CreateFunction(env, SurfaceChanged));
-    NAPI_EXPORT("surfaceDestroyed", CreateFunction(env, SurfaceDestroyed));
-    NAPI_EXPORT("configureView", CreateFunction(env, ConfigureView));
-    NAPI_EXPORT("enable", CreateFunction(env, Enable));
-    NAPI_EXPORT("disable", CreateFunction(env, Disable));
-    NAPI_EXPORT("render", CreateFunction(env, Render));
-    NAPI_EXPORT("extendCallNative", CreateFunction(env, ExtendCallNative));
-    NAPI_EXPORT("setContextType", CreateFunction(env, SetContextType));
-    NAPI_EXPORT("setDevicePixelRatio", CreateFunction(env, SetDevicePixelRatio));
-    NAPI_EXPORT("resetGlViewport", CreateFunction(env, ResetGlViewport));
-    NAPI_EXPORT("toDataURL", CreateFunction(env, ToDataURL));
-    NAPI_EXPORT("drawCanvas2Canvas", CreateFunction(env, DrawCanvas2Canvas));
-    NAPI_EXPORT("bindImageTexture", CreateFunction(env, BindImageTexture));
-    NAPI_EXPORT("bindCachedImageTexture", CreateFunction(env, BindCachedImageTexture));
-    NAPI_EXPORT("cacheImage", CreateFunction(env, CacheImage));
-    NAPI_EXPORT("getDeviceInfo", CreateFunction(env, GetDeviceInfo));
-    NAPI_EXPORT("addFontFamily", CreateFunction(env, AddFontFamily));
-    NAPI_EXPORT("getFontNames", CreateFunction(env, GetFontNames));
-    NAPI_EXPORT("setExtraFontLocation", CreateFunction(env, SetExtraFontLocation));
-    NAPI_EXPORT("setLogLevel", CreateFunction(env, SetLogLevel));
-    NAPI_EXPORT("resetComponent", CreateFunction(env, ResetComponent));
-    NAPI_EXPORT("texImage2D", CreateFunction(env, TexImage2D));
-    NAPI_EXPORT("texSubImage2D", CreateFunction(env, TexSubImage2D));
-    return exports;
-}
-
-} // namespace
-
-// 由 GCanvasXComponent.cpp 的 Init() 调用，统一在 'gcanvas' napi_module 的 exports 上注册
-// 全部 ArkTS 可调函数。XComponent 回调注册与 NAPI 函数导出共用同一 .so / 同一模块。
-extern "C" napi_value GCanvasNapi_Init(napi_env env, napi_value exports) {
-    GC_LOGI("GCanvasNapi_Init registered enable/render/extendCallNative");
-    return InitExports(env, exports);
-}
+/**
+ * GCanvasNapi — 把 C++ GCanvasEngine 以 NAPI 模块 'libgcanvas.so' 暴露给 ArkTS。
+ *
+ * ArkTS 侧 `import nativeModule from 'libgcanvas.so'`（GCanvasNativeEngine.ts）调用本模块
+ * 导出的函数。模块名 gcanvas 与 XComponent libraryname 一致，故本 .so 同时承担：
+ *   1. XComponent native window 回调（GCanvasXComponent.cpp 的 RegisterGCanvasModule）；
+ *   2. ArkTS 可调用的命令/字体/纹理 NAPI 函数（本文件）。
+ *
+ * 注意：ArkTS NAPI 互操作中，对象字面量（如 enable 的 args: {componentId, config}）经
+ * napi_value 传入，此处逐一取出字段。ArrayBuffer（像素缓冲）经 napi_get_arraybuffer_info 取指针。
+ */
+#include "GCanvasEngine.h"
+
+#include <hilog/log.h>
+#include <napi/native_api.h>
+
+#include <cstdint>
+#include <limits>
+#include <string>
+#include <vector>
+
+#define GC_LOGI(...) OH_LOG_INFO(LOG_APP, __VA_ARGS__)
+#define GC_LOGE(...) OH_LOG_ERROR(LOG_APP, __VA_ARGS__)
+
+namespace {
+
+using namespace gcanvas;
+
+std::string NapiToString(napi_env env, napi_value value) {
+    if (value == nullptr) {
+        return "";
+    }
+    size_t len = 0;
+    if (napi_get_value_string_utf8(env, value, nullptr, 0, &len) != napi_ok) {
+        return "";
+    }
+    std::vector<char> buffer(len + 1U, '\0');
+    if (napi_get_value_string_utf8(env, value, buffer.data(), buffer.size(), &len) != napi_ok) {
+        return "";
+    }
+    return std::string(buffer.data(), len);
+}
+
+std::vector<double> NapiToDoubleArray(napi_env env, napi_value configValue) {
+    std::vector<double> config;
+    if (configValue == nullptr) {
+        return config;
+    }
+    uint32_t length = 0;
+    if (napi_get_array_length(env, configValue, &length) != napi_ok) {
+        return config;
+    }
+    config.reserve(length);
+    for (uint32_t i = 0; i < length; ++i) {
+        napi_value elem = nullptr;
+        napi_get_element(env, configValue, i, &elem);
+        double v = 0;
+        if (napi_get_value_double(env, elem, &v) == napi_ok) {
+            config.push_back(v);
+        }
+    }
+    return config;
+}
+
+int32_t GetNamedInt32(napi_env env, napi_value object, const char *name) {
+    napi_value value = nullptr;
+    int32_t result = 0;
+    if (object != nullptr && napi_get_named_property(env, object, name, &value) == napi_ok) {
+        napi_get_value_int32(env, value, &result);
+    }
+    return result;
+}
+
+std::string GetNamedString(napi_env env, napi_value object, const char *name) {
+    napi_value value = nullptr;
+    if (object == nullptr || napi_get_named_property(env, object, name, &value) != napi_ok) {
+        return "";
+    }
+    return NapiToString(env, value);
+}
+
+DrawCanvas2CanvasArgs ParseDrawMap(napi_env env, napi_value mapValue) {
+    DrawCanvas2CanvasArgs result;
+    result.srcComponentId = GetNamedString(env, mapValue, "srcComponentId");
+    result.dstComponentId = GetNamedString(env, mapValue, "dstComponentId");
+    result.tw = GetNamedInt32(env, mapValue, "tw");
+    result.th = GetNamedInt32(env, mapValue, "th");
+    result.sx = GetNamedInt32(env, mapValue, "sx");
+    result.sy = GetNamedInt32(env, mapValue, "sy");
+    result.sw = GetNamedInt32(env, mapValue, "sw");
+    result.sh = GetNamedInt32(env, mapValue, "sh");
+    result.dx = GetNamedInt32(env, mapValue, "dx");
+    result.dy = GetNamedInt32(env, mapValue, "dy");
+    result.dw = GetNamedInt32(env, mapValue, "dw");
+    result.dh = GetNamedInt32(env, mapValue, "dh");
+    return result;
+}
+
+std::vector<std::string> NapiToStringArray(napi_env env, napi_value value) {
+    std::vector<std::string> result;
+    if (value == nullptr) {
+        return result;
+    }
+    uint32_t length = 0;
+    napi_get_array_length(env, value, &length);
+    for (uint32_t i = 0; i < length; ++i) {
+        napi_value elem = nullptr;
+        napi_get_element(env, value, i, &elem);
+        result.push_back(NapiToString(env, elem));
+    }
+    return result;
+}
+
+napi_value MakeString(napi_env env, const std::string &str) {
+    napi_value result = nullptr;
+    napi_create_string_utf8(env, str.c_str(), str.length(), &result);
+    return result;
+}
+
+using NapiCb = napi_value (*)(napi_env, napi_callback_info);
+
+napi_value CreateFunction(napi_env env, NapiCb cb) {
+    napi_value fn = nullptr;
+    napi_create_function(env, "fn", NAPI_AUTO_LENGTH, cb, nullptr, &fn);
+    return fn;
+}
+
+void *GetArrayBuffer(napi_env env, napi_value value, size_t *length) {
+    void *data = nullptr;
+    *length = 0;
+    bool isArrayBuffer = false;
+    napi_is_arraybuffer(env, value, &isArrayBuffer);
+    if (!isArrayBuffer) {
+        return nullptr;
+    }
+    napi_get_arraybuffer_info(env, value, &data, length);
+    return data;
+}
+
+bool HasRgbaBytes(size_t actualLength, int32_t width, int32_t height) {
+    if (width <= 0 || height <= 0) {
+        return false;
+    }
+    const size_t w = static_cast<size_t>(width);
+    const size_t h = static_cast<size_t>(height);
+    return w <= std::numeric_limits<size_t>::max() / h &&
+        w * h <= std::numeric_limits<size_t>::max() / 4U && actualLength >= w * h * 4U;
+}
+
+#define NAPI_EXPORT(name, fn) napi_set_named_property(env, exports, name, fn)
+
+napi_value BindSurface(napi_env env, napi_callback_info info) {
+    size_t argc = 4;
+    napi_value args[4] = {nullptr};
+    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
+    std::string componentId = NapiToString(env, argc > 0 ? args[0] : nullptr);
+    int64_t window = 0;
+    if (argc > 1) {
+        napi_get_value_int64(env, args[1], &window);
+    }
+    double w = 0, h = 0;
+    if (argc > 2) { napi_get_value_double(env, args[2], &w); }
+    if (argc > 3) { napi_get_value_double(env, args[3], &h); }
+    if (!componentId.empty() && window != 0 && w > 0 && h > 0) {
+        GCanvasEngine::Instance().OnSurfaceCreated(
+            componentId, reinterpret_cast<void *>(static_cast<uintptr_t>(window)),
+            static_cast<uint64_t>(w), static_cast<uint64_t>(h));
+    }
+    return nullptr;
+}
+
+napi_value Enable(napi_env env, napi_callback_info info) {
+    size_t argc = 2;
+    napi_value args[2] = {nullptr};
+    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
+    const std::string componentId = NapiToString(env, argc > 0 ? args[0] : nullptr);
+    const std::vector<double> config = NapiToDoubleArray(env, argc > 1 ? args[1] : nullptr);
+    GCanvasEngine::Instance().Enable(componentId, config);
+    return nullptr;
+}
+
+napi_value Disable(napi_env env, napi_callback_info info) {
+    size_t argc = 1;
+    napi_value argv[1] = {nullptr};
+    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+    GCanvasEngine::Instance().Disable(NapiToString(env, argv[0]));
+    return nullptr;
+}
+
+napi_value Render(napi_env env, napi_callback_info info) {
+    size_t argc = 3;
+    napi_value argv[3] = {nullptr};
+    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+    std::string canvasId = NapiToString(env, argc > 0 ? argv[0] : nullptr);
+    std::string cmd = NapiToString(env, argc > 1 ? argv[1] : nullptr);
+    int32_t type = 0;
+    if (argc > 2) { napi_get_value_int32(env, argv[2], &type); }
+    GCanvasEngine::Instance().Render(canvasId, cmd, type);
+    return nullptr;
+}
+
+napi_value ExtendCallNative(napi_env env, napi_callback_info info) {
+    size_t argc = 3;
+    napi_value argv[3] = {nullptr};
+    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+    const std::string contextId = NapiToString(env, argc > 0 ? argv[0] : nullptr);
+    const std::string args = NapiToString(env, argc > 1 ? argv[1] : nullptr);
+    int32_t type = 0;
+    if (argc > 2) { napi_get_value_int32(env, argv[2], &type); }
+    std::string result = GCanvasEngine::Instance().ExtendCallNative(contextId, args, type);
+    return MakeString(env, result);
+}
+
+napi_value SetContextType(napi_env env, napi_callback_info info) {
+    size_t argc = 2;
+    napi_value argv[2] = {nullptr};
+    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+    int32_t contextType = 0;
+    if (argc > 0) { napi_get_value_int32(env, argv[0], &contextType); }
+    std::string refId = NapiToString(env, argc > 1 ? argv[1] : nullptr);
+    GCanvasEngine::Instance().SetContextType(contextType, refId);
+    return nullptr;
+}
+
+napi_value SetDevicePixelRatio(napi_env env, napi_callback_info info) {
+    size_t argc = 2;
+    napi_value argv[2] = {nullptr};
+    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+    std::string refId = NapiToString(env, argc > 0 ? argv[0] : nullptr);
+    double ratio = 1;
+    if (argc > 1) { napi_get_value_double(env, argv[1], &ratio); }
+    GCanvasEngine::Instance().SetDevicePixelRatio(refId, ratio);
+    return nullptr;
+}
+
+napi_value ResetGlViewport(napi_env env, napi_callback_info info) {
+    size_t argc = 1;
+    napi_value argv[1] = {nullptr};
+    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+    GCanvasEngine::Instance().ResetGlViewport(NapiToString(env, argv[0]));
+    return nullptr;
+}
+
+napi_value ToDataURL(napi_env env, napi_callback_info info) {
+    size_t argc = 3;
+    napi_value argv[3] = {nullptr};
+    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+    std::string refId = NapiToString(env, argc > 0 ? argv[0] : nullptr);
+    std::string mime = NapiToString(env, argc > 1 ? argv[1] : nullptr);
+    double quality = 1;
+    if (argc > 2) { napi_get_value_double(env, argv[2], &quality); }
+    std::string result = GCanvasEngine::Instance().ToDataURL(refId, mime, quality);
+    return MakeString(env, result);
+}
+
+napi_value DrawCanvas2Canvas(napi_env env, napi_callback_info info) {
+    size_t argc = 1;
+    napi_value argv[1] = {nullptr};
+    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+    GCanvasEngine::Instance().DrawCanvas2Canvas(ParseDrawMap(env, argc > 0 ? argv[0] : nullptr));
+    return nullptr;
+}
+
+napi_value BindImageTexture(napi_env env, napi_callback_info info) {
+    size_t argc = 5;
+    napi_value argv[5] = {nullptr};
+    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+    std::string refId = NapiToString(env, argc > 0 ? argv[0] : nullptr);
+    int32_t imageId = 0;
+    if (argc > 1) { napi_get_value_int32(env, argv[1], &imageId); }
+    size_t length = 0;
+    void *pixels = GetArrayBuffer(env, argc > 2 ? argv[2] : nullptr, &length);
+    int32_t width = 0, height = 0;
+    if (argc > 3) { napi_get_value_int32(env, argv[3], &width); }
+    if (argc > 4) { napi_get_value_int32(env, argv[4], &height); }
+    if (HasRgbaBytes(length, width, height)) {
+        GCanvasEngine::Instance().BindImageTexture(refId, imageId, pixels, width, height);
+    }
+    return nullptr;
+}
+
+napi_value BindCachedImageTexture(napi_env env, napi_callback_info info) {
+    size_t argc = 2;
+    napi_value argv[2] = {nullptr};
+    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+    const std::string refId = NapiToString(env, argc > 0 ? argv[0] : nullptr);
+    int32_t imageId = 0;
+    if (argc > 1) { napi_get_value_int32(env, argv[1], &imageId); }
+    napi_value result = nullptr;
+    napi_get_boolean(env, GCanvasEngine::Instance().BindCachedImageTexture(refId, imageId), &result);
+    return result;
+}
+
+napi_value CacheImage(napi_env env, napi_callback_info info) {
+    size_t argc = 4;
+    napi_value argv[4] = {nullptr};
+    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+    int32_t id = 0;
+    if (argc > 0) { napi_get_value_int32(env, argv[0], &id); }
+    size_t length = 0;
+    void *pixels = GetArrayBuffer(env, argc > 1 ? argv[1] : nullptr, &length);
+    int32_t width = 0, height = 0;
+    if (argc > 2) { napi_get_value_int32(env, argv[2], &width); }
+    if (argc > 3) { napi_get_value_int32(env, argv[3], &height); }
+    if (HasRgbaBytes(length, width, height)) {
+        GCanvasEngine::Instance().CacheImage(id, pixels, width, height);
+    }
+    return nullptr;
+}
+
+napi_value GetDeviceInfo(napi_env env, napi_callback_info info) {
+    size_t argc = 1;
+    napi_value argv[1] = {nullptr};
+    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+    std::string args = NapiToString(env, argc > 0 ? argv[0] : nullptr);
+    return MakeString(env, GCanvasEngine::Instance().GetDeviceInfo(args));
+}
+
+napi_value AddFontFamily(napi_env env, napi_callback_info info) {
+    size_t argc = 2;
+    napi_value argv[2] = {nullptr};
+    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+    auto names = NapiToStringArray(env, argc > 0 ? argv[0] : nullptr);
+    auto files = NapiToStringArray(env, argc > 1 ? argv[1] : nullptr);
+    GCanvasEngine::Instance().AddFontFamily(names, files);
+    return nullptr;
+}
+
+napi_value GetFontNames(napi_env env, napi_callback_info info) {
+    (void)info;
+    auto names = GCanvasEngine::Instance().GetFontNames();
+    napi_value result = nullptr;
+    napi_create_array_with_length(env, names.size(), &result);
+    for (size_t i = 0; i < names.size(); ++i) {
+        napi_set_element(env, result, static_cast<uint32_t>(i), MakeString(env, names[i]));
+    }
+    return result;
+}
+
+napi_value SetExtraFontLocation(napi_env env, napi_callback_info info) {
+    size_t argc = 1;
+    napi_value argv[1] = {nullptr};
+    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+    GCanvasEngine::Instance().SetExtraFontLocation(NapiToString(env, argv[0]));
+    return nullptr;
+}
+
+napi_value SetLogLevel(napi_env env, napi_callback_info info) {
+    size_t argc = 1;
+    napi_value argv[1] = {nullptr};
+    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+    int32_t level = 0;
+    if (argc > 0) { napi_get_value_int32(env, argv[0], &level); }
+    GCanvasEngine::Instance().SetLogLevel(level);
+    return nullptr;
+}
+
+napi_value ResetComponent(napi_env env, napi_callback_info info) {
+    size_t argc = 1;
+    napi_value argv[1] = {nullptr};
+    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+    GCanvasEngine::Instance().ResetComponent(NapiToString(env, argv[0]));
+    return nullptr;
+}
+
+napi_value SurfaceChanged(napi_env env, napi_callback_info info) {
+    size_t argc = 3;
+    napi_value argv[3] = {nullptr};
+    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+    const std::string componentId = NapiToString(env, argc > 0 ? argv[0] : nullptr);
+    double width = 0;
+    double height = 0;
+    if (argc > 1) { napi_get_value_double(env, argv[1], &width); }
+    if (argc > 2) { napi_get_value_double(env, argv[2], &height); }
+    if (!componentId.empty() && width > 0 && height > 0) {
+        GCanvasEngine::Instance().OnSurfaceChanged(componentId, nullptr,
+                                                    static_cast<uint64_t>(width),
+                                                    static_cast<uint64_t>(height));
+    }
+    return nullptr;
+}
+
+napi_value SurfaceDestroyed(napi_env env, napi_callback_info info) {
+    size_t argc = 1;
+    napi_value argv[1] = {nullptr};
+    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+    const std::string componentId = NapiToString(env, argc > 0 ? argv[0] : nullptr);
+    if (!componentId.empty()) {
+        GCanvasEngine::Instance().OnSurfaceDestroyed(componentId);
+    }
+    return nullptr;
+}
+
+napi_value ConfigureView(napi_env env, napi_callback_info info) {
+    size_t argc = 2;
+    napi_value argv[2] = {nullptr};
+    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+    const std::string refId = NapiToString(env, argc > 0 ? argv[0] : nullptr);
+    bool enableFboMsaa = false;
+    if (argc > 1) { napi_get_value_bool(env, argv[1], &enableFboMsaa); }
+    GCanvasEngine::Instance().ConfigureView(refId, enableFboMsaa);
+    return nullptr;
+}
+
+napi_value TexImage2D(napi_env env, napi_callback_info info) {
+    size_t argc = 9;
+    napi_value argv[9] = {nullptr};
+    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+    std::string refId = NapiToString(env, argc > 0 ? argv[0] : nullptr);
+    int32_t target = 0, level = 0, internalformat = 0, format = 0, type = 0, width = 0, height = 0;
+    if (argc > 1) { napi_get_value_int32(env, argv[1], &target); }
+    if (argc > 2) { napi_get_value_int32(env, argv[2], &level); }
+    if (argc > 3) { napi_get_value_int32(env, argv[3], &internalformat); }
+    if (argc > 4) { napi_get_value_int32(env, argv[4], &format); }
+    if (argc > 5) { napi_get_value_int32(env, argv[5], &type); }
+    size_t length = 0;
+    void *pixels = GetArrayBuffer(env, argc > 6 ? argv[6] : nullptr, &length);
+    if (argc > 7) { napi_get_value_int32(env, argv[7], &width); }
+    if (argc > 8) { napi_get_value_int32(env, argv[8], &height); }
+    if (HasRgbaBytes(length, width, height)) {
+        GCanvasEngine::Instance().TexImage2D(refId, target, level, internalformat, format, type,
+                                             pixels, width, height);
+    }
+    return nullptr;
+}
+
+napi_value TexSubImage2D(napi_env env, napi_callback_info info) {
+    size_t argc = 10;
+    napi_value argv[10] = {nullptr};
+    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+    std::string refId = NapiToString(env, argc > 0 ? argv[0] : nullptr);
+    int32_t target = 0, level = 0, xoffset = 0, yoffset = 0, format = 0, type = 0, width = 0, height = 0;
+    if (argc > 1) { napi_get_value_int32(env, argv[1], &target); }
+    if (argc > 2) { napi_get_value_int32(env, argv[2], &level); }
+    if (argc > 3) { napi_get_value_int32(env, argv[3], &xoffset); }
+    if (argc > 4) { napi_get_value_int32(env, argv[4], &yoffset); }
+    if (argc > 5) { napi_get_value_int32(env, argv[5], &format); }
+    if (argc > 6) { napi_get_value_int32(env, argv[6], &type); }
+    size_t length = 0;
+    void *pixels = GetArrayBuffer(env, argc > 7 ? argv[7] : nullptr, &length);
+    if (argc > 8) { napi_get_value_int32(env, argv[8], &width); }
+    if (argc > 9) { napi_get_value_int32(env, argv[9], &height); }
+    if (HasRgbaBytes(length, width, height)) {
+        GCanvasEngine::Instance().TexSubImage2D(refId, target, level, xoffset, yoffset, format, type,
+                                                pixels, width, height);
+    }
+    return nullptr;
+}
+
+napi_value InitExports(napi_env env, napi_value exports) {
+    NAPI_EXPORT("bindSurface", CreateFunction(env, BindSurface));
+    NAPI_EXPORT("surfaceChanged", CreateFunction(env, SurfaceChanged));
+    NAPI_EXPORT("surfaceDestroyed", CreateFunction(env, SurfaceDestroyed));
+    NAPI_EXPORT("configureView", CreateFunction(env, ConfigureView));
+    NAPI_EXPORT("enable", CreateFunction(env, Enable));
+    NAPI_EXPORT("disable", CreateFunction(env, Disable));
+    NAPI_EXPORT("render", CreateFunction(env, Render));
+    NAPI_EXPORT("extendCallNative", CreateFunction(env, ExtendCallNative));
+    NAPI_EXPORT("setContextType", CreateFunction(env, SetContextType));
+    NAPI_EXPORT("setDevicePixelRatio", CreateFunction(env, SetDevicePixelRatio));
+    NAPI_EXPORT("resetGlViewport", CreateFunction(env, ResetGlViewport));
+    NAPI_EXPORT("toDataURL", CreateFunction(env, ToDataURL));
+    NAPI_EXPORT("drawCanvas2Canvas", CreateFunction(env, DrawCanvas2Canvas));
+    NAPI_EXPORT("bindImageTexture", CreateFunction(env, BindImageTexture));
+    NAPI_EXPORT("bindCachedImageTexture", CreateFunction(env, BindCachedImageTexture));
+    NAPI_EXPORT("cacheImage", CreateFunction(env, CacheImage));
+    NAPI_EXPORT("getDeviceInfo", CreateFunction(env, GetDeviceInfo));
+    NAPI_EXPORT("addFontFamily", CreateFunction(env, AddFontFamily));
+    NAPI_EXPORT("getFontNames", CreateFunction(env, GetFontNames));
+    NAPI_EXPORT("setExtraFontLocation", CreateFunction(env, SetExtraFontLocation));
+    NAPI_EXPORT("setLogLevel", CreateFunction(env, SetLogLevel));
+    NAPI_EXPORT("resetComponent", CreateFunction(env, ResetComponent));
+    NAPI_EXPORT("texImage2D", CreateFunction(env, TexImage2D));
+    NAPI_EXPORT("texSubImage2D", CreateFunction(env, TexSubImage2D));
+    return exports;
+}
+
+} // namespace
+
+// 由 GCanvasXComponent.cpp 的 Init() 调用，统一在 'gcanvas' napi_module 的 exports 上注册
+// 全部 ArkTS 可调函数。XComponent 回调注册与 NAPI 函数导出共用同一 .so / 同一模块。
+extern "C" napi_value GCanvasNapi_Init(napi_env env, napi_value exports) {
+    GC_LOGI("GCanvasNapi_Init registered enable/render/extendCallNative");
+    return InitExports(env, exports);
+}