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