• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1/*
2 * Copyright (c) 2024-2024 Huawei Device Co., Ltd.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 *     http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16/**
17 * @file Defines 3D node related interfaces
18 * @kit ArkGraphics3D
19 */
20
21import { SceneResource, Mesh, Morpher } from './SceneResources';
22import { Position3, Quaternion, Scale3, Color, Vec2, Vec3 } from './SceneTypes';
23import { PostProcessSettings } from './ScenePostProcessSettings';
24import { RaycastParameters, RaycastResult } from './Scene';
25
26/**
27 * Defines the layer mask of the node.
28 *
29 * @interface LayerMask
30 * @syscap SystemCapability.ArkUi.Graphics3D
31 * @since 12
32 */
33export interface LayerMask {
34  /**
35   * Get whether layer mask is enabled.
36   *
37   * @param { number } index - the layer mask
38   * @returns { boolean } whether layer mask is enabled
39   * @syscap SystemCapability.ArkUi.Graphics3D
40   * @since 12
41   */
42  getEnabled(index: number): boolean;
43
44  /**
45   * Set whether the layer mask is enabled.
46   *
47   * @param { number } index - the layer mask
48   * @param { boolean } enabled - whether layer mask is enabled
49   * @syscap SystemCapability.ArkUi.Graphics3D
50   * @since 12
51   */
52  setEnabled(index: number, enabled: boolean): void;
53}
54
55/**
56 * The enum of node type.
57 *
58 * @enum { number }
59 * @syscap SystemCapability.ArkUi.Graphics3D
60 * @since 12
61 */
62export enum NodeType {
63  /**
64   * The node is an empty node.
65   *
66   * @syscap SystemCapability.ArkUi.Graphics3D
67   * @since 12
68   */
69  NODE = 1,
70
71  /**
72   * The node is a geometry node.
73   *
74   * @syscap SystemCapability.ArkUi.Graphics3D
75   * @since 12
76   */
77  GEOMETRY = 2,
78
79  /**
80   * The node is a camera node.
81   *
82   * @syscap SystemCapability.ArkUi.Graphics3D
83   * @since 12
84   */
85  CAMERA = 3,
86
87  /**
88   * The node is a light node.
89   *
90   * @syscap SystemCapability.ArkUi.Graphics3D
91   * @since 12
92   */
93  LIGHT = 4
94}
95
96/**
97 * Defines a scene object container.
98 *
99 * @interface Container
100 * @syscap SystemCapability.ArkUi.Graphics3D
101 * @since 12
102 */
103export interface Container<T> {
104  /**
105   * Append a item to the container.
106   *
107   * @param { T } item - the item append to the end of container
108   * @syscap SystemCapability.ArkUi.Graphics3D
109   * @since 12
110   */
111  append(item: T): void;
112
113  /**
114   * Insert a item.
115   *
116   * @param { T } item - the item insert to the container
117   * @param { T | null } sibling - insert after this item, insert to the head if sibling is null
118   * @syscap SystemCapability.ArkUi.Graphics3D
119   * @since 12
120   */
121  insertAfter(item: T, sibling: T | null): void;
122
123  /**
124   * Remove a item from Container's children.
125   *
126   * @param { T } item - the item to be removed
127   * @syscap SystemCapability.ArkUi.Graphics3D
128   * @since 12
129   */
130  remove(item: T): void;
131
132  /**
133   * Returns a child at given index from this Container's child list.
134   *
135   * @param { number } index - the index of the child to return
136   * @returns { T | null } return the item specified by the index
137   * @syscap SystemCapability.ArkUi.Graphics3D
138   * @since 12
139   */
140  get(index: number): T | null;
141
142  /**
143   * Clear all children.
144   *
145   * @syscap SystemCapability.ArkUi.Graphics3D
146   * @since 12
147   */
148  clear(): void;
149
150  /**
151   * Returns the number of items in the container.
152   *
153   * @returns { number } the number of the container
154   * @syscap SystemCapability.ArkUi.Graphics3D
155   * @since 12
156   */
157  count(): number;
158}
159
160/**
161 * Defines Node interface.
162 *
163 * @extends SceneResource
164 * @interface Node
165 * @syscap SystemCapability.ArkUi.Graphics3D
166 * @since 12
167 */
168export interface Node extends SceneResource {
169  /**
170   * position of the node.
171   *
172   * @type { Position3 }
173   * @syscap SystemCapability.ArkUi.Graphics3D
174   * @since 12
175   */
176  position: Position3;
177
178  /**
179   * Rotation of the node.
180   *
181   * @type { Quaternion }
182   * @syscap SystemCapability.ArkUi.Graphics3D
183   * @since 12
184   */
185  rotation: Quaternion;
186
187  /**
188   * Scale of the node.
189   *
190   * @type { Scale3 }
191   * @syscap SystemCapability.ArkUi.Graphics3D
192   * @since 12
193   */
194  scale: Scale3;
195
196  /**
197   * Visibility flag for the node.
198   *
199   * @type { boolean }
200   * @syscap SystemCapability.ArkUi.Graphics3D
201   * @since 12
202   */
203  visible: boolean;
204
205  /**
206   * Type of the node.
207   *
208   * @type { NodeType }
209   * @readonly
210   * @syscap SystemCapability.ArkUi.Graphics3D
211   * @since 12
212   */
213  readonly nodeType: NodeType;
214
215  /**
216   * Layer mask of the node.
217   *
218   * @type { LayerMask }
219   * @readonly
220   * @syscap SystemCapability.ArkUi.Graphics3D
221   * @since 12
222   */
223  readonly layerMask: LayerMask;
224
225  /**
226   * Path of the node.
227   *
228   * @type { string }
229   * @readonly
230   * @syscap SystemCapability.ArkUi.Graphics3D
231   * @since 12
232   */
233  readonly path: string;
234
235  /**
236   * Parent of the node.
237   *
238   * @type { Node | null }
239   * @readonly
240   * @syscap SystemCapability.ArkUi.Graphics3D
241   * @since 12
242   */
243  readonly parent: Node | null;
244
245  /**
246   * Get node by path.
247   *
248   * @param { string } path - the path of the node queried
249   * @returns { Node | null }
250   * @syscap SystemCapability.ArkUi.Graphics3D
251   * @since 12
252   */
253  getNodeByPath(path: string): Node | null;
254
255  /**
256   * Children of the node.
257   *
258   * @type { Container<Node> }
259   * @readonly
260   * @syscap SystemCapability.ArkUi.Graphics3D
261   * @since 12
262   */
263  readonly children: Container<Node>
264}
265
266/**
267 * Defines Geometry interface.
268 *
269 * @extends Node
270 * @interface Geometry
271 * @syscap SystemCapability.ArkUi.Graphics3D
272 * @since 12
273 */
274export interface Geometry extends Node {
275  /**
276   * Mesh of the node.
277   *
278   * @type { Mesh }
279   * @readonly
280   * @syscap SystemCapability.ArkUi.Graphics3D
281   * @since 12
282   */
283  readonly mesh: Mesh;
284
285  /**
286   * Morpher target definition.
287   *
288   * @type { ?Morpher }
289   * @readonly
290   * @syscap SystemCapability.ArkUi.Graphics3D
291   * @since 20
292   */
293  readonly morpher?: Morpher;
294}
295
296/**
297 * The enum of light type.
298 *
299 * @enum { number }
300 * @syscap SystemCapability.ArkUi.Graphics3D
301 * @since 12
302 */
303export enum LightType {
304  /**
305   * Directional light.
306   *
307   * @syscap SystemCapability.ArkUi.Graphics3D
308   * @since 12
309   */
310  DIRECTIONAL = 1,
311
312  /**
313   * Spot light.
314   *
315   * @syscap SystemCapability.ArkUi.Graphics3D
316   * @since 12
317   */
318  SPOT = 2,
319}
320
321/**
322 * Defines light interface.
323 *
324 * @extends Node
325 * @interface Light
326 * @syscap SystemCapability.ArkUi.Graphics3D
327 * @since 12
328 */
329export interface Light extends Node {
330  /**
331   * The type of the light.
332   *
333   * @type { LightType }
334   * @readonly
335   * @syscap SystemCapability.ArkUi.Graphics3D
336   * @since 12
337   */
338  readonly lightType: LightType;
339
340  /**
341   * The color of the light.
342   *
343   * @type { Color }
344   * @syscap SystemCapability.ArkUi.Graphics3D
345   * @since 12
346   */
347  color: Color;
348
349  /**
350   * The intensity of the light.
351   *
352   * @type { number }
353   * @syscap SystemCapability.ArkUi.Graphics3D
354   * @since 12
355   */
356  intensity: number;
357
358  /**
359   * Whether casting shadows.
360   *
361   * @type { boolean }
362   * @syscap SystemCapability.ArkUi.Graphics3D
363   * @since 12
364   */
365  shadowEnabled: boolean;
366
367  /**
368   * Whether enable the light.
369   *
370   * @type { boolean }
371   * @syscap SystemCapability.ArkUi.Graphics3D
372   * @since 12
373   */
374  enabled: boolean;
375}
376
377/**
378 * Defines spot light.
379 *
380 * @extends Light
381 * @interface SpotLight
382 * @syscap SystemCapability.ArkUi.Graphics3D
383 * @since 12
384 */
385export interface SpotLight extends Light {
386}
387
388/**
389 * Defines directional light.
390 *
391 * @extends Light
392 * @interface DirectionalLight
393 * @syscap SystemCapability.ArkUi.Graphics3D
394 * @since 12
395 */
396export interface DirectionalLight extends Light {
397}
398
399/**
400 * Defines camera.
401 *
402 * @extends Node
403 * @interface Camera
404 * @syscap SystemCapability.ArkUi.Graphics3D
405 * @since 12
406 */
407export interface Camera extends Node {
408  /**
409   * Field of view of the camera.
410   *
411   * @type { number }
412   * @syscap SystemCapability.ArkUi.Graphics3D
413   * @since 12
414   */
415  fov: number;
416
417  /**
418   * Near plane of the directional light.
419   *
420   * @type { number }
421   * @syscap SystemCapability.ArkUi.Graphics3D
422   * @since 12
423   */
424  nearPlane: number;
425
426  /**
427   * Far plane of the directional light.
428   *
429   * @type { number }
430   * @syscap SystemCapability.ArkUi.Graphics3D
431   * @since 12
432   */
433  farPlane: number;
434
435  /**
436   * Whether enabled the camera.
437   *
438   * @type { boolean }
439   * @syscap SystemCapability.ArkUi.Graphics3D
440   * @since 12
441   */
442  enabled: boolean;
443
444  /**
445   * The post processing settings of the camera.
446   *
447   * @type { PostProcessSettings | null }
448   * @syscap SystemCapability.ArkUi.Graphics3D
449   * @since 12
450   */
451  postProcess: PostProcessSettings | null;
452
453  /**
454   * Background clear color (environment background overrides this color,
455   * BACKGROUND_NONE is needed for this to actually take effect).
456   *
457   * @type { Color | null }
458   * @syscap SystemCapability.ArkUi.Graphics3D
459   * @since 12
460   */
461  clearColor: Color | null;
462
463  /**
464   * Casts a ray to a position on the screen and lists what the ray hits.
465   * @param { Vec2 } viewPosition - Position to cast in the normalized device coordinates.
466   * @param { RaycastParameters } params - Options used to execute the ray cast.
467   * @returns { Promise<RaycastResult[]> } - Promise used to return an array of hit results, sorted from the closest to the farthest. The array may be empty.
468   * @syscap SystemCapability.ArkUi.Graphics3D
469   * @since 20
470   */
471  raycast(viewPosition: Vec2, params: RaycastParameters): Promise<RaycastResult[]>;
472}
473