1# SceneResource
2本模块提供3D图形中常用的基本资源类型。
3
4> **说明：**
5> - 本模块首批接口从API version 12开始支持，后续版本的新增接口，采用上角标标记接口的起始版本。
6
7## 导入模块
8```ts
9import { SceneResourceType, SceneResource, Shader, MaterialType, Material, ShaderMaterial,
10  SubMesh, Mesh, Animation, EnvironmentBackgroundType, Environment, Image } from '@kit.ArkGraphics3D';
11```
12## SceneResourceType
13场景资源类型枚举，对场景中的资源进行分类。
14
15**系统能力：** SystemCapability.ArkUi.Graphics3D
16
17| 名称 | 值 | 说明 |
18| ---- | ---- | ---- |
19| UNKNOWN | 0 | 未定义类型。 |
20| NODE | 1 | 结点类型。 |
21| ENVIRONMENT | 2 | 环境类型。 |
22| MATERIAL | 3 | 材质类型。 |
23| MESH | 4 | 网格类型。 |
24| ANIMATION | 5 | 动画类型。 |
25| SHADER | 6 | 着色器类型。 |
26| IMAGE | 7 | 图片类型。 |
27
28## SceneResource
29用于表示场景中的资源。
30
31### 属性
32
33**系统能力：** SystemCapability.ArkUi.Graphics3D
34
35| 名称 | 类型 | 只读 | 可选 | 说明 |
36| ---- | ---- | ---- | ---- | ---- |
37| name | string | 否 | 否 | 名称，没有特殊格式要求。 |
38| resourceType | [SceneResourceType](#sceneresourcetype) | 是 | 否 | 场景资源类型，默认值为undefined。|
39| uri | [ResourceStr](../apis-arkui/arkui-ts/ts-types.md#resourcestr) | 是 | 是 | 需要加载的资源，默认值为undefined。|
40
41### destroy
42destroy(): void
43
44销毁场景资源，释放所有关联的资源或引用，一旦被释放，资源就不能被再次使用或访问。
45
46**系统能力：** SystemCapability.ArkUi.Graphics3D
47
48**示例：**
49```ts
50import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
51  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
52
53function destroy() : void {
54  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
55  scene.then(async (result: Scene) => {
56    if (result) {
57      let sceneFactory: SceneResourceFactory = result.getResourceFactory();
58      let sceneResourceParameter: SceneResourceParameters = { name: "shaderResource",
59        uri: $rawfile("shaders/custom_shader/custom_material_sample.shader") };
60      let shader: Promise<Shader> = sceneFactory.createShader(sceneResourceParameter);
61      shader.then(async (shaderResult:Shader) => {
62         // 释放资源
63         shaderResult.destroy();
64      });
65    }
66  });
67}
68```
69
70## Shader
71着色器，继承自[SceneResource](#sceneresource)。
72
73### 属性
74
75**系统能力：** SystemCapability.ArkUi.Graphics3D
76
77| 名称 | 类型 | 只读 | 可选 | 说明 |
78| ---- | ---- | ---- | ---- | ---- |
79| inputs | Record<string, number \| Vec2 \| Vec3 \| Vec4 \| Image> | 是 | 否 | 着色器输入。 |
80
81## MaterialType
82场景中物体材质类型枚举。
83
84**系统能力：** SystemCapability.ArkUi.Graphics3D
85
86| 名称 | 值 | 说明 |
87| ---- | ---- | ---- |
88| SHADER | 1 | 材质由着色器定义。 |
89
90## Material
91材质类型，继承自[SceneResource](#sceneresource)。
92### 属性
93
94**系统能力：** SystemCapability.ArkUi.Graphics3D
95
96| 名称 | 类型 | 只读 | 可选 | 说明 |
97| ---- | ---- | ---- | ---- | ---- |
98| materialType | [MaterialType](#materialtype) | 是 | 否 | 材质类型。 |
99
100## ShaderMaterial
101着色器材质，继承自[Material](#material)。
102### 属性
103
104**系统能力：** SystemCapability.ArkUi.Graphics3D
105
106| 名称 | 类型 | 只读 | 可选 | 说明 |
107| ---- | ---- | ---- | ---- | ---- |
108| colorShader | [Shader](#shader) | 否 | 是 | 着色器，默认值为undefined。 |
109
110## SubMesh
111子网格类型。
112### 属性
113
114**系统能力：** SystemCapability.ArkUi.Graphics3D
115
116| 名称 | 类型 | 只读 | 可选 | 说明 |
117| ---- | ---- | ---- | ---- | ---- |
118| name | string | 否 | 否 | 名称，没有特殊格式要求。 |
119| material | [Material](#material) | 否 | 否 | 材质。 |
120| aabb | [Aabb](js-apis-inner-scene-types.md#aabb) | 是 | 否 | 轴对齐边界盒。 |
121
122## Mesh
123网格类型，继承自[SceneResource](#sceneresource)。
124### 属性
125
126**系统能力：** SystemCapability.ArkUi.Graphics3D
127
128| 名称 | 类型 | 只读 | 可选 | 说明 |
129| ---- | ---- | ---- | ---- | ---- |
130| subMeshes | [SubMesh](#submesh)[] | 是 | 否 | 子网格数组。 |
131| aabb | [Aabb](js-apis-inner-scene-types.md#aabb) | 是 | 否 | 轴对齐包围盒。|
132| materialOverride | [Material](#material) | 否 | 是 | 材质，默认为空。 |
133
134## Animation
135动画类型，继承自[SceneResource](#sceneresource)。
136### 属性
137
138**系统能力：** SystemCapability.ArkUi.Graphics3D
139
140| 名称 | 类型 | 只读 | 可选 | 说明 |
141| ---- | ---- | ---- | ---- | ---- |
142| enabled | boolean | 否 | 否 | 动画是否使能，true表示可以播放动画，false表示不可以播放动画。 |
143| duration | number | 是 | 否 | 动画持续时间，取值范围大于等于0。 |
144| running | boolean | 是 | 否 | 动画运行状态, true表示动画正在播放，false表示动画停止播放。 |
145| progress | number | 是 | 否 | 动画进度状态，取值区间为[0, 1]。 |
146
147### onFinished
148onFinished(callback: Callback\<void>): void
149
150动画播放结束时执行的的回调函数，动画播放完成或者finish操作会触发这个回调。
151
152**系统能力：** SystemCapability.ArkUi.Graphics3D
153
154**参数：**
155| 参数名 | 类型 | 必填 | 说明 |
156| ---- | ---- | ---- | ---- |
157| callback | Callback\<void> | 是 | 回调函数，返回值为空。 |
158
159**示例：**
160```ts
161import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
162  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
163
164function onFinished() : void {
165  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
166  scene.then(async (result: Scene) => {
167    if (result) {
168      let anim: Animation = result.animations[0];
169      // 注册回调函数
170      anim.onFinished(()=>{
171        console.info("onFinished");
172      });
173    }
174  });
175}
176```
177
178### onStarted
179onStarted(callback: Callback\<void>): void
180
181当动画开始播放时执行的回调函数，start操作以及restart操作也会触发这个回调。
182
183**参数：**
184| 参数名 | 类型 | 必填 | 说明 |
185| ---- | ---- | ---- | ---- |
186| callback | Callback\<void> | 是 | 回调函数，返回值为空。 |
187
188动画开始时会执行传入的回调函数。
189
190**系统能力：** SystemCapability.ArkUi.Graphics3D
191
192**示例：**
193```ts
194import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
195  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
196
197function onStarted() : void {
198  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
199  scene.then(async (result: Scene) => {
200    if (result) {
201      let anim: Animation = result.animations[0];
202      // 注册回调函数
203      anim.onStarted(()=>{
204        console.info("onStarted");
205      });
206    }
207  });
208}
209```
210
211### pause
212pause(): void
213
214将动画暂停，动画的播放进度保持在当前状态。
215
216**系统能力：** SystemCapability.ArkUi.Graphics3D
217
218**示例：**
219```ts
220import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
221  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
222
223function pause() : void {
224  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
225  scene.then(async (result: Scene) => {
226    if (result) {
227      let anim: Animation = result.animations[0];
228      // 暂停动画
229      anim.pause();
230    }
231  });
232}
233```
234
235### restart
236restart(): void
237
238从动画的起点开始播放动画。
239
240**系统能力：** SystemCapability.ArkUi.Graphics3D
241
242**示例：**
243```ts
244import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
245  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
246
247function restart() : void {
248  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
249  scene.then(async (result: Scene) => {
250    if (result) {
251      let anim: Animation = result.animations[0];
252      // 重启动画
253      anim.restart();
254    }
255  });
256}
257```
258
259### seek
260seek(position: number): void
261
262从指定位置开始播放动画。
263
264**系统能力：** SystemCapability.ArkUi.Graphics3D
265
266**参数：**
267| 参数名 | 类型 | 必填 | 说明 |
268| ---- | ---- | ---- | ---- |
269| position | number | 是 | 要重新播放动画的起始位置，取值区间为[0, 1]。 |
270
271**示例：**
272```ts
273import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
274  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
275
276function seek() : void {
277  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
278  scene.then(async (result: Scene) => {
279    if (result) {
280      let anim: Animation = result.animations[0];
281      // 指定动画的播放进度到10%
282      anim.seek(0.1);
283    }
284  });
285}
286```
287
288### start
289start(): void
290
291基于当前进度开始播放一个动画。
292
293**系统能力：** SystemCapability.ArkUi.Graphics3D
294
295**示例：**
296```ts
297import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
298  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
299
300function start() : void {
301  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
302  scene.then(async (result: Scene) => {
303    if (result) {
304      let anim: Animation = result.animations[0];
305      // 开始动画
306      anim.start();
307    }
308  });
309}
310```
311
312### stop
313stop(): void
314
315停止播放一个动画，并将动画的进度设置到未开始状态。
316
317**系统能力：** SystemCapability.ArkUi.Graphics3D
318
319**示例：**
320```ts
321import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
322  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
323
324function stop() : void {
325  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
326  scene.then(async (result: Scene) => {
327    if (result) {
328      let anim: Animation = result.animations[0];
329      // 停止播放动画，并将动画的进度设置到未开始状态
330      anim.stop();
331    }
332  });
333}
334```
335
336### finish
337finish(): void
338
339直接跳转到动画的最后，并将动画的进度设置到已结束状态。
340
341**系统能力：** SystemCapability.ArkUi.Graphics3D
342
343```ts
344import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
345  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';
346
347function finish() : void {
348  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
349  scene.then(async (result: Scene) => {
350    if (result) {
351      let anim: Animation = result.animations[0];
352      // 直接跳转到动画的最后，并将动画的进度设置到已结束状态。
353      anim.finish();
354    }
355  });
356}
357```
358
359## EnvironmentBackgroundType
360环境背景类型枚举。
361
362**系统能力：** SystemCapability.ArkUi.Graphics3D
363
364| 名称 | 值 | 说明 |
365| ---- | ---- | ---- |
366| BACKGROUND_NONE | 0 | 无背景。|
367| BACKGROUND_IMAGE | 1 | 图片背景。 |
368| BACKGROUND_CUBEMAP | 2 | 立方体贴图背景。|
369| BACKGROUND_EQUIRECTANGULAR | 3 | 等距矩形背景。 |
370
371## Environment
372环境类型，继承自[SceneResource](#sceneresource)。
373### 属性
374
375**系统能力：** SystemCapability.ArkUi.Graphics3D
376
377| 名称 | 类型 | 只读 | 可选 | 说明 |
378| ---- | ---- | ---- | ---- | ---- |
379| backgroundType | [EnvironmentBackgroundType](#environmentbackgroundtype) | 否 | 否 | 环境背景类型。 |
380| indirectDiffuseFactor | [Vec4](js-apis-inner-scene-types.md#vec4) | 否 | 否 | 间接散射系数。 |
381| indirectSpecularFactor | [Vec4](js-apis-inner-scene-types.md#vec4) | 否 | 否 | 间接反射系数。 |
382| environmentMapFactor | [Vec4](js-apis-inner-scene-types.md#vec4) | 否 | 否 | 环境地图系数。 |
383| environmentImage | [Image](#image) \| null | 否 | 是 | 环境图片，默认为undefined。 |
384| radianceImage | [Image](#image) \| null | 否 | 是 | 辐射图片，默认为undefined。 |
385| irradianceCoefficients | [Vec3](js-apis-inner-scene-types.md#vec3)[] | 否 | 是 | 辐射系数，默认为undefined。 |
386
387## Image
388图片类型，继承自[SceneResource](#sceneresource)。
389### 属性
390
391**系统能力：** SystemCapability.ArkUi.Graphics3D
392
393| 名称 | 类型 | 只读 | 可选 | 说明 |
394| ---- | ---- | ---- | ---- | ---- |
395| width | number | 是 | 否 | 图片宽度，取值范围大于0。 |
396| height | number | 是 | 否 | 图片高度，取值范围大于0。 |
397