1# Component3D
2The **Component3D** component is used to load 3D model resources and create custom rendering. It is typically used to present 3D animations.
3
4>  **NOTE**
5>
6>  This component is supported since API version 12. Updates will be marked with a superscript to indicate their earliest API version.
7
8## Child Components
9
10Not supported
11
12
13## APIs
14
15Component3D(sceneOptions?: SceneOptions)
16
17**Atomic service API**: This API can be used in atomic services since API version 12.
18
19**System capability**: SystemCapability.ArkUi.Graphics3D
20
21**Parameters**
22
23| Name      | Type                                 | Mandatory| Description                                                        |
24| ------------ | ------------------------------------- | ---- | ------------------------------------------------------------ |
25| sceneOptions | [SceneOptions](#sceneoptions) | No  | 3D scene configuration.<br>**NOTE**<br> The 3D scene configuration cannot be dynamically modified after the component is created.|
26
27
28## SceneOptions
29
30Provides the 3D scene configuration options.
31
32**Atomic service API**: This API can be used in atomic services since API version 12.
33
34**System capability**: SystemCapability.ArkUi.Graphics3D
35
36| Name       | Type                              | Mandatory  | Description                                      |
37| --------- | -------------------------------- | ---- | ---------------------------------------- |
38| scene     | [ResourceStr](ts-types.md#resourcestr) \| [Scene](#scene12) | No   | 3D model resource file or scene object.<br>Default value: **undefined**<br>**NOTE**<br>Currently, only GLTF files are supported.|
39| modelType | [ModelType](#modeltype) | No   | Composition mode of the 3D scene.<br>Default value: **ModelType.SURFACE**<br>**NOTE**<br>**ModelType.TEXTURE**: The GPU is used for composition.<br>**ModelType.SURFACE**: Dedicated hardware is used for composition.<br>In general cases, leave this parameter at its default settings.|
40
41## ModelType
42
43**Atomic service API**: This API can be used in atomic services since API version 12.
44
45**System capability**: SystemCapability.ArkUi.Graphics3D
46
47| Name   | Value  | Description                    |
48| ------- | ---- | ------------------------ |
49| TEXTURE | 0    | The GPU is used for composition of the 3D scene. |
50| SURFACE | 1    | Dedicated hardware is used for composition of the 3D scene.|
51
52## Scene<sup>12+</sup>
53
54type Scene = Scene
55
56Represents a 3D scene object.
57
58**Atomic service API**: This API can be used in atomic services since API version 12.
59
60**System capability**: SystemCapability.ArkUi.Graphics3D
61
62| Type                                                        | Description          |
63| ------------------------------------------------------------ | -------------- |
64| [Scene](../../apis-arkgraphics3d/js-apis-inner-scene.md#scene-1) | 3D scene object.|
65
66## Attributes
67
68In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported.
69
70### environment
71
72environment(uri: ResourceStr)
73
74Sets the 3D environment resource. Currently, only GLTF files are supported. Model resources cannot be dynamically modified after the component is created.
75
76**Atomic service API**: This API can be used in atomic services since API version 12.
77
78**System capability**: SystemCapability.ArkUi.Graphics3D
79
80**Parameters**
81
82| Name| Type                                  | Mandatory| Description        |
83| ------ | -------------------------------------- | ---- | ------------ |
84| uri    | [ResourceStr](ts-types.md#resourcestr) | Yes  | 3D environment resource.|
85
86### customRender
87
88customRender(uri: ResourceStr, selfRenderUpdate: boolean)
89
90Sets the custom 3D scene rendering pipeline. **uri** and **selfRenderUpdate** cannot be dynamically modified after the component is created.
91
92**Atomic service API**: This API can be used in atomic services since API version 12.
93
94**System capability**: SystemCapability.ArkUi.Graphics3D
95
96**Parameters**
97
98| Name          | Type                                  | Mandatory| Description                                                        |
99| ---------------- | -------------------------------------- | ---- | ------------------------------------------------------------ |
100| uri              | [ResourceStr](ts-types.md#resourcestr) | Yes  | Configuration file for creating a custom rendering pipeline.                                  |
101| selfRenderUpdate | boolean                                | Yes  | Whether rendering can be triggered when the external UI is not updated.<br>The value **true** means that rendering can be triggered when the external UI is not updated, and false means the opposite.|
102
103### shader
104
105shader(uri: ResourceStr)
106
107Sets the shader file for custom rendering. The shader file cannot be dynamically modified after the component is created.
108
109**Atomic service API**: This API can be used in atomic services since API version 12.
110
111**System capability**: SystemCapability.ArkUi.Graphics3D
112
113**Parameters**
114
115| Name| Type                                  | Mandatory| Description                        |
116| ------ | -------------------------------------- | ---- | ---------------------------- |
117| uri    | [ResourceStr](ts-types.md#resourcestr) | Yes  | Shader file for custom rendering.|
118
119### shaderImageTexture
120
121shaderImageTexture(uri: ResourceStr)
122
123Sets the texture resource used for custom rendering. To use multiple texture resources for custom rendering, call this API multiple times. The sequence in which the resources are used is the same as the call sequence. The texture resource cannot be dynamically modified after the component is created.
124
125**Atomic service API**: This API can be used in atomic services since API version 12.
126
127**System capability**: SystemCapability.ArkUi.Graphics3D
128
129**Parameters**
130
131| Name| Type                                  | Mandatory| Description                      |
132| ------ | -------------------------------------- | ---- | -------------------------- |
133| uri    | [ResourceStr](ts-types.md#resourcestr) | Yes  | Texture resource used for custom rendering.|
134
135### shaderInputBuffer
136
137shaderInputBuffer(buffer: Array&lt;number&gt;)
138
139Set the animation parameters used for custom rendering.
140
141**Atomic service API**: This API can be used in atomic services since API version 12.
142
143**System capability**: SystemCapability.ArkUi.Graphics3D
144
145**Parameters**
146
147| Name| Type          | Mandatory| Description                      |
148| ------ | -------------- | ---- | -------------------------- |
149| buffer | Array<number\> | Yes  | Animation parameters used for custom rendering.|
150
151### renderWidth
152
153renderWidth(value: Dimension)
154
155Sets the width of the 3D rendering resolution. The width and height of the rendering resolution may be different from those of the component. If this is the case, they are upsampled or downsampled to the component width and height.
156
157If this attribute is not specified, the default width of the rendering resolution is used.
158
159The rendering resolution cannot be dynamically changed after the component is created.
160
161**Atomic service API**: This API can be used in atomic services since API version 12.
162
163**System capability**: SystemCapability.ArkUi.Graphics3D
164
165**Parameters**
166
167| Name| Type                                | Mandatory| Description                |
168| ------ | ------------------------------------ | ---- | -------------------- |
169| value  | [Dimension](ts-types.md#dimension10) | Yes  | Width of the 3D rendering resolution.|
170
171### renderHeight
172
173renderHeight(value: Dimension)
174
175Sets the height of the 3D rendering resolution. The width and height of the rendering resolution may be different from those of the component. If this is the case, they are upsampled or downsampled to the component width and height.
176
177If this attribute is not specified, the default width of the rendering resolution is used.
178
179The rendering resolution cannot be dynamically changed after the component is created.
180
181**Atomic service API**: This API can be used in atomic services since API version 12.
182
183**System capability**: SystemCapability.ArkUi.Graphics3D
184
185**Parameters**
186
187| Name| Type                                | Mandatory| Description                |
188| ------ | ------------------------------------ | ---- | -------------------- |
189| value  | [Dimension](ts-types.md#dimension10) | Yes  | Height of the 3D rendering resolution.|
190
191## Events
192
193The [universal events](ts-universal-events-click.md) are supported.
194
195## Example
196You can preview how this component looks on a real device, but not in DevEco Studio Previewer.<br>
197Example of loading a GLTF model:<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```
217Example of custom rendering:<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```
285