1# 3D引擎接口示例 2 3### 介绍 4 5本实例主要测试了当前3D引擎提供的接口功能，调用了[@ohos.graphics.scene](https://gitee.com/openharmony/interface_sdk-js/blob/master/api/@ohos.graphics.scene.d.ts)中的接口，测试了每一个接口的功能。3D引擎渲染的画面会被显示在[Component3D](https://gitee.com/openharmony/interface_sdk-js/blob/master/api/@internal/component/ets/component3d.d.ts)这一控件中。点击按钮触发不同的功能，用户可以观察渲染画面的改变；此外，许多接口将不会直接导致渲染效果的改变，因此应用将会打印日志来检测这些接口是否正常，可以用“lume_api_test"来过滤。 6 7### 效果预览 8 9| 主页 | container | node_base | node_camera | 10|-------------------------------------|------------------------------------------|-------------------------------------|----------------------------| 11|  |  |  |  | 12 13| node_light | scene_environment | scene_animation | scene_shader | 14|--------------------------------------|---------------------------------------------|-------------------------------------------|----------------------------------------| 15|  |  |  |  | 16 17使用说明 18 191. 在主界面，可以点击按钮进入不同的子页面，每一个子页面分别测试了一类3D引擎的接口功能，在子页面点击back返回主界面。 202. 在container界面，点击按钮，可以添加、移除子节点，节点的结构信息已打印在界面上。在本示例中操作的子节点是一个头盔模型。 213. 在node_base界面，点击按钮对节点的基础属性如位置、旋转、大小、可见性等进行操作。在本示例中操作的子节点是一个头盔模型。 224. 在node_camera界面，点击按钮对相机的属性如投影、后处理等进行操作。 235. 在node_light界面，点击按钮对灯光的类型、颜色、强度、阴影等进行操作。 246. 在scene_environment界面，点击按钮对背景进行操作。 257. 在scene_animation界面，点击按钮进行动画的播放、暂停等操作的功能。 268. 在scene_shader界面，点击按钮进行纹理材质的操作。 27 28### 工程目录 29 30``` 31entry/src/main/ 32├─ets 33│ ├─entryability 34│ ├─graphics3d 35│ └─pages 36│ ├─container.ets // 子节点操作demo 37│ ├─Index.ets // 主界面 38│ ├─node_base.ets // 节点基础demo 39│ ├─node_camera.ets // 相机demo 40│ ├─node_light.ets // 灯光demo 41│ ├─scene_animation.ets // 动画demo 42│ ├─scene_environment.ets // 背景demo 43│ ├─scene_shader.ets // 纹理demo 44└─resources 45 ├─base 46 │ ├─element 47 │ ├─media 48 │ └─profile 49 ├─en_US 50 │ └─element 51 ├─rawfile 52 │ ├─assets 53 │ │ └─app 54 │ │ ├─rendernodegraphs 55 │ │ └─shaders 56 │ │ └─shader 57 │ ├─gltf // 本示例中用到的模型 58 │ │ ├─BrainStem 59 │ │ │ ├─glTF 60 │ │ │ ├─glTF-Binary 61 │ │ │ ├─glTF-Draco 62 │ │ │ ├─glTF-Embedded 63 │ │ │ ├─glTF-Meshopt 64 │ │ │ └─screenshot 65 │ │ ├─Cube 66 │ │ │ ├─glTF 67 │ │ │ └─screenshot 68 │ │ ├─CubeWithFloor 69 │ │ │ └─glTF 70 │ │ ├─DamagedHelmet 71 │ │ │ └─glTF 72 │ │ └─Environment 73 │ │ └─glTF 74 │ │ └─images 75 │ └─shaders 76 │ └─custom_shader 77 └─zh_CN 78 └─element 79``` 80 81### 具体实现 82* 添加、移除、遍历节点的功能接口封装在graphics3d/[SceneNodes.d.ts](https://gitee.com/openharmony/interface_sdk-js/blob/master/api/graphics3d/SceneNodes.d.ts)，源码参考：container.ets 83 * 初始时会使用深度优先的方式遍历并打印场景中每一个节点的信息，从场景的root节点开始； 84 * 删除节点：调用remove方法删除指定节点，不会重复删除，在本示例中删除了头盔节点； 85 * 添加节点：调用append方法在子节点列表的末尾添加指定节点，不会重复添加，在本示例中添加了头盔节点； 86 * 添加节点：调用insertAfter方法在子节点列表的指定位置添加指定节点，不会重复添加，在本示例中添加了头盔节点； 87 * 清除子节点：调用clear方法清除子节点列表的所有节点，本示例中清除了root的子节点； 88 * 获取子节点：调用get方法获取子节点列表中的指定节点； 89 * 获取子节点个数：调用count方法获取子节点列表的大小。 90* 对节点的基础属性如位置、旋转、大小等操作的功能接口封装在graphics3d/[SceneNodes.d.ts](https://gitee.com/openharmony/interface_sdk-js/blob/master/api/graphics3d/SceneNodes.d.ts)，源码参考：node_base.ets 91 * 修改scale属性改变节点的大小，本示例中改变了头盔的大小； 92 * 修改position属性改变节点的位置，本示例中改变了头盔的x轴坐标； 93 * 修改rotation属性改变节点的旋转方向，改变子节点的父节点的rotation同样会改变子节点的旋转方向（position同理），本示例中改变了头盔的旋转方向； 94 * 修改节点的visible属性改变节点的可见性，本示例中改变了头盔的可见性； 95 * 使用getEnabled和setEnabled操作节点的layerMask，本示例中将layerMask的信息打印在界面上。 96 97* 对相机的属性如投影、后处理等进行操作的功能接口封装在graphics3d/[SceneNodes.d.ts](https://gitee.com/openharmony/interface_sdk-js/blob/master/api/graphics3d/SceneNodes.d.ts)，源码参考：node_camera.ets 98 * 修改fov属性改变投影的视场角，本示例中设置了45/60/90三种； 99 * 修改nearPlane和farPlane属性投影的近平面和远平面； 100 * 修改enabled属性改变相机是否启用，设为false之后控件中的画面将不再刷新； 101 * 修改postProcess.toneMapping.type属性可以改变用于色调映射的方法，目前有ACES/ACES_2020/FILMIC三种； 102 * 修改postProcess.toneMapping.exposure属性可以改变用于色调映射的曝光参数； 103 * 修改clearColor属性可以设置每一帧的刷新背景色，设置a通道为零可以获得一个透明的背景，设置为null时不会刷新全部背景像素。 104 105* 对灯光的类型、颜色、强度、阴影等进行操作的功能接口封装在graphics3d/[SceneNodes.d.ts](https://gitee.com/openharmony/interface_sdk-js/blob/master/api/graphics3d/SceneNodes.d.ts)，源码参考：node_light.ets 106 * lightType属性为只读，表示灯光的种类，目前有DIRECTIONAL和SPOT两种，分别为平行光和点光源； 107 * 修改enabled属性改变灯光是否启用； 108 * 修改color属性可以改变灯光的颜色，本示例中有三种可以变化； 109 * 修改intensity属性可以改变灯光的强度； 110 * 修改shadowEnabled属性可以设置灯光是否产生阴影。 111 112* 对背景进行操作的功能接口封装在graphics3d/[SceneResources.d.ts](https://gitee.com/openharmony/interface_sdk-js/blob/master/api/graphics3d/SceneResources.d.ts)，源码参考：scene_environment.ets 113 * 同时修改backgroundType和environmentImage可以设置背景图片，backgroundType为BACKGROUND_IMAGE或BACKGROUND_EQUIRECTANGULAR时对应png或者jpeg格式的图片；类型为BACKGROUND_CUBEMAP时对应ktx格式的图片；类型为BACKGROUND_NONE时不设置背景图片，需要同时将camera的clearColor的a通道设置为0以获得透明背景； 114 * 修改radianceImage属性改变PBR中的环境贴图； 115 * 修改indirectDiffuseFactor属性改变PBR中的相应参数； 116 * 修改indirectSpecularFactor属性改变PBR中的相应参数； 117 * 修改irradianceCoefficients属性改变PBR中的相应参数； 118 * 修改environmentMapFactor属性改变背景图的相应参数。 119 120* 对动画的播放、暂停等进行操作的功能接口封装在graphics3d/[SceneResources.d.ts](https://gitee.com/openharmony/interface_sdk-js/blob/master/api/graphics3d/SceneResources.d.ts)，源码参考：scene_animation.ets 121 * 修改enabled属性改变动画是否启用； 122 * 只读属性duration、running、progress为动画的时长、进行状态、已经进行的比例； 123 * 调用start方法控制动画开启； 124 * 调用pause方法控制动画暂停； 125 * 调用stop方法控制动画停止，并将动画状态设置为开头； 126 * 调用finish方法控制动画结束，并将动画状态设置为结尾； 127 * 调用restart方法控制动画从头开始； 128 * 调用seek方法控制动画设置到指定状态； 129 * onStarted方法在动画开始时执行传入的回调； 130 * onFinished方法在动画结束时执行传入的回调。 131 132- 对纹理材质进行操作的功能接口封装在graphics3d/[SceneResources.d.ts](https://gitee.com/openharmony/interface_sdk-js/blob/master/api/graphics3d/SceneResources.d.ts)，源码参考：scene_shader.ets 133 * 首先创建一个shader作为ShaderMaterial的colorShader，再创建一个material作为纹理的ShaderMaterial； 134 * 使用Geometry获取相应的带有Material的Mesh节点； 135 * 修改shader的input参数； 136 * 修改subMesh的material属性，将其变为自定义的ShaderMaterial； 137 * 修改materialOverride属性，将纹理覆盖为自定义的ShaderMaterial。 138 139### 相关权限 140 141暂无 142 143### 依赖 144 145暂无 146 147### 约束与限制 148 1491. 本示例仅支持标准系统上运行，支持设备：RK3568; 1502. 本示例仅支持API12版本SDK，SDK版本号：(API Version 12 5.0.0.24)，镜像版本号：OpenHarmony 5.0.0.24； 1513. 本示例需要使用DevEco Studio Next Developer Preview2 (Build Version: 4.1.3.700)才可编译运行； 152 153### 下载 154 155``` 156git init 157git config core.sparsecheckout true 158echo code/BasicFeature/Graphics/Graphics3d/ > .git/info/sparse-checkout 159git remote add origin https://gitee.com/openharmony/applications_app_samples.git 160git pull origin master 161```
