1# Scene 2本模块作为ArkGraphics 3D基础模块,提供SceneResourceParamters、SceneNodeParamters等通用数据类型。同时提供glTF模型加载,场景元素、资源创建等基础方法。 3 4> **说明:** 5> - 本模块首批接口从API version 12开始支持,后续版本的新增接口,采用上角标标记接口的起始版本。 6 7## 导入模块 8```ts 9import { SceneResourceParameters, SceneNodeParameters, SceneResourceFactory, Scene } from '@kit.ArkGraphics3D'; 10``` 11 12## SceneResourceParameters 13场景资源参数对象。包含name和uri。用于提供场景资源的名称以及3D场景所需的资源文件路径。 14 15**系统能力:** SystemCapability.ArkUi.Graphics3D 16| 名称 | 类型 | 只读 | 可选 | 说明 | 17| ---- | ---- | ---- | ---- | ---- | 18| name | string | 否 | 否 | 要创建资源的名称,可由开发者自定填写。| 19| uri | [ResourceStr](../apis-arkui/arkui-ts/ts-types.md#resourcestr) | 否 | 是 | 3D场景所需的资源文件路径。默认值为undefined。| 20 21**示例:** 22```ts 23import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters, 24 LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D'; 25 26function createShaderPromise() : Promise<Shader> { 27 return new Promise(() => { 28 let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf")); 29 scene.then(async (result: Scene) => { 30 let sceneFactory: SceneResourceFactory = result.getResourceFactory(); 31 32 // 创建SceneResourceParameters类型变量并以此创建shader 33 let sceneResourceParameter: SceneResourceParameters = { name: "shaderResource", 34 uri: $rawfile("shaders/custom_shader/custom_material_sample.shader") }; 35 let shader: Promise<Shader> = sceneFactory.createShader(sceneResourceParameter); 36 return shader; 37 }); 38 }); 39} 40``` 41 42## SceneNodeParameters 43场景结点参数对象,它用于提供场景结点层次中的名称和路径。 44 45**系统能力:** SystemCapability.ArkUi.Graphics3D 46| 名称 | 类型 | 只读 | 可选 | 说明 | 47| ---- | ---- | ---- | ---- | ---- | 48| name | string | 否 | 否 | 要创建的结点名称,可由开发者自定义填写。 49| path | string | 否 | 是 | 场景结点层次中的路径。用于指定创建的摄影机、灯光或结点在场景结点层次中的放置位置。每层之间使用'/'符号进行分割。如果未提供,则将其设置为根结点的子结点。默认值为undefined。| 50 51**示例:** 52```ts 53import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters, 54 LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D'; 55 56function createNodePromise() : Promise<Node> { 57 return new Promise(() => { 58 let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf")); 59 scene.then(async (result: Scene) => { 60 let sceneFactory: SceneResourceFactory = result.getResourceFactory(); 61 62 // 创建SceneNodeParameters类型变量并以此创建node 63 let sceneNodeParameter: SceneNodeParameters = { name: "empty_node", 64 path:"/rootNode_/empty_node" }; 65 let node: Promise<Node> = sceneFactory.createNode(sceneNodeParameter); 66 return node; 67 }); 68 }); 69} 70``` 71## SceneResourceFactory 72用于创建3D场景中资源的接口,例如相机、光源等。 73 74### createCamera 75createCamera(params: SceneNodeParameters): Promise\<Camera> 76 77根据结点参数创建相机, 使用Promise异步回调。 78 79**系统能力:** SystemCapability.ArkUi.Graphics3D 80 81**参数:** 82| 参数名 | 类型 | 必填 | 说明 | 83| ---- | ---- | ---- | ---- | 84| params | [SceneNodeParameters](#scenenodeparameters) | 是 | 场景结点参数。 | 85 86**返回值:** 87| 类型 | 说明 | 88| ---- | ---- | 89| Promise\<[Camera](js-apis-inner-scene-nodes.md#camera)> | Promise对象,返回相机对象。 | 90 91**示例:** 92```ts 93import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters, 94 LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D'; 95 96function createCameraPromise() : Promise<Camera> { 97 return new Promise(() => { 98 let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf")); 99 scene.then(async (result: Scene) => { 100 let sceneFactory: SceneResourceFactory = result.getResourceFactory(); 101 let sceneCameraParameter: SceneNodeParameters = { name: "camera1" }; 102 // 创建相机 103 let camera: Promise<Camera> = sceneFactory.createCamera(sceneCameraParameter); 104 return camera; 105 }); 106 }); 107} 108``` 109 110### createLight 111createLight(params: SceneNodeParameters, lightType: LightType): Promise\<Light> 112 113根据结点参数和灯光类型创建灯光, 使用Promise异步回调。 114 115**系统能力:** SystemCapability.ArkUi.Graphics3D 116 117**参数:** 118| 参数名 | 类型 | 必填 | 说明 | 119| ---- | ---- | ---- | ---- | 120| params | [SceneNodeParameters](#scenenodeparameters) | 是 | 场景结点参数。 | 121| lightType | [LightType](js-apis-inner-scene-nodes.md#lighttype) | 是 | 灯光类型。 | 122 123**返回值:** 124| 类型 | 说明 | 125| ---- | ---- | 126| Promise\<[Light](js-apis-inner-scene-nodes.md#light)> | Promise对象,返回灯光对象。 | 127 128**示例:** 129```ts 130import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters, 131 LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D'; 132 133function createLightPromise() : Promise<Light> { 134 return new Promise(() => { 135 let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf")); 136 scene.then(async (result: Scene) => { 137 let sceneFactory: SceneResourceFactory = result.getResourceFactory(); 138 let sceneLightParameter: SceneNodeParameters = { name: "light" }; 139 // 创建平行光 140 let light: Promise<Light> = sceneFactory.createLight(sceneLightParameter, LightType.DIRECTIONAL); 141 return light; 142 }); 143 }); 144} 145``` 146 147### createNode 148createNode(params: SceneNodeParameters): Promise\<Node> 149 150创建结点, 使用Promise异步回调。 151 152**系统能力:** SystemCapability.ArkUi.Graphics3D 153 154**参数:** 155| 参数名 | 类型 | 必填 | 说明 | 156| ---- | ---- | ---- | ---- | 157| params | [SceneNodeParameters](#scenenodeparameters) | 是 | 场景结点参数。 | 158 159**返回值:** 160| 类型 | 说明 | 161| ---- | ---- | 162| Promise\<[Node](js-apis-inner-scene-nodes.md#node)> | Promise对象,返回结点对象。 | 163 164**示例:** 165```ts 166import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters, 167 LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D'; 168 169function createNodePromise() : Promise<Node> { 170 return new Promise(() => { 171 let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf")); 172 scene.then(async (result: Scene) => { 173 let sceneFactory: SceneResourceFactory = result.getResourceFactory(); 174 let sceneNodeParameter: SceneNodeParameters = { name: "empty_node", 175 path:"/rootNode_/empty_node" }; 176 // 创建节点 177 let node: Promise<Node> = sceneFactory.createNode(sceneNodeParameter); 178 return node; 179 }); 180 }); 181} 182``` 183 184### createMaterial 185createMaterial(params: SceneResourceParameters, materialType: MaterialType): Promise\<Material> 186 187根据场景资源参数和材质类型创建材质, 使用Promise异步回调。 188 189**系统能力:** SystemCapability.ArkUi.Graphics3D 190 191**参数:** 192| 参数名 | 类型 | 必填 | 说明 | 193| ---- | ---- | ---- | ---- | 194| params | [SceneResourceParameters](#sceneresourceparameters) | 是 | 场景资源参数。 | 195| materialType | [MaterialType](js-apis-inner-scene-resources.md#materialtype) | 是 | 材质类型。 | 196 197**返回值:** 198| 类型 | 说明 | 199| ---- | ---- | 200| Promise\<[Material](js-apis-inner-scene-resources.md#material)> | Promise对象,返回材质对象。| 201 202**示例:** 203```ts 204import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters, 205 LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D'; 206 207function createMaterialPromise() : Promise<Material> { 208 return new Promise(() => { 209 let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf")); 210 scene.then(async (result: Scene) => { 211 let sceneFactory: SceneResourceFactory = result.getResourceFactory(); 212 let sceneMaterialParameter: SceneResourceParameters = { name: "material" }; 213 // 创建材质 214 let material: Promise<Material> = sceneFactory.createMaterial(sceneMaterialParameter, MaterialType.SHADER); 215 return material; 216 }); 217 }); 218} 219``` 220 221### createShader 222createShader(params: SceneResourceParameters): Promise\<Shader> 223 224根据场景资源参数创建着色器, 使用Promise异步回调。 225 226**系统能力:** SystemCapability.ArkUi.Graphics3D 227 228**参数:** 229| 参数名 | 类型 | 必填 | 说明 | 230| ---- | ---- | ---- | ---- | 231| params | [SceneResourceParameters](#sceneresourceparameters) | 是 | 场景资源参数。 | 232 233**返回值:** 234| 类型 | 说明 | 235| ---- | ---- | 236| Promise\<[Shader](js-apis-inner-scene-resources.md#shader)> | Promise对象,返回着色器对象。 | 237 238**示例:** 239```ts 240import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters, 241 LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D'; 242 243function createShaderPromise() : Promise<Shader> { 244 return new Promise(() => { 245 let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf")); 246 scene.then(async (result: Scene) => { 247 let sceneFactory: SceneResourceFactory = result.getResourceFactory(); 248 let sceneResourceParameter: SceneResourceParameters = { name: "shaderResource", 249 uri: $rawfile("shaders/custom_shader/custom_material_sample.shader") }; 250 // 创建shader 251 let shader: Promise<Shader> = sceneFactory.createShader(sceneResourceParameter); 252 return shader; 253 }); 254 }); 255} 256``` 257 258 259### createImage 260createImage(params: SceneResourceParameters): Promise\<Image> 261 262创建图片资源, 使用Promise异步回调。 263 264**系统能力:** SystemCapability.ArkUi.Graphics3D 265 266**参数:** 267| 参数名 | 类型 | 必填 | 说明 | 268| ---- | ---- | ---- | ---- | 269| params | [SceneResourceParameters](#sceneresourceparameters) | 是 | 场景资源参数。 | 270 271**返回值:** 272| 类型 | 说明 | 273| ---- | ---- | 274| Promise\<[Image](js-apis-inner-scene-resources.md#image)> | Promise对象,返回图片对象。 | 275 276**示例:** 277```ts 278import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters, 279 LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D'; 280 281function createImagePromise() : Promise<Image> { 282 return new Promise(() => { 283 let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf")); 284 scene.then(async (result: Scene) => { 285 let sceneFactory: SceneResourceFactory = result.getResourceFactory(); 286 let sceneImageParameter: SceneResourceParameters = { name: "image", uri: $rawfile("bricks.jpg") }; 287 // 创建Image 288 let image: Promise<Image> = sceneFactory.createImage(sceneImageParameter); 289 return image; 290 }); 291 }); 292} 293``` 294 295### createEnvironment 296createEnvironment(params: SceneResourceParameters): Promise\<Environment> 297 298根据场景资源参数创建环境, 使用Promise异步回调。 299 300**系统能力:** SystemCapability.ArkUi.Graphics3D 301 302**参数:** 303| 参数名 | 类型 | 必填 | 说明 | 304| ---- | ---- | ---- | ---- | 305| params | [SceneResourceParameters](#sceneresourceparameters) | 是 | 场景资源参数。 | 306 307**返回值:** 308| 类型 | 说明 | 309| ---- | ---- | 310| Promise\<[Environment](js-apis-inner-scene-resources.md#environment)> | Promise对象,返回环境对象。 | 311 312**示例:** 313```ts 314import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters, 315 LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D'; 316 317function createEnvironmentPromise() : Promise<Environment> { 318 return new Promise(() => { 319 let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf")); 320 scene.then(async (result: Scene) => { 321 let sceneFactory: SceneResourceFactory = result.getResourceFactory(); 322 let sceneEnvironmentParameter: SceneResourceParameters = { name: "env", uri: $rawfile("bricks.ktx") }; 323 // 创建Environment 324 let env: Promise<Environment> = sceneFactory.createEnvironment(sceneEnvironmentParameter); 325 return env; 326 }); 327 }); 328} 329``` 330 331## Scene 332用于设置场景。 333 334### 属性 335 336**系统能力:** SystemCapability.ArkUi.Graphics3D 337 338| 名称 | 类型 | 只读 | 可选 | 说明 | 339| ---- | ---- | ---- | ---- | ---- | 340| environment | [Environment](js-apis-inner-scene-resources.md#environment) | 否 | 否 | 环境对象。 | 341| animations | [Animation](js-apis-inner-scene-resources.md#animation)[] | 是 | 否 | 动画数组。 用于保存3D场景中的动画对象。| 342| root | [Node](js-apis-inner-scene-nodes.md#node) \| null | 是 | 否 | 3D场景树根结点。 | 343 344### load 345static load(uri?: ResourceStr): Promise\<Scene> 346 347通过传入的资源路径加载资源。 348 349**系统能力:** SystemCapability.ArkUi.Graphics3D 350 351**参数:** 352| 参数名 | 类型 | 必填 | 说明 | 353| ---- | ---- | ---- | ---- | 354| uri | [ResourceStr](../apis-arkui/arkui-ts/ts-types.md#resourcestr) | 否 | 待加载的模型文件资源路径,默认值为undefined。| 355 356**返回值:** 357| 类型 | 说明 | 358| ---- | ---- | 359| Promise\<[Scene](#scene)> | Promise对象,返回场景对象。| 360 361**示例:** 362```ts 363import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters, 364 LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D'; 365 366function loadModel() : void { 367 // 加载模型 368 let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf")); 369 scene.then(async (result: Scene) => {}); 370} 371``` 372 373### getNodeByPath 374getNodeByPath(path: string, type?: NodeType): Node | null 375 376通过路径获取结点。 377 378**系统能力:** SystemCapability.ArkUi.Graphics3D 379 380**参数:** 381| 参数名 | 类型 | 必填 | 说明 | 382| ---- | ---- | ---- | ---- | 383| path | string | 是 | 场景结点层次中的路径。每层之间使用'/'符号进行分割。| 384| type | [NodeType](js-apis-inner-scene-nodes.md#nodetype) | 否 | 预期返回的结点类型。默认值为空。| 385 386**返回值:** 387| 类型 | 说明 | 388| ---- | ---- | 389| [Node](js-apis-inner-scene-nodes.md#node) \| null | 返回请求结点的实例,如果没有找到或者找到的节点类型与传入的参数不相符则返回空。 | 390 391**示例:** 392```ts 393import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters, 394 LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D'; 395 396function getNode() : void { 397 let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf")); 398 scene.then(async (result: Scene) => { 399 if (result) { 400 // 寻找指定路径的节点 401 let node : Node | null = result.getNodeByPath("rootNode_"); 402 } 403 }); 404} 405``` 406 407### getResourceFactory 408getResourceFactory(): SceneResourceFactory 409 410获取场景资源工厂对象。 411 412**系统能力:** SystemCapability.ArkUi.Graphics3D 413 414**返回值:** 415| 类型 | 说明 | 416| ---- | ---- | 417| [SceneResourceFactory](js-apis-inner-scene.md#sceneresourcefactory)| 返回场景资源工厂对象。 | 418 419**示例:** 420```ts 421import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters, 422 LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D'; 423 424function getFactory() : void { 425 let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf")); 426 scene.then(async (result: Scene) => { 427 if (result) { 428 // 获得SceneResourceFactory对象 429 let sceneFactory: SceneResourceFactory = result.getResourceFactory(); 430 } 431 }); 432} 433``` 434 435### destroy 436destroy(): void 437 438销毁场景,释放所有的场景资源。 439 440**系统能力:** SystemCapability.ArkUi.Graphics3D 441 442**示例:** 443```ts 444import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters, 445 LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D'; 446 447function destroy() : void { 448 let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf")); 449 scene.then(async (result: Scene) => { 450 if (result) { 451 // 销毁scene 452 result.destroy(); 453 } 454 }); 455} 456``` 457