@hmos-library-adapter/fast 0.0.17-beta.0 → 0.0.17-beta.2

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/solutions/ohos-window-bridge/examples/gl-rendering-lib-host/README.md

@@ -0,0 +1,79 @@
+# examples/gl-rendering-lib-host —— GL 渲染库上屏宿主配方（真机验证）
+
+**这是第三类库的上屏配方**：GL 渲染库（Coin3D/OpenSceneGraph/bgfx 类）——本体不建窗口、
+没有平台后端层可写，渲染契约 = **宿主 makeCurrent 后库在当前上下文发 GL 命令**。
+与 [glfw-triangle](../glfw-triangle/) 的本质区别：窗口库要写 L3 后端（库内部有 backend 层可挂），
+**渲染库没有后端可写——宿主 demo 直接扮演 examples/glfw 的宿主角色**。走错模板就会觉得
+「这库没法上屏」。
+
+> 实证：Coin3D（Open Inventor）鸿蒙适配 2026-09-09 真机三次冷启动 `COINOWB VERDICT: PASS`
+>（逐像素非背景统计，Maleoon 916 / gl4es wrapper 1.1.7）。本目录代码本体即该案例宿主。
+
+## 判定：你是不是这类库
+
+问两个问题（完整判定线见 `../../capability-domains/graphical-window.md`「scan 判定要点」）：
+1. 库的渲染出口写 FB0 / 依赖 swap 呈现？（是 → 本配方；只出纹理/FBO → 离屏读回即够，免上屏）
+2. 源码特征：`makeCurrent` 契约出现在 **examples/**（外部宿主如 SoXt/GLUT/GLFW 调它），
+   src/ 里没有窗口系统后端层（无 `src/x11_*`/`src/win32_*`/QPA）？（是 → 本配方）
+
+## 五步配方
+
+| 步 | 命令/动作 | 要点 |
+|---|---|---|
+| 1 | `ohpt-agent scaffold --kind cpp-gui-owb-demo -w <ws> --out harmony-demo-owb` | 骨架 + OWB 桥自动装配（OWB 落位由 scaffold 注入，CMake/bash 已对齐——勿手改路径） |
+| 2 | `bash <owb>/build/build.sh`（或 SDK 下 cmake 直配 `build/CMakeLists.txt`） | 出 `libohos_window_bridge.so`；4KB 页对齐已内建 |
+| 3 | 本目录 `cpp/gl_rendering_host.cpp` 覆盖 `entry/src/main/cpp/gui_shell.cpp`，按内标替换「换成你的库」段 | 宿主自管 EGL（真窗口表面）+ gl4es bootstrap + 库契约接线 |
+| 4 | CMake 补库链接（见下方「宿主 CMake 增量」） | **不链 GLESv3**；加 `EGL_NO_X11` 守卫 |
+| 5 | `bash scripts/build-hap.sh` → `ohpt-agent sign-demo -w <ws> --demo-dir <out> --install` → `verify-demo` 取证 | 主证据 = hilog 逐像素 VERDICT 行；截图存档待人工验收 |
+
+## 三处渲染库专属差异（与普通 GLES 应用不同，全部来自真机踩坑）
+
+1. **gl4es bootstrap 必须在库首次 GL 调用之前**：NOEGL+NO_INIT_CONSTRUCTOR 形态的 gl4es
+   不会自举。宿主 makeCurrent 后立刻做四件套：`set_getprocaddress(eglGetProcAddress)` +
+   `set_getmainfbsize`（查当前 EGL surface 尺寸）+ `initialize_gl4es()` +
+   per-context `NewGLState/ActivateGLState`。做晚了库的桌面 GL 符号会解析到 ES 占位桩 → 首绘崩。
+2. **EGL 头守卫**：gl4es include 目录自带 `EGL/` 头会拉 X11。宿主 TU 必须定义
+   `EGL_NO_PLATFORM_SPECIFIC_TYPES=1 EGL_NO_X11=1`（与 Coin patches/0002 对 gl_egl.cpp 同款）。
+3. **上下文显式 ES3 + 不链 GLESv3**：`eglCreateContext` 空/低属性列表在 OHOS 落 ES1.x；
+   必须显式 `EGL_CONTEXT_MAJOR_VERSION=3 (0x3098)`。链接只留 `libGL.so.1`（gl4es），删模板默认的
+   `GLESv3`——宿主与库的 GL 调用统一走翻译层，避免桌面/ES 两套符号解析。
+
+## 宿主 CMake 增量（相对 scaffold 生成的 CMakeLists）
+
+```cmake
+# 渲染库产物（工作区 dist/lib）+ gl4es 头
+set(COIN_LIB "${WS}/dist/lib/libCoin.so.80")      # 换成你的库 .so
+set(GL4ES_LIB "${WS}/dist/lib/libGL.so.1")
+set(COIN_INCS "${WS}/build/src-ohos/include"      # 库安装头
+              "${WS}/deps/gl4es-1.1.6/src/include")  # gl4esinit.h / GL/gl.h
+target_compile_definitions(__XCOMP__ PRIVATE EGL_NO_PLATFORM_SPECIFIC_TYPES=1 EGL_NO_X11=1)
+# target_link_libraries：加 ${COIN_LIB} ${GL4ES_LIB}，删 GLESv3
+```
+
+## 库契约接线（唯一要动的渲染段）
+
+```cpp
+// makeCurrent + bootstrap 之后：
+SoDB::init();                          // ← 换成你库的初始化
+SoSeparator* root = ...;               // ← 场景图/绘制对象
+SoSceneManager* mgr = ...;             // ← 或你库的 render-to-current-context 入口
+mgr->render();                         // ← 每帧
+eglSwapBuffers(s_dpy, s_surf);         // ← 呈现
+```
+
+## 取证纪律
+
+- `logEvidence()`（见 `cpp/gl_rendering_host.cpp`）在 frame=2 / frame=60 各做一次
+  `glReadPixels` 非背景像素统计并打 `VERDICT: PASS/BLACK` 行——**两帧差值证明活渲染循环**，
+  单帧统计可能撞上恰好同帧的假绿。
+- 真机结论（Coin 案）：**真窗口表面路径首帧即稳、无需 warmup**；surfaceless+FBO 离屏路径
+  存在 gl4es 冷启动不稳定——渲染类验证载体优先级：窗口表面 > surfaceless+FBO。
+- 三处名字全等纪律照旧：`Index.ets libraryname` == CMake target == `OWB_OHOS_THREAD_APP("名")`。
+
+## 文件与去处
+
+| 本目录文件 | 拷到 | 作用 |
+|---|---|---|
+| `cpp/gl_rendering_host.cpp` | `entry/src/main/cpp/gui_shell.cpp`（覆盖） | L1 宿主本体：EGL 窗口表面 + bootstrap + 取证，内标「换成你的库」 |
+| `cpp/CMakeLists-snippet.cmake` | 参考段（并入 scaffold 生成的 CMakeLists） | 库链接 + 守卫 + 删 GLESv3 |
+| `ets/Index.ets` | 不需拷——scaffold 生成的即是同款 | SURFACE XComponent 占满窗口 |

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/solutions/ohos-window-bridge/examples/gl-rendering-lib-host/cpp/CMakeLists-snippet.cmake

@@ -0,0 +1,30 @@
+# 并入 scaffold 生成的 entry/src/main/cpp/CMakeLists.txt（GL 渲染库专属增量）。
+# 完整配方见同目录 README.md；这里只列「模板之外要加/要删的三处」。
+
+# ── 1) 渲染库产物与头（工作区相对路径按你的库改）──────────────────────────
+set(COIN_LIB "${WS}/dist/lib/libCoin.so.80")          # ← 你的库 .so
+set(GL4ES_LIB "${WS}/dist/lib/libGL.so.1")            # gl4es 翻译层（dist/lib）
+set(COIN_INCS "${WS}/build/src-ohos/include"          # ← 你的库安装头
+              "${WS}/deps/gl4es-1.1.6/src/include")   # gl4esinit.h / GL/gl.h
+
+# ── 2) EGL 头守卫：gl4es include 自带 EGL/ 头会拉 X11，必须压掉 ─────────────
+target_compile_definitions(__XCOMP__ PRIVATE
+    EGL_NO_PLATFORM_SPECIFIC_TYPES=1
+    EGL_NO_X11=1)
+
+target_include_directories(__XCOMP__ PRIVATE ${COIN_INCS})
+
+# ── 3) 链接：加库 + gl4es，删 GLESv3 ────────────────────────────────────
+# 所有 GL 调用（宿主直呼 + 库内部）统一走 libGL.so.1（gl4es），
+# 避免桌面/ES 两套符号解析（不链 GLESv3 是刻意的，别加回去）。
+# target_link_libraries(__XCOMP__ PRIVATE
+#     ${OWB_LIB}
+#     ${COIN_LIB}
+#     ${GL4ES_LIB}
+#     EGL
+#     native_window
+#     native_window_manager
+#     ace_ndk.z
+#     ace_napi.z
+#     hilog_ndk.z
+#     -Wl,-z,max-page-size=0x1000)

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/solutions/ohos-window-bridge/examples/gl-rendering-lib-host/cpp/gl_rendering_host.cpp

@@ -0,0 +1,226 @@
+// gl_rendering_host.cpp —— GL 渲染库上屏宿主（真机验证本体，Coin 2026-09 案）。
+//
+// 契约：宿主自管 EGL（XComponent SURFACE→OHNativeWindow→eglCreateWindowSurface）
+//   → gl4es 手动 bootstrap → 库在当前上下文渲染 → eglSwapBuffers。
+// 配方与三处专属差异见同目录 README.md；「>>> 换成你的库 <<<」标记是唯一要动的段。
+// 三处名字必须全等：Index.ets libraryname == add_library(名) == 末尾 OWB_OHOS_THREAD_APP("名")。
+#include <EGL/egl.h>
+#include <EGL/eglext.h>
+#include <cstring>
+#include <cstdlib>
+#include <cmath>
+
+#include <hilog/log.h>
+#define DLOG(...) OH_LOG_Print(LOG_APP, LOG_INFO, 0xD001, "GLHOST", __VA_ARGS__)
+
+// >>> 换成你的库 <<<：库的公开头（渲染入口/初始化）
+#include <Inventor/SoDB.h>
+#include <Inventor/SoSceneManager.h>
+#include <Inventor/nodes/SoBaseColor.h>
+#include <Inventor/nodes/SoCone.h>
+#include <Inventor/nodes/SoLightModel.h>
+#include <Inventor/nodes/SoPerspectiveCamera.h>
+#include <Inventor/nodes/SoRotationXYZ.h>
+#include <Inventor/nodes/SoSeparator.h>
+
+// 桌面 GL 语义经 gl4es（libGL.so.1）承接；宿主直呼的 glGetString/glReadPixels 也走翻译层，
+// 与库同一上下文语义。守卫见 CMake（EGL_NO_PLATFORM_SPECIFIC_TYPES=1 EGL_NO_X11=1）。
+#include <GL/gl.h>
+#include <gl4esinit.h>
+
+#include "ohos_window_bridge.h"
+#include "owb_ohos_app.h"
+
+static EGLDisplay s_dpy = EGL_NO_DISPLAY;
+static EGLSurface s_surf = EGL_NO_SURFACE;
+static EGLContext s_ctx = EGL_NO_CONTEXT;
+static int s_width = 0;
+static int s_height = 0;
+
+#ifndef EGL_CONTEXT_MAJOR_VERSION
+#define EGL_CONTEXT_MAJOR_VERSION 0x3098
+#endif
+#ifndef EGL_OPENGL_ES3_BIT
+#define EGL_OPENGL_ES3_BIT 0x0040
+#endif
+
+// gl4es（NOEGL 形态）需要知道默认帧缓冲尺寸——查当前 EGL 窗口表面。
+static void owb_getmainfbsize(int* width, int* height)
+{
+  if (s_dpy != EGL_NO_DISPLAY && s_surf != EGL_NO_SURFACE) {
+    EGLint w = 0, h = 0;
+    if (eglQuerySurface(s_dpy, s_surf, EGL_WIDTH, &w) == EGL_TRUE &&
+        eglQuerySurface(s_dpy, s_surf, EGL_HEIGHT, &h) == EGL_TRUE && w > 0 && h > 0) {
+      *width = w;
+      *height = h;
+    }
+  }
+}
+
+// 渐进回退选配置：RGBA8+D24+S8 → 去 stencil → 去 depth（窗口表面位始终保留）。
+static EGLConfig chooseConfig(void)
+{
+  EGLint ladders[][21] = {
+    {EGL_SURFACE_TYPE, EGL_WINDOW_BIT, EGL_RENDERABLE_TYPE, EGL_OPENGL_ES3_BIT,
+     EGL_RED_SIZE, 8, EGL_GREEN_SIZE, 8, EGL_BLUE_SIZE, 8, EGL_ALPHA_SIZE, 8,
+     EGL_DEPTH_SIZE, 24, EGL_STENCIL_SIZE, 8, EGL_SAMPLES, 0, EGL_NONE},
+    {EGL_SURFACE_TYPE, EGL_WINDOW_BIT, EGL_RENDERABLE_TYPE, EGL_OPENGL_ES3_BIT,
+     EGL_RED_SIZE, 8, EGL_GREEN_SIZE, 8, EGL_BLUE_SIZE, 8, EGL_ALPHA_SIZE, 8,
+     EGL_DEPTH_SIZE, 24, EGL_SAMPLES, 0, EGL_NONE},
+    {EGL_SURFACE_TYPE, EGL_WINDOW_BIT, EGL_RENDERABLE_TYPE, EGL_OPENGL_ES3_BIT,
+     EGL_RED_SIZE, 8, EGL_GREEN_SIZE, 8, EGL_BLUE_SIZE, 8, EGL_ALPHA_SIZE, 8,
+     EGL_NONE},
+  };
+  for (int i = 0; i < 3; i++) {
+    EGLConfig cfg = nullptr;
+    EGLint num = 0;
+    if (eglChooseConfig(s_dpy, ladders[i], &cfg, 1, &num) == EGL_TRUE && num > 0) {
+      DLOG("eglChooseConfig hit ladder %d", i);
+      return cfg;
+    }
+  }
+  return nullptr;
+}
+
+static int initEGL(void* nativeWindow)
+{
+  s_dpy = eglGetDisplay(EGL_DEFAULT_DISPLAY);
+  if (s_dpy == EGL_NO_DISPLAY) { DLOG("eglGetDisplay FAIL"); return 0; }
+  EGLint maj = 0, mnr = 0;
+  if (eglInitialize(s_dpy, &maj, &mnr) != EGL_TRUE) {
+    DLOG("eglInitialize FAIL 0x%x", eglGetError());
+    return 0;
+  }
+  if (eglBindAPI(EGL_OPENGL_ES_API) != EGL_TRUE) {
+    DLOG("eglBindAPI FAIL 0x%x", eglGetError());
+    return 0;
+  }
+  EGLConfig cfg = chooseConfig();
+  if (!cfg) { DLOG("no matching EGL config"); return 0; }
+  s_surf = eglCreateWindowSurface(s_dpy, cfg, (EGLNativeWindowType)nativeWindow, 0);
+  if (s_surf == EGL_NO_SURFACE) {
+    DLOG("eglCreateWindowSurface FAIL 0x%x", eglGetError());
+    return 0;
+  }
+  eglQuerySurface(s_dpy, s_surf, EGL_WIDTH, &s_width);
+  eglQuerySurface(s_dpy, s_surf, EGL_HEIGHT, &s_height);
+  DLOG("eglCreateWindowSurface OK %dx%d", s_width, s_height);
+  // OHOS 教训：显式 ES3，禁止空属性列表（默认落 ES1.x → gl4es 语义塌方）。
+  const EGLint ctxAttrs[] = {EGL_CONTEXT_MAJOR_VERSION, 3, EGL_NONE};
+  s_ctx = eglCreateContext(s_dpy, cfg, EGL_NO_CONTEXT, ctxAttrs);
+  if (s_ctx == EGL_NO_CONTEXT) {
+    DLOG("eglCreateContext(ES3) FAIL 0x%x", eglGetError());
+    return 0;
+  }
+  if (eglMakeCurrent(s_dpy, s_surf, s_surf, s_ctx) != EGL_TRUE) {
+    DLOG("eglMakeCurrent FAIL 0x%x", eglGetError());
+    return 0;
+  }
+  eglSwapInterval(s_dpy, 1);
+  return 1;
+}
+
+// gl4es 手动 bootstrap（NO_INIT_CONSTRUCTOR 形态）：必须在库首次 GL 调用之前。
+static void bootstrapGl4es(void)
+{
+  set_getprocaddress((void *(*)(const char *))eglGetProcAddress);
+  set_getmainfbsize(&owb_getmainfbsize);
+  initialize_gl4es();
+  void* glstate = NewGLState(NULL, 0);
+  ActivateGLState(glstate);
+  DLOG("gl4es bootstrapped (initialize + procaddress + mainfbsize + GLState)");
+}
+
+// 上屏取证：读回默认帧缓冲统计非背景像素；frame=2/60 双采样，两帧差值证明活渲染。
+static void logEvidence(int frame)
+{
+  if (s_width <= 0 || s_height <= 0) return;
+  const int total = s_width * s_height;
+  unsigned char* px = (unsigned char*)malloc((size_t)total * 4);
+  if (!px) return;
+  glPixelStorei(GL_PACK_ALIGNMENT, 1);
+  glReadPixels(0, 0, s_width, s_height, GL_RGBA, GL_UNSIGNED_BYTE, px);
+  int nonbg = 0;
+  for (int i = 0; i < total; i++) {
+    const unsigned char* p = px + i * 4;
+    if ((255 - (int)p[0]) + (255 - (int)p[1]) + (255 - (int)p[2]) > 30) nonbg++;
+  }
+  DLOG("frame=%d readback=%dx%d nonbg=%d/%d", frame, s_width, s_height, nonbg, total);
+  DLOG(nonbg > 0 ? "GLHOST VERDICT: PASS frame=%d nonbg=%d" : "GLHOST VERDICT: BLACK frame=%d", frame, nonbg);
+  free(px);
+}
+
+int main(int argc, char** argv)
+{
+  (void)argc;
+  (void)argv;
+  OWB_Initialize();
+  if (OWB_WaitForSurface(15.0) != OWB_OK) { DLOG("no surface within 15s"); return 1; }
+  OWB_SurfaceInfo info;
+  int bound = 0;
+  for (int i = 0, n = OWB_GetSurfaceCount(); i < n; i++) {
+    if (OWB_GetSurfaceInfoByIndex(i, &info) == OWB_OK) { OWB_AcquireSurface(info.surfaceId); bound = 1; break; }
+  }
+  if (!bound) { DLOG("no surface registered"); return 1; }
+
+  if (!initEGL(OWB_GetNativeWindow(info.surfaceId))) return 1;
+  bootstrapGl4es();
+  DLOG("GL_VERSION=%s", (const char*)glGetString(GL_VERSION));
+  DLOG("GL_RENDERER=%s", (const char*)glGetString(GL_RENDERER));
+
+  // >>> 换成你的库 <<<：初始化 + 场景/绘制对象 + 每帧渲染入口
+  SoDB::init();
+  SoSeparator* root = new SoSeparator;
+  root->ref();
+  SoPerspectiveCamera* camera = new SoPerspectiveCamera;
+  camera->nearDistance = 0.01f;
+  camera->farDistance = 100.0f;
+  root->addChild(camera);
+  SoLightModel* lightModel = new SoLightModel;
+  lightModel->model = SoLightModel::BASE_COLOR;
+  root->addChild(lightModel);
+  SoBaseColor* color = new SoBaseColor;
+  color->rgb = SbColor(1.0f, 0.55f, 0.1f);
+  root->addChild(color);
+  SoRotationXYZ* spin = new SoRotationXYZ;
+  root->addChild(spin);
+  root->addChild(new SoCone);
+  SoSceneManager* manager = new SoSceneManager;
+  manager->setBackgroundColor(SbColor(1.0f, 1.0f, 1.0f));
+  manager->setSceneGraph(root);
+  manager->setWindowSize(SbVec2s((short)s_width, (short)s_height));
+  camera->viewAll(root, manager->getViewportRegion());
+
+  int frame = 0;
+  float angle = 0.0f;
+  for (;;) {
+    OWB_Event ev;
+    while (OWB_PollEvent(&ev)) {
+      if (ev.type == OWB_EVENT_WINDOW_CLOSE || ev.type == OWB_EVENT_SURFACE_DESTROYED) goto done;
+      if (ev.type == OWB_EVENT_SURFACE_CHANGED) {
+        OWB_SurfaceInfo cur;
+        if (OWB_GetSurfaceInfoById(info.surfaceId, &cur) == OWB_OK && cur.width > 0) {
+          s_width = cur.width;
+          s_height = cur.height;
+          manager->setWindowSize(SbVec2s((short)s_width, (short)s_height));
+        }
+      }
+    }
+    spin->angle = angle;
+    angle += 0.02f;
+    if (angle > 6.28318f) angle -= 6.28318f;
+    manager->render();                       // ← 你库的 render-to-current-context 入口
+    if (frame == 2 || frame == 60) logEvidence(frame);
+    eglSwapBuffers(s_dpy, s_surf);
+    frame++;
+  }
+
+done:
+  DLOG("exiting: frames=%d (勿调库的 finish/静态析构敏感接口——上游退出期撕裂见错误图谱)", frame);
+  manager->setSceneGraph(NULL);
+  root->unref();
+  delete manager;
+  return 0;
+}
+
+OWB_OHOS_THREAD_APP("coinowb_demo")  // ← 换成你的模块名（三处全等）

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/solutions/ohos-window-bridge/examples/glfw-triangle/README.md

@@ -0,0 +1,25 @@
+# examples/glfw-triangle —— OWB 上屏参考 demo（真机验证）
+
+**这是 [docs/EXAMPLE-GLFW.md](../../docs/EXAMPLE-GLFW.md) 的 L0/L1 代码本体**，已在鸿蒙 PC 真机跑通（签名装 HAP → 拉起 → 橙色三角形上屏，GPU Maleoon 916 / GL ES 3.2）。**图形库要上屏，先照抄这个再改**——别从零写渲染，MVP 矩阵坑会让你得到全黑窗还误判成「EGL/GL 环境坏」。
+
+## 文件与去处
+
+| 本 example 文件 | 拷到 harmony-demo 的 | 作用 |
+|---|---|---|
+| `cpp/glfw_triangle.cpp` | `entry/src/main/cpp/` | L1 应用本体：`main()` + GLES3 渲染 + 末尾 `OWB_OHOS_THREAD_APP("glfw_demo")` |
+| `cpp/CMakeLists.txt` | `entry/src/main/cpp/` | native 构建（链 OWB + EGL/GLESv3 + 4KB 对齐） |
+| `ets/Index.ets` | `entry/src/main/ets/pages/` | L0：SURFACE XComponent 占满窗口 |
+| （另需）本资产 `arkts-host/OWBWindowControl.ets` | `entry/src/main/ets/common/` | Index.ets import 的窗口控制 helper |
+| （另需）本资产 `napi/`、`include/`、`src/`（整目录） | 工作区 `deps/ohos-window-bridge/` | OWB 桥本体，`build/build.sh` 出 `.so` |
+
+HAP 工程脚手架（`AppScope/`、`entry/src/main/module.json5`、`build-profile.json5`、EntryAbility）用 `ohpt-agent scaffold --kind cpp-gui-owb-demo -w <ws>` 生成（勿手写 `build-profile.json5`，runtimeOS 配错触发 E121）；本 example 只给 OWB 特有的那几件，叠加进生成的骨架即可。签名装机走 `ohpt-agent sign-demo -w <ws> --install`，上屏取证走 `ohpt-agent verify-demo -w <ws>`。
+
+## 换成你的库要改哪
+
+- **渲染（库无关）**：`glfw_triangle.cpp` 里 shader / VBO / `while` 循环内的 `glDrawArrays` 换成你库的绘制。**MVP 矩阵坑的正解与告警就写在该循环的注释里**（本 demo 已避开）——那是权威，别在别处另写一份。
+- **窗口（GLFW 特有）**：`glfwInit/glfwCreateWindow/glfwSwapBuffers/glfwPollEvents` 是 GLFW 的 windowing；SDL/GLUT/自绘换成各自的入口，其余（OWB 宏、CMake、Index.ets）不动。GLFW 后端本体怎么接 OWB 见 [docs/EXAMPLE-GLFW.md](../../docs/EXAMPLE-GLFW.md) 的 L3 与 [templates/skeleton-backend/](../../templates/skeleton-backend/)。
+
+## 三处名字必须全等
+
+`glfw_demo` 出现在三处、必须一字不差（对不齐 = native 模块 Init 不被调 = 黑屏、常无报错）：
+`Index.ets` 的 `libraryname:'glfw_demo'` == `CMakeLists.txt` 的 `add_library(glfw_demo …)`（产出 `libglfw_demo.so`）== `glfw_triangle.cpp` 末尾 `OWB_OHOS_THREAD_APP("glfw_demo")`。换库时统一改成你的名。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/solutions/ohos-window-bridge/examples/glfw-triangle/cpp/CMakeLists.txt

@@ -0,0 +1,57 @@
+# GLFW × OWB 上屏 demo 的 native 构建（应用 .so = libglfw_demo.so）。
+# 拷进目标工作区的 harmony-demo 后由 hvigor(cmake) 编。真机验证过的配置，照抄改名即可。
+#
+# 三处名字必须全等（对不齐 = 黑屏且常无明显报错）：
+#   ArkTS XComponent 的 libraryname='glfw_demo'  ==  下面 add_library(glfw_demo …)  ==  glfw_triangle.cpp 末尾 OWB_OHOS_THREAD_APP("glfw_demo")
+cmake_minimum_required(VERSION 3.16)
+project(glfw_demo)
+
+set(CMAKE_C_STANDARD 99)
+set(CMAKE_C_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_STANDARD 11)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fPIC")
+set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -fPIC")
+
+add_definitions(-D_DEFAULT_SOURCE)
+
+# 工作区根（pc-workspace-layout 约定）：本文件在 harmony-demo/entry/src/main/cpp/ 下，向上 5 级。
+# 拷到别的层级要相应调整这一行。dist/lib 放构建产物，deps/ 放 vendored 依赖，source/ 放上游源码。
+get_filename_component(WS "${CMAKE_CURRENT_SOURCE_DIR}/../../../../.." ABSOLUTE)
+set(GLFW_DIST "${WS}/dist/lib")
+set(OWB_ROOT "${WS}/deps/ohos-window-bridge")   # ← 整目录拷贝自本方案资产
+set(GLFW_INCLUDE "${WS}/source/include")
+
+set(GLFW_LIB "${GLFW_DIST}/libglfw3.a")              # 你库交叉编译产物（含 OHOS 后端）
+set(OWB_LIB "${GLFW_DIST}/libohos_window_bridge.so")  # OWB build/build.sh 产物
+
+if (NOT EXISTS "${GLFW_LIB}")
+    message(FATAL_ERROR "libglfw3.a not found at ${GLFW_LIB}; build GLFW (with OHOS backend) first")
+endif()
+if (NOT EXISTS "${OWB_LIB}")
+    message(FATAL_ERROR "libohos_window_bridge.so not found at ${OWB_LIB}; run OWB build/build.sh")
+endif()
+
+# demo 应用本体 + OWB 的 L1 napi 胶水（owb_napi.cpp 提供 HookXComponent/InstallWindowControl）
+add_library(glfw_demo SHARED
+    glfw_triangle.cpp
+    ${OWB_ROOT}/napi/owb_napi.cpp)
+
+target_include_directories(glfw_demo PRIVATE
+    ${GLFW_INCLUDE}
+    ${OWB_ROOT}/include
+    ${OWB_ROOT}/napi)
+
+# EGL/GLESv3 = 鸿蒙 PC 开箱即用的 GPU 栈；native_window* = surface；ace_* = XComponent/napi；
+# -Wl,-z,max-page-size=0x1000 = 4KB 页对齐（不加 dlopen 可能 SIGSEGV，见 OWB README）。
+target_link_libraries(glfw_demo PRIVATE
+    ${GLFW_LIB}
+    ${OWB_LIB}
+    EGL
+    GLESv3
+    native_window
+    native_window_manager
+    ace_ndk.z
+    ace_napi.z
+    hilog_ndk.z
+    -Wl,-z,max-page-size=0x1000)

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/solutions/ohos-window-bridge/examples/glfw-triangle/cpp/glfw_triangle.cpp

@@ -0,0 +1,200 @@
+//========================================================================
+// GLFW × ohos_window_bridge —— 鸿蒙 PC 上屏参考 demo（OpenGL ES 3，旋转三角形）
+//
+// 已真机验证：签名装 HAP → 拉起 → 橙色三角形上屏（GPU Maleoon 916 / GL ES 3.2）。
+// 这是 OWB「端到端实例」的 L1 应用本体（配套 docs/EXAMPLE-GLFW.md）。想把自己的
+// 图形库搬上鸿蒙 PC？**照抄这个**：
+//   • 渲染部分（shader / 矩阵 / draw）**库无关**——换掉 render 那几行为你库的绘制即可；
+//   • 窗口部分（glfw*）是 GLFW 特有——SDL/GLUT/自绘 换成各自的 windowing，其余不动；
+//   • 末尾一行 OWB_OHOS_THREAD_APP 宏把「桌面 main()」搬上鸿蒙 worker 线程，应用零平台代码。
+//
+// ⚠ **上屏最常踩的坑 = MVP 矩阵**（本 demo 已避开，见 while 循环内注释）：黑屏先按矩阵排查，
+//    别急着归因「EGL 失败 / libEGL 缺 / GL 环境不可用」——GLES/EGL 在鸿蒙 PC 开箱即用。
+//========================================================================
+
+#include <GLFW/glfw3.h>
+#include "owb_ohos_app.h"
+
+#include <GLES3/gl3.h>
+#include <math.h>
+#include <hilog/log.h>
+#define DLOG(...) OH_LOG_Print(LOG_APP, LOG_INFO, 0xD001, "GLFWDEMO", __VA_ARGS__)
+
+static const char* vertexShaderSource =
+    "#version 300 es\n"
+    "layout(location = 0) in vec3 vPosition;\n"
+    "uniform mat4 uMVP;\n"
+    "void main() {\n"
+    "    gl_Position = uMVP * vec4(vPosition, 1.0);\n"
+    "}\n";
+
+static const char* fragmentShaderSource =
+    "#version 300 es\n"
+    "precision mediump float;\n"
+    "out vec4 fragColor;\n"
+    "uniform vec3 uColor;\n"
+    "void main() {\n"
+    "    fragColor = vec4(uColor, 1.0);\n"
+    "}\n";
+
+// 编译着色器并**检查编译状态**——上屏排障第一步，别默认它编过了
+static GLuint compileShader(GLenum type, const char* source)
+{
+    GLuint shader = glCreateShader(type);
+    glShaderSource(shader, 1, &source, NULL);
+    glCompileShader(shader);
+    GLint ok = 0;
+    glGetShaderiv(shader, GL_COMPILE_STATUS, &ok);
+    if (!ok) {
+        char log[512] = {0};
+        glGetShaderInfoLog(shader, sizeof(log), NULL, log);
+        DLOG("shader compile FAIL type=%d: %{public}s", (int)type, log);
+    } else {
+        DLOG("shader compile OK type=%d", (int)type);
+    }
+    return shader;
+}
+
+static GLuint createProgram(const char* vs, const char* fs)
+{
+    GLuint program = glCreateProgram();
+    GLuint v = compileShader(GL_VERTEX_SHADER, vs);
+    GLuint f = compileShader(GL_FRAGMENT_SHADER, fs);
+    glAttachShader(program, v);
+    glAttachShader(program, f);
+    glLinkProgram(program);
+    glDeleteShader(v);
+    glDeleteShader(f);
+    return program;
+}
+
+static void rotateZ(float* m, float angle)
+{
+    float c = cosf(angle), s = sinf(angle);
+    m[0] = c;  m[1] = -s; m[2] = 0.0f; m[3] = 0.0f;
+    m[4] = s;  m[5] = c;  m[6] = 0.0f; m[7] = 0.0f;
+    m[8] = 0;  m[9] = 0;  m[10] = 1.0f; m[11] = 0.0f;
+    m[12] = 0; m[13] = 0; m[14] = 0.0f; m[15] = 1.0f;
+}
+
+// 输入 demo：点击窗口切换尺寸（走 OWB 双向窗口控制桥 → @ohos.window）
+static int tapCount = 0;
+static void keyCallback(GLFWwindow* window, int key, int scancode, int action, int mods)
+{
+    (void)scancode; (void)mods;
+    if (action == GLFW_PRESS && key == GLFW_KEY_ESCAPE)
+        glfwSetWindowShouldClose(window, GLFW_TRUE);
+}
+
+static void mouseButtonCallback(GLFWwindow* window, int button, int action, int mods)
+{
+    (void)mods;
+    if (button == GLFW_MOUSE_BUTTON_LEFT && action == GLFW_PRESS)
+    {
+        tapCount++;
+        if (tapCount == 1)
+            glfwSetWindowSize(window, 900, 600);
+        else if (tapCount == 2)
+            glfwMaximizeWindow(window);
+        else if (tapCount == 3)
+            glfwRestoreWindow(window);
+        else
+            tapCount = 0;
+    }
+}
+
+int main(int argc, char** argv)
+{
+    (void)argc; (void)argv;
+
+    if (!glfwInit()) {
+        DLOG("glfwInit FAIL");
+        return -1;
+    }
+    DLOG("glfwInit OK");
+
+    glfwWindowHint(GLFW_CLIENT_API, GLFW_OPENGL_ES_API);
+    glfwWindowHint(GLFW_CONTEXT_VERSION_MAJOR, 3);
+    glfwWindowHint(GLFW_CONTEXT_VERSION_MINOR, 2);
+
+    GLFWwindow* window = glfwCreateWindow(640, 480, "GLFW OHOS Demo", NULL, NULL);
+    if (!window)
+    {
+        DLOG("glfwCreateWindow FAIL");
+        glfwTerminate();
+        return -1;
+    }
+    DLOG("glfwCreateWindow OK");
+
+    glfwMakeContextCurrent(window);
+    // 打印 GL 身份——上屏排障必备（确认 EGL/GLES 上下文真建起来了、拿到的是硬件 GPU）
+    DLOG("makeContextCurrent done; GL_VERSION=%{public}s GL_RENDERER=%{public}s",
+         (const char*)glGetString(GL_VERSION), (const char*)glGetString(GL_RENDERER));
+    glfwSetKeyCallback(window, keyCallback);
+    glfwSetMouseButtonCallback(window, mouseButtonCallback);
+    glfwSwapInterval(1);
+
+    GLuint program = createProgram(vertexShaderSource, fragmentShaderSource);
+    glUseProgram(program);
+
+    GLuint vao, vbo;
+    glGenVertexArrays(1, &vao);
+    glGenBuffers(1, &vbo);
+    glBindVertexArray(vao);
+    glBindBuffer(GL_ARRAY_BUFFER, vbo);
+
+    // 顶点直接落在 NDC（裁剪空间 ±0.5 平面），无需投影即可上屏
+    float vertices[] = {
+        0.0f,  0.5f, 0.0f,
+       -0.5f, -0.5f, 0.0f,
+        0.5f, -0.5f, 0.0f
+    };
+    glBufferData(GL_ARRAY_BUFFER, sizeof(vertices), vertices, GL_STATIC_DRAW);
+    glEnableVertexAttribArray(0);
+    glVertexAttribPointer(0, 3, GL_FLOAT, GL_FALSE, 0, NULL);
+
+    GLint mvpLoc = glGetUniformLocation(program, "uMVP");
+    GLint colorLoc = glGetUniformLocation(program, "uColor");
+
+    float rot[16], mvp[16];
+    int width, height;
+    glfwGetFramebufferSize(window, &width, &height);
+
+    DLOG("GL up: %{public}dx%{public}d renderer=%{public}s", width, height, (const char*)glGetString(GL_RENDERER));
+    double lastTime = glfwGetTime();
+    while (!glfwWindowShouldClose(window))
+    {
+        double now = glfwGetTime();
+        float angle = (float)(now - lastTime);
+        rotateZ(rot, angle);
+        // ⚠ MVP 矩阵坑（黑屏头号原因，本 demo 已避开）：顶点已在 NDC(±0.5)，只需 2D 旋转、不要透视。
+        //   若你要加 3D 透视：① 必须 m[15]=1（写成 0 → w=0 → 顶点裁到无穷远 → 全黑窗）；
+        //   ② C 数组是**行主序**，glUniformMatrix4fv 默认按**列主序**读——要么最后一参传 GL_TRUE 转置，
+        //   要么自己按列主序填。黑屏别急着归因 EGL/GL 环境，先核这两条。
+        for (int i = 0; i < 16; i++) mvp[i] = rot[i];
+
+        glViewport(0, 0, width, height);
+        glClearColor(0.12f, 0.12f, 0.15f, 1.0f);
+        glClear(GL_COLOR_BUFFER_BIT);
+
+        glUseProgram(program);
+        glUniformMatrix4fv(mvpLoc, 1, GL_FALSE, mvp);
+        glUniform3f(colorLoc, 0.8f, 0.4f, 0.2f);
+        glBindVertexArray(vao);
+        glDrawArrays(GL_TRIANGLES, 0, 3);
+
+        glfwSwapBuffers(window);
+        glfwPollEvents();
+    }
+
+    glDeleteBuffers(1, &vbo);
+    glDeleteVertexArrays(1, &vao);
+    glDeleteProgram(program);
+    glfwDestroyWindow(window);
+    glfwTerminate();
+    return 0;
+}
+
+// 平台入口壳：一行宏 = demo 的 napi 模块（worker 线程跑上面的 main()）。
+// 参数字符串必须与 ArkTS XComponent 的 libraryname、CMake target 名三处全等（此处 "glfw_demo"）。
+OWB_OHOS_THREAD_APP("glfw_demo")

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/solutions/ohos-window-bridge/examples/glfw-triangle/ets/Index.ets

@@ -0,0 +1,33 @@
+// L0 宿主页（真机验证过）：一个 SURFACE XComponent 占满窗口 = 原生像素上屏通道。
+// 放到 harmony-demo 的 entry/src/main/ets/pages/Index.ets。ETS 侧到此为止——不 import .so、
+// 不写渲染逻辑（那些在 native 的 main() 里，经 libraryname 串到 native 模块，见 docs/EXAMPLE-GLFW.md）。
+//
+// libraryname:'glfw_demo' 必须与 CMake target 名、native 侧 OWB_OHOS_THREAD_APP("glfw_demo") 三处全等。
+// onLoad 里 owbBindWindowControl 接上 OWB 的双向窗口控制桥（可选；不接窗口 resize/max 就走不通，
+// 但三角形照样上屏）。OWBWindowControl.ets 拷贝自本方案资产 arkts-host/，放到 ets/common/。
+import { window } from '@kit.ArkUI';
+import { owbBindWindowControl } from '../common/OWBWindowControl';
+
+@Entry
+@Component
+struct Index {
+  private xcCtl: XComponentController = new XComponentController();
+
+  build() {
+    Column() {
+      XComponent({
+        id: 'glfwSurface',
+        type: XComponentType.SURFACE,
+        libraryname: 'glfw_demo',
+        controller: this.xcCtl
+      })
+        .width('100%')
+        .height('100%')
+        .onLoad(() => {
+          owbBindWindowControl(this.xcCtl, AppStorage.get<window.Window>('owbMainWindow'));
+        })
+    }
+    .width('100%')
+    .height('100%')
+  }
+}