1# Component3D
23D渲染组件，可以加载3D模型资源并做自定义渲染，通常用于3D动效场景。
3
4>  **说明：**
5>
6>  该组件从API Version 12开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
7
8## 子组件
9
10无
11
12
13## 接口
14
15Component3D(sceneOptions?: SceneOptions)
16
17**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
18
19**系统能力：** SystemCapability.ArkUi.Graphics3D
20
21**参数：**
22
23| 参数名       | 类型                                  | 必填 | 说明                                                         |
24| ------------ | ------------------------------------- | ---- | ------------------------------------------------------------ |
25| sceneOptions | [SceneOptions](#sceneoptions对象说明) | 否   | 3D场景配置选项。<br/>**说明：** <br/> 3D场景配置选项在控件创建后不支持动态修改。 |
26
27
28## SceneOptions对象说明
29
30Component3D组件配置选项。
31
32**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
33
34**系统能力：** SystemCapability.ArkUi.Graphics3D
35
36| 名称        | 类型                               | 必填   | 说明                                       |
37| --------- | -------------------------------- | ---- | ---------------------------------------- |
38| scene     | [ResourceStr](ts-types.md#resourcestr)&nbsp;\|&nbsp;[Scene](#scene12) | 否    | 3D模型资源文件或场景对象，默认值为undefined。<br/>**说明：** <br/>目前仅支持GLTF格式资源。 |
39| modelType | [ModelType](#modeltype枚举说明) | 否    | 3D场景显示合成方式。<br/>默认值：ModelType.SURFACE<br/>**说明：** <br/>设置为ModelType.TEXTURE时通过GPU合成显示。<br/>设置为ModelType.SURFACE时通过专有硬件合成显示。<br/>一般开发者可以使用默认值而无需关心此项设置。 |
40
41## ModelType枚举说明
42
43**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
44
45**系统能力：** SystemCapability.ArkUi.Graphics3D
46
47| 名称    | 值   | 说明                     |
48| ------- | ---- | ------------------------ |
49| TEXTURE | 0    | 使用GPU合成显示3D场景。  |
50| SURFACE | 1    | 使用专有硬件显示3D场景。 |
51
52## Scene<sup>12+</sup>
53
54type Scene = Scene
55
56设置3D场景。
57
58**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
59
60**系统能力：** SystemCapability.ArkUi.Graphics3D
61
62| 类型                                                         | 说明           |
63| ------------------------------------------------------------ | -------------- |
64| [Scene](../../apis-arkgraphics3d/js-apis-inner-scene.md#scene-1) | 用于设置场景。 |
65
66## 属性
67
68除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性：
69
70### environment
71
72environment(uri: ResourceStr)
73
74设置3D环境资源。目前仅支持GLTF格式资源，模型资源在控件创建后不支持动态修改。
75
76**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
77
78**系统能力：** SystemCapability.ArkUi.Graphics3D
79
80**参数：**
81
82| 参数名 | 类型                                   | 必填 | 说明         |
83| ------ | -------------------------------------- | ---- | ------------ |
84| uri    | [ResourceStr](ts-types.md#resourcestr) | 是   | 3D环境资源。 |
85
86### customRender
87
88customRender(uri: ResourceStr, selfRenderUpdate: boolean)
89
90设置三维场景渲染的渲染管道。管线配置及自渲染属性在控件创建后不支持动态修改。
91
92**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
93
94**系统能力：** SystemCapability.ArkUi.Graphics3D
95
96**参数：**
97
98| 参数名           | 类型                                   | 必填 | 说明                                                         |
99| ---------------- | -------------------------------------- | ---- | ------------------------------------------------------------ |
100| uri              | [ResourceStr](ts-types.md#resourcestr) | 是   | 自定义渲染管线的配置文件。                                   |
101| selfRenderUpdate | boolean                                | 是   | 当设置为true时外部UI没有更新时也能触发动效渲染。<br/>当设置为false时只有外部UI更新才能触发渲染。 |
102
103### shader
104
105shader(uri: ResourceStr)
106
107设置自定义渲染的shader文件资源。自定义渲染的shader文件资源在控件创建后不支持动态修改。
108
109**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
110
111**系统能力：** SystemCapability.ArkUi.Graphics3D
112
113**参数：**
114
115| 参数名 | 类型                                   | 必填 | 说明                         |
116| ------ | -------------------------------------- | ---- | ---------------------------- |
117| uri    | [ResourceStr](ts-types.md#resourcestr) | 是   | 自定义渲染的shader文件资源。 |
118
119### shaderImageTexture
120
121shaderImageTexture(uri: ResourceStr)
122
123设置自定义渲染用到的纹理资源。若自定义渲染用到多个纹理资源则调用多次，绑定点与调用顺序一致，不支持纹理更换。纹理资源在控件创建后不支持动态修改。
124
125**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
126
127**系统能力：** SystemCapability.ArkUi.Graphics3D
128
129**参数：**
130
131| 参数名 | 类型                                   | 必填 | 说明                       |
132| ------ | -------------------------------------- | ---- | -------------------------- |
133| uri    | [ResourceStr](ts-types.md#resourcestr) | 是   | 自定义渲染用到的纹理资源。 |
134
135### shaderInputBuffer
136
137shaderInputBuffer(buffer: Array&lt;number&gt;)
138
139设置自定义渲染用到的动效参数。
140
141**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
142
143**系统能力：** SystemCapability.ArkUi.Graphics3D
144
145**参数：**
146
147| 参数名 | 类型           | 必填 | 说明                       |
148| ------ | -------------- | ---- | -------------------------- |
149| buffer | Array<number\> | 是   | 自定义渲染用到的动效参数。 |
150
151### renderWidth
152
153renderWidth(value: Dimension)
154
155设置3D渲染分辨率的宽度。渲染分辨率的长宽可以不同于控件的长宽，若渲染分辨率与控件分辨率长宽不一致时会上采样或下采样到控件长宽。
156
157不调用此属性时默认渲染分辨率。
158
159渲染分辨率在控件创建后不支持动态修改。
160
161**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
162
163**系统能力：** SystemCapability.ArkUi.Graphics3D
164
165**参数：**
166
167| 参数名 | 类型                                 | 必填 | 说明                 |
168| ------ | ------------------------------------ | ---- | -------------------- |
169| value  | [Dimension](ts-types.md#dimension10) | 是   | 3D渲染分辨率的宽度。 |
170
171### renderHeight
172
173renderHeight(value: Dimension)
174
175设置3D渲染分辨率的长度。渲染分辨率的长宽可以不同于控件的长宽，若渲染分辨率与控件分辨率长宽不一致时会上采样或下采样到控件长宽。
176
177不调用此属性时默认渲染分辨率。
178
179渲染分辨率在控件创建后不支持动态修改。
180
181**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
182
183**系统能力：** SystemCapability.ArkUi.Graphics3D
184
185**参数：**
186
187| 参数名 | 类型                                 | 必填 | 说明                 |
188| ------ | ------------------------------------ | ---- | -------------------- |
189| value  | [Dimension](ts-types.md#dimension10) | 是   | 3D渲染分辨率的长度。 |
190
191## 事件
192
193支持[通用事件](ts-universal-events-click.md)。
194
195## 示例
196示例效果请以真机运行为准，当前DevEco Studio预览器不支持。<br/>
197GLTF模型加载示例。 <br/>
198```ts
199// xxx.ets
200@Entry
201@Component
202struct Index {
203  scene: SceneOptions = { scene: $rawfile('gltf/DamageHemlt/glTF/DamagedHelmet.gltf'), modelType: ModelType.SURFACE};
204  build() {
205    Row() {
206      Column() {
207        Text('GLTF Example')
208        Component3D( this.scene )
209          .environment($rawfile('gltf/Environment/glTF/Environment.gltf'))
210          .renderWidth('90%').renderHeight('90%')
211      }.width('100%')
212    }
213    .height('100%')
214  }
215}
216```
217自定义渲染示例。 <br/>
218
219```ts
220import { Animator as animator, AnimatorResult } from '@kit.ArkUI';
221
222class EngineTime {
223  totalTimeUs = 0;
224  deltaTimeUs = 0;
225};
226
227let engineTime = new EngineTime();
228let frameCount: number = 0;
229
230function TickFrame() {
231  if (frameCount == 10) {
232    engineTime.totalTimeUs += 1.0;
233    engineTime.deltaTimeUs += 1.0;
234    frameCount = 0;
235  } else {
236    frameCount++;
237  }
238}
239
240@Entry
241@Component
242struct Index {
243  scene: SceneOptions = { scene: $rawfile('gltf/DamageHemlt/glTF/DamagedHelmet.gltf'), modelType: ModelType.SURFACE};
244  backAnimator: AnimatorResult = animator.create({
245    duration: 2000,
246    easing: "ease",
247    delay: 0,
248    fill: "none",
249    direction: "normal",
250    iterations: -1,
251    begin: 100,
252    end: 200,
253  });
254  @State timeDelta: number[] = [1.0, 2.0];
255  create() {
256    this.backAnimator.onfinish = () => {
257      console.log('backAnimator onfinish');
258    }
259    this.backAnimator.onframe = value => {
260      TickFrame();
261      this.timeDelta[0] = engineTime.deltaTimeUs;
262    }
263
264  }
265  build() {
266    Row() {
267      Column() {
268        Text('custom rendering')
269        Component3D()
270          .shader($rawfile('assets/app/shaders/shader/London.shader'))
271          .shaderImageTexture($rawfile('assets/London.jpg'))
272          .shaderInputBuffer(this.timeDelta)
273          .customRender($rawfile('assets/app/rendernodegraphs/London.rng'), true)
274          .renderWidth('90%').renderHeight('90%')
275          .onAppear(() => {
276            this.create();
277            this.backAnimator.play();
278          }).width('50%').height('50%')
279      }.width('100%')
280    }
281    .height('100%')
282  }
283}
284```