目录

AR Engine

Overview

Provides APIs related to the augmented reality capability of AR Engine.

Covers basic AR capabilities, including motion tracking, environment tracking, and hit testing.

Start version: 5.0.0(12)

Summary

[h2]Files

Name

Description

ar_engine_core.h

Declares the APIs for accessing AR Engine, and provides basic AR Engine capabilities, including motion tracking, environment tracking, and hit testing.

[h2]Structs

Name

Description

struct AREngine_ClipPlaneDistance

Distance to the clipping planes.

[h2]Macro Definition

Name

Description

ARENGINE_AABB_POINT_SIZE = 6

Size of the bounding box coordinate array.

ARENGINE_POSE_RAW_SIZE = 7

Size of the pose data array.

ARENGINE_VIEW_MATRIX_SIZE = 16

Size of the transformation matrix array.

ARENGINE_DISTORTION_COUNT = 5

Number of camera distortion parameters.

[h2]Type Definitions

Name

Description

typedef struct AREngine_ARConfig AREngine_ARConfig

Configures AREngine_ARSession capabilities (which capabilities and modes to use).

typedef struct AREngine_ARSession AREngine_ARSession

Manages the system status of AR Engine.

typedef struct AREngine_ARPose AREngine_ARPose

Indicates the pose (translation + rotation), representing an immutable rigid transformation from one coordinate system to another.

typedef struct AREngine_ARCamera AREngine_ARCamera

Indicates the camera information for the current frame.

typedef struct AREngine_ARCameraIntrinsics AREngine_ARCameraIntrinsics

Indicates intrinsic camera parameters, including fx, fy, cx, cy, and camera distortion parameters.

typedef struct AREngine_ARCameraConfig AREngine_ARCameraConfig

Provides camera configuration information, such as the image size to be processed by CPU, or the texture size to be processed by GPU.

typedef struct AREngine_ARFrame AREngine_ARFrame

Indicates a frame of data processed by AR Engine.

typedef struct AREngine_ARPointCloud AREngine_ARPointCloud

Indicates a collection of trackable 3D point clouds.

typedef struct AREngine_ARTrackable AREngine_ARTrackable

Indicates a trackable object, such as a point or a plane.

typedef struct AREngine_ARTrackableList AREngine_ARTrackableList

Indicates a list of trackable objects.

typedef struct AREngine_ARPlane AREngine_ARPlane

Indicates a plane object, which describes the detected trackable plane information.

typedef struct AREngine_ARPoint AREngine_ARPoint

Indicates a point object, which describes the detected trackable point data.

typedef struct AREngine_ARTarget AREngine_ARTarget

Indicates an object, which describes a trackable semantic object, such as a semantic plane.

typedef struct AREngine_ARAnchor AREngine_ARAnchor

Indicates an anchor object, which describes the spatial location associated with a trackable object.

typedef struct AREngine_ARAnchorList AREngine_ARAnchorList

Indicates a list of anchor objects.

typedef struct AREngine_ARHitResult AREngine_ARHitResult

Indicates the hit testing result object, which describes the hit testing result of a single trackable object.

typedef struct AREngine_ARHitResultList AREngine_ARHitResultList

Indicates the list of hit testing results.

typedef struct AREngine_ARImage AREngine_ARImage

Indicates the camera video stream frame object.

[h2]Enumerations

Name

Description

AREngine_ARTrackableType {

ARENGINE_TRACKABLE_BASE = 0x41520100, ARENGINE_TRACKABLE_PLANE = 0x41520101, ARENGINE_TRACKABLE_POINT = 0x41520102, ARENGINE_TRACKABLE_TARGET = 0x50000008,

ARENGINE_TRACKABLE_INVALID = 0

}

Type of a trackable object, such as a plane or a point.

AREngine_ARTrackingState { ARENGINE_TRACKING_STATE_TRACKING = 0, ARENGINE_TRACKING_STATE_PAUSED = 1, ARENGINE_TRACKING_STATE_STOPPED = 2 }

Tracking status of the trackable object.

AREngine_ARTrackingStateReason { ARENGINE_TRACKING_STATE_REASON_NONE = 0, ARENGINE_TRACKING_STATE_REASON_EXCESSIVE_MOTION = 1, ARENGINE_TRACKING_STATE_REASON_INSUFFICIENT_FEATURES = 2 }

Possible causes of tracking failures.

AREngine_ARPlaneFindingMode { ARENGINE_PLANE_FINDING_MODE_DISABLED = 0, ARENGINE_PLANE_FINDING_MODE_HORIZONTAL = 1, ARENGINE_PLANE_FINDING_MODE_VERTICAL = 2, ARENGINE_PLANE_FINDING_MODE_HORIZONTAL_AND_VERTICAL = 3 }

Plane finding mode.

AREngine_ARUpdateMode { ARENGINE_UPDATE_MODE_BLOCKING = 0, ARENGINE_UPDATE_MODE_LATEST = 1 }

Data update mode specified by HMS_AREngine_ARSession_Update.

AREngine_ARPowerMode { ARENGINE_POWER_MODE_NORMAL = 0, ARENGINE_POWER_MODE_POWER_SAVING = 1, ARENGINE_POWER_MODE_PERFORMANCE_FIRST = 2, ARENGINE_POWER_MODE_BOOST = 3 ,

ARENGINE_POWER_MODE_ULTRA_POWER_SAVING = 11}

Power consumption mode.

AREngine_ARFocusMode { ARENGINE_FOCUS_MODE_FIXED = 0, ARENGINE_FOCUS_MODE_AUTO = 1 }

Focus mode.

AREngine_ARPlaneType { ARENGINE_PLANE_FACING_HORIZONTAL_UPWARD = 0, ARENGINE_PLANE_FACING_HORIZONTAL_DOWNWARD = 1, ARENGINE_PLANE_FACING_VERTICAL = 2, ARENGINE_PLANE_FACING_INVALID = 3 }

Plane type.

AREngine_ARType { ARENGINE_TYPE_WORLD = 0x01 }

AR capability type.

AREngine_ARSemanticMode { ARENGINE_SEMANTIC_MODE_NONE = 0, ARENGINE_SEMANTIC_MODE_PLANE = 1, ARENGINE_SEMANTIC_MODE_TARGET = 2 }

Semantic mode.

AREngine_ARPointOrientationMode { ARENGINE_POINT_ORIENTATION_INITIALIZED_TO_IDENTITY = 0, ARENGINE_POINT_ORIENTATION_ESTIMATED_SURFACE_NORMAL = 1 }

Orientation mode.

AREngine_ARSemanticPlaneLabel {

ARENGINE_PLANE_UNKNOWN = 0, ARENGINE_PLANE_WALL = 1, ARENGINE_PLANE_FLOOR = 2, ARENGINE_PLANE_SEAT = 3,

ARENGINE_PLANE_TABLE = 4, ARENGINE_PLANE_CEILING = 5, ARENGINE_PLANE_DOOR = 6, ARENGINE_PLANE_WINDOW = 7,

ARENGINE_PLANE_BED = 8

}

Semantic type of the current plane.

AREngine_ARTargetShapeLabel { ARENGINE_TARGET_SHAPE_UNKNOWN = 0, ARENGINE_TARGET_SHAPE_CUBE = 1, ARENGINE_TARGET_SHAPE_CIRCLE = 2, ARENGINE_TARGET_SHAPE_RECTANGLE = 3 }

Shape of the recognized object.

AREngine_ARPoseType { ARENGINE_POSE_TYPE_IDENTITY = 0, ARENGINE_POSE_TYPE_ROTATE_90 = 1, ARENGINE_POSE_TYPE_ROTATE_180 = 2, ARENGINE_POSE_TYPE_ROTATE_270 = 3 }

Pose type.

AREngine_ARImageFormat { ARENGINE_IMAGE_UNKNOWN = 0, ARENGINE_IMAGE_YUV_420_888 = 2 }

Image format.

AREngine_ARPreviewMode { ARENGINE_PREVIEW_MODE_ENABLED = 0, ARENGINE_PREVIEW_MODE_DISABLED = 1 }

Preview mode.

AREngine_ARStatus {

ARENGINE_SUCCESS = 0, ARENGINE_ERROR_PERMISSION_NOT_GRANTED = 201, ARENGINE_ERROR_INVALID_ARGUMENT = 401, ARENGINE_ERROR_DEVICE_NOT_SUPPORTED = 801,

ARENGINE_ERROR_FATAL = 1009200001, ARENGINE_ERROR_SESSION_PAUSED = 1009200002, ARENGINE_ERROR_SESSION_NOT_PAUSED = 1009200003, ARENGINE_ERROR_NOT_TRACKING = 1009200004,

ARENGINE_ERROR_TEXTURE_NOT_SET = 1009200005, ARENGINE_ERROR_MISSING_GL_CONTEXT = 1009200006, ARENGINE_ERROR_UNSUPPORTED_CONFIGURATION = 1009200007, ARENGINE_ERROR_RESOURCE_EXHAUSTED = 1009200008,

ARENGINE_ERROR_NOT_AVAILABLE = 1009200009, ARENGINE_ERROR_CAMERA_NOT_AVAILABLE = 1009200010

}

Error code returned by an API.

[h2]Functions

Name

Description

AREngine_ARStatus HMS_AREngine_ARConfig_Create (const AREngine_ARSession *session, AREngine_ARConfig **outConfig)

Creates a configuration object with a proper default configuration.

void HMS_AREngine_ARConfig_Destroy (AREngine_ARConfig *config)

Releases the memory used by a specific configuration object.

AREngine_ARStatus HMS_AREngine_ARConfig_GetPlaneFindingMode (const AREngine_ARSession *session, const AREngine_ARConfig *config, AREngine_ARPlaneFindingMode *planeFindingMode)

Obtains the current plane finding mode.

AREngine_ARStatus HMS_AREngine_ARConfig_SetPlaneFindingMode (const AREngine_ARSession *session, AREngine_ARConfig *config, AREngine_ARPlaneFindingMode planeFindingMode)

Sets the plane finding mode.

AREngine_ARStatus HMS_AREngine_ARConfig_GetUpdateMode (const AREngine_ARSession *session, const AREngine_ARConfig *config, AREngine_ARUpdateMode *updateMode)

Obtains the current preview update mode.

AREngine_ARStatus HMS_AREngine_ARConfig_SetUpdateMode (const AREngine_ARSession *session, AREngine_ARConfig *config, AREngine_ARUpdateMode updateMode)

Sets the preview update mode.

AREngine_ARStatus HMS_AREngine_ARConfig_GetPowerMode (const AREngine_ARSession *session, const AREngine_ARConfig *config, AREngine_ARPowerMode *powerMode)

Obtains the current power consumption mode.

AREngine_ARStatus HMS_AREngine_ARConfig_SetPowerMode (const AREngine_ARSession *session, AREngine_ARConfig *config, AREngine_ARPowerMode powerMode)

Sets the power consumption mode.

AREngine_ARStatus HMS_AREngine_ARConfig_GetFocusMode (const AREngine_ARSession *session, const AREngine_ARConfig *config, AREngine_ARFocusMode *focusMode)

Obtains the current focus mode.

AREngine_ARStatus HMS_AREngine_ARConfig_SetFocusMode (const AREngine_ARSession *session, AREngine_ARConfig *config, AREngine_ARFocusMode focusMode)

Sets the focus mode.

AREngine_ARStatus HMS_AREngine_ARConfig_SetPreviewSize (const AREngine_ARSession *session, AREngine_ARConfig *config, uint32_t width, uint32_t height)

Sets the preview image size.

AREngine_ARStatus HMS_AREngine_ARConfig_GetARType (const AREngine_ARSession *session, const AREngine_ARConfig *config, AREngine_ARType *type)

Obtains the AR capability type in use.

AREngine_ARStatus HMS_AREngine_ARConfig_SetARType (const AREngine_ARSession *session, AREngine_ARConfig *config, AREngine_ARType type)

Sets the AR capability type to use.

AREngine_ARStatus HMS_AREngine_ARConfig_GetSemanticMode (const AREngine_ARSession *session, const AREngine_ARConfig *config, AREngine_ARSemanticMode *mode)

Obtains the current semantic recognition mode. This function is valid after HMS_AREngine_ARConfig_SetSemanticMode has been called.

AREngine_ARStatus HMS_AREngine_ARConfig_SetSemanticMode (const AREngine_ARSession *session, AREngine_ARConfig *config, AREngine_ARSemanticMode mode)

Sets the semantic recognition mode.

AREngine_ARStatus HMS_AREngine_ARConfig_GetMaxMapSize (const AREngine_ARSession *session, const AREngine_ARConfig *config, uint64_t *maxMapSize)

Obtains the maximum memory size for storing map data.

AREngine_ARStatus HMS_AREngine_ARConfig_SetMaxMapSize (const AREngine_ARSession *session, AREngine_ARConfig *config, uint64_t maxMapSize)

Sets the maximum memory size for storing map data.

AREngine_ARStatus HMS_AREngine_ARSession_Create (void *env, void *applicationContext, AREngine_ARSession **outSessionPointer)

Creates an AREngine_ARSession session. This function depends on the camera, acceleration sensor, and gyroscope sensor permissions.

AREngine_ARStatus HMS_AREngine_ARSession_Stop (AREngine_ARSession *session)

Stops AR Engine and the camera preview stream, clears the plane and anchor data, releases the camera, and terminates the session.

void HMS_AREngine_ARSession_Destroy (AREngine_ARSession *session)

Releases the resources used by the AREngine_ARSession session.

AREngine_ARStatus HMS_AREngine_ARSession_Resume (AREngine_ARSession *session)

Starts AREngine_ARSession, or restores AREngine_ARSession after HMS_AREngine_ARSession_Pause is called.

AREngine_ARStatus HMS_AREngine_ARSession_Pause (AREngine_ARSession *session)

Pauses the session, stops the camera preview stream, and releases the camera (otherwise, other apps will not be able to use the camera service), without clearing the plane and anchor data.

AREngine_ARStatus HMS_AREngine_ARSession_Update (AREngine_ARSession *session, AREngine_ARFrame *outFrame)

Updates the computation result of AR Engine.

AREngine_ARStatus HMS_AREngine_ARSession_Configure (AREngine_ARSession *session, const AREngine_ARConfig *config)

Configures an AREngine_ARSession session.

AREngine_ARStatus HMS_AREngine_ARSession_AcquireNewAnchor (AREngine_ARSession *session, const AREngine_ARPose *pose, AREngine_ARAnchor **outAnchor)

Creates an anchor for continuous tracking.

AREngine_ARStatus HMS_AREngine_ARSession_SetCameraGLTexture (AREngine_ARSession *session, uint32_t textureId)

Sets the OpenGL texture for storing the camera preview stream data.

AREngine_ARStatus HMS_AREngine_ARSession_SetDisplayGeometry (AREngine_ARSession *session, AREngine_ARPoseType rotation, int32_t width, int32_t height)

Sets the display height and width (in pixels). Make sure that the height and width you set here are consistent with those of the display view. Otherwise, an error will occur with the camera preview.

AREngine_ARStatus HMS_AREngine_ARSession_GetAllAnchors (const AREngine_ARSession *session, AREngine_ARAnchorList *outAnchorList)

Obtains all anchors, including anchors in all states contained in AREngine_ARTrackingState.

AREngine_ARStatus HMS_AREngine_ARSession_GetAllTrackables (const AREngine_ARSession *session, AREngine_ARTrackableType filterType, AREngine_ARTrackableList *outTrackableList)

Obtains the list of all trackable objects of the specified type.

AREngine_ARStatus HMS_AREngine_ARSession_GetCameraConfig (const AREngine_ARSession *session, AREngine_ARCameraConfig *outCameraConfig)

Obtains the camera configuration information.

AREngine_ARStatus HMS_AREngine_ARPose_Create (const AREngine_ARSession *session, const float *poseRaw, const uint32_t poseRawSize, AREngine_ARPose **outPose)

Allocates and initializes a new pose object. You can leave poseRaw empty to create an uninitialized pose object, and then call HMS_AREngine_ARPoint_GetPose and HMS_AREngine_ARAnchor_GetPose to assign a value to the pose object.

void HMS_AREngine_ARPose_Destroy (AREngine_ARPose *pose)

Releases the memory used by the pose object.

AREngine_ARStatus HMS_AREngine_ARPose_GetPoseRaw (const AREngine_ARSession *session, const AREngine_ARPose *pose, float *outPoseRaw, int32_t poseRawSize)

Obtains pose data from the pose object, including translation components and rotation components. The obtained pose data is an array with 7 elements: poseRaw[0] to poseRaw[3] are rotation quaternions, and poseRaw[4] to poseRaw[6] are translation components (x, y, z).

AREngine_ARStatus HMS_AREngine_ARPose_GetMatrix (const AREngine_ARSession *session, const AREngine_ARPose *pose, float *outMatrixColMajor4x4, int32_t matrixColMajor4x4Size)

Converts the pose data into a 4 x 4 matrix. outMatrixColMajor4x4 is the array for storing the matrix, where data is stored in column-major order. Coordinates in the local coordinate system can be converted into ones in the world coordinate system by multiplying this matrix with the coordinates in the local coordinate system.

AREngine_ARStatus HMS_AREngine_ARCamera_GetPose (const AREngine_ARSession *session, const AREngine_ARCamera *camera, AREngine_ARPose *outPose)

Sets outPose to the pose of the physical camera in the world space in the latest frame. The pose is that of the OpenGL camera, where the positive direction of the x-axis is to the right, the positive direction of the y-axis is upwards, and the negative direction of the z-axis is the look-at direction of the camera. The camera position refers to the physical camera position, and the orientation of the camera's x-axis and y-axis is not affected by the screen orientation (taking display rotation into account).

AREngine_ARStatus HMS_AREngine_ARCamera_GetDisplayOrientedPose (const AREngine_ARSession *session, const AREngine_ARCamera *camera, AREngine_ARPose *outPose)

Sets outPose to the pose of the virtual camera (facing the display) in the world space, in order to render AR content into the latest frame. The pose is that of the OpenGL camera, where the positive direction of the x-axis is to the right, the positive direction of the y-axis is upwards, and the negative direction of the z-axis is the look-at direction of the camera. The camera position refers to the physical camera position, and the orientation of the camera's x-axis and y-axis is affected by the screen orientation (taking display rotation into account).

AREngine_ARStatus HMS_AREngine_ARCamera_GetViewMatrix (const AREngine_ARSession *session, const AREngine_ARCamera *camera, float *outColMajor4x4, int32_t colMajor4x4Num)

Obtains the view matrix of the camera in the latest frame.

AREngine_ARStatus HMS_AREngine_ARCamera_GetTrackingState (const AREngine_ARSession *session, const AREngine_ARCamera *camera, AREngine_ARTrackingState *outTrackingState)

Obtains the current tracking status of the camera. The camera pose is available only when the tracking status is ARENGINE_TRACKING_STATE_TRACKING.

AREngine_ARStatus HMS_AREngine_ARCamera_GetTrackingStateReason (const AREngine_ARSession *session, const AREngine_ARCamera *camera, AREngine_ARTrackingStateReason *outTrackingStateReason)

Obtains the reason why the current tracking status of the camera is ARENGINE_TRACKING_STATE_PAUSED. When the current tracking status of the camera is ARENGINE_TRACKING_STATE_TRACKING, the function returns ARENGINE_TRACKING_STATE_REASON_NONE.

AREngine_ARStatus HMS_AREngine_ARCamera_GetProjectionMatrix (const AREngine_ARSession *session, const AREngine_ARCamera *camera, AREngine_ClipPlaneDistance clipPlaneDistance, float *outDestColMajor4x4, int32_t destColMajor4x4Num)

Obtains the projection matrix used for rendering virtual content on top of the camera image. This matrix can be used for converting from the camera coordinate system to the clip coordinate system.

AREngine_ARStatus HMS_AREngine_ARCamera_GetImageIntrinsics (const AREngine_ARSession *session, const AREngine_ARCamera *camera, AREngine_ARCameraIntrinsics *outIntrinsics)

Obtains the object of the offline intrinsic camera parameters. This object can be used obtain the camera's focal length, image size, principal point, and distortion parameters.

void HMS_AREngine_ARCamera_Release (AREngine_ARCamera *camera)

Releases the reference to the camera. You need to call HMS_AREngine_ARCamera_Release if you have called HMS_AREngine_ARFrame_AcquireCamera. Calling this method before HMS_AREngine_ARFrame_AcquireCamera is called does not take effect.

AREngine_ARStatus HMS_AREngine_ARCameraIntrinsics_Create (const AREngine_ARSession *session, AREngine_ARCameraIntrinsics **outIntrinsics)

Creates an object of the intrinsic camera parameters.

void HMS_AREngine_ARCameraIntrinsics_Destroy (AREngine_ARCameraIntrinsics *intrinsics)

Releases a specific object of intrinsic camera parameters.

AREngine_ARStatus HMS_AREngine_ARCameraIntrinsics_GetFocalLength (const AREngine_ARSession *session, const AREngine_ARCameraIntrinsics *intrinsics, float *outFocalX, float *outFocalY)

Obtains the focal length of a camera in pixels.

AREngine_ARStatus HMS_AREngine_ARCameraIntrinsics_GetPrincipalPoint (const AREngine_ARSession *session, const AREngine_ARCameraIntrinsics *intrinsics, float *outPrincipalX, float *outPrincipalY)

Obtains the principal point of a camera, with the location of the point expressed in pixels.

AREngine_ARStatus HMS_AREngine_ARCameraIntrinsics_GetImageDimensions (const AREngine_ARSession *session, const AREngine_ARCameraIntrinsics *intrinsics, int32_t *outWidth, int32_t *outHeight)

Obtains the camera image size, including the width and height (in pixels).

AREngine_ARStatus HMS_AREngine_ARCameraIntrinsics_GetDistortion (const AREngine_ARSession *session, const AREngine_ARCameraIntrinsics *intrinsics, float *outDistortion, int32_t distortionNum)

Obtains a camera's distortion coefficients, which include 5 components: outDistortion[0] to outDistortion [2] represent k1, k2, and k3 (radial distortion coefficients), and outDistortion [3] to outDistortion [4] are the tangential distortion coefficients.

AREngine_ARStatus HMS_AREngine_ARFrame_Create (const AREngine_ARSession *session, AREngine_ARFrame **outFrame)

Creates an AREngine_ARFrame object and stores the pointer in *outFrame.

void HMS_AREngine_ARFrame_Destroy (AREngine_ARFrame *frame)

Deletes the current AREngine_ARFrame object.

AREngine_ARStatus HMS_AREngine_ARFrame_GetDisplayGeometryChanged (const AREngine_ARSession *session, const AREngine_ARFrame *frame, int32_t *outGeometryChangeState)

Obtains whether the display (length, width, and rotation) changes. If so, you need to call HMS_AREngine_ARFrame_TransformDisplayUvCoords again to obtain the correct coordinates of the texture map. If the return value of outGeometryChangeState is 0, no changes have occurred. Otherwise, changes have occurred.

AREngine_ARStatus HMS_AREngine_ARFrame_GetTimestamp (const AREngine_ARSession *session, const AREngine_ARFrame *frame, int64_t *outTimestampNs)

Obtains the timestamp information (in nanoseconds) of the current frame.

AREngine_ARStatus HMS_AREngine_ARFrame_TransformDisplayUvCoords (const AREngine_ARSession *session, const AREngine_ARFrame *frame, int32_t elementSize, const float *uvsIn, float *uvsOut)

Converts the texture coordinates so that the background image captured by the camera can be correctly displayed.

AREngine_ARStatus HMS_AREngine_ARFrame_HitTest (const AREngine_ARSession *session, const AREngine_ARFrame *frame, float pixelX, float pixelY, AREngine_ARHitResultList *hitResultList)

Casts a ray from the camera, with the direction of the ray determined by the points (pixelX, pixelY) in the preview area. pixelX and pixelY can be obtained through the XComponent's DispatchTouchEvent() event.

AREngine_ARStatus HMS_AREngine_ARFrame_AcquirePointCloud (const AREngine_ARSession *session, const AREngine_ARFrame *frame, AREngine_ARPointCloud **outPointCloud)

Returns the point cloud data of the current frame.

AREngine_ARStatus HMS_AREngine_ARFrame_AcquireCamera (const AREngine_ARSession *session, const AREngine_ARFrame *frame, AREngine_ARCamera **outCamera)

Obtains the camera parameter object of the current frame.

AREngine_ARStatus HMS_AREngine_ARFrame_GetUpdatedTrackables (const AREngine_ARSession *session, const AREngine_ARFrame *frame, AREngine_ARTrackableType filterType, AREngine_ARTrackableList *outTrackableList)

Obtains the updated trackable object of the specified type after HMS_AREngine_ARSession_Update is called.

AREngine_ARStatus HMS_AREngine_ARFrame_AcquireCameraImage (const AREngine_ARSession *session, const AREngine_ARFrame *frame, AREngine_ARImage **outImage)

Obtains the image of the current frame of the camera.

AREngine_ARStatus HMS_AREngine_ARPointCloud_GetData (const AREngine_ARSession *session, const AREngine_ARPointCloud *pointCloud, const float **outPointCloudData)

Obtains the coordinates of all points in a point cloud, as well as their confidence array.

AREngine_ARStatus HMS_AREngine_ARPointCloud_GetNumberOfPoints (const AREngine_ARSession *session, const AREngine_ARPointCloud *pointCloud, int32_t *outNumberOfPoints)

Obtains the coordinates of all points in a point cloud, as well as their confidence array size. This function is used together with HMS_AREngine_ARPointCloud_GetData.

AREngine_ARStatus HMS_AREngine_ARPointCloud_GetTimestamp (const AREngine_ARSession *session, const AREngine_ARPointCloud *pointCloud, int64_t *outTimestampNs)

Obtains the timestamp when the current point cloud is detected, in nanoseconds.

void HMS_AREngine_ARPointCloud_Release (AREngine_ARPointCloud *pointCloud)

Releases the memory used by the point cloud object.

AREngine_ARStatus HMS_AREngine_ARAnchor_GetPose (const AREngine_ARSession *session, const AREngine_ARAnchor *anchor, AREngine_ARPose *outPose)

Obtains the pose of a specific anchor in the world coordinate system.

AREngine_ARStatus HMS_AREngine_ARAnchor_GetTrackingState (const AREngine_ARSession *session, const AREngine_ARAnchor *anchor, AREngine_ARTrackingState *outTrackingState)

Obtains the tracking status of the pose of a specific anchor.

AREngine_ARStatus HMS_AREngine_ARAnchor_Detach (AREngine_ARSession *session, AREngine_ARAnchor *anchor)

Instructs AR Engine to stop tracking an anchor and unbind it. However, this function does not release the anchor. You need to release the anchor by calling HMS_AREngine_ARAnchor_Release.

void HMS_AREngine_ARAnchor_Release (AREngine_ARAnchor *anchor)

Releases the memory used by a specific anchor object. Before releasing the memory, instruct AR Engine to stop tracking and unbind the anchor.

AREngine_ARStatus HMS_AREngine_ARTrackableList_Create (const AREngine_ARSession *session, AREngine_ARTrackableList **outTrackableList)

Creates a list of trackable objects.

void HMS_AREngine_ARTrackableList_Destroy (AREngine_ARTrackableList *trackableList)

Releases the list of trackable objects, along with all the anchor references it holds.

AREngine_ARStatus HMS_AREngine_ARTrackableList_GetSize (const AREngine_ARSession *session, const AREngine_ARTrackableList *trackableList, int32_t *outSize)

Obtains the number of trackable objects in the list.

AREngine_ARStatus HMS_AREngine_ARTrackableList_AcquireItem (const AREngine_ARSession *session, const AREngine_ARTrackableList *trackableList, int32_t index, AREngine_ARTrackable **outTrackable)

Obtains the object at a specific index from the trackable object list.

void HMS_AREngine_ARTrackable_Release (AREngine_ARTrackable *trackable)

Releases a trackable object.

AREngine_ARStatus HMS_AREngine_ARTrackable_GetType (const AREngine_ARSession *session, const AREngine_ARTrackable *trackable, AREngine_ARTrackableType *outTrackableType)

Obtains the type of a trackable object.

AREngine_ARStatus HMS_AREngine_ARTrackable_GetTrackingState (const AREngine_ARSession *session, const AREngine_ARTrackable *trackable, AREngine_ARTrackingState *outTrackingState)

Obtains the tracking status of the current trackable object.

AREngine_ARStatus HMS_AREngine_ARTrackable_AcquireNewAnchor (AREngine_ARSession *session, AREngine_ARTrackable *trackable, AREngine_ARPose *pose, AREngine_ARAnchor **outAnchor)

Creates an anchor object using the pose information of the trackable object. This anchor will be bound to the current trackable object.

AREngine_ARStatus HMS_AREngine_ARTrackable_GetAnchors (AREngine_ARSession *session, const AREngine_ARTrackable *trackable, AREngine_ARAnchorList *outAnchorList)

Obtains a list of anchor objects bound to the input trackable objects.

AREngine_ARStatus HMS_AREngine_ARPlane_AcquireSubsumedBy (const AREngine_ARSession *session, const AREngine_ARPlane *plane, AREngine_ARPlane **outSubsumedBy)

Obtains the parent plane of a plane (a parent plane is generated when a plane is merged with another one). If there is no parent plane, NULL is returned.

AREngine_ARStatus HMS_AREngine_ARPlane_GetType (const AREngine_ARSession *session, const AREngine_ARPlane *plane, AREngine_ARPlaneType *outPlaneType)

Obtains the plane type.

AREngine_ARStatus HMS_AREngine_ARPlane_GetCenterPose (const AREngine_ARSession *session, const AREngine_ARPlane *plane, AREngine_ARPose *outPose)

Obtains the pose information for the conversion from the local coordinate system of a plane to the world coordinate system.

AREngine_ARStatus HMS_AREngine_ARPlane_GetLabel (const AREngine_ARSession *session, const AREngine_ARPlane *plane, AREngine_ARSemanticPlaneLabel *label)

Obtains the semantic type of a plane, such as desktop and floor. When using this function, you need to call HMS_AREngine_ARConfig_SetSemanticMode to enable the semantic recognition mode.

AREngine_ARStatus HMS_AREngine_ARPlane_GetExtentX (const AREngine_ARSession *session, const AREngine_ARPlane *plane, float *outExtentX)

Obtains the length of the plane's bounding rectangle along the x-axis of the plane's local coordinate system, such as the width of the rectangle.

AREngine_ARStatus HMS_AREngine_ARPlane_GetExtentZ (const AREngine_ARSession *session, const AREngine_ARPlane *plane, float *outExtentZ)

Obtains the length of the plane's bounding rectangle along the z-axis of the plane's local coordinate system, such as the height of the rectangle.

AREngine_ARStatus HMS_AREngine_ARPlane_GetPolygonSize (const AREngine_ARSession *session, const AREngine_ARPlane *plane, int32_t *outPolygonSize)

Obtains the size of the 2D vertex array of the detected plane. This function is used together with HMS_AREngine_ARPlane_GetPolygon.

AREngine_ARStatus HMS_AREngine_ARPlane_GetPolygon (const AREngine_ARSession *session, const AREngine_ARPlane *plane, float *outPolygonXz, int32_t polygonSize)

Obtains the 2D vertex array of the detected plane, in the format of [x1, z1, x2, z2, ...].

AREngine_ARStatus HMS_AREngine_ARPlane_IsPoseInExtents (const AREngine_ARSession *session, const AREngine_ARPlane *plane, const AREngine_ARPose *pose, int32_t *outPoseInExtents)

Checks whether a pose is within the plane's bounding rectangle.

AREngine_ARStatus HMS_AREngine_ARPlane_IsPoseInPolygon (const AREngine_ARSession *session, const AREngine_ARPlane *plane, const AREngine_ARPose *pose, int32_t *outPoseInPolygon)

Checks whether a pose is within the plane's bounding polygon.

AREngine_ARStatus HMS_AREngine_ARPoint_GetOrientationMode (const AREngine_ARSession *session, const AREngine_ARPoint *point, AREngine_ARPointOrientationMode *outOrientationMode)

Obtains the orientation mode of an input point.

AREngine_ARStatus HMS_AREngine_ARPoint_GetPose (const AREngine_ARSession *session, const AREngine_ARPoint *point, AREngine_ARPose *outPose)

Obtains the pose information of an input point.

AREngine_ARStatus HMS_AREngine_ARHitResultList_Create (const AREngine_ARSession *session, AREngine_ARHitResultList **outHitResultList)

Creates a list of hit testing result objects.

void HMS_AREngine_ARHitResultList_Destroy (AREngine_ARHitResultList *hitResultList)

Releases the list of hit testing result objects, as well as all hit testing result objects in the list.

AREngine_ARStatus HMS_AREngine_ARHitResultList_GetSize (const AREngine_ARSession *session, const AREngine_ARHitResultList *hitResultList, int32_t *outSize)

Obtains the number of objects in the hit testing result object list.

AREngine_ARStatus HMS_AREngine_ARHitResultList_GetItem (const AREngine_ARSession *session, const AREngine_ARHitResultList *hitResultList, int32_t index, AREngine_ARHitResult *outHitResult)

Obtains the hit testing result object at a specific index from the hit testing result list.

AREngine_ARStatus HMS_AREngine_ARHitResult_Create (const AREngine_ARSession *session, AREngine_ARHitResult **outHitResult)

Creates an empty hit testing result object.

void HMS_AREngine_ARHitResult_Destroy (AREngine_ARHitResult *hitResult)

Releases the memory used by the hit testing result object.

AREngine_ARStatus HMS_AREngine_ARHitResult_GetDistance (const AREngine_ARSession *session, const AREngine_ARHitResult *hitResult, float *outDistance)

Obtains the distance from the camera to the hit location, in meters.

AREngine_ARStatus HMS_AREngine_ARHitResult_GetHitPose (const AREngine_ARSession *session, const AREngine_ARHitResult *hitResult, AREngine_ARPose *outPose)

Obtains the pose of an intersection. The pose's translation component corresponds to the intersection's coordinates in the world coordinate system, while its rotation component varies according to the type of the intersection (such as the intersection with a plane or a point cloud).

AREngine_ARStatus HMS_AREngine_ARHitResult_AcquireTrackable (const AREngine_ARSession *session, const AREngine_ARHitResult *hitResult, AREngine_ARTrackable **outTrackable)

Obtains the trackable object that is hit.

AREngine_ARStatus HMS_AREngine_ARHitResult_AcquireNewAnchor (AREngine_ARSession *session, AREngine_ARHitResult *hitResult, AREngine_ARAnchor **outAnchor)

Creates an anchor at the intersection.

AREngine_ARStatus HMS_AREngine_ARTarget_GetCenterPose (const AREngine_ARSession *session, const AREngine_ARTarget *target, AREngine_ARPose *outARPose)

Obtains the pose object for the conversion from the local coordinate system of the target semantic object to the world coordinate system.

AREngine_ARStatus HMS_AREngine_ARTarget_GetAxisAlignedBoundingBox(const AREngine_ARSession *session, const AREngine_ARTarget *target, float *outAabb, int32_t aabbSize)

Obtains the coordinates of the minimum bounding box of a semantic object, in the format of (xmin, ymin, zmin, xmax, ymax, zmax).

AREngine_ARStatus HMS_AREngine_ARTarget_GetRadius (const AREngine_ARSession *session, const AREngine_ARTarget *target, float *radius)

Obtains the sphere radius of a semantic object.

AREngine_ARStatus HMS_AREngine_ARTarget_GetShapeType (const AREngine_ARSession *session, const AREngine_ARTarget *target, AREngine_ARTargetShapeLabel *shape)

Obtains the shape type of a semantic object.

AREngine_ARStatus HMS_AREngine_ARAnchorList_Create (const AREngine_ARSession *session, AREngine_ARAnchorList **outAnchorList)

Creates a list of anchor objects.

void HMS_AREngine_ARAnchorList_Destroy (AREngine_ARAnchorList *anchorList)

Releases a list of anchor objects.

AREngine_ARStatus HMS_AREngine_ARAnchorList_GetSize (const AREngine_ARSession *session, const AREngine_ARAnchorList *anchorList, int32_t *outSize)

Obtains the number of anchors in the anchor object list.

AREngine_ARStatus HMS_AREngine_ARAnchorList_AcquireItem (const AREngine_ARSession *session, const AREngine_ARAnchorList *anchorList, int32_t index, AREngine_ARAnchor **outAnchor)

Obtains the anchor at a specific location from the anchor object list.

AREngine_ARStatus HMS_AREngine_ARCameraConfig_Create (const AREngine_ARSession *session, AREngine_ARCameraConfig **outCameraConfig)

Creates a camera configuration object.

void HMS_AREngine_ARCameraConfig_Destroy (AREngine_ARCameraConfig *cameraConfig)

Releases a camera configuration object.

AREngine_ARStatus HMS_AREngine_ARCameraConfig_GetImageDimensions (const AREngine_ARSession *session, const AREngine_ARCameraConfig *cameraConfig, int32_t *outWidth, int32_t *outHeight)

Obtains the size of the image sent by the camera to the CPU for processing from a camera configuration object.

AREngine_ARStatus HMS_AREngine_ARCameraConfig_GetTextureDimensions (const AREngine_ARSession *session, const AREngine_ARCameraConfig *cameraConfig, int32_t *outWidth, int32_t *outHeight)

Obtains the size of the image texture sent by the camera to the GPU for processing from a camera configuration object.

AREngine_ARStatus HMS_AREngine_ARImage_GetFormat (const AREngine_ARSession *session, const AREngine_ARImage *image, AREngine_ARImageFormat *outFormat)

Obtains the image format of the current frame.

AREngine_ARStatus HMS_AREngine_ARImage_GetWidth (const AREngine_ARSession *session, const AREngine_ARImage *image, int32_t *outWidth)

Obtains the image width of the current frame.

AREngine_ARStatus HMS_AREngine_ARImage_GetHeight (const AREngine_ARSession *session, const AREngine_ARImage *image, int32_t *outHeight)

Obtains the image height of the current frame.

AREngine_ARStatus HMS_AREngine_ARImage_GetPlaneCount (const AREngine_ARSession *session, const AREngine_ARImage *image, int32_t *outCount)

Obtains the number of planes in the current frame.

AREngine_ARStatus HMS_AREngine_ARImage_GetPlaneData (const AREngine_ARSession *session, const AREngine_ARImage *image, int32_t planeIndex, const uint8_t **outData, int32_t *outLength)

Obtains the plane data in the current frame.

AREngine_ARStatus HMS_AREngine_ARImage_GetPlanePixelStride (const AREngine_ARSession *session, const AREngine_ARImage *image, int32_t planeIndex, int32_t *outPixelStride)

Obtains the distance between the start points of two consecutive pixels in an image, in bytes. The pixel stride is always greater than 0.

AREngine_ARStatus HMS_AREngine_ARImage_GetPlaneRowStride (const AREngine_ARSession *session, const AREngine_ARImage *image, int32_t planeIndex, int32_t *outRowStride)

Obtains the number of bytes between the start positions of two consecutive pixel lines in an image. The line spacing is always greater than 0.

AREngine_ARStatus HMS_AREngine_ARImage_GetTimestamp (const AREngine_ARSession *session, const AREngine_ARImage *image, int64_t *outTimestamp)

Gets the timestamp of an image (in nanoseconds). Timestamps are usually monotonically increasing. The specific meaning and time base of the timestamp depend on the image source. Timestamps of images from different sources may have different time bases, so they should not be compared with each other.

void HMS_AREngine_ARImage_Release (AREngine_ARImage *image)

Releases the image object of the current frame, that is, the object created by HMS_AREngine_ARFrame_AcquireCameraImage.

AREngine_ARStatus HMS_AREngine_ARConfig_SetCameraPreviewMode (const AREngine_ARSession *session, AREngine_ARConfig *config, AREngine_ARPreviewMode mode)

Sets the preview mode.

AREngine_ARStatus HMS_AREngine_ARConfig_GetCameraPreviewMode (const AREngine_ARSession *session, AREngine_ARConfig *config, AREngine_ARPreviewMode *outMode)

Obtains the current preview mode.

Macro Description

[h2]ARENGINE_AABB_POINT_SIZE

const static int32_t ARENGINE_AABB_POINT_SIZE = 6

Description:

Size of the bounding box coordinate array.

Start version: 5.0.0(12)

[h2]ARENGINE_POSE_RAW_SIZE

const static int32_t ARENGINE_POSE_RAW_SIZE = 7

Description:

Size of the pose data array.

Start version: 5.0.0(12)

[h2]ARENGINE_VIEW_MATRIX_SIZE

const static int32_t ARENGINE_VIEW_MATRIX_SIZE = 16

Description:

Size of the transformation matrix array.

Start version: 5.0.0(12)

[h2]ARENGINE_DISTORTION_COUNT

const static int32_t ARENGINE_DISTORTION_COUNT = 5

Description:

Number of camera distortion parameters.

Start version: 5.0.0(12)

Type Description

[h2]AREngine_ARAnchor

typedef struct AREngine_ARAnchor AREngine_ARAnchor

Description:

Indicates an anchor object, which describes the spatial location associated with a trackable object.

Start version: 5.0.0(12)

[h2]AREngine_ARAnchorList

typedef struct AREngine_ARAnchorList AREngine_ARAnchorList

Description:

Indicates a list of anchor objects.

Start version: 5.0.0(12)

[h2]AREngine_ARCamera

typedef struct AREngine_ARCamera AREngine_ARCamera

Description:

Indicates the camera information for the current frame.

Start version: 5.0.0(12)

[h2]AREngine_ARCameraConfig

typedef struct AREngine_ARCameraConfig AREngine_ARCameraConfig

Description:

Provides camera configuration information, such as the image size to be processed by CPU, or the texture size to be processed by GPU.

Start version: 5.0.0(12)

[h2]AREngine_ARCameraIntrinsics

typedef struct AREngine_ARCameraIntrinsics AREngine_ARCameraIntrinsics

Description:

Indicates intrinsic camera parameters, including fx, fy, cx, cy, and camera distortion parameters.

Start version: 5.0.0(12)

[h2]AREngine_ARConfig

typedef struct AREngine_ARConfig AREngine_ARConfig

Description:

Configures AREngine_ARSession capabilities (which capabilities and modes to use).

Start version: 5.0.0(12)

[h2]AREngine_ARFrame

typedef struct AREngine_ARFrame AREngine_ARFrame

Description:

Indicates a frame of data processed by AR Engine.

Start version: 5.0.0(12)

[h2]AREngine_ARHitResult

typedef struct AREngine_ARHitResult AREngine_ARHitResult

Description:

Indicates the hit testing result object, which describes the hit testing result of a single trackable object.

Start version: 5.0.0(12)

[h2]AREngine_ARHitResultList

typedef struct AREngine_ARHitResultList AREngine_ARHitResultList

Description:

Indicates the list of hit testing results.

Start version: 5.0.0(12)

[h2]AREngine_ARImage

typedef struct AREngine_ARImage AREngine_ARImage

Description:

Indicates the camera video stream frame object.

Start version: 5.0.0(12)

[h2]AREngine_ARPlane

typedef struct AREngine_ARPlane AREngine_ARPlane

Description:

Indicates a plane object, which describes the detected trackable plane information.

Start version: 5.0.0(12)

[h2]AREngine_ARPoint

typedef struct AREngine_ARPoint AREngine_ARPoint

Description:

Indicates a point object, which describes the detected trackable point data.

Start version: 5.0.0(12)

[h2]AREngine_ARPointCloud

typedef struct AREngine_ARPointCloud AREngine_ARPointCloud

Description:

Indicates a collection of trackable 3D point clouds.

Start version: 5.0.0(12)

[h2]AREngine_ARPose

typedef struct AREngine_ARPose AREngine_ARPose

Description:

Indicates the pose (translation + rotation), representing an immutable rigid transformation from one coordinate system to another.

Start version: 5.0.0(12)

[h2]AREngine_ARSession

typedef struct AREngine_ARSession AREngine_ARSession

Description:

Manages the system status of AR Engine.

Start version: 5.0.0(12)

[h2]AREngine_ARTarget

typedef struct AREngine_ARTarget AREngine_ARTarget

Description:

Indicates an object, which describes a trackable semantic object, such as a semantic plane.

Start version: 5.0.0(12)

[h2]AREngine_ARTrackable

typedef struct AREngine_ARTrackable AREngine_ARTrackable

Description:

Indicates a trackable object, such as a point or plane.

After obtaining the object, if you need to obtain the center point position of the plane (by calling HMS_AREngine_ARPlane_GetCenterPose), obtain the pose information of the point (by calling HMS_AREngine_ARPoint_GetPose), or perform any other operations on this object, convert this object into another one (such as AREngine_ARPlane or AREngine_ARPoint) according to the type of this trackable object (obtained through HMS_AREngine_ARTrackable_GetType), by referring to AREngine_ARPlane *arPlane = reinterpret_cast<AREngine_ARPlane *>(trackable).

Start version: 5.0.0(12)

[h2]AREngine_ARTrackableList

typedef struct AREngine_ARTrackableList AREngine_ARTrackableList

Description:

Indicates a list of trackable objects.

Start version: 5.0.0(12)

Enum Description

[h2]AREngine_ARFocusMode

enum AREngine_ARFocusMode

Description:

Focus mode.

Start version: 5.0.0(12)

Enumerated Value

Description

ARENGINE_FOCUS_MODE_FIXED

Focus fixed to infinity.

ARENGINE_FOCUS_MODE_AUTO

Auto focus.

[h2]AREngine_ARImageFormat

enum AREngine_ARImageFormat

Description:

Image format.

Start version: 5.0.0(12)

Enumerated Value

Description

ARENGINE_IMAGE_UNKNOWN

Unknown image format.

ARENGINE_IMAGE_YUV_420_888

The ARENGINE_IMAGE_YUV_420_888 format consists of three data buffers, with the Y plane indexed as 0, the U plane indexed as 1, and the V plane indexed as 2. The Y plane does not intersect with the U/V plane. That is, the pixel stride of the Y plane is always 1. The U and V planes share the same row stride and pixel stride.

[h2]AREngine_ARPlaneFindingMode

enum AREngine_ARPlaneFindingMode

Description:

Plane finding mode.

Start version: 5.0.0(12)

Enumerated Value

Description

ARENGINE_PLANE_FINDING_MODE_DISABLED

Plane finding is disabled.

ARENGINE_PLANE_FINDING_MODE_HORIZONTAL

Only horizontal planes are detected.

ARENGINE_PLANE_FINDING_MODE_VERTICAL

Only vertical planes are detected.

ARENGINE_PLANE_FINDING_MODE_HORIZONTAL_AND_VERTICAL

Both horizontal and vertical planes are detected.

[h2]AREngine_ARPlaneType

enum AREngine_ARPlaneType

Description:

Plane type.

Start version: 5.0.0(12)

Enumerated Value

Description

ARENGINE_PLANE_FACING_HORIZONTAL_UPWARD

A horizontal plane facing up (such as the ground and desk platform).

ARENGINE_PLANE_FACING_HORIZONTAL_DOWNWARD

A horizontal plane facing down (such as the ceiling).

ARENGINE_PLANE_FACING_VERTICAL

A vertical plane.

ARENGINE_PLANE_FACING_INVALID

Unsupported type.

[h2]AREngine_ARPointOrientationMode

enum AREngine_ARPointOrientationMode

Description:

Orientation mode.

Start version: 5.0.0(12)

Enumerated Value

Description

ARENGINE_POINT_ORIENTATION_INITIALIZED_TO_IDENTITY

The orientation is consistent with that of the world coordinate system, but with minor adjustments.

ARENGINE_POINT_ORIENTATION_ESTIMATED_SURFACE_NORMAL

The orientation is determined by the estimated plane's normal vector.

[h2]AREngine_ARPoseType

enum AREngine_ARPoseType

Description:

Pose type.

Start version: 5.0.0(12)

Enumerated Value

Description

ARENGINE_POSE_TYPE_IDENTITY

Default pose.

ARENGINE_POSE_TYPE_ROTATE_90

Pose that performs a 90-degree rotation.

ARENGINE_POSE_TYPE_ROTATE_180

Pose that performs a 180-degree rotation.

ARENGINE_POSE_TYPE_ROTATE_270

Pose that performs a 270-degree rotation.

[h2]AREngine_ARPowerMode

enum AREngine_ARPowerMode

Description:

Power consumption mode.

Start version: 5.0.0(12)

Enumerated Value

Description

ARENGINE_POWER_MODE_NORMAL

Normal mode.

ARENGINE_POWER_MODE_POWER_SAVING

Power saving mode.

ARENGINE_POWER_MODE_PERFORMANCE_FIRST

Performance-preferred mode.

ARENGINE_POWER_MODE_BOOST

Outputs the device pose information only. The power consumption in this mode is lower than that in ARENGINE_POWER_MODE_NORMAL mode. In this mode, plane-related settings, such as HMS_AREngine_ARConfig_SetPlaneFindingMode, do not take effect.

ARENGINE_POWER_MODE_ULTRA_POWER_SAVING

Ultra power saving mode.

[h2]AREngine_ARPreviewMode

enum AREngine_ARPreviewMode

Description:

Preview mode.

Start version: 5.0.0(12)

Enumerated Value

Description

ARENGINE_PREVIEW_MODE_ENABLED

Enables camera preview.

ARENGINE_PREVIEW_MODE_DISABLED

Disables camera preview, for example, when in VR mode and the preview stream is not required. In this mode, OpenGL textures set through HMS_AREngine_ARSession_SetCameraGLTexture won't be updated.

[h2]AREngine_ARSemanticMode

enum AREngine_ARSemanticMode

Description:

Semantic mode.

Start version: 5.0.0(12)

Enumerated Value

Description

ARENGINE_SEMANTIC_MODE_NONE

Semantics not used.

ARENGINE_SEMANTIC_MODE_PLANE

Uses plane semantics.

ARENGINE_SEMANTIC_MODE_TARGET

Uses object semantics.

[h2]AREngine_ARSemanticPlaneLabel

enum AREngine_ARSemanticPlaneLabel

Description:

Semantic type of the current plane.

Start version: 5.0.0(12)

Enumerated Value

Description

ARENGINE_PLANE_UNKNOWN

Unknown type.

ARENGINE_PLANE_WALL

Wall.

ARENGINE_PLANE_FLOOR

Floor.

ARENGINE_PLANE_SEAT

Seat.

ARENGINE_PLANE_TABLE

Table.

ARENGINE_PLANE_CEILING

Ceiling.

ARENGINE_PLANE_DOOR

Door.

ARENGINE_PLANE_WINDOW

Window.

ARENGINE_PLANE_BED

Bed.

[h2]AREngine_ARStatus

enum AREngine_ARStatus

Description:

Error code returned by an API.

Start version: 5.0.0(12)

Enumerated Value

Description

ARENGINE_SUCCESS

Success.

ARENGINE_ERROR_PERMISSION_NOT_GRANTED

Permissions not granted, such as the camera permission.

ARENGINE_ERROR_INVALID_ARGUMENT

Invalid parameters, for example, the input parameter is empty or invalid.

ARENGINE_ERROR_DEVICE_NOT_SUPPORTED

Device not compatible.

ARENGINE_ERROR_FATAL

Failure.

ARENGINE_ERROR_SESSION_PAUSED

Session paused.

ARENGINE_ERROR_SESSION_NOT_PAUSED

Session not paused.

ARENGINE_ERROR_NOT_TRACKING

Not tracking.

ARENGINE_ERROR_TEXTURE_NOT_SET

Texture not set.

ARENGINE_ERROR_MISSING_GL_CONTEXT

GL context missing.

ARENGINE_ERROR_UNSUPPORTED_CONFIGURATION

Configuration not supported.

ARENGINE_ERROR_RESOURCE_EXHAUSTED

Resource exhausted.

ARENGINE_ERROR_NOT_AVAILABLE

Service unavailable.

ARENGINE_ERROR_CAMERA_NOT_AVAILABLE

Camera unavailable.

[h2]AREngine_ARTargetShapeLabel

enum AREngine_ARTargetShapeLabel

Description:

Shape of the recognized object.

Start version: 5.0.0(12)

Enumerated Value

Description

ARENGINE_TARGET_SHAPE_UNKNOWN

Unknown shape.

ARENGINE_TARGET_SHAPE_CUBE

Cube. The bounding box of regular objects can be recognized as a cube.

ARENGINE_TARGET_SHAPE_CIRCLE

Circle.

ARENGINE_TARGET_SHAPE_RECTANGLE

Rectangle.

[h2]AREngine_ARTrackableType

enum AREngine_ARTrackableType

Description:

Type of a trackable object, such as a plane or a point.

Start version: 5.0.0(12)

Enumerated Value

Description

ARENGINE_TRACKABLE_BASE

Basic trackable object type, which can be used as the default AREngine_ARTrackableType.

ARENGINE_TRACKABLE_PLANE

Trackable object of the plane type.

ARENGINE_TRACKABLE_POINT

Trackable object of the point type.

ARENGINE_TRACKABLE_TARGET

Trackable object of the object type.

ARENGINE_TRACKABLE_INVALID

Invalid trackable object type.

[h2]AREngine_ARTrackingState

enum AREngine_ARTrackingState

Description:

Tracking status of the trackable object.

Start version: 5.0.0(12)

Enumerated Value

Description

ARENGINE_TRACKING_STATE_TRACKING

Tracking status: being tracked.

ARENGINE_TRACKING_STATE_PAUSED

Tracking status: paused.

ARENGINE_TRACKING_STATE_STOPPED

Tracking status: stopped.

[h2]AREngine_ARTrackingStateReason

enum AREngine_ARTrackingStateReason

Description:

Possible causes of tracking failures.

Start version: 5.0.0(12)

Enumerated Value

Description

ARENGINE_TRACKING_STATE_REASON_NONE

Tracking failure cause: none.

ARENGINE_TRACKING_STATE_REASON_EXCESSIVE_MOTION

Tracking failure cause: targets moving fast.

ARENGINE_TRACKING_STATE_REASON_INSUFFICIENT_FEATURES

Tracking failure cause: insufficient visual features (such as weak texture).

[h2]AREngine_ARType

enum AREngine_ARType

Description:

AR capability type.

Start version: 5.0.0(12)

Enumerated Value

Description

ARENGINE_TYPE_WORLD

Environment tracking capability.

[h2]AREngine_ARUpdateMode

enum AREngine_ARUpdateMode

Description:

Data update mode specified by HMS_AREngine_ARSession_Update.

Start version: 5.0.0(12)

Enumerated Value

Description

ARENGINE_UPDATE_MODE_BLOCKING

HMS_AREngine_ARSession_Update returns results only when new frames are available.

ARENGINE_UPDATE_MODE_LATEST

HMS_AREngine_ARSession_Update returns results immediately (returns the previous frame when no new frame is available).

Function Description

[h2]HMS_AREngine_ARAnchor_Detach()

AREngine_ARStatus HMS_AREngine_ARAnchor_Detach(AREngine_ARSession *session, AREngine_ARAnchor *anchor)

Description:

Instructs AR Engine to stop tracking and unbinds an anchor. However, this function does not release the anchor. You need to release the anchor by calling HMS_AREngine_ARAnchor_Release.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

anchor

Anchor object to be unbound. For details, please refer to AREngine_ARAnchor.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARAnchor_GetPose()

AREngine_ARStatus HMS_AREngine_ARAnchor_GetPose(const AREngine_ARSession *session, const AREngine_ARAnchor *anchor, AREngine_ARPose *outPose)

Description:

Obtains the pose of a specific anchor in the world coordinate system.

Each time HMS_AREngine_ARSession_Update is called, the pose information returned by HMS_AREngine_ARAnchor_GetPose may change.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

anchor

Anchor, whose pose needs to be obtained. For details, please refer to AREngine_ARAnchor.

outPose

Pose object of the anchor. For details, please refer to AREngine_ARPose.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARAnchor_GetTrackingState()

AREngine_ARStatus HMS_AREngine_ARAnchor_GetTrackingState(const AREngine_ARSession *session, const AREngine_ARAnchor *anchor, AREngine_ARTrackingState *outTrackingState)

Description:

Obtains the tracking status of the pose of a specific anchor.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

anchor

Anchor, the tracking status of whose pose needs to be obtained. For details, please refer to AREngine_ARAnchor.

outTrackingState

Tracking status of the anchor's current pose. For details, please refer to AREngine_ARTrackingState.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARAnchor_Release()

void HMS_AREngine_ARAnchor_Release(AREngine_ARAnchor *anchor)

Description:

Releases the memory used by a specific anchor object. Before releasing the memory, instruct AR Engine to stop tracking and unbind the anchor.

Start version: 5.0.0(12)

Parameters:

Name

Description

anchor

Anchor object to be released. For details, please refer to AREngine_ARAnchor.

[h2]HMS_AREngine_ARAnchorList_AcquireItem()

AREngine_ARStatus HMS_AREngine_ARAnchorList_AcquireItem(const AREngine_ARSession *session, const AREngine_ARAnchorList *anchorList, int32_t index, AREngine_ARAnchor **outAnchor)

Description:

Obtains the anchor at a specific location from the anchor object list.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

anchorList

List of anchor objects. For details, please refer to AREngine_ARAnchorList.

index

Index of the anchor to be obtained in the anchor object list.

outAnchor

Anchor information to be returned. For details, please refer to AREngine_ARAnchor.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARAnchorList_Create()

AREngine_ARStatus HMS_AREngine_ARAnchorList_Create(const AREngine_ARSession *session, AREngine_ARAnchorList **outAnchorList)

Description:

Creates a list of anchor objects.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

outAnchorList

Reference to the anchor object list to be created. For details, please refer to AREngine_ARAnchorList.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARAnchorList_Destroy()

void HMS_AREngine_ARAnchorList_Destroy(AREngine_ARAnchorList *anchorList)

Description:

Releases a list of anchor objects.

Start version: 5.0.0(12)

Parameters:

Name

Description

anchorList

To-be-released list of anchor objects. For details, please refer to AREngine_ARAnchorList.

[h2]HMS_AREngine_ARAnchorList_GetSize()

AREngine_ARStatus HMS_AREngine_ARAnchorList_GetSize(const AREngine_ARSession *session, const AREngine_ARAnchorList *anchorList, int32_t *outSize)

Description:

Obtains the number of anchors in the anchor object list.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

anchorList

List of anchor objects. For details, please refer to AREngine_ARAnchorList.

outSize

Number of anchors in the anchor object list.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARCamera_GetDisplayOrientedPose()

AREngine_ARStatus HMS_AREngine_ARCamera_GetDisplayOrientedPose(const AREngine_ARSession *session, const AREngine_ARCamera *camera, AREngine_ARPose *outPose)

Description:

Sets outPose to the pose of the virtual camera (facing the display) in the world space, in order to render AR content into the latest frame. The pose is that of the OpenGL camera, where the positive direction of the x-axis is to the right, the positive direction of the y-axis is upwards, and the negative direction of the z-axis is the look-at direction of the camera. The camera position refers to the physical camera position, and the orientation of the camera's x-axis and y-axis is affected by the screen orientation (taking display rotation into account).

The pose information can be used only when ARENGINE_TRACKING_STATE_TRACKING is returned by HMS_AREngine_ARCamera_GetTrackingState.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

camera

Camera corresponding to the session. For details, please refer to AREngine_ARCamera.

outPose

Pose of the virtual camera in the world space. For details, please refer to AREngine_ARPose.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARCamera_GetImageIntrinsics()

AREngine_ARStatus HMS_AREngine_ARCamera_GetImageIntrinsics(const AREngine_ARSession *session, const AREngine_ARCamera *camera, AREngine_ARCameraIntrinsics *outIntrinsics)

Description:

Obtains the object of the offline intrinsic camera parameters. This object can be used obtain the camera's focal length, image size, principal point, and distortion parameters.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

camera

Camera corresponding to the session. For details, please refer to AREngine_ARCamera.

outIntrinsics

Object of the intrinsic camera parameters. For details, please refer to AREngine_ARCameraIntrinsics.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARCamera_GetPose()

AREngine_ARStatus HMS_AREngine_ARCamera_GetPose(const AREngine_ARSession *session, const AREngine_ARCamera *camera, AREngine_ARPose *outPose)

Description:

Sets outPose to the pose of the physical camera in the world space in the latest frame. The pose is that of the OpenGL camera, where the positive direction of the x-axis is to the right, the positive direction of the y-axis is upwards, and the negative direction of the z-axis is the look-at direction of the camera. The camera position refers to the physical camera position, and the orientation of the camera's x-axis and y-axis is not affected by the screen orientation (taking display rotation into account). The pose information can be used only when ARENGINE_TRACKING_STATE_TRACKING is returned by HMS_AREngine_ARCamera_GetTrackingState.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

camera

Camera corresponding to the session. For details, please refer to AREngine_ARCamera.

outPose

Pose of the physical camera in the world space. For details, please refer to AREngine_ARPose.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARCamera_GetProjectionMatrix()

AREngine_ARStatus HMS_AREngine_ARCamera_GetProjectionMatrix(const AREngine_ARSession *session, const AREngine_ARCamera *camera, AREngine_ClipPlaneDistance clipPlaneDistance, float *outDestColMajor4x4, int32_t destColMajor4x4Num)

Description:

Obtains the projection matrix used for rendering virtual content on top of the camera image. This matrix can be used for converting from the camera coordinate system to the clip coordinate system.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

camera

Camera corresponding to the session. For details, please refer to AREngine_ARCamera.

clipPlaneDistance

Distance to the OpenGL clipping plane. For details, please refer to AREngine_ClipPlaneDistance.

outDestColMajor4x4

Array consisting of 16 floating point numbers, indicating a column-major uniform transformation matrix in OpenGL.

destColMajor4x4Num

Array size: ARENGINE_VIEW_MATRIX_SIZE.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARCamera_GetTrackingState()

AREngine_ARStatus HMS_AREngine_ARCamera_GetTrackingState(const AREngine_ARSession *session, const AREngine_ARCamera *camera, AREngine_ARTrackingState *outTrackingState)

Description:

Obtains the current tracking status of the camera. The camera pose is available only when the tracking status is ARENGINE_TRACKING_STATE_TRACKING.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

camera

Camera corresponding to the session. For details, please refer to AREngine_ARCamera.

outTrackingState

current tracking status of the camera. For details, please refer to AREngine_ARTrackingState.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARCamera_GetTrackingStateReason()

AREngine_ARStatus HMS_AREngine_ARCamera_GetTrackingStateReason(const AREngine_ARSession *session, const AREngine_ARCamera *camera, AREngine_ARTrackingStateReason *outTrackingStateReason)

Description:

Obtains the reason why the current tracking status of the camera is ARENGINE_TRACKING_STATE_PAUSED. When the current tracking status of the camera is ARENGINE_TRACKING_STATE_TRACKING, the function returns ARENGINE_TRACKING_STATE_REASON_NONE.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

camera

Camera corresponding to the session. For details, please refer to AREngine_ARCamera.

outTrackingStateReason

Cause of the tracking failure. For details, please refer to AREngine_ARTrackingStateReason.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARCamera_GetViewMatrix()

AREngine_ARStatus HMS_AREngine_ARCamera_GetViewMatrix(const AREngine_ARSession *session, const AREngine_ARCamera *camera, float *outColMajor4x4, int32_t colMajor4x4Num)

Description:

Obtains the view matrix of the camera in the latest frame.

This matrix performs the inverse transformation of the pose obtained through HMS_AREngine_ARCamera_GetDisplayOrientedPose. That is, it transforms the world coordinate system to the camera coordinate system.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

camera

Camera corresponding to the session. For details, please refer to AREngine_ARCamera.

outColMajor4x4

Array consisting of 16 floating point numbers, indicating a column-major uniform transformation matrix in OpenGL.

colMajor4x4Num

Array size. The array size must be greater than or equal to ARENGINE_VIEW_MATRIX_SIZE.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARCamera_Release()

void HMS_AREngine_ARCamera_Release(AREngine_ARCamera *camera)

Description:

Releases the reference to the camera. You need to call HMS_AREngine_ARCamera_Release if you have called HMS_AREngine_ARFrame_AcquireCamera. Calling this method before HMS_AREngine_ARFrame_AcquireCamera is called does not take effect.

Start version: 5.0.0(12)

Parameters:

Name

Description

camera

Camera reference to be released. For details, please refer to AREngine_ARCamera.

[h2]HMS_AREngine_ARCameraConfig_Create()

AREngine_ARStatus HMS_AREngine_ARCameraConfig_Create(const AREngine_ARSession *session, AREngine_ARCameraConfig **outCameraConfig)

Description:

Creates a camera configuration object.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

outCameraConfig

Pointer to the newly allocated address of the camera configuration object. For details, please refer to AREngine_ARCameraConfig.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARCameraConfig_Destroy()

void HMS_AREngine_ARCameraConfig_Destroy(AREngine_ARCameraConfig *cameraConfig)

Description:

Releases a camera configuration object.

Start version: 5.0.0(12)

Parameters:

Name

Description

cameraConfig

Pointer to the camera configuration object. For details, please refer to AREngine_ARCameraConfig.

[h2]HMS_AREngine_ARCameraConfig_GetImageDimensions()

AREngine_ARStatus HMS_AREngine_ARCameraConfig_GetImageDimensions(const AREngine_ARSession *session, const AREngine_ARCameraConfig *cameraConfig, int32_t *outWidth, int32_t *outHeight)

Description:

Obtains the size of the image sent by the camera to the CPU for processing from a camera configuration object.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

cameraConfig

Pointer to the camera configuration object. For details, please refer to AREngine_ARCameraConfig.

outWidth

Image width, in pixels.

outHeight

Image height, in pixels.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARCameraConfig_GetTextureDimensions()

AREngine_ARStatus HMS_AREngine_ARCameraConfig_GetTextureDimensions(const AREngine_ARSession *session, const AREngine_ARCameraConfig *cameraConfig, int32_t *outWidth, int32_t *outHeight)

Description:

Obtains the size of the image texture sent by the camera to the GPU for processing from a camera configuration object.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

cameraConfig

Pointer to the camera configuration object. For details, please refer to AREngine_ARCameraConfig.

outWidth

Image texture width, in pixels.

outHeight

Image texture height, in pixels.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARCameraIntrinsics_Create()

AREngine_ARStatus HMS_AREngine_ARCameraIntrinsics_Create(const AREngine_ARSession *session, AREngine_ARCameraIntrinsics **outIntrinsics)

Description:

Creates an object of the intrinsic camera parameters.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

outIntrinsics

Pointer to the newly allocated address of the object of intrinsic camera parameters. For details, please refer to AREngine_ARCameraIntrinsics.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARCameraIntrinsics_Destroy()

void HMS_AREngine_ARCameraIntrinsics_Destroy(AREngine_ARCameraIntrinsics *intrinsics)

Description:

Releases a specific object of intrinsic camera parameters.

Start version: 5.0.0(12)

Parameters:

Name

Description

intrinsics

To-be-released object of intrinsic camera parameters. For details, please refer to AREngine_ARCameraIntrinsics.

[h2]HMS_AREngine_ARCameraIntrinsics_GetDistortion()

AREngine_ARStatus HMS_AREngine_ARCameraIntrinsics_GetDistortion(const AREngine_ARSession *session, const AREngine_ARCameraIntrinsics *intrinsics, float *outDistortion, int32_t distortionNum)

Description:

Obtains a camera's distortion coefficients, which include 5 components: outDistortion[0] to outDistortion [2] represent k1, k2, and k3 (radial distortion coefficients), and outDistortion [3] to outDistortion [4] are the tangential distortion coefficients.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

intrinsics

Pointer to the object of intrinsic camera parameters. For details, please refer to AREngine_ARCameraIntrinsics.

outDistortion

Array of camera distortion parameters.

distortionNum

Number of camera distortion parameters. For details, please refer to ARENGINE_DISTORTION_COUNT.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARCameraIntrinsics_GetFocalLength()

AREngine_ARStatus HMS_AREngine_ARCameraIntrinsics_GetFocalLength(const AREngine_ARSession *session, const AREngine_ARCameraIntrinsics *intrinsics, float *outFocalX, float *outFocalY)

Description:

Obtains the focal length of a camera in pixels.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

intrinsics

Pointer to the object of intrinsic camera parameters. For details, please refer to AREngine_ARCameraIntrinsics.

outFocalX

Pixel focal length in the x(u) direction of the intrinsic camera parameter matrix.

outFocalY

Pixel focal length in the y(v) direction of the intrinsic camera parameter matrix.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARCameraIntrinsics_GetImageDimensions()

AREngine_ARStatus HMS_AREngine_ARCameraIntrinsics_GetImageDimensions(const AREngine_ARSession *session, const AREngine_ARCameraIntrinsics *intrinsics, int32_t *outWidth, int32_t *outHeight)

Description:

Obtains the camera image size, including the width and height (in pixels).

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

intrinsics

Pointer to the object of intrinsic camera parameters. For details, please refer to AREngine_ARCameraIntrinsics.

outWidth

Camera image width, in pixels.

outHeight

Camera image height, in pixels.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARCameraIntrinsics_GetPrincipalPoint()

AREngine_ARStatus HMS_AREngine_ARCameraIntrinsics_GetPrincipalPoint(const AREngine_ARSession *session, const AREngine_ARCameraIntrinsics *intrinsics, float *outPrincipalX, float *outPrincipalY)

Description:

Obtains the principal point of a camera, with the location of the point expressed in pixels.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

intrinsics

Pointer to the object of intrinsic camera parameters. For details, please refer to AREngine_ARCameraIntrinsics.

outPrincipalX

x-axis coordinate of the camera's principal point.

outPrincipalY

y-axis coordinate of the camera's principal point.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARConfig_Create()

AREngine_ARStatus HMS_AREngine_ARConfig_Create(const AREngine_ARSession *session, AREngine_ARConfig **outConfig)

Description:

Creates a configuration object with a proper default configuration.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

outConfig

Pointer to the newly allocated address of the configuration object. For details, please refer to AREngine_ARConfig.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARConfig_Destroy()

void HMS_AREngine_ARConfig_Destroy(AREngine_ARConfig *config)

Description:

Releases the memory used by a specific configuration object.

Start version: 5.0.0(12)

Parameters:

Name

Description

config

To-be-released configuration object. For details, please refer to AREngine_ARConfig.

[h2]HMS_AREngine_ARConfig_GetARType()

AREngine_ARStatus HMS_AREngine_ARConfig_GetARType(const AREngine_ARSession *session, const AREngine_ARConfig *config, AREngine_ARType *type)

Description:

Obtains the AR capability type in use.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

config

Points to the configuration object with the target configuration information. For details, please refer to AREngine_ARConfig.

type

Type of the AR Engine capability in use. For details, please refer to AREngine_ARType.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARConfig_GetCameraPreviewMode()

AREngine_ARStatus HMS_AREngine_ARConfig_GetCameraPreviewMode(const AREngine_ARSession *session, AREngine_ARConfig *config, AREngine_ARPreviewMode *outMode)

Description:

Obtains the current preview mode.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

config

Points to the configuration object with the target configuration information. For details, please refer to AREngine_ARConfig.

outMode

Camera preview mode. For details, please refer to AREngine_ARPreviewMode.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARConfig_GetFocusMode()

AREngine_ARStatus HMS_AREngine_ARConfig_GetFocusMode(const AREngine_ARSession *session, const AREngine_ARConfig *config, AREngine_ARFocusMode *focusMode)

Description:

Obtains the current focus mode.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

config

Points to the configuration object with the target configuration information. For details, please refer to AREngine_ARConfig.

focusMode

Focus mode. For details, please refer to AREngine_ARFocusMode.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARConfig_GetMaxMapSize()

AREngine_ARStatus HMS_AREngine_ARConfig_GetMaxMapSize(const AREngine_ARSession *session, const AREngine_ARConfig *config, uint64_t *maxMapSize)

Description:

Obtains the maximum memory size for storing map data.

You can call this API to obtain the maximum memory size for storing map data after HMS_AREngine_ARSession_Configure is executed.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

config

Points to the configuration object with the target configuration information. For details, please refer to AREngine_ARConfig.

maxMapSize

Maximum memory size for storing map data, in MB.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARConfig_GetPlaneFindingMode()

AREngine_ARStatus HMS_AREngine_ARConfig_GetPlaneFindingMode(const AREngine_ARSession *session, const AREngine_ARConfig *config, AREngine_ARPlaneFindingMode *planeFindingMode)

Description:

Obtains the current plane finding mode.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

config

Points to the configuration object with the target configuration information. For details, please refer to AREngine_ARConfig.

planeFindingMode

Plane finding mode. For details, please refer to AREngine_ARPlaneFindingMode.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARConfig_GetPowerMode()

AREngine_ARStatus HMS_AREngine_ARConfig_GetPowerMode(const AREngine_ARSession *session, const AREngine_ARConfig *config, AREngine_ARPowerMode *powerMode)

Description:

Obtains the current power consumption mode.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

config

Points to the configuration object with the target configuration information. For details, please refer to AREngine_ARConfig.

powerMode

Power consumption mode. For details, please refer to AREngine_ARPowerMode.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARConfig_GetSemanticMode()

AREngine_ARStatus HMS_AREngine_ARConfig_GetSemanticMode(const AREngine_ARSession *session, const AREngine_ARConfig *config, AREngine_ARSemanticMode *mode)

Description:

Obtains the current semantic recognition mode. This function is valid after HMS_AREngine_ARConfig_SetSemanticMode has been called.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

config

Points to the configuration object with the target configuration information. For details, please refer to AREngine_ARConfig.

mode

Semantic mode. For details, please refer to AREngine_ARSemanticMode.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARConfig_GetUpdateMode()

AREngine_ARStatus HMS_AREngine_ARConfig_GetUpdateMode(const AREngine_ARSession *session, const AREngine_ARConfig *config, AREngine_ARUpdateMode *updateMode)

Description:

Obtains the current preview update mode.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

config

Points to the configuration object with the target configuration information. For details, please refer to AREngine_ARConfig.

updateMode

Preview update mode. For details, please refer to AREngine_ARUpdateMode.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARConfig_SetARType()

AREngine_ARStatus HMS_AREngine_ARConfig_SetARType(const AREngine_ARSession *session, AREngine_ARConfig *config, AREngine_ARType type)

Description:

Sets the AR capability type to use.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

config

Points to the configuration object with the target configuration information. For details, please refer to AREngine_ARConfig.

type

Type of capabilities supported by AR Engine. For details, please refer to AREngine_ARType.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARConfig_SetCameraPreviewMode()

AREngine_ARStatus HMS_AREngine_ARConfig_SetCameraPreviewMode(const AREngine_ARSession *session, AREngine_ARConfig *config, AREngine_ARPreviewMode mode)

Description:

Sets the preview mode.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

config

Points to the configuration object with the target configuration information. For details, please refer to AREngine_ARConfig.

mode

Camera preview mode. For details, please refer to AREngine_ARPreviewMode.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARConfig_SetFocusMode()

AREngine_ARStatus HMS_AREngine_ARConfig_SetFocusMode(const AREngine_ARSession *session, AREngine_ARConfig *config, AREngine_ARFocusMode focusMode)

Description:

Sets the focus mode.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

config

Points to the configuration object with the target configuration information. For details, please refer to AREngine_ARConfig.

focusMode

Focus mode. For details, please refer to AREngine_ARFocusMode.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARConfig_SetMaxMapSize()

AREngine_ARStatus HMS_AREngine_ARConfig_SetMaxMapSize(const AREngine_ARSession *session, AREngine_ARConfig *config, uint64_t maxMapSize)

Description:

Sets the maximum memory size for storing map data.

If the value you set is indicated as invalid, a valid size closest to the value you set will take effect. The default value of the maximum memory size is 800 MB.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

config

Points to the configuration object with the target configuration information. For details, please refer to AREngine_ARConfig.

maxMapSize

Maximum memory size for storing map data, in MB. The value ranges from 100 MB to 16 GB. You are advised to set the memory size according to the device's memory capacity. Exceeding the hardware limits may result in unexpected errors.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARConfig_SetPlaneFindingMode()

AREngine_ARStatus HMS_AREngine_ARConfig_SetPlaneFindingMode(const AREngine_ARSession *session, AREngine_ARConfig *config, AREngine_ARPlaneFindingMode planeFindingMode)

Description:

Sets the plane finding mode.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

config

Points to the configuration object with the target configuration information. For details, please refer to AREngine_ARConfig.

planeFindingMode

Plane finding mode. For details, please refer to AREngine_ARPlaneFindingMode.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARConfig_SetPowerMode()

AREngine_ARStatus HMS_AREngine_ARConfig_SetPowerMode(const AREngine_ARSession *session, AREngine_ARConfig *config, AREngine_ARPowerMode powerMode)

Description:

Sets the power consumption mode.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

config

Points to the configuration object with the target configuration information. For details, please refer to AREngine_ARConfig.

powerMode

Power consumption mode. For details, please refer to AREngine_ARPowerMode.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARConfig_SetPreviewSize()

AREngine_ARStatus HMS_AREngine_ARConfig_SetPreviewSize(const AREngine_ARSession *session, AREngine_ARConfig *config, uint32_t width, uint32_t height)

Description:

Sets the preview image size.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

config

Points to the configuration object with the target configuration information. For details, please refer to AREngine_ARConfig.

width

Width of the preview image, in pixels. You can check the value by calling OH_CameraManager_GetSupportedCameraOutputCapability.

height

Height of the preview image, in pixels. You can check the value by calling OH_CameraManager_GetSupportedCameraOutputCapability.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARConfig_SetSemanticMode()

AREngine_ARStatus HMS_AREngine_ARConfig_SetSemanticMode(const AREngine_ARSession *session, AREngine_ARConfig *config, AREngine_ARSemanticMode mode)

Description:

Sets the semantic recognition mode.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

config

Points to the configuration object with the target configuration information. For details, please refer to AREngine_ARConfig.

mode

Semantic mode. For details, please refer to AREngine_ARSemanticMode.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARConfig_SetUpdateMode()

AREngine_ARStatus HMS_AREngine_ARConfig_SetUpdateMode(const AREngine_ARSession *session, AREngine_ARConfig *config, AREngine_ARUpdateMode updateMode)

Description:

Sets the preview update mode.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

config

Points to the configuration object with the target configuration information. For details, please refer to AREngine_ARConfig.

updateMode

Preview update mode. For details, please refer to AREngine_ARUpdateMode.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARFrame_AcquireCamera()

AREngine_ARStatus HMS_AREngine_ARFrame_AcquireCamera(const AREngine_ARSession *session, const AREngine_ARFrame *frame, AREngine_ARCamera **outCamera)

Description:

Obtains the camera parameter object of the current frame.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

frame

Current frame object. For details, please refer to AREngine_ARFrame.

outCamera

Camera parameter object of the current frame. For details, please refer to AREngine_ARCamera.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARFrame_AcquireCameraImage()

AREngine_ARStatus HMS_AREngine_ARFrame_AcquireCameraImage(const AREngine_ARSession *session, const AREngine_ARFrame *frame, AREngine_ARImage **outImage)

Description:

Obtains the image of the current frame of the camera.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

frame

Current frame object. For details, please refer to AREngine_ARFrame.

outImage

Image object of the current frame. For details, please refer to AREngine_ARImage.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARFrame_AcquirePointCloud()

AREngine_ARStatus HMS_AREngine_ARFrame_AcquirePointCloud(const AREngine_ARSession *session, const AREngine_ARFrame *frame, AREngine_ARPointCloud **outPointCloud)

Description:

Returns the point cloud data of the current frame.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

frame

Current frame object. For details, please refer to AREngine_ARFrame.

outPointCloud

Point cloud object of the current frame. For details, please refer to AREngine_ARPointCloud.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARFrame_Create()

AREngine_ARStatus HMS_AREngine_ARFrame_Create(const AREngine_ARSession *session, AREngine_ARFrame **outFrame)

Description:

Creates an AREngine_ARFrame object and stores the pointer in *outFrame.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

outFrame

Current frame object. For details, please refer to AREngine_ARFrame.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARFrame_Destroy()

void HMS_AREngine_ARFrame_Destroy(AREngine_ARFrame *frame)

Description:

Deletes the current AREngine_ARFrame object.

Start version: 5.0.0(12)

Parameters:

Name

Description

frame

Current frame object. For details, please refer to AREngine_ARFrame.

[h2]HMS_AREngine_ARFrame_GetDisplayGeometryChanged()

AREngine_ARStatus HMS_AREngine_ARFrame_GetDisplayGeometryChanged(const AREngine_ARSession *session, const AREngine_ARFrame *frame, int32_t *outGeometryChangeState)

Description:

Obtains whether the display (length, width, and rotation) changes. If so, you need to call HMS_AREngine_ARFrame_TransformDisplayUvCoords again to obtain the correct coordinates of the texture map. If the return value of outGeometryChangeState is 0, no changes have occurred. Otherwise, changes have occurred.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

frame

Current frame object. For details, please refer to AREngine_ARFrame.

outGeometryChangeState

Indicates whether the display (length, width, and rotation) changes. Value 0 indicates that no change has occurred. Other values indicate that changes have occurred.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARFrame_GetTimestamp()

AREngine_ARStatus HMS_AREngine_ARFrame_GetTimestamp(const AREngine_ARSession *session, const AREngine_ARFrame *frame, int64_t *outTimestampNs)

Description:

Obtains the timestamp information (in nanoseconds) of the current frame.

HMS_AREngine_ARSession_SetDisplayGeometry()

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

frame

Current frame object. For details, please refer to AREngine_ARFrame.

outTimestampNs

Timestamp information, in nanoseconds.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARFrame_GetUpdatedTrackables()

AREngine_ARStatus HMS_AREngine_ARFrame_GetUpdatedTrackables(const AREngine_ARSession *session, const AREngine_ARFrame *frame, AREngine_ARTrackableType filterType, AREngine_ARTrackableList * outTrackableList)

Description:

Obtains the updated trackable object of the specified type after HMS_AREngine_ARSession_Update is called.

For details about trackable object types, please refer to AREngine_ARTrackableType.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

frame

Current frame object. For details, please refer to AREngine_ARFrame.

filterType

Type of the trackable object to be returned. For details, please refer to AREngine_ARTrackableType.

outTrackableList

List of trackable objects. For details, please refer to AREngine_ARTrackableList.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARFrame_HitTest()

AREngine_ARStatus HMS_AREngine_ARFrame_HitTest(const AREngine_ARSession *session, const AREngine_ARFrame *frame, float pixelX, float pixelY, AREngine_ARHitResultList *hitResultList)

Description:

Casts a ray from the camera, with the direction of the ray determined by the points (pixelX, pixelY) in the preview area. pixelX and pixelY can be obtained through the XComponent's DispatchTouchEvent() event.

The ray collides with the plane or the points in the point cloud tracked by the system (if the point cloud is recognized), resulting in intersections and hit results. The intersections are sorted by their distance from the device, from closest to farthest, and stored in a list. (pixelX, pixelY) indicate the coordinates of a pixel in the preview area.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

frame

Current frame object. For details, please refer to AREngine_ARFrame.

pixelX

X coordinate.

pixelY

Y coordinate.

hitResultList

Hit result list. For details, please refer to AREngine_ARHitResultList.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARFrame_TransformDisplayUvCoords()

AREngine_ARStatus HMS_AREngine_ARFrame_TransformDisplayUvCoords(const AREngine_ARSession *session, const AREngine_ARFrame *frame, int32_t elementSize, const float *uvsIn, float *uvsOut)

Description:

Converts the texture coordinates so that the background image captured by the camera can be correctly displayed.

You need to call this method to convert the texture coordinates only when outGeometryChangeState returned by HMS_AREngine_ARFrame_GetDisplayGeometryChanged is not 0, or when you have set a new display size by calling HMS_AREngine_ARSession_SetDisplayGeometry.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

frame

Current frame object. For details, please refer to AREngine_ARFrame.

elementSize

Number of texture coordinates to be converted. The value must be a multiple of 2 (uv coordinates).

uvsIn

Original input uv coordinates. The array size is elementSize.

uvsOut

Converted uv coordinates. The array size is elementSize.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARHitResult_AcquireNewAnchor()

AREngine_ARStatus HMS_AREngine_ARHitResult_AcquireNewAnchor(AREngine_ARSession *session, AREngine_ARHitResult *hitResult, AREngine_ARAnchor **outAnchor)

Description:

Creates an anchor at the intersection.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

hitResult

Hit testing result object. For details, please refer to AREngine_ARHitResult.

outAnchor

Newly created anchor object. For details, please refer to AREngine_ARAnchor.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARHitResult_AcquireTrackable()

AREngine_ARStatus HMS_AREngine_ARHitResult_AcquireTrackable(const AREngine_ARSession *session, const AREngine_ARHitResult *hitResult, AREngine_ARTrackable **outTrackable)

Description:

Obtains the trackable object that is hit.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

hitResult

Hit testing result object. For details, please refer to AREngine_ARHitResult.

outTrackable

Trackable object that is hit. For details, please refer to AREngine_ARTrackable.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARHitResult_Create()

AREngine_ARStatus HMS_AREngine_ARHitResult_Create(const AREngine_ARSession *session, AREngine_ARHitResult **outHitResult)

Description:

Creates an empty hit testing result object.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

outHitResult

Hit testing result object to be created. For details, please refer to AREngine_ARHitResult.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARHitResult_Destroy()

void HMS_AREngine_ARHitResult_Destroy(AREngine_ARHitResult *hitResult)

Description:

Releases the memory used by the hit testing result object.

Start version: 5.0.0(12)

Parameters:

Name

Description

hitResult

Hit testing result object to be released. For details, please refer to AREngine_ARHitResult.

[h2]HMS_AREngine_ARHitResult_GetDistance()

AREngine_ARStatus HMS_AREngine_ARHitResult_GetDistance(const AREngine_ARSession *session, const AREngine_ARHitResult *hitResult, float *outDistance)

Description:

Obtains the distance from the camera to the hit location, in meters.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

hitResult

Hit testing result object. For details, please refer to AREngine_ARHitResult.

outDistance

Distance from the camera to the hit object, in meters.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARHitResult_GetHitPose()

AREngine_ARStatus HMS_AREngine_ARHitResult_GetHitPose(const AREngine_ARSession *session, const AREngine_ARHitResult *hitResult, AREngine_ARPose *outPose)

Description:

Obtains the pose of an intersection. The pose's translation component corresponds to the intersection's coordinates in the world coordinate system, while its rotation component varies according to the type of the intersection (such as the intersection with a plane or a point cloud).

  1. When a ray collides with the plane, in the local coordinate system: X+ is perpendicular to the ray and parallel to the tracked plane; Y+ is the normal vector of the tracked plane; Z+ is parallel to the plane and roughly points to the camera.
  2. When a ray collides with points in a point cloud, the system attempts to estimate a plane with the point cloud of the hit area.
    1. If HMS_AREngine_ARPoint_GetOrientationMode returns ARENGINE_POINT_ORIENTATION_ESTIMATED_SURFACE_NORMAL, X+ is perpendicular to the ray and parallel to the tracked plane, Y+ is the normal vector of the tracked plane, and Z+ is parallel to the plane and roughly points to the camera.
    2. If ARENGINE_POINT_ORIENTATION_INITIALIZED_TO_IDENTITY is returned, the orientation of the coordinates won't change with the plane's angle. X+ is perpendicular to the ray and points to the right (from the device's perspective), Y+ points upward, and Z+ roughly points to the camera. For details, please refer to the orientation mode definition.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

hitResult

Hit testing result object. For details, please refer to AREngine_ARHitResult.

outPose

Intersection pose. For details, please refer to AREngine_ARPose.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARHitResultList_Create()

AREngine_ARStatus HMS_AREngine_ARHitResultList_Create(const AREngine_ARSession *session, AREngine_ARHitResultList **outHitResultList)

Description:

Creates a list of hit testing result objects.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

outHitResultList

To-be-created list of hit testing result objects. For details, please refer to AREngine_ARHitResultList.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARHitResultList_Destroy()

void HMS_AREngine_ARHitResultList_Destroy(AREngine_ARHitResultList *hitResultList)

Description:

Releases the list of hit testing result objects, as well as all hit testing result objects in the list.

Start version: 5.0.0(12)

Parameters:

Name

Description

hitResultList

To-be-released list of hit testing result objects. For details, please refer to AREngine_ARHitResultList.

[h2]HMS_AREngine_ARHitResultList_GetItem()

AREngine_ARStatus HMS_AREngine_ARHitResultList_GetItem(const AREngine_ARSession *session, const AREngine_ARHitResultList *hitResultList, int32_t index, AREngine_ARHitResult *outHitResult)

Description:

Obtains the hit testing result object at a specific index from the hit testing result list.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

hitResultList

List of hit testing result objects. For details, please refer to AREngine_ARHitResultList.

index

Index of the hit testing result object to be obtained.

outHitResult

Hit testing result object to be obtained. For details, please refer to AREngine_ARHitResult.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARHitResultList_GetSize()

AREngine_ARStatus HMS_AREngine_ARHitResultList_GetSize(const AREngine_ARSession *session, const AREngine_ARHitResultList *hitResultList, int32_t *outSize)

Description:

Obtains the number of objects in the hit testing result object list.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

hitResultList

List of hit testing result objects. For details, please refer to AREngine_ARHitResultList.

outSize

List size.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARImage_GetFormat()

AREngine_ARStatus HMS_AREngine_ARImage_GetFormat(const AREngine_ARSession *session, const AREngine_ARImage *image, AREngine_ARImageFormat *outFormat)

Description:

Obtains the image format of the current frame.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

image

Input image data. For details, please refer to AREngine_ARImage.

outFormat

Image format of the current frame.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARImage_GetHeight()

AREngine_ARStatus HMS_AREngine_ARImage_GetHeight(const AREngine_ARSession *session, const AREngine_ARImage *image, int32_t *outHeight)

Description:

Obtains the image height of the current frame.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

image

Image object of the current frame. For details, please refer to AREngine_ARImage.

outHeight

Image height (in pixels) of the current frame.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARImage_GetPlaneCount()

AREngine_ARStatus HMS_AREngine_ARImage_GetPlaneCount(const AREngine_ARSession *session, const AREngine_ARImage *image, int32_t *outCount)

Description:

Obtains the number of planes in the current frame.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

image

Image object of the current frame. For details, please refer to AREngine_ARImage.

outCount

Number of planes in the current frame.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARImage_GetPlaneData()

AREngine_ARStatus HMS_AREngine_ARImage_GetPlaneData(const AREngine_ARSession *session, const AREngine_ARImage *image, int32_t planeIndex, const uint8_t **outData, int32_t *outLength)

Description:

Obtains the plane data in the current frame.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

image

Image object of the current frame. For details, please refer to AREngine_ARImage.

planeIndex

Plane index. The value ranges from 0 to n-1, where n is the number of planes in the image.

outData

Pointer to the current image data.

outLength

Length of the current image (in bytes).

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARImage_GetPlanePixelStride()

AREngine_ARStatus HMS_AREngine_ARImage_GetPlanePixelStride(const AREngine_ARSession *session, const AREngine_ARImage *image, int32_t planeIndex, int32_t *outPixelStride)

Description:

Obtains the distance between the start points of two consecutive pixels in an image, in bytes. The pixel stride is always greater than 0.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

image

Image object of the current frame. For details, please refer to AREngine_ARImage.

planeIndex

Plane index. The value ranges from 0 to n-1, where n is the number of planes in the image.

outPixelStride

Image stride (in bytes).

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARImage_GetPlaneRowStride()

AREngine_ARStatus HMS_AREngine_ARImage_GetPlaneRowStride(const AREngine_ARSession *session, const AREngine_ARImage *image, int32_t planeIndex, int32_t *outRowStride)

Description:

Obtains the number of bytes between the start positions of two consecutive pixel lines in an image. The line spacing is always greater than 0.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

image

Image object of the current frame. For details, please refer to AREngine_ARImage.

planeIndex

Plane index. The value ranges from 0 to n-1, where n is the number of planes in the image.

outRowStride

Row stride (in bytes).

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARImage_GetTimestamp()

AREngine_ARStatus HMS_AREngine_ARImage_GetTimestamp(const AREngine_ARSession *session, const AREngine_ARImage *image, int64_t *outTimestamp)

Description:

Gets the timestamp of an image (in nanoseconds). Timestamps are usually monotonically increasing. The specific meaning and time base of the timestamp depend on the image source. Timestamps of images from different sources may have different time bases, so they should not be compared with each other.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

image

Image object of the current frame. For details, please refer to AREngine_ARImage.

outTimestamp

Timestamp of the image (in nanoseconds).

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARImage_GetWidth()

AREngine_ARStatus HMS_AREngine_ARImage_GetWidth(const AREngine_ARSession *session, const AREngine_ARImage *image, int32_t *outWidth)

Description:

Obtains the image width of the current frame.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

image

Image object of the current frame. For details, please refer to AREngine_ARImage.

outWidth

Image width (in pixels) of the current frame.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARImage_Release()

void HMS_AREngine_ARImage_Release(AREngine_ARImage *image)

Description:

Releases the image object of the current frame, that is, the object created by HMS_AREngine_ARFrame_AcquireCameraImage.

Start version: 5.0.0(12)

Parameters:

Name

Description

image

Image object of the current frame. For details, please refer to AREngine_ARImage.

[h2]HMS_AREngine_ARPlane_AcquireSubsumedBy()

AREngine_ARStatus HMS_AREngine_ARPlane_AcquireSubsumedBy(const AREngine_ARSession *session, const AREngine_ARPlane *plane, AREngine_ARPlane **outSubsumedBy)

Description:

Obtains the parent plane of a plane (a parent plane is generated when a plane is merged with another one). If there is no parent plane, NULL is returned.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

plane

Plane object to be processed. For details, please refer to AREngine_ARPlane.

outSubsumedBy

Parent plane object of a specific plane. For details, please refer to AREngine_ARPlane.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARPlane_GetCenterPose()

AREngine_ARStatus HMS_AREngine_ARPlane_GetCenterPose(const AREngine_ARSession *session, const AREngine_ARPlane *plane, AREngine_ARPose *outPose)

Description:

Obtains the pose information for the conversion from the local coordinate system of a plane to the world coordinate system.

In the plane's local coordinate system (right-handed): The origin is at the center of the plane's bounding rectangle; the x-axis is along the longer edge, the z-axis is along the shorter edge, and Y+ indicates the plane's normal vector.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

plane

Plane object to be processed. For details, please refer to AREngine_ARPlane.

outPose

Pose information for the conversion from the local coordinate system of a plane to the world coordinate system. For details, please refer to AREngine_ARPose.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARPlane_GetExtentX()

AREngine_ARStatus HMS_AREngine_ARPlane_GetExtentX(const AREngine_ARSession *session, const AREngine_ARPlane *plane, float *outExtentX)

Description:

Obtains the length of the plane's bounding rectangle along the x-axis of the plane's local coordinate system, such as the width of the rectangle.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

plane

Plane object to be processed. For details, please refer to AREngine_ARPlane.

outExtentX

Length of the plane's bounding rectangle along the x-axis of the plane's local coordinate system, in meters.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARPlane_GetExtentZ()

AREngine_ARStatus HMS_AREngine_ARPlane_GetExtentZ(const AREngine_ARSession *session, const AREngine_ARPlane *plane, float *outExtentZ)

Description:

Obtains the length of the plane's bounding rectangle along the z-axis of the plane's local coordinate system, such as the height of the rectangle.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

plane

Plane object to be processed. For details, please refer to AREngine_ARPlane.

outExtentZ

Length of the plane's bounding rectangle along the z-axis of the plane's local coordinate system, in meters.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARPlane_GetLabel()

AREngine_ARStatus HMS_AREngine_ARPlane_GetLabel(const AREngine_ARSession *session, const AREngine_ARPlane *plane, AREngine_ARSemanticPlaneLabel *label)

Description:

Obtains the semantic type of a plane, such as desktop and floor. When using this function, you need to call HMS_AREngine_ARConfig_SetSemanticMode to enable the semantic recognition mode.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

plane

Plane object to be processed. For details, please refer to AREngine_ARPlane.

label

Semantic type of the current plane. For details, please refer to AREngine_ARSemanticPlaneLabel.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARPlane_GetPolygon()

AREngine_ARStatus HMS_AREngine_ARPlane_GetPolygon(const AREngine_ARSession *session, const AREngine_ARPlane *plane, float *outPolygonXz, int32_t polygonSize)

Description:

Obtains the 2D vertex array of the detected plane, in the format of [x1, z1, x2, z2, ...].

These values are defined in the x-z plane of the plane's local coordinate system and must be converted to the world coordinate system through HMS_AREngine_ARPlane_GetCenterPose.

Note: The returned coordinates [x1, z1, x2, z2, ...] in the vertical plane are also the coordinates in the local coordinate system, which should be converted to the world coordinate system through HMS_AREngine_ARPlane_GetCenterPose.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

plane

Plane object to be processed. For details, please refer to AREngine_ARPlane.

outPolygonXz

Array consisting of 2D vertices of the detected plane.

polygonSize

Size of the 2D vertex array, which is obtained through HMS_AREngine_ARPlane_GetPolygonSize.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARPlane_GetPolygonSize()

AREngine_ARStatus HMS_AREngine_ARPlane_GetPolygonSize(const AREngine_ARSession *session, const AREngine_ARPlane *plane, int32_t *outPolygonSize)

Description:

Obtains the size of the 2D vertex array of the detected plane. This function is used together with HMS_AREngine_ARPlane_GetPolygon.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

plane

Plane object to be processed. For details, please refer to AREngine_ARPlane.

outPolygonSize

Size of a 2D vertex array.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARPlane_GetType()

AREngine_ARStatus HMS_AREngine_ARPlane_GetType(const AREngine_ARSession *session, const AREngine_ARPlane *plane, AREngine_ARPlaneType *outPlaneType)

Description:

Obtains the plane type.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

plane

Plane object to be processed. For details, please refer to AREngine_ARPlane.

outPlaneType

Plane type. For details, please refer to AREngine_ARPlaneType.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARPlane_IsPoseInExtents()

AREngine_ARStatus HMS_AREngine_ARPlane_IsPoseInExtents(const AREngine_ARSession *session, const AREngine_ARPlane *plane, const AREngine_ARPose *pose, int32_t *outPoseInExtents)

Description:

Checks whether a pose is within the plane's bounding rectangle.

A none-zero value is returned if the input pose (obtained through HMS_AREngine_ARHitResult_GetHitPose) is within the plane's bounding rectangle.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

plane

Plane object to be processed. For details, please refer to AREngine_ARPlane.

pose

Pose information. For details, please refer to AREngine_ARPose.

outPoseInExtents

Indicates whether the pose is within the plane's bounding rectangle. Value 0 indicates that it is out of the range, and other values indicate that it is within the range.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARPlane_IsPoseInPolygon()

AREngine_ARStatus HMS_AREngine_ARPlane_IsPoseInPolygon(const AREngine_ARSession *session, const AREngine_ARPlane *plane, const AREngine_ARPose *pose, int32_t *outPoseInPolygon)

Description:

Checks whether a pose is within the plane's bounding polygon.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

plane

Plane object to be processed. For details, please refer to AREngine_ARPlane.

pose

Pose information. For details, please refer to AREngine_ARPose.

outPoseInPolygon

Indicates whether the pose is within the plane's bounding polygon. Value 0 indicates that it is out of the range, and other values indicate that it is within the range.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARPoint_GetOrientationMode()

AREngine_ARStatus HMS_AREngine_ARPoint_GetOrientationMode(const AREngine_ARSession *session, const AREngine_ARPoint *point, AREngine_ARPointOrientationMode *outOrientationMode)

Description:

Obtains the orientation mode of an input point.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

point

Input point object. For details, please refer to AREngine_ARPoint.

outOrientationMode

Orientation mode of an input point. For details, please refer to AREngine_ARPointOrientationMode.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARPoint_GetPose()

AREngine_ARStatus HMS_AREngine_ARPoint_GetPose(const AREngine_ARSession *session, const AREngine_ARPoint *point, AREngine_ARPose *outPose)

Description:

Obtains the pose information of an input point.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

point

Input point object. For details, please refer to AREngine_ARPoint.

outPose

Pose information of the input point. For details, please refer to AREngine_ARPose.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARPointCloud_GetData()

AREngine_ARStatus HMS_AREngine_ARPointCloud_GetData(const AREngine_ARSession *session, const AREngine_ARPointCloud *pointCloud, const float **outPointCloudData)

Description:

Obtains the coordinates of all points in a point cloud, as well as their confidence array.

The coordinates are in the world coordinate system and are right-handed coordinates. You can obtain the point cloud object by calling HMS_AREngine_ARFrame_AcquirePointCloud.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

pointCloud

Point cloud object. For details, please refer to AREngine_ARPointCloud.

outPointCloudData

Coordinates of all points in a point cloud, as well as their confidence array, in the format [x0, y0, z0, c0, x1, y1, z1, c1, x2...].

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARPointCloud_GetNumberOfPoints()

AREngine_ARStatus HMS_AREngine_ARPointCloud_GetNumberOfPoints(const AREngine_ARSession *session, const AREngine_ARPointCloud *pointCloud, int32_t *outNumberOfPoints)

Description:

Obtains the coordinates of all points in a point cloud, as well as their confidence array size. This function is used together with HMS_AREngine_ARPointCloud_GetData.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

pointCloud

Point cloud object. For details, please refer to AREngine_ARPointCloud.

outNumberOfPoints

Coordinates of all points in a point cloud, as well as their confidence array size.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARPointCloud_GetTimestamp()

AREngine_ARStatus HMS_AREngine_ARPointCloud_GetTimestamp(const AREngine_ARSession *session, const AREngine_ARPointCloud *pointCloud, int64_t *outTimestampNs)

Description:

Obtains the timestamp when the current point cloud is detected, in nanoseconds.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

pointCloud

Point cloud object. For details, please refer to AREngine_ARPointCloud.

outTimestampNs

Timestamp when the current point cloud is detected.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARPointCloud_Release()

void HMS_AREngine_ARPointCloud_Release(AREngine_ARPointCloud *pointCloud)

Description:

Releases the memory used by the point cloud object.

Start version: 5.0.0(12)

Parameters:

Name

Description

pointCloud

To-be-released point cloud object. For details, please refer to AREngine_ARPointCloud.

[h2]HMS_AREngine_ARPose_Create()

AREngine_ARStatus HMS_AREngine_ARPose_Create(const AREngine_ARSession *session, const float *poseRaw, const uint32_t poseRawSize, AREngine_ARPose **outPose)

Description:

Allocates and initializes a new pose object. You can leave poseRaw empty to create an uninitialized pose object, and then call HMS_AREngine_ARPoint_GetPose and HMS_AREngine_ARAnchor_GetPose to assign a value to the pose object.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

poseRaw

Pose data, including translation components and rotation components. The obtained pose data is an array with 7 elements: poseRaw[0] to poseRaw[3] are rotation quaternions, and poseRaw[4] to poseRaw[6] are translation components (x, y, z).

poseRawSize

Array size, which should be greater than or equal to ARENGINE_POSE_RAW_SIZE.

outPose

Newly created pose object. For details, please refer to AREngine_ARPose.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARPose_Destroy()

void HMS_AREngine_ARPose_Destroy(AREngine_ARPose *pose)

Description:

Releases the memory used by the pose object.

Start version: 5.0.0(12)

Parameters:

Name

Description

pose

Pose object to be released. For details, please refer to AREngine_ARPose.

[h2]HMS_AREngine_ARPose_GetMatrix()

AREngine_ARStatus HMS_AREngine_ARPose_GetMatrix(const AREngine_ARSession *session, const AREngine_ARPose *pose, float *outMatrixColMajor4x4, int32_t matrixColMajor4x4Size)

Description:

Converts the pose data into a 4 x 4 matrix. outMatrixColMajor4x4 is the array for storing the matrix, where data is stored in column-major order. Coordinates in the local coordinate system can be converted into ones in the world coordinate system by multiplying this matrix with the coordinates in the local coordinate system.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

pose

Pose object. For details, please refer to AREngine_ARPose.

outMatrixColMajor4x4

Array with 16 floating point numbers, which are stored in a column-major order.

matrixColMajor4x4Size

Array size: ARENGINE_VIEW_MATRIX_SIZE

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARPose_GetPoseRaw()

AREngine_ARStatus HMS_AREngine_ARPose_GetPoseRaw(const AREngine_ARSession *session, const AREngine_ARPose *pose, float *outPoseRaw, int32_t poseRawSize)

Description:

Obtains pose data from the pose object, including translation components and rotation components. The obtained pose data is an array with 7 elements: poseRaw[0] to poseRaw[3] are rotation quaternions, and poseRaw[4] to poseRaw[6] are translation components (x, y, z).

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

pose

Pose object. For details, please refer to AREngine_ARPose.

outPoseRaw

Pose data.

poseRawSize

Array size: ARENGINE_POSE_RAW_SIZE

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARSession_AcquireNewAnchor()

AREngine_ARStatus HMS_AREngine_ARSession_AcquireNewAnchor(AREngine_ARSession *session, const AREngine_ARPose *pose, AREngine_ARAnchor **outAnchor)

Description:

Creates an anchor for continuous tracking.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

pose

Pose object used for creating an anchor. For details, please refer to AREngine_ARPose.

outAnchor

Created anchor object. For details, please refer to AREngine_ARAnchor.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARSession_Configure()

AREngine_ARStatus HMS_AREngine_ARSession_Configure(AREngine_ARSession *session, const AREngine_ARConfig *config)

Description:

Configures an AREngine_ARSession session.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

config

Configuration object to be applied on the device. For details, please refer to AREngine_ARConfig.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARSession_Create()

AREngine_ARStatus HMS_AREngine_ARSession_Create(void *env, void *applicationContext, AREngine_ARSession **outSessionPointer)

Description:

Creates an AREngine_ARSession session. This function depends on the camera, acceleration sensor, and gyroscope sensor permissions.

Start version: 5.0.0(12)

Parameters:

Name

Description

env

JNI environment for the current APK.

applicationContext

App context.

outSessionPointer

Created session object. For details, please refer to AREngine_ARSession.

Returns:

Status type, indicating the calling status of the method.

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARSession_Destroy()

void HMS_AREngine_ARSession_Destroy(AREngine_ARSession *session)

Description:

Releases the resources used by the AREngine_ARSession session.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARSession_GetAllAnchors()

AREngine_ARStatus HMS_AREngine_ARSession_GetAllAnchors(const AREngine_ARSession *session, AREngine_ARAnchorList *outAnchorList)

Description:

Obtains all anchors, including anchors in all states contained in AREngine_ARTrackingState.

During app processing, only anchors in the ARENGINE_TRACKING_STATE_TRACKING state need to be drawn, and anchors in the ARENGINE_TRACKING_STATE_STOPPED state need to be deleted.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

outAnchorList

List of all anchor objects. For details, please refer to AREngine_ARAnchorList.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARSession_GetAllTrackables()

AREngine_ARStatus HMS_AREngine_ARSession_GetAllTrackables(const AREngine_ARSession *session, AREngine_ARTrackableType filterType, AREngine_ARTrackableList *outTrackableList)

Description:

Obtains the list of all trackable objects of the specified type.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

filterType

Type of the current trackable object. For details, please refer to AREngine_ARTrackableType.

outTrackableList

A list of trackable objects of a specified type. For details, please refer to AREngine_ARTrackableList.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARSession_GetCameraConfig()

AREngine_ARStatus HMS_AREngine_ARSession_GetCameraConfig(const AREngine_ARSession *session, AREngine_ARCameraConfig *outCameraConfig)

Description:

Obtains the camera configuration information.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

outCameraConfig

Camera configuration. For details, please refer to AREngine_ARCameraConfig.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARSession_Pause()

AREngine_ARStatus HMS_AREngine_ARSession_Pause(AREngine_ARSession *session)

Description:

Pauses the session, stops the camera preview stream, and releases the camera (otherwise, other apps will not be able to use the camera service), without clearing the plane and anchor data.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARSession_Resume()

AREngine_ARStatus HMS_AREngine_ARSession_Resume(AREngine_ARSession *session)

Description:

Starts AREngine_ARSession, or restores AREngine_ARSession after HMS_AREngine_ARSession_Pause is called.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARSession_SetCameraGLTexture()

AREngine_ARStatus HMS_AREngine_ARSession_SetCameraGLTexture(AREngine_ARSession *session, uint32_t textureId)

Description:

Sets the OpenGL texture for storing the camera preview stream data.

After your app calls HMS_AREngine_ARSession_Update, AR Engine will update the camera preview to the texture.

When using the texture, set it to the GL_TEXTURE_EXTERNAL_OES type, for example, by calling glBindTexture(GL_TEXTURE_EXTERNAL_OES, textureId).

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

textureId

OpenGL textureId of the camera preview data stream. The value is greater than 0.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARSession_SetDisplayGeometry()

AREngine_ARStatus HMS_AREngine_ARSession_SetDisplayGeometry(AREngine_ARSession *session, AREngine_ARPoseType rotation, int32_t width, int32_t height)

Description:

Sets the display height and width (in pixels). Make sure that the height and width you set here are consistent with those of the display view. Otherwise, an error will occur with the camera preview.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

rotation

Display rotation constant. The value is an enum defined in AREngine_ARPoseType.

width

Display width, in pixels.

height

Display height, in pixels.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARSession_Stop()

AREngine_ARStatus HMS_AREngine_ARSession_Stop(AREngine_ARSession *session)

Description:

Stops AR Engine and the camera preview stream, clears the plane and anchor data, releases the camera, and terminates the session.

After this method is called, you need to create AREngine_ARSession if you want to start AR Engine again.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARSession_Update()

AREngine_ARStatus HMS_AREngine_ARSession_Update(AREngine_ARSession *session, AREngine_ARFrame *outFrame)

Description:

Updates the computation result of AR Engine.

Call this API when you need to obtain the latest data. For example, after the camera moves, call this API to obtain the new anchor's coordinates, plane coordinates, and image frames obtained by the camera.

If HMS_AREngine_ARConfig_GetUpdateMode returns ARENGINE_UPDATE_MODE_BLOCKING, this function is blocked until a new frame is available.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

outFrame

Updated frame object. For details, please refer to AREngine_ARFrame.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARTarget_GetAxisAlignedBoundingBox()

AREngine_ARStatus HMS_AREngine_ARTarget_GetAxisAlignedBoundingBox(const AREngine_ARSession *session, const AREngine_ARTarget *target, float *outAabb, int32_t aabbSize)

Description:

Obtains the coordinates of the minimum bounding box of a semantic object, in the format of (xmin, ymin, zmin, xmax, ymax, zmax).

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

target

Target semantic object to be processed. For details, please refer to AREngine_ARTarget.

outAabb

Coordinate set of the minimum bounding box of a semantic object.

aabbSize

Array size: ARENGINE_AABB_POINT_SIZE

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARTarget_GetCenterPose()

AREngine_ARStatus HMS_AREngine_ARTarget_GetCenterPose(const AREngine_ARSession *session, const AREngine_ARTarget *target, AREngine_ARPose *outARPose)

Description:

Obtains the pose object for the conversion from the local coordinate system of the target semantic object to the world coordinate system.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

target

Target semantic object to be processed. For details, please refer to AREngine_ARTarget.

outARPose

Pose for the conversion from the local coordinate system of the target semantic object to the world coordinate system. For details, please refer to AREngine_ARPose.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARTarget_GetRadius()

AREngine_ARStatus HMS_AREngine_ARTarget_GetRadius(const AREngine_ARSession *session, const AREngine_ARTarget *target, float *radius)

Description:

Obtains the sphere radius of a semantic object.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

target

Target semantic object to be processed. For details, please refer to AREngine_ARTarget.

radius

Sphere radius of the target semantic object, in meters.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARTarget_GetShapeType()

AREngine_ARStatus HMS_AREngine_ARTarget_GetShapeType(const AREngine_ARSession *session, const AREngine_ARTarget *target, AREngine_ARTargetShapeLabel *shape)

Description:

Obtains the shape type of a semantic object.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

target

Target semantic object to be processed. For details, please refer to AREngine_ARTarget.

shape

Shape type of the target semantic object. For details, please refer to AREngine_ARTargetShapeLabel.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARTrackable_AcquireNewAnchor()

AREngine_ARStatus HMS_AREngine_ARTrackable_AcquireNewAnchor(AREngine_ARSession *session, AREngine_ARTrackable *trackable, AREngine_ARPose *pose, AREngine_ARAnchor **outAnchor)

Description:

Creates an anchor object using the pose information of the trackable object. This anchor will be bound to the current trackable object.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

trackable

Trackable object.

pose

Pose information of a trackable object.

outAnchor

Newly created anchor object.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARTrackable_GetAnchors()

AREngine_ARStatus HMS_AREngine_ARTrackable_GetAnchors(AREngine_ARSession *session, const AREngine_ARTrackable *trackable, AREngine_ARAnchorList *outAnchorList)

Description:

Obtains a list of anchor objects bound to the input trackable objects.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

trackable

Trackable object. For details, please refer to AREngine_ARTrackable.

outAnchorList

List of anchor objects. This list must be created using HMS_AREngine_ARAnchorList_Create. If you use a list that has been created, values will be reassigned for this list.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARTrackable_GetTrackingState()

AREngine_ARStatus HMS_AREngine_ARTrackable_GetTrackingState(const AREngine_ARSession *session, const AREngine_ARTrackable *trackable, AREngine_ARTrackingState *outTrackingState)

Description:

Obtains the tracking status of the current trackable object.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

trackable

Trackable object. For details, please refer to AREngine_ARTrackable.

outTrackingState

Tracking status of the trackable object. For details, please refer to AREngine_ARTrackingState.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARTrackable_GetType()

AREngine_ARStatus HMS_AREngine_ARTrackable_GetType(const AREngine_ARSession *session, const AREngine_ARTrackable *trackable, AREngine_ARTrackableType *outTrackableType)

Description:

Obtains the type of a trackable object.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

trackable

Trackable object. For details, please refer to AREngine_ARTrackable.

outTrackableType

Type of the trackable object. For details, please refer to AREngine_ARTrackableType.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARTrackable_Release()

void HMS_AREngine_ARTrackable_Release(AREngine_ARTrackable *trackable)

Description:

Releases a trackable object.

Start version: 5.0.0(12)

Parameters:

Name

Description

trackable

Trackable objects to be released. For details, please refer to AREngine_ARTrackable.

[h2]HMS_AREngine_ARTrackableList_AcquireItem()

AREngine_ARStatus HMS_AREngine_ARTrackableList_AcquireItem(const AREngine_ARSession *session, const AREngine_ARTrackableList *trackableList, int32_t index, AREngine_ARTrackable **outTrackable)

Description:

Obtains the object at a specific index from the trackable object list.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

trackableList

List of trackable objects. For details, please refer to AREngine_ARTrackableList.

index

Location of a trackable object in the trackable object list.

outTrackable

Target trackable object. For details, please refer to AREngine_ARTrackable.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARTrackableList_Create()

AREngine_ARStatus HMS_AREngine_ARTrackableList_Create(const AREngine_ARSession *session, AREngine_ARTrackableList **outTrackableList)

Description:

Creates a list of trackable objects.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

outTrackableList

List of trackable objects. For details, please refer to AREngine_ARTrackableList.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.

[h2]HMS_AREngine_ARTrackableList_Destroy()

void HMS_AREngine_ARTrackableList_Destroy(AREngine_ARTrackableList *trackableList)

Description:

Releases the list of trackable objects, along with all the anchor references it holds.

Start version: 5.0.0(12)

Parameters:

Name

Description

trackableList

To-be-released list of trackable objects. For details, please refer to AREngine_ARTrackableList.

[h2]HMS_AREngine_ARTrackableList_GetSize()

AREngine_ARStatus HMS_AREngine_ARTrackableList_GetSize(const AREngine_ARSession *session, const AREngine_ARTrackableList *trackableList, int32_t *outSize)

Description:

Obtains the number of trackable objects in the list.

Start version: 5.0.0(12)

Parameters:

Name

Description

session

AREngine_ARSession object.

trackableList

List of trackable objects. For details, please refer to AREngine_ARTrackableList.

outSize

Number of trackable objects in the trackable object list.

Returns:

Execution status. For details, please refer to AREngine_ARStatus.