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 11. 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
18**Parameters**
19
20| Name         | Type                             | Mandatory  | Description                                    |
21| ------------ | --------------------------------- | ---- | ---------------------------------------- |
22| sceneOptions | [SceneOptions](#sceneoptions) | No   | 3D scene configuration.<br>**NOTE**<br> The 3D scene configuration cannot be dynamically modified after the component is created.|
23
24
25## SceneOptions
26
27Provides the 3D scene configuration options.
28
29| Name       | Type                              | Mandatory  | Description                                      |
30| --------- | -------------------------------- | ---- | ---------------------------------------- |
31| scene     | [Resource](ts-types.md#resource)\|[Scene](../../apis-arkgraphics3d/js-apis-inner-scene.md#scene-1)<sup>12+</sup> | No   | 3D model resource file or scene object.<br>Default value: **undefined**<br>**NOTE**<br>Currently, only GLTF files are supported.|
32| 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.|
33
34## ModelType
35
36| Name     | Description            |
37| ------- | -------------- |
38| TEXTURE | The GPU is used for composition of the 3D scene.|
39| SURFACE | Dedicated hardware is used for composition of the 3D scene. |
40
41
42## Attributes
43
44In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported.
45
46### environment
47
48environment(uri: Resource)
49
50Sets the 3D environment resource. Currently, only GLTF files are supported. Model resources cannot be dynamically modified after the component is created.
51
52**System capability**: SystemCapability.ArkUi.Graphics3D
53
54**Parameters**
55
56| Name| Type                            | Mandatory| Description        |
57| ------ | -------------------------------- | ---- | ------------ |
58| uri    | [Resource](ts-types.md#resource) | Yes  | 3D environment resource.|
59
60### customRender
61
62customRender(uri: Resource, selfRenderUpdate: boolean)
63
64Sets the custom 3D scene rendering pipeline. **uri** and **selfRenderUpdate** cannot be dynamically modified after the component is created.
65
66**System capability**: SystemCapability.ArkUi.Graphics3D
67
68**Parameters**
69
70| Name          | Type                            | Mandatory| Description                                                        |
71| ---------------- | -------------------------------- | ---- | ------------------------------------------------------------ |
72| uri              | [Resource](ts-types.md#resource) | Yes  | Configuration file for creating a custom rendering pipeline.                                  |
73| 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.|
74
75### shader
76
77shader(uri: Resource)
78
79Sets the shader file for custom rendering. The shader file cannot be dynamically modified after the component is created.
80
81**System capability**: SystemCapability.ArkUi.Graphics3D
82
83**Parameters**
84
85| Name| Type                            | Mandatory| Description                        |
86| ------ | -------------------------------- | ---- | ---------------------------- |
87| uri    | [Resource](ts-types.md#resource) | Yes  | Shader file for custom rendering.|
88
89### shaderImageTexture
90
91shaderImageTexture(uri: Resource)
92
93Sets 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.
94
95**System capability**: SystemCapability.ArkUi.Graphics3D
96
97**Parameters**
98
99| Name| Type                            | Mandatory| Description                      |
100| ------ | -------------------------------- | ---- | -------------------------- |
101| uri    | [Resource](ts-types.md#resource) | Yes  | Texture resource used for custom rendering.|
102
103### shaderInputBuffer
104
105shaderInputBuffer(buffer: Array&lt;number&gt;)
106
107Set the animation parameters used for custom rendering. 
108
109**System capability**: SystemCapability.ArkUi.Graphics3D
110
111**Parameters**
112
113| Name| Type          | Mandatory| Description                      |
114| ------ | -------------- | ---- | -------------------------- |
115| buffer | Array<number\> | Yes  | Animation parameters used for custom rendering.|
116
117### renderWidth
118
119renderWidth(value: Dimension)
120
121Sets 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.
122
123If this attribute is not specified, the default width of the rendering resolution is used.
124
125The rendering resolution cannot be dynamically changed after the component is created.
126
127**System capability**: SystemCapability.ArkUi.Graphics3D
128
129**Parameters**
130
131| Name| Type                                | Mandatory| Description                |
132| ------ | ------------------------------------ | ---- | -------------------- |
133| value  | [Dimension](ts-types.md#dimension10) | Yes  | Width of the 3D rendering resolution.|
134
135### renderHeight
136
137renderHeight(value: Dimension)
138
139Sets 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.
140
141If this attribute is not specified, the default width of the rendering resolution is used.
142
143The rendering resolution cannot be dynamically changed after the component is created.
144
145**System capability**: SystemCapability.ArkUi.Graphics3D
146
147**Parameters**
148
149| Name| Type                                | Mandatory| Description                |
150| ------ | ------------------------------------ | ---- | -------------------- |
151| value  | [Dimension](ts-types.md#dimension10) | Yes  | Height of the 3D rendering resolution.|
152
153## Events
154
155The [universal events](ts-universal-events-click.md) are supported.
156
157## Example
158You can preview how this component looks on a real device, but not in DevEco Studio Previewer.<br>
159Example of loading a GLTF model:<br>
160```ts
161// xxx.ets
162@Entry
163@Component
164struct Index {
165  scene: SceneOptions = { scene: $rawfile('gltf/DamageHemlt/glTF/DamagedHelmet.gltf'), modelType: ModelType.SURFACE};
166  build() {
167    Row() {
168      Column() {
169        Text('GLTF Example')
170        Component3D( this.scene )
171          .environment($rawfile('gltf/Environment/glTF/Environment.gltf'))
172          .renderWidth('90%').renderHeight('90%')
173      }.width('100%')
174    }
175    .height('100%')
176  }
177}
178```
179Example of custom rendering:<br>
180
181```ts
182import animator, { AnimatorResult } from '@ohos.animator';
183class EngineTime {
184  totalTimeUs = 0;
185  deltaTimeUs = 0;
186};
187
188let engineTime = new EngineTime();
189let frameCount: number = 0;
190
191function TickFrame() {
192  if (frameCount == 10) {
193    engineTime.totalTimeUs += 1.0;
194    engineTime.deltaTimeUs += 1.0;
195    frameCount = 0;
196  } else {
197    frameCount++;
198  }
199}
200
201@Entry
202@Component
203struct Index {
204  scene: SceneOptions = { scene: $rawfile('gltf/DamageHemlt/glTF/DamagedHelmet.gltf'), modelType: ModelType.SURFACE};
205  backAnimator: AnimatorResult = animator.create({
206    duration: 2000,
207    easing: "ease",
208    delay: 0,
209    fill: "none",
210    direction: "normal",
211    iterations: -1,
212    begin: 100,
213    end: 200,
214  });
215  @State timeDelta: number[] = [1.0, 2.0];
216  create() {
217    this.backAnimator.onfinish = () => {
218      console.log('backAnimator onfinish');
219    }
220    this.backAnimator.onframe = value => {
221      TickFrame();
222      this.timeDelta[0] = engineTime.deltaTimeUs;
223    }
224
225  }
226  build() {
227    Row() {
228      Column() {
229        Text('custom rendering')
230        Component3D()
231          .shader($rawfile('assets/app/shaders/shader/London.shader'))
232          .shaderImageTexture($rawfile('assets/London.jpg'))
233          .shaderInputBuffer(this.timeDelta)
234          .customRender($rawfile('assets/app/rendernodegraphs/London.rng'), true)
235          .renderWidth('90%').renderHeight('90%')
236          .onAppear(() => {
237            this.create();
238            this.backAnimator.play();
239          }).width('50%').height('50%')
240      }.width('100%')
241    }
242    .height('100%')
243  }
244}
245```
246<!--no_check-->