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 parameters for manual rendering. 161 * 162 * @interface RenderParameters 163 * @syscap SystemCapability.ArkUi.Graphics3D 164 * @since 15 165 */ 166export interface RenderParameters { 167 /** 168 * If true, the renderer should always render even if there have been no changes in the scene 169 * since the previous frame. If false, renderer may omit rendering if no changes have been made. 170 * 171 * @type { ?boolean } 172 * @syscap SystemCapability.ArkUi.Graphics3D 173 * @since 15 174 */ 175 alwaysRender?: boolean; 176} 177 178/** 179 * Defines the 3d scene. 180 * 181 * @syscap SystemCapability.ArkUi.Graphics3D 182 * @since 12 183 */ 184export class Scene { 185 /** 186 * Create a new scene from a ResourceStr. 187 * 188 * @param { ResourceStr } uri - the resource of creating a scene 189 * @returns { Promise<Scene> } promise a scene 190 * @static 191 * @syscap SystemCapability.ArkUi.Graphics3D 192 * @since 12 193 */ 194 static load(uri? : ResourceStr): Promise<Scene>; 195 196 /** 197 * The environment of the scene. 198 * 199 * @type { Environment } 200 * @syscap SystemCapability.ArkUi.Graphics3D 201 * @since 12 202 */ 203 environment: Environment; 204 205 /** 206 * The animations of the scene. 207 * 208 * @type { Animation[] } 209 * @readonly 210 * @syscap SystemCapability.ArkUi.Graphics3D 211 * @since 12 212 */ 213 readonly animations: Animation[]; 214 215 /** 216 * The root node of the scene. 217 * 218 * @type { Node | null } 219 * @readonly 220 * @syscap SystemCapability.ArkUi.Graphics3D 221 * @since 12 222 */ 223 readonly root: Node | null; 224 225 /** 226 * Get a node by path. 227 * 228 * @param { string } path - the path of the node 229 * @param { NodeType } type - verify the type of node, if it does not match, return null 230 * @returns { Node | null } if the node is found by it's path 231 * @syscap SystemCapability.ArkUi.Graphics3D 232 * @since 12 233 */ 234 getNodeByPath(path: string, type?: NodeType): Node | null; 235 236 /** 237 * Get resource factory. 238 * 239 * @returns { SceneResourceFactory } if the node is found by it's path 240 * @syscap SystemCapability.ArkUi.Graphics3D 241 * @since 12 242 */ 243 getResourceFactory(): SceneResourceFactory; 244 245 /** 246 * Release all native scene resources. All TS references will be undefined. 247 * 248 * @syscap SystemCapability.ArkUi.Graphics3D 249 * @since 12 250 */ 251 destroy(): void; 252 253 /** 254 * A new frame is rendered for all active camera. 255 * 256 * @param { RenderParameters } params - Rendering parameters 257 * @returns { boolean } True if rendering was scheduled, false otherwise 258 * @syscap SystemCapability.ArkUi.Graphics3D 259 * @since 15 260 */ 261 renderFrame(params?: RenderParameters): boolean; 262} 263