harmony 鸿蒙Scene

  • 2025-06-12
  • 浏览 (3)

Scene

The Scene module is the basic module of ArkGraphics 3D and provides common data types such as SceneResourceParameters and SceneNodeParameters. It also provides basic methods such as glTF model loading, scene creation, and resource creation.

NOTE

The initial APIs of this module are supported since API version 12. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

import { SceneResourceParameters, SceneNodeParameters, RaycastResult, RaycastParameters,RenderResourceFactory,
  SceneResourceFactory, SceneComponent, RenderContext, RenderParameters, Scene } from '@kit.ArkGraphics3D';

SceneResourceParameters

Describes the scene resource parameters (name and uri), which are used to provide the name of a scene resource and the path of the resource file required in the 3D scene.

System capability: SystemCapability.ArkUi.Graphics3D |Name|Type|Read Only|Optional|Description| |—-|—-|—-|—-|—-| |name|string|No|No|Name of the scene resource. It is customizable.| |uri|ResourceStr|No|Yes|Path of the resource file required in the 3D scene. The default value is undefined.|

Example

import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';

function createShaderPromise() : Promise<Shader> {
  return new Promise(() => {
    let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.glb"));
    scene.then(async (result: Scene) => {
      let sceneFactory: SceneResourceFactory = result.getResourceFactory();

      // Create a variable of the SceneResourceParameters type and use it to create a shader.
      let sceneResourceParameter: SceneResourceParameters = { name: "shaderResource",
        uri: $rawfile("shaders/custom_shader/custom_material_sample.shader") };
      let shader: Promise<Shader> = sceneFactory.createShader(sceneResourceParameter);
      return shader;
    });
  });
}

SceneNodeParameters

Describes the scene node parameters, which are used to provide the name and path in the scene node tree.

System capability: SystemCapability.ArkUi.Graphics3D |Name|Type|Read Only|Optional|Description| |—-|—-|—-|—-|—-| |name|string|No|No|Name of the scene node. It is customizable.| |path|string|No|Yes|Path in the scene node tree. It specifies the position of the created camera, light, or node in the scene node tree. Each layer is separated by a slash (/). If no path is provided, the node is set as a child node of the root node. The default value is undefined.|

Example

import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';

function createNodePromise() : Promise<Node> {
  return new Promise(() => {
    let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.glb"));
    scene.then(async (result: Scene) => {
      let sceneFactory: SceneResourceFactory = result.getResourceFactory();

      // Create a variable of the SceneNodeParameters type and use it to create a node.
      let sceneNodeParameter: SceneNodeParameters = { name: "empty_node",
        path:"/rootNode_/empty_node" };
      let node: Promise<Node> = sceneFactory.createNode(sceneNodeParameter);
      return node;
    });
  });
}

RaycastResult20+

Describes a result object from raycasting, containing details about the 3D object hit by the ray.

System capability: SystemCapability.ArkUi.Graphics3D |Name|Type|Read Only|Optional|Description| |—-|—-|—-|—-|—-| |node|Node|Yes|No|3D scene node hit by the ray. You can use this node to manipulate the target object (for example, moving, rotating, or hiding the object).| |centerDistance|number|Yes|No|Distance from the center of the bounding box of the hit object to the center of the camera. The value must be greater than 0.| |hitPosition|Position3|Yes|No|Precise world coordinates ({x: number, y: number, z: number}) of the point where the ray hit the object.|

RaycastParameters20+

Describes the configuration parameters for raycasting, defining the behavior of raycasting.

System capability: SystemCapability.ArkUi.Graphics3D |Name|Type|Read Only|Optional|Description| |—-|—-|—-|—-|—-| |rootNode|Node|No|Yes|Limits the detection scope to this node and its child nodes. If this parameter is not specified, the entire scene is detected.|

RenderResourceFactory20+

Provides APIs to create rendering resources that can be shared among multiple scenes with a shared RenderContext.

createShader

createShader(params: SceneResourceParameters): Promise<Shader>

Creates a shader based on the scene resource parameters. This API uses a promise to return the result.

System capability: SystemCapability.ArkUi.Graphics3D

Parameters |Name|Type|Mandatory|Description| |—-|—-|—-|—-| |params|SceneResourceParameters|Yes|Parameters for creating the shader.|

Return value |Type|Description| |—-|—-| |Promise<Shader>|Promise used to return the Shader object created.|

Example

import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node, RenderContext, RenderResourceFactory } from '@kit.ArkGraphics3D';

function createShaderResource(): Promise<Shader> {
  return Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.glb"))
    .then(scene => {
      const renderContext = scene.getRenderContext();
      if (!renderContext) {
        return Promise.reject(new Error("RenderContext is null"));
      }

      const renderResourceFactory = renderContext.getRenderResourceFactory();
      let shaderParams: SceneResourceParameters = {
        name: "custom_shader",
        uri: $rawfile("shaders/custom_shader/custom_material_sample.shader")
      };
      return renderResourceFactory.createShader(shaderParams);
    });
}

createImage

createImage(params: SceneResourceParameters): Promise<Image>

Creates an image based on the scene resource parameters. This API uses a promise to return the result.

System capability: SystemCapability.ArkUi.Graphics3D

Parameters |Name|Type|Mandatory|Description| |—-|—-|—-|—-| |params|SceneResourceParameters|Yes|Parameters for creating the image.|

Return value |Type|Description| |—-|—-| |Promise<Image>|Promise used to return the Image object created.|

Example

import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node, RenderContext, RenderResourceFactory } from '@kit.ArkGraphics3D';

function createImageResource(): Promise<Image> {
  return Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.glb"))
    .then(scene => {
      const renderContext = scene.getRenderContext();
      if (!renderContext) {
        return Promise.reject(new Error("RenderContext is null"));
      }

      const renderResourceFactory = renderContext.getRenderResourceFactory();
      let imageParams: SceneResourceParameters = {
        name: "sampleImage",
        uri: $rawfile("image/Cube_BaseColor.png")
      };
      return renderResourceFactory.createImage(imageParams);
    });
}

createMesh

createMesh(params: SceneResourceParameters, geometry: GeometryDefinition): Promise<MeshResource>

Creates a mesh based on the scene resource parameters and geometry definition. This API uses a promise to return the result.

System capability: SystemCapability.ArkUi.Graphics3D

Parameters |Name|Type|Mandatory|Description| |—-|—-|—-|—-| |params|SceneResourceParameters|Yes|Parameters for creating the mesh.| |geometry|GeometryDefinition|Yes|Geometry of the mesh to create.|

Return value |Type|Description| |—-|—-| |Promise<MeshResource>|Promise used to return the Mesh object created.|

Example

import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node, RenderContext, RenderResourceFactory,
  GeometryDefinition, MeshResource } from '@kit.ArkGraphics3D';

function createMeshResource(): Promise<MeshResource> {
  return Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.glb"))
    .then(scene => {
      const renderContext = scene.getRenderContext();
      if (!renderContext) {
        return Promise.reject(new Error("RenderContext is null"));
      }
      const renderResourceFactory = renderContext.getRenderResourceFactory();
      let geometry = new CustomGeometry(
        [
          { x: 0, y: 0, z: 0 },
          { x: 1, y: 0, z: 0 },
          { x: 1, y: 1, z: 0 },
          { x: 0, y: 1, z: 0 },
          { x: 0, y: 0, z: 1 },
          { x: 1, y: 0, z: 1 },
          { x: 1, y: 1, z: 1 },
          { x: 0, y: 1, z: 1 }
        ],
        [
          0, 1, 2, 2, 3, 0,
          4, 5, 6, 6, 7, 4,
          0, 4, 5, 5, 1, 0,
          1, 5, 6, 6, 2, 1,
          2, 6, 7, 7, 3, 2,
          3, 7, 4, 4, 0, 3
        ]
      );
      geometry.topology = PrimitiveTopology.TRIANGLE_LIST;
      geometry.normals = [
        { x: 0, y: 0, z: 1 },
        { x: 0, y: 0, z: 1 },
        { x: 0, y: 0, z: 1 },
        { x: 0, y: 0, z: 1 },
        { x: 0, y: 0, z: 1 },
        { x: 0, y: 0, z: 1 },
        { x: 0, y: 0, z: 1 },
        { x: 0, y: 0, z: 1 }
      ];

      geometry.uvs = [
        { x: 0, y: 0 },
        { x: 1, y: 0 },
        { x: 1, y: 1 },
        { x: 0, y: 1 },
        { x: 0, y: 0 },
        { x: 1, y: 0 },
        { x: 1, y: 1 },
        { x: 0, y: 1 }
      ];
      geometry.colors = [
        { r: 1, g: 0, b: 0, a: 1 },
        { r: 0, g: 1, b: 0, a: 1 },
        { r: 0, g: 0, b: 1, a: 1 },
        { r: 1, g: 1, b: 0, a: 1 },
        { r: 1, g: 0, b: 1, a: 1 },
        { r: 0, g: 1, b: 1, a: 1 },
        { r: 1, g: 1, b: 1, a: 1 },
        { r: 0, g: 0, b: 0, a: 1 }
      ];
      let sceneResourceParameter: SceneResourceParameters = {
        name: "cubeMesh",
        uri: $rawfile("models/cube.obj")
      };
      return renderResourceFactory.createMesh(sceneResourceParameter, geometry);
    });
}

createSampler

createSampler(params:SceneResourceParameters): Promise<Sampler>

Creates a sampler based on the scene resource parameters. This API uses a promise to return the result.

System capability: SystemCapability.ArkUi.Graphics3D

Parameters |Name|Type|Mandatory|Description| |—-|—-|—-|—-| |params|SceneResourceParameters|Yes|Parameters for creating the sampler.|

Return value |Type|Description| |—-|—-| |Promise<Sampler>|Promise used to return the Sampler object created.|

Example

import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node, RenderContext, RenderResourceFactory,
  Sampler } from '@kit.ArkGraphics3D';

function createSamplerResource(): Promise<Sampler> {
  return Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.glb"))
    .then(scene => {
      const renderContext = scene.getRenderContext();
      if (!renderContext) {
        return Promise.reject(new Error("RenderContext is null"));
      }

      const renderResourceFactory = renderContext.getRenderResourceFactory();
      let samplerParams: SceneResourceParameters = {
        name: "sampler1",
        uri: $rawfile("image/Cube_BaseColor.png")
      };
      return renderResourceFactory.createSampler(samplerParams);
    });
}

createScene

createScene(uri?: ResourceStr): Promise<Scene>

Creates a scene from the specified resource URI. If no URI is specified, an empty scene is created. This API uses a promise to return the result.

System capability: SystemCapability.ArkUi.Graphics3D

Parameters |Name|Type|Mandatory|Description| |—-|—-|—-|—-| |uri|ResourceStr|No|Resource path used for creating the scene. If no resource path is passed, an empty scene is created.|

Return value |Type|Description| |—-|—-| |Promise<Scene>|Promise used to return the Scene object created.|

Example

import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node, RenderContext, RenderResourceFactory,
  ResourceStr } from '@kit.ArkGraphics3D';

function createScenePromise(fromFile: boolean = false): Promise<Scene> {
  return Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.glb"))
    .then(scene => {
      const renderContext = scene.getRenderContext();
      if (!renderContext) {
        return Promise.reject(new Error("RenderContext is null"));
      }

      const renderResourceFactory = renderContext.getRenderResourceFactory();
      if (fromFile) {
        // Create a scene from a file.
        return renderResourceFactory.createScene($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.glb"));
      } else {
        // Create an empty scene.
        return renderResourceFactory.createScene();
      }
    });
}

SceneResourceFactory

Provides APIs for creating resources, such as cameras and light sources, used in 3D scenes. This class inherits from RenderResourceFactory.

createCamera

createCamera(params: SceneNodeParameters): Promise<Camera>

Creates a camera based on scene node parameters. This API uses a promise to return the result.

System capability: SystemCapability.ArkUi.Graphics3D

Parameters |Name|Type|Mandatory|Description| |—-|—-|—-|—-| |params|SceneNodeParameters|Yes|Scene node parameters.|

Return value |Type|Description| |—-|—-| |Promise<Camera>|Promise used to return the Camera object created.|

Example

import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';

function createCameraPromise() : Promise<Camera> {
  return new Promise(() => {
    let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.glb"));
    scene.then(async (result: Scene) => {
      let sceneFactory: SceneResourceFactory = result.getResourceFactory();
      let sceneCameraParameter: SceneNodeParameters = { name: "camera1" };
      // Create a camera.
      let camera: Promise<Camera> = sceneFactory.createCamera(sceneCameraParameter);
      return camera;
    });
  });
}

createLight

createLight(params: SceneNodeParameters, lightType: LightType): Promise<Light>

Creates a light based on the scene node parameters and light type. This API uses a promise to return the result.

System capability: SystemCapability.ArkUi.Graphics3D

Parameters |Name|Type|Mandatory|Description| |—-|—-|—-|—-| |params|SceneNodeParameters|Yes|Scene node parameters.| |lightType|LightType|Yes|Light type.|

Return value |Type|Description| |—-|—-| |Promise<Light>|Promise used to return the Light object created.|

Example

import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';

function createLightPromise() : Promise<Light> {
  return new Promise(() => {
    let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.glb"));
    scene.then(async (result: Scene) => {
      let sceneFactory: SceneResourceFactory = result.getResourceFactory();
      let sceneLightParameter: SceneNodeParameters = { name: "light" };
      // Create directional light.
      let light: Promise<Light> = sceneFactory.createLight(sceneLightParameter, LightType.DIRECTIONAL);
      return light;
    });
  });
}

createNode

createNode(params: SceneNodeParameters): Promise<Node>

Creates a node. This API uses a promise to return the result.

System capability: SystemCapability.ArkUi.Graphics3D

Parameters |Name|Type|Mandatory|Description| |—-|—-|—-|—-| |params|SceneNodeParameters|Yes|Scene node parameters.|

Return value |Type|Description| |—-|—-| |Promise<Node>|Promise used to return the Node object.|

Example

import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';

function createNodePromise() : Promise<Node> {
  return new Promise(() => {
    let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.glb"));
    scene.then(async (result: Scene) => {
      let sceneFactory: SceneResourceFactory = result.getResourceFactory();
      let sceneNodeParameter: SceneNodeParameters = { name: "empty_node",
        path:"/rootNode_/empty_node" };
      // Create a node.
      let node: Promise<Node> = sceneFactory.createNode(sceneNodeParameter);
      return node;
    });
  });
}

createMaterial

createMaterial(params: SceneResourceParameters, materialType: MaterialType): Promise<Material>

Creates a material based on the scene resource parameters and material type. This API uses a promise to return the result.

System capability: SystemCapability.ArkUi.Graphics3D

Parameters |Name|Type|Mandatory|Description| |—-|—-|—-|—-| |params|SceneResourceParameters|Yes|Scene resource parameters.| |materialType|MaterialType|Yes|Material type.|

Return value |Type|Description| |—-|—-| |Promise<Material>|Promise used to return the Material object.|

Example

import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';

function createMaterialPromise() : Promise<Material> {
  return new Promise(() => {
    let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.glb"));
    scene.then(async (result: Scene) => {
      let sceneFactory: SceneResourceFactory = result.getResourceFactory();
      let sceneMaterialParameter: SceneResourceParameters = { name: "material" };
      // Create a material.
      let material: Promise<Material> = sceneFactory.createMaterial(sceneMaterialParameter, MaterialType.SHADER);
      return material;
    });
  });
}

createEnvironment

createEnvironment(params: SceneResourceParameters): Promise<Environment>

Creates an environment based on the scene resource parameters. This API uses a promise to return the result.

System capability: SystemCapability.ArkUi.Graphics3D

Parameters |Name|Type|Mandatory|Description| |—-|—-|—-|—-| |params|SceneResourceParameters|Yes|Scene resource parameters.|

Return value |Type|Description| |—-|—-| |Promise<Environment>|Promise used to return the Environment object created.|

Example

import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';

function createEnvironmentPromise() : Promise<Environment> {
  return new Promise(() => {
    let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.glb"));
    scene.then(async (result: Scene) => {
      let sceneFactory: SceneResourceFactory = result.getResourceFactory();
      let sceneEnvironmentParameter: SceneResourceParameters = { name: "env", uri: $rawfile("KTX/quarry_02_2k_radiance.ktx") };
      // Create an environment.
      let env: Promise<Environment> = sceneFactory.createEnvironment(sceneEnvironmentParameter);
      return env;
    });
  });
}

createGeometry18+

createGeometry(params: SceneNodeParameters, mesh:MeshResource): Promise<Geometry>

Creates a geometry object based on the scene node parameters and mesh data. This API uses a promise to return the result.

System capability: SystemCapability.ArkUi.Graphics3D

Parameters |Name|Type|Mandatory|Description| |—-|—-|—-|—-| |params|SceneNodeParameters|Yes|Scene node parameters.| |mesh|MeshResource|Yes|Mesh data parameters.|

Return value |Type|Description| |—-|—-| |Promise<Geometry>|Promise used to return the Geometry object created.|

Example

import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node, Geometry, CubeGeometry, MeshResource} from '@kit.ArkGraphics3D';

function createGeometryPromise() : Promise<Geometry> {
  return new Promise(() => {
    let scene: Promise<Scene> = Scene.load();
    scene.then(async (result: Scene|undefined) => {
      if (!result) {
        return;
      }
      let sceneFactory: SceneResourceFactory = result.getResourceFactory();
      let cubeGeom = new CubeGeometry();
      cubeGeom.size = { x: 1, y: 1, z: 1 };
      let meshRes = await sceneFactory.createMesh({ name: "MeshName" }, cubeGeom);
      console.info("TEST createGeometryPromise");
      let geometry: Promise<Geometry> = sceneFactory.createGeometry({ name: "GeometryName" }, meshRes);
      return geometry;
    });
  });
}

SceneComponent20+

Represents a basic scene component, which is used to describe the component information of a scene node, including the component name and its properties.

Properties

System capability: SystemCapability.ArkUi.Graphics3D

Name Type Read Only Optional Description
name string No No Name of the scene component, which is customizable.
property Record Yes No A set of component properties stored in key-value pairs. It supports various basic and complex types to describe various properties of the scene component.

RenderContext20+

Defines the context of all rendering resources. Multiple scenes created within the same render context can share rendering resources.

getRenderResourceFactory

getRenderResourceFactory() : RenderResourceFactory

Obtains the rendering resource factory, which provides APIs for creating different rendering resources.

System capability: SystemCapability.ArkUi.Graphics3D

Return value |Type|Description| |—-|—-| |RenderResourceFactory|RenderResourceFactory instance for creating rendering resources.|

Example

import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node, RenderContext, RenderResourceFactory,
  RenderContext } from '@kit.ArkGraphics3D';

function getRenderResourceFactory(): void {
  Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.glb"))
    .then(scene => {
      const renderContext = scene.getRenderContext();
      if (!renderContext) {
        console.error("RenderContext is null");
        return;
      }

      const renderResourceFactory = renderContext.getRenderResourceFactory();
      console.info("TEST getRenderResourceFactory");
    });
}

loadPlugin

loadPlugin(name: string): Promise<boolean>

Loads a plugin by name. The API locates and loads the corresponding plugin resource using the provided plugin name. It uses a promise to return the result.

System capability: SystemCapability.ArkUi.Graphics3D

Parameters |Name|Type|Mandatory|Description| |—-|—-|—-|—-| |name|string|Yes|Name of the plugin to load, which must be a system predefined or registered and available plugin name, and follow the naming conventions.|

Return value |Type|Description| |—-|—-| |Promise<boolean>|Promise used to return a Boolean value, indicating whether the plugin is loaded. The value true means that the plugin is loaded, and false means the opposite.|

Example

import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node, RenderContext, RenderResourceFactory,
  RenderContext } from '@kit.ArkGraphics3D';

function loadPlugin(): void {
  Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.glb"))
    .then(scene => {
      const renderContext = scene.getRenderContext();
      if (!renderContext) {
        console.error("RenderContext is null");
        return Promise.resolve(false);
      }
      return renderContext.loadPlugin("pluginName");
    })
    .then(result => {
      if (result) {
        console.info("plugin load success");
      } else {
        console.error("plugin load failed");
      }
    });
}

RenderParameters15+

Describes the rendering parameters.

System capability: SystemCapability.ArkUi.Graphics3D |Name|Type|Read Only|Optional|Description| |—-|—-|—-|—-|—-| |alwaysRender15+|boolean|No|Yes|Whether to render every frame. The value true means to render every frame, and false means to render frames on demand. The default value is true.|

Scene

Describes a scene.

Properties

System capability: SystemCapability.ArkUi.Graphics3D

Name Type Read Only Optional Description
environment Environment No No Environment object.
animations Animation[] Yes No Animation objects in the 3D scene.
root Node |null Yes No Root node in the 3D scene tree.

load

static load(uri?: ResourceStr): Promise<Scene>

Loads a resource by path. This API uses a promise to return the result.

System capability: SystemCapability.ArkUi.Graphics3D

Parameters |Name|Type|Mandatory|Description| |—-|—-|—-|—-| |uri|ResourceStr|No|Path of the model file resource to load. The default value is undefined.|

Return value |Type|Description| |—-|—-| |Promise<Scene>|Promise used to return the Scene object created.|

Example

import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';

function loadModel() : void {
  // Load the model.
  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.glb"));
  scene.then(async (result: Scene) => {});
}

getNodeByPath

getNodeByPath(path: string, type?: NodeType): Node|null

Obtains a node by path.

System capability: SystemCapability.ArkUi.Graphics3D

Parameters |Name|Type|Mandatory|Description| |—-|—-|—-|—-| |path|string|Yes|Path in the scene node tree. Each layer is separated by a slash (/).| |type|NodeType|No|Type of the node expected. The default value is null.|

Return value |Type|Description| |—-|—-| |Node |null|Returns the Node object requested. If no node is found in the specified path or the found node type does not match the expected type, null is returned.|

Example

import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';

function getNode() : void {
  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.glb"));
  scene.then(async (result: Scene) => {
    if (result) {
         // Search for a node in the specified path.
        let node : Node|null = result.getNodeByPath("rootNode_");
    }
  });
}

getResourceFactory

getResourceFactory(): SceneResourceFactory

Obtains the scene resource factory.

System capability: SystemCapability.ArkUi.Graphics3D

Return value |Type|Description| |—-|—-| |SceneResourceFactory|Scene resource factory.|

Example

import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';

function getFactory() : void {
  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.glb"));
  scene.then(async (result: Scene) => {
    if (result) {
         // Obtain a SceneResourceFactory object.
        let sceneFactory: SceneResourceFactory = result.getResourceFactory();
    }
  });
}

destroy

destroy(): void

Destroys this scene and releases all scene resources.

System capability: SystemCapability.ArkUi.Graphics3D

Example

import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';

function destroy() : void {
  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.glb"));
  scene.then(async (result: Scene) => {
    if (result) {
         // Destroy the scene.
        result.destroy();
    }
  });
}

importNode18+

importNode(name: string, node: Node, parent: Node|null): Node

Imports a node from another scene.

System capability: SystemCapability.ArkUi.Graphics3D

Parameters |Name|Type|Mandatory|Description| |—-|—-|—-|—-| |name|string|Yes|Name of the imported node, which can be customized without specific constraints.| |node|Node|Yes|Node to import.| |parent|Node |null|Yes|Parent node of the imported node in the new scene.|

Return value |Type|Description| |—-|—-| |Node|Node imported.|

Example

import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node, Geometry, CubeGeometry, MeshResource} from '@kit.ArkGraphics3D';

function ImportNodeTest() {
  Scene.load().then(async (result: Scene|undefined) => {
    if (!result) {
      return;
    }
    Scene.load($rawfile("gltf/AnimatedCube/glTF/AnimatedCube.glb"))
      .then(async (extScene: Scene) => {
        let extNode = extScene.getNodeByPath("rootNode_/Unnamed Node 1/AnimatedCube");
        console.info("TEST ImportNodeTest");
        let node = result.importNode("scene", extNode, result.root);
        if (node) {
          node.position.x = 5;
        }
      });
  });
}

importScene18+

importScene(name: string, scene: Scene, parent: Node|null): Node

Imports another scene into the current one.

System capability: SystemCapability.ArkUi.Graphics3D

Parameters |Name|Type|Mandatory|Description| |—-|—-|—-|—-| |name|string|Yes|Root node name of the imported scene, which can be customized without specific constraints.| |scene|Scene|Yes|Scene to import.| |parent|Node |null|Yes|Parent node of the imported scene in the new scene.|

Return value |Type|Description| |—-|—-| |Node|Root node of the imported scene.|

Example

import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node, Geometry, CubeGeometry, MeshResource} from '@kit.ArkGraphics3D';

function ImportSceneTest() {
  Scene.load().then(async (result: Scene|undefined) => {
    if (!result) {
      return;
    }
    let content = await result.getResourceFactory().createScene($rawfile("gltf/DamagedHelmet/glTF/DamagedHelmet.glb"))
    console.info("TEST ImportSceneTest");
    result.importScene("helmet", content, null);
  });
}

renderFrame15+

renderFrame(params?: RenderParameters): boolean

Renders frames on demand, such as controlling the frame rate.

System capability: SystemCapability.ArkUi.Graphics3D

Parameters |Name|Type|Mandatory|Description| |—-|—-|—-|—-| |params|RenderParameters|No|Rendering parameters. The default value is undefined.|

Return value |Type|Description| |—-|—-| |boolean|Rendering result. The value true is returned if rendering is successfully scheduled; returns false otherwise.|

Example

import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node, Geometry, CubeGeometry, MeshResource} from '@kit.ArkGraphics3D';

function RenderFrameTest() {
  Scene.load($rawfile("gltf/DamagedHelmet/glTF/DamagedHelmet.glb"))
    .then(async (result: Scene|undefined) => {
      if (!result) {
        return;
      }
      console.info("TEST RenderFrameTest");
      result.renderFrame({ alwaysRender: true });
  });
}

createComponent20+

createComponent(node: Node, name: string): Promise<SceneComponent>

Creates a component and attaches it to a node. This API uses a promise to return the result.

System capability: SystemCapability.ArkUi.Graphics3D

Parameters |Name|Type|Mandatory|Description| |—-|—-|—-|—-| |node|Node|Yes|Node to which the component will be attached.| |name|string|Yes|Name of the component to create, which is defined by individual plugins.|

Return value |Type|Description| |—-|—-| |Promise<SceneComponent>|Promise used to return the SceneComponent object created.|

Example

import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node, Geometry, CubeGeometry, MeshResource, SceneComponent } from '@kit.ArkGraphics3D';

function createComponentTest(): Promise<SceneComponent> {
  return Scene.load($rawfile("gltf/DamagedHelmet/glTF/DamagedHelmet.glb"))
    .then(result => {
      if (!result) {
        console.error("Scene load failed: result is undefined");
        return Promise.reject(new Error("Scene load failed"));
      }
      console.info("TEST createComponentTest");
      return result.createComponent(result.root, "myComponent");
    })
    .then(component => {
      console.info("createComponent success");
      return component;
    });
}

getComponent20+

getComponent(node: Node, name: string): SceneComponent|null

Obtains the component instance from a node based on the component name.

System capability: SystemCapability.ArkUi.Graphics3D

Parameters |Name|Type|Mandatory|Description| |—-|—-|—-|—-| |node|Node|Yes|Node to which the component is attached.| |name|string|Yes|Name of the component to obtain. The value must be a system predefined or registered custom component name, and follow the naming conventions.|

Return value |Type|Description| |—-|—-| |SceneComponent |null|SceneComponent object corresponding to the given name, or null if not found.|

Example

import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node, Geometry, CubeGeometry, MeshResource, SceneComponent } from '@kit.ArkGraphics3D';

function getComponentTest() {
  Scene.load($rawfile("gltf/DamagedHelmet/glTF/DamagedHelmet.glb"))
    .then(async (result: Scene|undefined) => {
      if (!result) {
        console.error("Scene load failed");
        return;
      }
      console.info("TEST getComponentTest");
      let component = result.getComponent(result.root, "myComponent");
      if (component) {
        console.info("getComponent success");
      } else {
        console.warn("Component not found");
      }
    });
}

getRenderContext20+

getRenderContext(): RenderContext|null

Obtains the rendering context associated with the current graphics object.

Return value |Type|Description| |—-|—-| |RenderContext |null|Rendering context associated with the current object, or null if no rendering context is associated.|

Example

import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node, Geometry, CubeGeometry, MeshResource, SceneComponent, RenderContext } from '@kit.ArkGraphics3D';

function getRenderContextTest() {
  Scene.load($rawfile("gltf/DamagedHelmet/glTF/DamagedHelmet.glb"))
    .then(result => {
      console.info("TEST getRenderContextTest");
      const context = result.getRenderContext();
      if (context) {
        console.info("getRenderContext success");
      } else {
        console.warn("RenderContext is null");
      }
    });
}

你可能感兴趣的鸿蒙文章

harmony 鸿蒙ArkGraphics 3D

harmony 鸿蒙SceneNode

harmony 鸿蒙ScenePostProcessSettings

harmony 鸿蒙SceneResource

harmony 鸿蒙SceneType

harmony 鸿蒙@ohos.graphics.scene (ArkGraphics 3D)

0  赞
  • 所属分类： 后端技术
  • 本文标签：
  • 版权声明： 原创文章如转载，请注明本文链接: https://m.seaxiang.com/blog/ZnlBX4
热门推荐
标签云
Linux Java Spring Spring Boot docker 大数据 前端 生活 maven golang 软件 spring cloud fintech mac vscode 其他 区块链 以太坊 V神 开发者 技术 股票 git greenplum 分布式事务 chrome mysql flink kafka 设计模式 原理 鸿蒙 seo
最新文章
本文目录