README.md
1# Native OpenGL 3D Graphics
2
3
4
5### Introduction
6
7This sample mainly introduces how developers can use the Native window interface and XComponent to create 3D Graphics.
8
9### Usage
10
11The application page displays call to the Native window API and OpenGL(ES) API.
12
13
14### Constraints
15
16This sample can only be run on standard-system devices.
17
README_zh.md
1# OpenGL三棱椎
2
3### 介绍
4
5XComponent控件常用于相机预览流的显示和游戏画面的绘制,在OpenHarmony上，可以配合Native Window创建OpenGL开发环境，并最终将OpenGL绘制的图形显示到XComponent控件。本示例基于"Native C++"模板，调用OpenGL(OpenGL ES)图形库相关API绘制3D图形（三棱锥），并将结果渲染到页面的XComponent控件中进行展示。同时，还可以在屏幕上通过触摸滑动手势对三棱锥进行旋转，最终得到不同角度的图形并显示到页面。
6
7> **说明**
8> 本示例XComponent接口使用方法已停止演进，推荐使用方法请参考[ArkTSXComponent示例](../ArkTSXComponent/README_zh.md)。
9### 效果预览
10
11| 首页 | 滑动屏幕旋转变换 |
12| -------------------------------------- | ---------------------------------------- |
13|  |  |
14
15使用说明
16
17应用界面中展示了XComponent相关控件的使用，及采用OpenGL (OpenGL ES)相关标准API绘制3D图形（三棱锥，3D渲染的光源用的是简单的线性光源）。此外，可在屏幕触摸滑动，以使三棱锥进行旋转，其中主要采用了napi接口来更新3D图形的旋转角度。
18
19### 工程目录
20
21```
22entry/src/main/
23|---cpp
24| |---CMakeLists.txt // cmake编译配置
25| |---app_napi.cpp // 调用native接口
26| |---include
27| | |---app_napi.h
28| | |---tetrahedron.h
29| | |---util
30| | |---log.h
31| | |---napi_manager.h
32| | |---napi_util.h
33| | |---native_common.h
34| | |---native_interface_xcomponent.h
35| |---module.cpp // napi模块注册
36| |---napi_manager.cpp
37| |---napi_util.cpp
38| |---tetrahedron.cpp // OpenGL (ES) 三棱锥实现
39| |---type
40| |---libentry
41| |---oh-package.json5
42| |---tetrahedron_napi.d.ts // 接口导出
43|---ets
44| |---entryability
45| | |---EntryAbility.ts
46| |---pages
47| | |---Index.ets // 首页
48| |---utils
49| |---Logger.ets // 日志工具
50|
51```
52
53### 具体实现
54
55通过在IDE中创建Native C++工程，在C++代码中定义接口为Init和Update用于3D图形绘制环境的初始化和图形渲染更新，并映射NAPI相关接口UpdateAngle。ArkTS侧主要利用XComponent控件实现Index.ets，C++侧主要采用OpenGL ES相关标准API实现三棱锥的绘制流程相关代码，并可与ArkTS进行交互。
56
57应用启动时，NAPI模块也相应进行初始化，此时可通过C++侧的OH_NativeXComponent_GetXComponentId()接口，获取到当前XComponent控件的控件指针，并给到C++侧三棱锥绘制相关的Init和Update函数，实现3D图形显示。同时，为实现三棱锥的触摸屏滑动旋转效果，在C++代码中映射的NAPI接口UpdateAngle给到ArkTS侧调用。ArkTS侧需在导入NAPI模块"libtetrahedron_napi.so"正确的前提下，通过调用src/main/cpp/type/libentry/tetrahedron_napi.d.ts中声明的UpdateAngle接口更新三棱锥旋转角度。
58主要源码参考：[napi_manager.cpp](entry/src/main/cpp/napi_manager.cpp)、[app_napi.cpp](entry/src/main/cpp/app_napi.cpp)和[tetrahedron.cpp](entry/src/main/cpp/tetrahedron.cpp)。
59
60Native XComponent相关函数如下：
61
62| 函数名称 | 描述 |
63| ------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- |
64| OH_NativeXComponent_GetXComponentId(OH_NativeXComponent *component, char *id, uint64_t *size) | 获取ArkUI XComponent的id |
65| OH_NativeXComponent_GetXComponentSize(OH_NativeXComponent *component, const void *window, uint64_t *width, uint64_t *height) | 获取ArkUI XComponent持有的surface的大小 |
66| OH_NativeXComponent_GetXComponentOffset(OH_NativeXComponent *component, const void *window, double *x, double *y) | 获取ArkUI XComponent组件相对屏幕左上顶点的偏移量 |
67| OH_NativeXComponent_GetTouchEvent(OH_NativeXComponent *component, const void *window, OH_NativeXComponent_TouchEvent *touchEvent) | 获取ArkUI XComponent调度的触摸事件 |
68| OH_NativeXComponent_GetTouchPointToolType(OH_NativeXComponent *component, uint32_t pointIndex, OH_NativeXComponent_TouchPointToolType *toolType) | 获取ArkUI XComponent触摸点工具类型 |
69| OH_NativeXComponent_GetTouchPointTiltX(OH_NativeXComponent *component, uint32_t pointIndex, float *tiltX) | 获取ArkUI XComponent触摸点倾斜与X轴角度 |
70| OH_NativeXComponent_GetTouchPointTiltY(OH_NativeXComponent *component, uint32_t pointIndex, float *tiltY) | 获取ArkUI XComponent触摸点倾斜与Y轴角度 |
71| OH_NativeXComponent_GetMouseEvent(OH_NativeXComponent *component, const void *window, OH_NativeXComponent_MouseEvent *mouseEvent) | 获取ArkUI XComponent调度的鼠标事件 |
72| OH_NativeXComponent_RegisterCallback(OH_NativeXComponent *component, OH_NativeXComponent_Callback *callback) | 实例注册回调 |
73| OH_NativeXComponent_RegisterMouseEventCallback(OH_NativeXComponent *component, OH_NativeXComponent_MouseEvent_Callback *callback) | 实例注册鼠标事件回调 |
74
75### 相关权限
76
77不涉及。
78
79### 依赖
80
81不涉及。
82
83### 约束与限制
84
851. 本示例仅支持标准系统上运行。
86
872. 本示例已适配API version 10版本SDK，SDK版本号(API Version 10 Release),镜像版本号(4.0Release) 。
88
893. 本示例需要使用DevEco Studio 版本号(4.0Release)及以上版本才可编译运行。
90
91### 下载
92
93如需单独下载本工程，执行如下命令：
94
95```
96git init
97git config core.sparsecheckout true
98echo code/BasicFeature/Native/NdkOpenGL/ > .git/info/sparse-checkout
99git remote add origin https://gitee.com/openharmony/applications_app_samples.git
100git pull origin master
101```
