• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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## RenderParameters<sup>15+</sup>
332渲染控制参数对象，用于控制场景是否持续渲染。
333
334**系统能力：** SystemCapability.ArkUi.Graphics3D
335| 名称 | 类型 | 只读 | 可选 | 说明 |
336| ---- | ---- | ---- | ---- | ---- |
337| alwaysRender | boolean | 否 | 是 | 控制信号。true表示场景将持续渲染画面，false表示场景只渲染一帧画面。默认值为undefined表示场景只渲染一帧画面。 |
338
339
340## Scene
341用于设置场景。
342
343### 属性
344
345**系统能力：** SystemCapability.ArkUi.Graphics3D
346
347| 名称 | 类型 | 只读 | 可选 | 说明 |
348| ---- | ---- | ---- | ---- | ---- |
349| environment | [Environment](js-apis-inner-scene-resources.md#environment) | 否 | 否 | 环境对象。 |
350| animations | [Animation](js-apis-inner-scene-resources.md#animation)[] | 是 | 否 | 动画数组。 用于保存3D场景中的动画对象。|
351| root | [Node](js-apis-inner-scene-nodes.md#node) \| null | 是 | 否 | 3D场景树根结点。 |
352
353### load
354static load(uri?: ResourceStr): Promise\<Scene>
355
356通过传入的资源路径加载资源。
357
358**系统能力：** SystemCapability.ArkUi.Graphics3D
359
360**参数：**
361| 参数名 | 类型 | 必填 | 说明 |
362| ---- | ---- | ---- | ---- |
363| uri | [ResourceStr](../apis-arkui/arkui-ts/ts-types.md#resourcestr) | 否 | 待加载的模型文件资源路径，默认值为undefined。|
364
365**返回值：**
366| 类型 | 说明 |
367| ---- | ---- |
368| Promise\<[Scene](#scene)> | Promise对象，返回场景对象。|
369
370**示例：**
371```ts
372import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
373  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
374
375function loadModel() : void {
376  // 加载模型
377  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
378  scene.then(async (result: Scene) => {});
379}
380```
381
382### getNodeByPath
383getNodeByPath(path: string, type?: NodeType): Node | null
384
385通过路径获取结点。
386
387**系统能力：** SystemCapability.ArkUi.Graphics3D
388
389**参数：**
390| 参数名 | 类型 | 必填 | 说明 |
391| ---- | ---- | ---- | ---- |
392| path | string | 是 | 场景结点层次中的路径。每层之间使用'/'符号进行分割。|
393| type | [NodeType](js-apis-inner-scene-nodes.md#nodetype) | 否 | 预期返回的结点类型。默认值为空。|
394
395**返回值：**
396| 类型 | 说明 |
397| ---- | ---- |
398| [Node](js-apis-inner-scene-nodes.md#node) \| null | 返回请求结点的实例，如果没有找到或者找到的节点类型与传入的参数不相符则返回空。 |
399
400**示例：**
401```ts
402import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
403  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
404
405function getNode() : void {
406  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
407  scene.then(async (result: Scene) => {
408    if (result) {
409         // 寻找指定路径的节点
410        let node : Node | null = result.getNodeByPath("rootNode_");
411    }
412  });
413}
414```
415
416### getResourceFactory
417getResourceFactory(): SceneResourceFactory
418
419获取场景资源工厂对象。
420
421**系统能力：** SystemCapability.ArkUi.Graphics3D
422
423**返回值：**
424| 类型 | 说明 |
425| ---- | ---- |
426| [SceneResourceFactory](js-apis-inner-scene.md#sceneresourcefactory)| 返回场景资源工厂对象。 |
427
428**示例：**
429```ts
430import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
431  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
432
433function getFactory() : void {
434  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
435  scene.then(async (result: Scene) => {
436    if (result) {
437         // 获得SceneResourceFactory对象
438        let sceneFactory: SceneResourceFactory = result.getResourceFactory();
439    }
440  });
441}
442```
443
444### renderFrame<sup>15+</sup>
445renderFrame(params?: RenderParameters): boolean
446
447渲染新的一帧，同时可以设置是否持续渲染。
448
449**系统能力：** SystemCapability.ArkUi.Graphics3D
450
451**参数：**
452| 参数名 | 类型 | 必填 | 说明 |
453| ---- | ---- | ---- | ---- |
454| params | [RenderParameters](#renderparameters15) | 否 | 渲染控制参数，是否持续渲染。 默认值为undefined。 |
455
456**返回值：**
457| 类型 | 说明 |
458| ---- | ---- |
459| boolean | 渲染及参数设置是否成功。true表示执行成功，false表示执行失败。 |
460
461**示例：**
462```ts
463import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
464  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node, RenderParameters } from '@kit.ArkGraphics3D';
465
466function renderFrame() : void {
467  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
468  scene.then(async (result: Scene) => {
469    if (result) {
470         // 执行渲染且持续渲染
471        let renderParameters: RenderParameters = { alwaysRender: true };
472        let controlResult: boolean = result.renderFrame(renderParameters);
473    }
474  });
475}
476```
477
478### destroy
479destroy(): void
480
481销毁场景，释放所有的场景资源。
482
483**系统能力：** SystemCapability.ArkUi.Graphics3D
484
485**示例：**
486```ts
487import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
488  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
489
490function destroy() : void {
491  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
492  scene.then(async (result: Scene) => {
493    if (result) {
494         // 销毁scene
495        result.destroy();
496    }
497  });
498}
499```
500