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