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 scene related interfaces 18 * @kit ArkGraphics3D 19 */ 20 21import { Shader, MaterialType, Material, Animation, Environment, Image, MeshResource } from './SceneResources'; 22import { Camera, LightType, Light, Node, NodeType, Geometry } from './SceneNodes'; 23import { Position3, Color, GeometryDefinition } from './SceneTypes'; 24 25/** 26 * The scene resource parameters type. 27 * 28 * @typedef SceneResourceParameters 29 * @syscap SystemCapability.ArkUi.Graphics3D 30 * @since 12 31 */ 32export interface SceneResourceParameters { 33 /** 34 * The name of the scene resource parameters. 35 * 36 * @type { string } 37 * @syscap SystemCapability.ArkUi.Graphics3D 38 * @since 12 39 */ 40 name: string; 41 42 /** 43 * The resource uri of the scene resource parameters. 44 * 45 * @type { ?ResourceStr } 46 * @syscap SystemCapability.ArkUi.Graphics3D 47 * @since 12 48 */ 49 uri?: ResourceStr; 50} 51 52/** 53 * The scene node parameters type. 54 * 55 * @typedef SceneNodeParameters 56 * @syscap SystemCapability.ArkUi.Graphics3D 57 * @since 12 58 */ 59export interface SceneNodeParameters { 60 /** 61 * The name of the scene node parameters. 62 * 63 * @type { string } 64 * @syscap SystemCapability.ArkUi.Graphics3D 65 * @since 12 66 */ 67 name: string; 68 69 /** 70 * The path of the scene node parameters. 71 * 72 * @type { ?string } 73 * @syscap SystemCapability.ArkUi.Graphics3D 74 * @since 12 75 */ 76 path?: string; 77} 78 79/** 80 * The scene resource factory. 81 * 82 * @interface SceneResourceFactory 83 * @syscap SystemCapability.ArkUi.Graphics3D 84 * @since 12 85 */ 86export interface SceneResourceFactory { 87 /** 88 * Create a camera. 89 * 90 * @param { SceneNodeParameters } params - the param of creating a camera 91 * @returns { Promise<Camera> } promise a camera 92 * @syscap SystemCapability.ArkUi.Graphics3D 93 * @since 12 94 */ 95 createCamera(params: SceneNodeParameters): Promise<Camera>; 96 97 /** 98 * Create a light. 99 * 100 * @param { SceneNodeParameters } params - the param of creating a light 101 * @param { LightType } lightType - the type of the light 102 * @returns { Promise<Light> } promise a light 103 * @syscap SystemCapability.ArkUi.Graphics3D 104 * @since 12 105 */ 106 createLight(params: SceneNodeParameters, lightType: LightType): Promise<Light>; 107 108 /** 109 * Create a node. 110 * 111 * @param { SceneNodeParameters } params - the param of creating a node 112 * @returns { Promise<Node> } promise a node 113 * @syscap SystemCapability.ArkUi.Graphics3D 114 * @since 12 115 */ 116 createNode(params: SceneNodeParameters): Promise<Node>; 117 118 /** 119 * Create a material. 120 * 121 * @param { SceneResourceParameters } params - the param of creating a material 122 * @param { MaterialType } materialType - the type of the material 123 * @returns { Promise<Material> } promise a material 124 * @syscap SystemCapability.ArkUi.Graphics3D 125 * @since 12 126 */ 127 createMaterial(params: SceneResourceParameters, materialType: MaterialType): Promise<Material>; 128 129 /** 130 * Create a shader. 131 * 132 * @param { SceneResourceParameters } params - the param of creating a shader 133 * @returns { Promise<Shader> } promise a shader 134 * @syscap SystemCapability.ArkUi.Graphics3D 135 * @since 12 136 */ 137 createShader(params: SceneResourceParameters): Promise<Shader>; 138 139 /** 140 * Create a image. 141 * 142 * @param { SceneResourceParameters } params - the param of creating a image 143 * @returns { Promise<Image> } promise a image 144 * @syscap SystemCapability.ArkUi.Graphics3D 145 * @since 12 146 */ 147 createImage(params: SceneResourceParameters): Promise<Image>; 148 149 /** 150 * Create a environment. 151 * 152 * @param { SceneResourceParameters } params - the param of creating a Environment object 153 * @returns { Promise<Environment> } promise a Environment 154 * @syscap SystemCapability.ArkUi.Graphics3D 155 * @since 12 156 */ 157 createEnvironment(params: SceneResourceParameters): Promise<Environment>; 158 159 /** 160 * Create a geometry node. 161 * 162 * @param { SceneNodeParameters } params - the param of creating a geometry 163 * @param { MeshResource } mesh resource - The mesh data for the geometry 164 * @returns { Promise<Geometry> } promise a geometry 165 * @syscap SystemCapability.ArkUi.Graphics3D 166 * @since 18 167 */ 168 createGeometry(params: SceneNodeParameters, mesh:MeshResource): Promise<Geometry>; 169 170 /** 171 * Create a Mesh from an array of vertices. 172 * 173 * @param { SceneResourceParameters } params - the param of creating a Mesh object 174 * @param { GeometryDefinition } geometry - what sort of a geometric shape to create 175 * @returns { Promise<MeshResource> } promise a Mesh 176 * @syscap SystemCapability.ArkUi.Graphics3D 177 * @since 18 178 */ 179 createMesh(params: SceneResourceParameters, geometry: GeometryDefinition): Promise<MeshResource>; 180 181 /** 182 * Create a new scene from a Resource. 183 * 184 * @param { Resource } uri - the resource of creating a scene 185 * @returns { Promise<Scene> } promise a scene 186 * @syscap SystemCapability.ArkUi.Graphics3D 187 * @since 18 188 */ 189 createScene(uri?: ResourceStr): Promise<Scene>; 190} 191 192/** 193 * Defines parameters for manual rendering. 194 * 195 * @interface RenderParameters 196 * @syscap SystemCapability.ArkUi.Graphics3D 197 * @since 15 198 */ 199export interface RenderParameters { 200 /** 201 * If true, the renderer should always render even if there have been no changes in the scene 202 * since the previous frame. If false, renderer may omit rendering if no changes have been made. 203 * 204 * @type { ?boolean } 205 * @syscap SystemCapability.ArkUi.Graphics3D 206 * @since 15 207 */ 208 alwaysRender?: boolean; 209} 210 211/** 212 * Defines the 3d scene. 213 * 214 * @syscap SystemCapability.ArkUi.Graphics3D 215 * @since 12 216 */ 217export class Scene { 218 /** 219 * Create a new scene from a ResourceStr. 220 * 221 * @param { ResourceStr } uri - the resource of creating a scene 222 * @returns { Promise<Scene> } promise a scene 223 * @static 224 * @syscap SystemCapability.ArkUi.Graphics3D 225 * @since 12 226 */ 227 static load(uri? : ResourceStr): Promise<Scene>; 228 229 /** 230 * The environment of the scene. 231 * 232 * @type { Environment } 233 * @syscap SystemCapability.ArkUi.Graphics3D 234 * @since 12 235 */ 236 environment: Environment; 237 238 /** 239 * The animations of the scene. 240 * 241 * @type { Animation[] } 242 * @readonly 243 * @syscap SystemCapability.ArkUi.Graphics3D 244 * @since 12 245 */ 246 readonly animations: Animation[]; 247 248 /** 249 * The root node of the scene. 250 * 251 * @type { Node | null } 252 * @readonly 253 * @syscap SystemCapability.ArkUi.Graphics3D 254 * @since 12 255 */ 256 readonly root: Node | null; 257 258 /** 259 * Get a node by path. 260 * 261 * @param { string } path - the path of the node 262 * @param { NodeType } type - verify the type of node, if it does not match, return null 263 * @returns { Node | null } if the node is found by it's path 264 * @syscap SystemCapability.ArkUi.Graphics3D 265 * @since 12 266 */ 267 getNodeByPath(path: string, type?: NodeType): Node | null; 268 269 /** 270 * Get resource factory. 271 * 272 * @returns { SceneResourceFactory } if the node is found by it's path 273 * @syscap SystemCapability.ArkUi.Graphics3D 274 * @since 12 275 */ 276 getResourceFactory(): SceneResourceFactory; 277 278 /** 279 * Release all native scene resources. All TS references will be undefined. 280 * 281 * @syscap SystemCapability.ArkUi.Graphics3D 282 * @since 12 283 */ 284 destroy(): void; 285 286 /** 287 * Import node into the scene. The original node may come from separate Scene. 288 * The node will be cloned and any modifications to the old node will not be visible after the import. 289 * 290 * @param { string } name - The name of the newly created node. 291 * @param { Node } node - The node to be imported. 292 * @param { Node | null} parent - The parent node or null for root 293 * @returns { Node } The newly created node. 294 * @syscap SystemCapability.ArkUi.Graphics3D 295 * @since 18 296 */ 297 importNode(name: string, node: Node, parent: Node | null): Node; 298 299 /** 300 * Import scene into the scene as a node. The node hierarchy will appear under the parent node. 301 * All animations from the scene will be duplicated in the scene. 302 * 303 * @param { string } name - The name of the newly created node 304 * @param { Scene } scene - The scene to be imported. 305 * @param { Node | null } parent - The parent node or null for root 306 * @returns { Node } The newly created node. 307 * @syscap SystemCapability.ArkUi.Graphics3D 308 * @since 18 309 */ 310 importScene(name: string, scene: Scene, parent: Node | null): Node; 311 312 /** 313 * A new frame is rendered for all active camera. 314 * 315 * @param { RenderParameters } params - Rendering parameters 316 * @returns { boolean } True if rendering was scheduled, false otherwise 317 * @syscap SystemCapability.ArkUi.Graphics3D 318 * @since 15 319 */ 320 renderFrame(params?: RenderParameters): boolean; 321} 322