openharmony 鸿蒙 js-apis-inner-scene

2025-06-12 浏览 (1)

Scene

本模块作为ArkGraphics 3D基础模块，提供SceneResourceParameters、SceneNodeParameters等通用数据类型。同时提供glTF模型加载，场景元素、资源创建等基础方法。

说明：

  • 本模块首批接口从API version 12开始支持，后续版本的新增接口，采用上角标标记接口的起始版本。

导入模块

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

SceneResourceParameters

场景资源参数对象，包含name和uri，用于提供场景资源的名称以及3D场景所需的资源文件路径。

系统能力： SystemCapability.ArkUi.Graphics3D

名称类型只读可选说明
namestring否否要创建资源的名称，可由开发者自定填写，用于标识该场景资源。
uriResourceStr否是3D场景所需的资源文件路径。默认值为undefined。

示例：

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();

      // 创建SceneResourceParameters类型变量并以此创建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

场景结点参数对象，它用于提供场景结点层次中的名称和路径。

系统能力： SystemCapability.ArkUi.Graphics3D

名称类型只读可选说明
namestring否否要创建的结点名称，可由开发者自定义填写，用于标识场景结点。
pathstring否是场景结点层次中的路径。用于指定创建的摄影机、灯光或结点在场景结点层次中的放置位置。每层之间使用'/'符号进行分割。如果未提供，则将其设置为根结点的子结点。默认值为undefined。

示例：

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();

      // 创建SceneNodeParameters类型变量并以此创建node
      let sceneNodeParameter: SceneNodeParameters = { name: "empty_node",
        path:"/rootNode_/empty_node" };
      let node: Promise<Node> = sceneFactory.createNode(sceneNodeParameter);
      return node;
    });
  });
}

RaycastResult20+

射线检测命中结果对象，包含被射线击中的3D物体详细信息。

系统能力： SystemCapability.ArkUi.Graphics3D

名称类型只读可选说明
nodeNode是否被射线击中的3D场景节点，可通过该节点操作目标物体（如移动、旋转、隐藏）。
centerDistancenumber是否命中物体包围盒中心到摄像机中心的距离，取值范围大于0。
hitPositionPosition3是否射线与物体碰撞点的精确世界坐标（{x: number, y: number, z: number}）。

RaycastParameters20+

射线检测参数配置，用于定义射线检测的行为。

系统能力： SystemCapability.ArkUi.Graphics3D

名称类型只读可选说明
rootNodeNode否是限定检测范围：仅检测该节点及其子节点。未设置时检测全场景。

RenderResourceFactory20+

用于创建可在共享RenderContext的多个场景（Scene）中共享的渲染资源。

createShader

createShader(params: SceneResourceParameters): Promise<Shader>

根据指定场景资源参数创建一个着色器，使用Promise异步回调。

系统能力： SystemCapability.ArkUi.Graphics3D

参数：

参数名类型必填说明
paramsSceneResourceParameters是创建着色器的参数。

返回值：

类型说明
Promise<Shader>Promise对象，返回创建的着色器对象。

示例：

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>

根据指定场景资源参数创建一个图像资源，使用Promise异步回调。

系统能力： SystemCapability.ArkUi.Graphics3D

参数：

参数名类型必填说明
paramsSceneResourceParameters是创建图像的参数。

返回值：

类型说明
Promise<Image>Promise对象，返回创建的图像对象。

示例：

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>

根据指定场景资源参数和几何体定义（GeometryDefinition）创建一个网格资源（MeshResource），使用Promise异步回调。

系统能力： SystemCapability.ArkUi.Graphics3D

参数：

参数名类型必填说明
paramsSceneResourceParameters是创建网格资源的参数。
geometryGeometryDefinition是几何形状定义，描述要创建的网格形状。

返回值：

类型说明
Promise<MeshResource>Promise对象，返回创建的网格资源对象。

示例：

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>

根据指定场景资源参数创建一个采样器资源，使用Promise异步回调。

系统能力： SystemCapability.ArkUi.Graphics3D

参数：

参数名类型必填说明
paramsSceneResourceParameters是创建采样器的参数。

返回值：

类型说明
Promise<Sampler>Promise对象，返回创建的采样器对象。

示例：

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>

从指定的资源URI创建一个新的场景。如果不指定URI，则创建一个空场景，使用Promise异步回调。

系统能力： SystemCapability.ArkUi.Graphics3D

参数：

参数名类型必填说明
uriResourceStr否创建场景使用的资源路径，如果未传入资源路径，则默认创建一个空场景。

返回值：

类型说明
Promise<Scene>Promise对象，返回创建的场景对象。

示例：

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) {
        // 从文件创建场景
        return renderResourceFactory.createScene($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.glb"));
      } else {
        // 创建空场景
        return renderResourceFactory.createScene();
      }
    });
}

SceneResourceFactory

用于创建3D场景中资源的接口，例如相机、光源等，继承自RenderResourceFactory。

createCamera

createCamera(params: SceneNodeParameters): Promise<Camera>

根据结点参数创建相机，使用Promise异步回调。

系统能力： SystemCapability.ArkUi.Graphics3D

参数：

参数名类型必填说明
paramsSceneNodeParameters是场景结点参数。

返回值：

类型说明
Promise<Camera>Promise对象，返回相机对象。

示例：

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" };
      // 创建相机
      let camera: Promise<Camera> = sceneFactory.createCamera(sceneCameraParameter);
      return camera;
    });
  });
}

createLight

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

根据结点参数和灯光类型创建灯光，使用Promise异步回调。

系统能力： SystemCapability.ArkUi.Graphics3D

参数：

参数名类型必填说明
paramsSceneNodeParameters是场景结点参数。
lightTypeLightType是灯光类型。

返回值：

类型说明
Promise<Light>Promise对象，返回灯光对象。

示例：

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" };
      // 创建平行光
      let light: Promise<Light> = sceneFactory.createLight(sceneLightParameter, LightType.DIRECTIONAL);
      return light;
    });
  });
}

createNode

createNode(params: SceneNodeParameters): Promise<Node>

创建结点，使用Promise异步回调。

系统能力： SystemCapability.ArkUi.Graphics3D

参数：

参数名类型必填说明
paramsSceneNodeParameters是场景结点参数。

返回值：

类型说明
Promise<Node>Promise对象，返回结点对象。

示例：

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" };
      // 创建节点
      let node: Promise<Node> = sceneFactory.createNode(sceneNodeParameter);
      return node;
    });
  });
}

createMaterial

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

根据场景资源参数和材质类型创建材质，使用Promise异步回调。

系统能力： SystemCapability.ArkUi.Graphics3D

参数：

参数名类型必填说明
paramsSceneResourceParameters是场景资源参数。
materialTypeMaterialType是材质类型。

返回值：

类型说明
Promise<Material>Promise对象，返回材质对象。

示例：

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" };
      // 创建材质
      let material: Promise<Material> = sceneFactory.createMaterial(sceneMaterialParameter, MaterialType.SHADER);
      return material;
    });
  });
}

createEnvironment

createEnvironment(params: SceneResourceParameters): Promise<Environment>

根据场景资源参数创建环境，使用Promise异步回调。

系统能力： SystemCapability.ArkUi.Graphics3D

参数：

参数名类型必填说明
paramsSceneResourceParameters是场景资源参数。

返回值：

类型说明
Promise<Environment>Promise对象，返回环境对象。

示例：

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") };
      // 创建Environment
      let env: Promise<Environment> = sceneFactory.createEnvironment(sceneEnvironmentParameter);
      return env;
    });
  });
}

createGeometry18+

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

根据场景结点参数和网格数据创建几何对象，使用Promise异步回调。

系统能力： SystemCapability.ArkUi.Graphics3D

参数：

参数名类型必填说明
paramsSceneNodeParameters是场景结点参数。
meshMeshResource是网格数据参数。

返回值：

类型说明
Promise<Geometry>Promise对象，返回几何对象。

示例：

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+

表示基础场景组件，用于描述场景节点的组件信息，包括组件名称及其对应的属性集合。

属性

系统能力： SystemCapability.ArkUi.Graphics3D

名称类型只读可选说明
namestring否否要创建场景组件的名称，可由开发者自定填写，用于标识场景组件。
propertyRecord<string, string |number |Vec2 |Vec3 |Vec4 |Image |boolean |number[] |string[] |Image[]>是否组件的属性集合，以键值对形式存储。支持多种基础类型和复杂类型，用于描述场景组件的各种属性。

RenderContext20+

定义了所有渲染资源的上下文。在同一渲染上下文中创建的多个场景之间，可以共享渲染资源。

getRenderResourceFactory

getRenderResourceFactory() : RenderResourceFactory

获取渲染资源工厂，提供创建不同渲染资源的功能。

系统能力： SystemCapability.ArkUi.Graphics3D

返回值：

类型说明
RenderResourceFactory返回一个RenderResourceFactory实例，用于创建渲染资源。

示例：

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>

用于加载指定名称的插件，通过插件名称查找并加载对应的插件资源，使用Promise异步回调。

系统能力： SystemCapability.ArkUi.Graphics3D

参数：

参数名类型必填说明
namestring是要加载的插件名称，必须是系统预定义或已注册且可用的插件名称，且符合命名规范。

返回值：

类型说明
Promise<boolean>返回一个Promise对象，解析结果为boolean类型，表示插件加载是否成功。true表示加载成功，false表示加载失败。

示例：

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+

渲染参数接口。

系统能力： SystemCapability.ArkUi.Graphics3D

名称类型只读可选说明
alwaysRender15+boolean否是表示是否每一帧都渲染。true表示每一帧都渲染，false表示按需渲染。默认值为true。

Scene

用于设置场景。

属性

系统能力： SystemCapability.ArkUi.Graphics3D

名称类型只读可选说明
environmentEnvironment否否环境对象。
animationsAnimation[]是否动画数组，用于保存3D场景中的动画对象。
rootNode |null是否3D场景树根结点。

load

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

通过传入的资源路径加载资源，使用Promise异步回调。

系统能力： SystemCapability.ArkUi.Graphics3D

参数：

参数名类型必填说明
uriResourceStr否待加载的模型文件资源路径，默认值为undefined。

返回值：

类型说明
Promise<Scene>Promise对象，返回场景对象。

示例：

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

function loadModel() : void {
  // 加载模型
  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

通过路径获取结点。

系统能力： SystemCapability.ArkUi.Graphics3D

参数：

参数名类型必填说明
pathstring是场景结点层次中的路径。每层之间使用'/'符号进行分割。
typeNodeType否预期返回的结点类型。默认值为空。

返回值：

类型说明
Node |null返回请求结点的实例，如果没有找到或者找到的节点类型与传入的参数不相符则返回空。

示例：

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) {
         // 寻找指定路径的节点
        let node : Node|null = result.getNodeByPath("rootNode_");
    }
  });
}

getResourceFactory

getResourceFactory(): SceneResourceFactory

获取场景资源工厂对象。

系统能力： SystemCapability.ArkUi.Graphics3D

返回值：

类型说明
SceneResourceFactory返回场景资源工厂对象。

示例：

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) {
         // 获得SceneResourceFactory对象
        let sceneFactory: SceneResourceFactory = result.getResourceFactory();
    }
  });
}

destroy

destroy(): void

销毁场景，释放所有的场景资源。

系统能力： SystemCapability.ArkUi.Graphics3D

示例：

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) {
         // 销毁scene
        result.destroy();
    }
  });
}

importNode18+

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

一般用于从其他场景导入结点。

系统能力： SystemCapability.ArkUi.Graphics3D

参数：

参数名类型必填说明
namestring是导入结点后的名称，由开发者自定义，无特殊要求。
nodeNode是被导入的结点。
parentNode |null是被导入结点在新场景中的父结点。

返回值：

类型说明
Node被导入的结点。

示例：

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

在当前场景中导入其他场景。

系统能力： SystemCapability.ArkUi.Graphics3D

参数：

参数名类型必填说明
namestring是导入场景的根结点名称，由开发者自定义，无特殊要求。
sceneScene是被导入的场景。
parentNode |null是被导入场景在新场景中的父结点。

返回值：

类型说明
Node被导入场景的根结点。

示例：

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

通过该接口可以实现按需渲染，例如控制渲染帧率。

系统能力： SystemCapability.ArkUi.Graphics3D

参数：

参数名类型必填说明
paramsRenderParameters否渲染参数，默认值为undefined。

返回值：

类型说明
boolean渲染被成功调度返回true，否则返回false。

示例：

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>

在指定节点上创建新的组件，根据组件名称异步创建并附加到节点上，使用Promise异步回调。

系统能力： SystemCapability.ArkUi.Graphics3D

参数：

参数名类型必填说明
nodeNode是组件需要附加到的节点。
namestring是要创建的组件名称，由各插件定义有效名称。

返回值：

类型说明
Promise<SceneComponent>Promise对象，返回新创建的场景组件。

示例：

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

根据指定的组件名称，从给定节点上获取对应的组件实例。

系统能力： SystemCapability.ArkUi.Graphics3D

参数：

参数名类型必填说明
nodeNode是组件附加的节点。
namestring是需要获取的组件名称，必须为系统预定义或已注册的自定义组件名称，且需符合命名规范。

返回值：

类型说明
SceneComponent |null返回对应名称的组件对象，若未找到则返回null。

示例：

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

获取当前图形对象所关联的渲染环境信息。

返回值：

类型说明
RenderContext |null返回当前对象关联的渲染上下文，若对象尚未关联任何渲染上下文，则返回null。

示例：

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（方舟3D图形）

harmony 鸿蒙SceneNode

harmony 鸿蒙ScenePostProcessSettings

harmony 鸿蒙SceneResource

harmony 鸿蒙SceneType

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

  • 所属分类： 后端技术
  • 本文标签： 鸿蒙 软件
  • 版权声明： 本文链接 https://seaxiang.com/blog/x0g8NK