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 } from './SceneResources'; 22import { Camera, LightType, Light, Node, NodeType } from './SceneNodes'; 23 24/** 25 * The scene resource parameters type. 26 * 27 * @typedef SceneResourceParameters 28 * @syscap SystemCapability.ArkUi.Graphics3D 29 * @since 12 30 */ 31export interface SceneResourceParameters { 32 /** 33 * The name of the scene resource parameters. 34 * 35 * @type { string } 36 * @syscap SystemCapability.ArkUi.Graphics3D 37 * @since 12 38 */ 39 name: string; 40 41 /** 42 * The resource uri of the scene resource parameters. 43 * 44 * @type { ?ResourceStr } 45 * @syscap SystemCapability.ArkUi.Graphics3D 46 * @since 12 47 */ 48 uri?: ResourceStr; 49} 50 51/** 52 * The scene node parameters type. 53 * 54 * @typedef SceneNodeParameters 55 * @syscap SystemCapability.ArkUi.Graphics3D 56 * @since 12 57 */ 58export interface SceneNodeParameters { 59 /** 60 * The name of the scene node parameters. 61 * 62 * @type { string } 63 * @syscap SystemCapability.ArkUi.Graphics3D 64 * @since 12 65 */ 66 name: string; 67 68 /** 69 * The path of the scene node parameters. 70 * 71 * @type { ?string } 72 * @syscap SystemCapability.ArkUi.Graphics3D 73 * @since 12 74 */ 75 path?: string; 76} 77 78/** 79 * The scene resource factory. 80 * 81 * @interface SceneResourceFactory 82 * @syscap SystemCapability.ArkUi.Graphics3D 83 * @since 12 84 */ 85export interface SceneResourceFactory { 86 /** 87 * Create a camera. 88 * 89 * @param { SceneNodeParameters } params - the param of creating a camera 90 * @returns { Promise<Camera> } promise a camera 91 * @syscap SystemCapability.ArkUi.Graphics3D 92 * @since 12 93 */ 94 createCamera(params: SceneNodeParameters): Promise<Camera>; 95 96 /** 97 * Create a light. 98 * 99 * @param { SceneNodeParameters } params - the param of creating a light 100 * @param { LightType } lightType - the type of the light 101 * @returns { Promise<Light> } promise a light 102 * @syscap SystemCapability.ArkUi.Graphics3D 103 * @since 12 104 */ 105 createLight(params: SceneNodeParameters, lightType: LightType): Promise<Light>; 106 107 /** 108 * Create a node. 109 * 110 * @param { SceneNodeParameters } params - the param of creating a node 111 * @returns { Promise<Node> } promise a node 112 * @syscap SystemCapability.ArkUi.Graphics3D 113 * @since 12 114 */ 115 createNode(params: SceneNodeParameters): Promise<Node>; 116 117 /** 118 * Create a material. 119 * 120 * @param { SceneResourceParameters } params - the param of creating a material 121 * @param { MaterialType } materialType - the type of the material 122 * @returns { Promise<Material> } promise a material 123 * @syscap SystemCapability.ArkUi.Graphics3D 124 * @since 12 125 */ 126 createMaterial(params: SceneResourceParameters, materialType: MaterialType): Promise<Material>; 127 128 /** 129 * Create a shader. 130 * 131 * @param { SceneResourceParameters } params - the param of creating a shader 132 * @returns { Promise<Shader> } promise a shader 133 * @syscap SystemCapability.ArkUi.Graphics3D 134 * @since 12 135 */ 136 createShader(params: SceneResourceParameters): Promise<Shader>; 137 138 /** 139 * Create a image. 140 * 141 * @param { SceneResourceParameters } params - the param of creating a image 142 * @returns { Promise<Image> } promise a image 143 * @syscap SystemCapability.ArkUi.Graphics3D 144 * @since 12 145 */ 146 createImage(params: SceneResourceParameters): Promise<Image>; 147 148 /** 149 * Create a environment. 150 * 151 * @param { SceneResourceParameters } params - the param of creating a Environment object 152 * @returns { Promise<Environment> } promise a Environment 153 * @syscap SystemCapability.ArkUi.Graphics3D 154 * @since 12 155 */ 156 createEnvironment(params: SceneResourceParameters): Promise<Environment>; 157} 158 159/** 160 * Defines the 3d scene. 161 * 162 * @syscap SystemCapability.ArkUi.Graphics3D 163 * @since 12 164 */ 165export class Scene { 166 /** 167 * Create a new scene from a ResourceStr. 168 * 169 * @param { ResourceStr } uri - the resource of creating a scene 170 * @returns { Promise<Scene> } promise a scene 171 * @static 172 * @syscap SystemCapability.ArkUi.Graphics3D 173 * @since 12 174 */ 175 static load(uri? : ResourceStr): Promise<Scene>; 176 177 /** 178 * The environment of the scene. 179 * 180 * @type { Environment } 181 * @syscap SystemCapability.ArkUi.Graphics3D 182 * @since 12 183 */ 184 environment: Environment; 185 186 /** 187 * The animations of the scene. 188 * 189 * @type { Animation[] } 190 * @readonly 191 * @syscap SystemCapability.ArkUi.Graphics3D 192 * @since 12 193 */ 194 readonly animations: Animation[]; 195 196 /** 197 * The root node of the scene. 198 * 199 * @type { Node | null } 200 * @readonly 201 * @syscap SystemCapability.ArkUi.Graphics3D 202 * @since 12 203 */ 204 readonly root: Node | null; 205 206 /** 207 * Get a node by path. 208 * 209 * @param { string } path - the path of the node 210 * @param { NodeType } type - verify the type of node, if it does not match, return null 211 * @returns { Node | null } if the node is found by it's path 212 * @syscap SystemCapability.ArkUi.Graphics3D 213 * @since 12 214 */ 215 getNodeByPath(path: string, type?: NodeType): Node | null; 216 217 /** 218 * Get resource factory. 219 * 220 * @returns { SceneResourceFactory } if the node is found by it's path 221 * @syscap SystemCapability.ArkUi.Graphics3D 222 * @since 12 223 */ 224 getResourceFactory(): SceneResourceFactory; 225 226 /** 227 * Release all native scene resources. All TS references will be undefined. 228 * 229 * @syscap SystemCapability.ArkUi.Graphics3D 230 * @since 12 231 */ 232 destroy(): void; 233} 234