程序包 ohos.agp.render.render3d.util

接口 SceneUtil

public interface SceneUtil

Adds 3D objects to a scene, such as casting rays.

从以下版本开始:

3

嵌套类概要

嵌套类

限定符和类型	接口	说明
static interface	SceneUtil.RayCastResult	Represents the ray-cast result.

方法概要

限定符和类型	方法	说明
Entity	createLightDirectional(Quaternion rotation, boolean isShadowEnabled, Vector3 color, float intensity)	Create a directional light and add it to a scene.
Entity	createLightPoint(Vector3 position, boolean isShadowEnabled, Vector3 color, float intensity)	Creates a point light and adds it to the scene.
Entity	createLightSpot(Vector3 position, Quaternion rotation, boolean isShadowEnabled, Vector3 color, float intensity)	Creates a spotlight and adds it to the scene.
Entity	createPerspectiveCamera(Vector3 position, Quaternion rotation, float znear, float zfar, float fovDegrees)	Creates a perspective camera and adds it to the scene.
Entity	generateCone(String name, ResourceHandle material, float radius, float length, int sectors)	Generates a cone entity.
ResourceHandle	generateConeMesh(String name, ResourceHandle material, float radius, float length, int sectors)	Generates a cone mesh.
Entity	generateCube(String name, ResourceHandle material, float width, float height, float depth)	Generates a cube entity.
ResourceHandle	generateCubeMesh(String name, ResourceHandle material, float width, float height, float depth)	Generates a cube mesh.
Entity	generatePlane(String name, ResourceHandle material, float width, float depth)	Generates a plane entity.
ResourceHandle	generatePlaneMesh(String name, ResourceHandle material, float width, float depth)	Generates a plane mesh.
Entity	generateSphere(String name, ResourceHandle material, float radius, int rings, int sectors)	Generates a sphere entity.
ResourceHandle	generateSphereMesh(String name, ResourceHandle material, float radius, int rings, int sectors)	Generates a sphere mesh.
BoundingBox	getBoundsUsingTransform(Entity entity, boolean isRecursive)	Calculates the entity boundary using the transformation component.
BoundingBox	getBoundsUsingWorldMatrix(Entity entity, boolean isRecursive)	Calculates the entity boundary using the world matrix.
List<SceneUtil.RayCastResult>	rayCast(Vector3 origin, Vector3 direction)	Obtains a list of objects cast by the ray in a scene.
List<SceneUtil.RayCastResult>	rayCastFromCamera(Entity camera, Vector2 screenPos)	Obtains a list of objects that are cast by the ray from a camera.
Vector3	screenToWorld(Entity camera, Vector3 screenPoint)	Projects the coordinate of a point from the screen to the world using the specified camera.
void	updateCameraViewport(Entity camera, int renderResolutionX, int renderResolutionY)	Updates camera viewport and aspect ratio according to render resolution.
void	updateCameraViewport(Entity camera, int renderResolutionX, int renderResolutionY, boolean isAutoAspect, float fovDegrees)	Updates the camera viewport based on the rendering resolution, and determines the aspect ratio and FOV based on the screen shape.
Vector3	worldToScreen(Entity camera, Vector3 worldPoint)	Projects the coordinate of a point from the world to the screen using the specified camera.

方法详细资料

generateCubeMesh

ResourceHandle generateCubeMesh(String name,
                                ResourceHandle material,
                                float width,
                                float height,
                                float depth)

Generates a cube mesh.

参数:

name - Indicates the name of the cube mesh.

material - Indicates the material used by the cube mesh.

width - Indicates the width of the cube mesh.

height - Indicates the height of the cube mesh.

depth - Indicates the depth of the cube mesh.

返回:

Returns the generated cube mesh.

generatePlaneMesh

ResourceHandle generatePlaneMesh(String name,
                                 ResourceHandle material,
                                 float width,
                                 float depth)

Generates a plane mesh.

参数:

name - Indicates the name of the plane mesh.

material - Indicates the material used by the plane mesh.

width - Indicates the X-axis width of the plane mesh.

depth - Indicates the Z-axis height of the plane mesh.

返回:

Returns the generated plane mesh.

generateSphereMesh

ResourceHandle generateSphereMesh(String name,
                                  ResourceHandle material,
                                  float radius,
                                  int rings,
                                  int sectors)

Generates a sphere mesh.

参数:

name - Indicates the name of the sphere mesh.

material - Indicates the material used by the sphere mesh.

radius - Indicates the radius of the sphere mesh.

rings - Indicates the number of rings in the sphere mesh.

sectors - Indicates the number of sectors in each ring.

返回:

Returns the generated sphere mesh.

generateConeMesh

ResourceHandle generateConeMesh(String name,
                                ResourceHandle material,
                                float radius,
                                float length,
                                int sectors)

Generates a cone mesh.

参数:

name - Indicates the name of the cone mesh.

material - Indicates the material used by the cone mesh.

radius - Indicates the radius of the cone mesh.

length - Indicates the length of the cone mesh.

sectors - Indicates the number of sectors in the cone mesh ring.

返回:

Returns the generated cone mesh.

generateCube

Entity generateCube(String name,
                    ResourceHandle material,
                    float width,
                    float height,
                    float depth)

Generates a cube entity.

参数:

name - Indicates the name of the cube entity.

material - Indicates the material used by the corresponding mesh. The default glTF material will be used if no material is specified.

width - Indicates the width (on X-axis) of the cube entity.

height - Indicates the length (on Y-axis) of the cube entity.

depth - Indicates the depth (on Z-axis) of the cube entity.

返回:

Returns the generated cube entity.

generatePlane

Entity generatePlane(String name,
                     ResourceHandle material,
                     float width,
                     float depth)

Generates a plane entity.

参数:

name - Indicates the name of the plane entity.

material - Indicates the material used by the corresponding mesh. The default glTF material will be used if no material is specified.

width - Indicates the width (on X-axis) of the plane entity.

depth - Indicates the depth (on Z-axis) of the plane entity.

返回:

Returns the generated plane entity.

generateSphere

Entity generateSphere(String name,
                      ResourceHandle material,
                      float radius,
                      int rings,
                      int sectors)

Generates a sphere entity.

参数:

name - Indicates the name of the sphere entity.

material - Indicates the material used by the corresponding mesh. The default glTF material will be used if no material is specified.

radius - Indicates the radius of the sphere entity.

rings - Indicates the number of rings in the sphere entity.

sectors - Indicates the number of sectors in each ring.

返回:

Returns the generated sphere entity.

generateCone

Entity generateCone(String name,
                    ResourceHandle material,
                    float radius,
                    float length,
                    int sectors)

Generates a cone entity.

参数:

name - Indicates the name of the cone entity.

material - Indicates the material used by the corresponding mesh. The default glTF material will be used if no material is specified.

radius - Indicates the radius of the cone entity.

length - Indicates the length of the cone entity.

sectors - Indicates the number of sectors in the cone entity ring.

返回:

Returns the generated cone entity.

screenToWorld

Vector3 screenToWorld(Entity camera,
                      Vector3 screenPoint)

Projects the coordinate of a point from the screen to the world using the specified camera.

参数:

camera - Indicates the specified camera used for coordinate projection.

screenPoint - Indicates the screen coordinate.

返回:

Returns the world coordinate of the projected point.

worldToScreen

Vector3 worldToScreen(Entity camera,
                      Vector3 worldPoint)

Projects the coordinate of a point from the world to the screen using the specified camera.

参数:

camera - Indicates the specified camera used for coordinate projection.

worldPoint - Indicates the world coordinate.

返回:

Returns the screen coordinate of the projected point.

rayCast

List<SceneUtil.RayCastResult> rayCast(Vector3 origin,
                                      Vector3 direction)

Obtains a list of objects cast by the ray in a scene.

参数:

origin - Indicates the start position of the ray.

direction - Indicates the direction of the ray.

返回:

Returns all ray-cast objects, which are sorted according to the distance from the start position.

rayCastFromCamera

List<SceneUtil.RayCastResult> rayCastFromCamera(Entity camera,
                                                Vector2 screenPos)

Obtains a list of objects that are cast by the ray from a camera.

参数:

camera - Indicates the camera used for ray casting.

screenPos - Indicates the screen position. The coordinate (0, 0) indicates the upper left corner of the screen, while (1, 1) indicates the lower right corner of the screen.

返回:

Returns all ray-cast objects, which are sorted according to the distance from the start position.

getBoundsUsingTransform

BoundingBox getBoundsUsingTransform(Entity entity,
                                    boolean isRecursive)

Calculates the entity boundary using the transformation component.

If the entity boundary needs to be calculated recursively, this method will calculate all child entities in the hierarchy of the root entity. You can call this method before the Entity-Component System (ECS) updates other entity components, but this means that neither animation nor skin will be included in the calculation.

参数:

entity - Indicates the root entity used for boundary calculation.

isRecursive - Indicates whether all child entities of the root entity are included for recursive calculation.

返回:

Returns the bounding box of the entity.

getBoundsUsingWorldMatrix

BoundingBox getBoundsUsingWorldMatrix(Entity entity,
                                      boolean isRecursive)

Calculates the entity boundary using the world matrix.

If the entity boundary needs to be calculated recursively, this method will calculate all child entities in the hierarchy of the root entity. You can call this method before the ECS updates other entity components, but this means that neither animation nor skin will be included in the calculation.

参数:

entity - Indicates the root entity used for boundary calculation.

isRecursive - Indicates whether all child entities of the root entity are included in the calculation.

返回:

Returns the bounding box of the entity.

createPerspectiveCamera

Entity createPerspectiveCamera(Vector3 position,
                               Quaternion rotation,
                               float znear,
                               float zfar,
                               float fovDegrees)

Creates a perspective camera and adds it to the scene.

参数:

position - Indicates the camera position, which is the start position by default.

rotation - Indicates the rotation degree of the camera, which is Quaternion#IDENTITY by default.

znear - Indicates the near-plane distance, which is 0.1 by default.

zfar - Indicates the far-plane distance, which is 4000 by default.

fovDegrees - Indicates the Field Of View (FOV) degree of the camera, which is 60 by default.

返回:

Returns the created perspective camera.

updateCameraViewport

void updateCameraViewport(Entity camera,
                          int renderResolutionX,
                          int renderResolutionY,
                          boolean isAutoAspect,
                          float fovDegrees)

Updates the camera viewport based on the rendering resolution, and determines the aspect ratio and FOV based on the screen shape.

参数:

camera - Indicates the camera to update.

renderResolutionX - Indicates the width of the rendering resolution.

renderResolutionY - Indicates the height of the rendering resolution.

isAutoAspect - Indicates whether auto-calculation of aspect ratio is enabled. true indicates that the aspect ratio is also calculated.

fovDegrees - Indicates the Y-axis FOV (in radians) of a horizontal screen, or X-axis FOV of a vertical screen.

updateCameraViewport

void updateCameraViewport(Entity camera,
                          int renderResolutionX,
                          int renderResolutionY)

Updates camera viewport and aspect ratio according to render resolution.

参数:

camera - Camera entity.

renderResolutionX - Horizontal render resolution.

renderResolutionY - Vertical render resolution.

createLightDirectional

Entity createLightDirectional(Quaternion rotation,
                              boolean isShadowEnabled,
                              Vector3 color,
                              float intensity)

Create a directional light and add it to a scene.

参数:

rotation - Direction of the light.

isShadowEnabled - Sets whether this light is supposed to cast shadows.

color - Color of the light.

intensity - Intensity of the light.

返回:

Newly created light entity.

createLightSpot

Entity createLightSpot(Vector3 position,
                       Quaternion rotation,
                       boolean isShadowEnabled,
                       Vector3 color,
                       float intensity)

Creates a spotlight and adds it to the scene.

参数:

position - Indicates the spotlight position.

rotation - Indicates the spotlight direction.

isShadowEnabled - Indicates whether spotlight projection is enabled.

color - Indicates the spotlight color.

intensity - Indicates the spotlight intensity.

返回:

Returns the created spotlight.

createLightPoint

Entity createLightPoint(Vector3 position,
                        boolean isShadowEnabled,
                        Vector3 color,
                        float intensity)

Creates a point light and adds it to the scene.

参数:

position - Indicates the light point position.

isShadowEnabled - Indicates whether the light point projection is enabled.

color - Indicates the point light color.

intensity - Indicates the light point intensity.

返回:

Returns the created light point.