开放能力
开发平台
行业应用
生态合作
开发与教学
资讯 社区 控制台
技术能力
语音技术
文字识别
人脸与人体
图像技术
语言与知识
视频技术
AR与VR
数据智能
场景方案
部署方案
行业应用
智能教育
智能医疗
智能零售
智能工业
企业服务
智能政务
信息服务
智能园区

ARScene

场景类,主要处理节点树的管理、手势交互控制器和物理全局配置管理等。

​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​
Public methods
ARScene get_root_node
获取场景中的根节点
ARScene get_node_by_name
通过节点名称获取场景中的节点
ARScene node_with_name
通过节点名称获取场景中的节点
ARScene set_event_handler
对整个场景设置手势交互事件
ARScene switch_camera_by_name
切换场景观测相机
ARScene clone_node
克隆指定的节点, 并返回一个新的节点
ARScene delete_node
删除指定节点
ARScene get_active_camera
获取当前场景中的观察者相机(透视投影)
ARScene set_update_handler
设置场景每一帧渲染update()之前的回调
ARScene get_physics_world
获取物理世界对象
ARScene create_physics_world
获取物理世界对象
ARScene get_input_controller
获取手势输入响应的控制器类
ARScene Key-Value Coding
KVC支持
ARScene Key-Value Observing
KVO支持

get_root_node

API起始版本:190

ARNode* get_root_node();

获取场景中的根节点

Return

  • ARNode : 返回场景根节点
sample:

local root_node = scene:get_root_node()

get_node_by_name

API起始版本:190

ARNode& get_node_by_name(string & name);

通过节点名称获取场景中的节点

Parameters

  • string | name : 需要获取的节点名称

Return

  • ARNode : 返回该名称节点
sample:

local node = scene:get_node_by_name("node_name")

node_with_name

API起始版本:190

ARNode* node_with_name(string & name);

通过节点名称获取场景中的节点

Parameters

  • string | name : 需要获取的节点名称

Return

  • ARNode : 返回该名称节点
sample:
local node = scene:node_with_name("node_name")

set_event_handler

API起始版本:190

void set_event_handler(int event_type, int handler_id);

对整个场景设置手势交互事件

Parameters

  • int | event_type : 手势交互事件类型。0:click, 1:long-press, 2:scroll, 4:pinch, 5:unpinch,1-5暂不支持
  • int | handler_id : 回调函数id

switch_camera_by_name

API起始版本:190

void switch_camera_by_name(string &camera_name, bool animated = false);

切换场景观测相机

Parameters

  • string | camera_name : 要切换的相机名称
  • bool | animated : 是否重置观测视角

clone_node

API起始版本:190

ARNode& clone_node(string &cloned_node_name, string &prefix);

克隆指定的节点, 并返回一个新的节点

Parameters

  • string | cloned_node_name : 要被克隆的节点的名字
  • string | prefix : 新克隆节点名字的前缀

Return

  • ARNode : 返回被克隆出的新的节点
sample:

local new_node = scene:clone_node("node", "clone1")

--新的节点名字会是(clone1)node,如果被克隆的节点有子节点,那么新的节点的子节点也会加上"(clone1)"的前缀
--如果克隆一个克隆节点,那么新的克隆节点只会替换()中的内容
--如:local new_node2 = scene_clone_node("(clone)node", clone2) 此时new_node2名字为(clone2)node

delete_node

API起始版本:190

void delete_node(string &name);

删除指定节点。 新版本中请使用 remove_node_by_name()

get_active_camera

API起始版本:190

ARCamera& get_active_camera();

获取当前场景中的观察者相机(透视投影)

Return

  • ARCamera 返回一个相机类的对象。
sample:

local camera = scene:get_active_camera()
camera:set_property_float("fov", 60)

set_update_handler

API起始版本:190

 void set_update_handler(ARLuaFunction handler);

设置场景每一帧渲染update()之前的回调,用于自定义动画、持续逻辑判断等

Parameters

  • LUA_FUNCTION | handler : 回调函数,一个Lua原生方法
sample code:

function on_update()
     ARLOG("before node:update()")
end

scene:set_update_handler(on_update)

get_physics_world

API起始版本:190

ARPhysicsWorld& get_physics_world()

获取物理世界对象,详见物理特效专题文档

create_physics_world

API起始版本:190

void create_physics_world(ARVec3& gravity)

获取物理世界对象,详见物理特效专题文档

get_input_controller

API起始版本:190

InputController* get_input_controller();

获取手势输入响应的控制器类,详见手势交互专题文档

KVC支持 (Key-Value Coding)

API起始版本:190

set_property

void set_property_int(string &key, int value);

void set_property_bool(string &key, bool value);

void set_property_float(string &key, float value);

void set_property_string(string &key, string value);

void set_property_vec2(string &key, ARVec2 value)

void set_property_vec4(string &key, ARVec4 value)

通过Key-Value的方式来设置Application的属性

Parameters

  • string | key : 对应的要修改的property的名字
  • int /bool/ float/ string/ ARVec2/ARVec4 | value : 要设置的值

当前版本可用的Key和对应的Value Type如下:

Key Value Type description Default
"name" string scene的名字
"visible" bool 是否可见 true
"interaction/disable_all" bool 是否禁用所有手势交互 false
"interaction/disable_pinch" bool 是否禁用双指捏合操作 false
"interaction/disable_click" bool 是否禁用点击操作 false
"interaction/disable_scroll" bool 是否禁用滑动操作 false
"interaction/disable_long_press" bool 是否禁用长按操作 false
"interaction/disable_double_click" bool 是否禁用双击操作 false
"interaction/disable_two_finger_scroll" bool 是否禁用双指滑动操作 false
"interaction/enable_touch_zone " bool 是否开启可操作范围设置(热区)(全局开关) false
"interaction/plane_move_limit_near" float 在给定平面上手势交互移动物体时的离相机最近距离限制
"interaction/ plane_move_limit_far " float 在给定平面上手势交互移动物体时的离相机最远距离限制
"offscreen_guidance/enabled" bool 是否开启场景中主体离开屏幕可视区域时的找寻引导 false
"offscreen_guidance/target_node_name" string 对应的当离开屏幕可视区域时要显示找寻引导的对应的节点的名称
"offscreen_guidance/current_state" string 当前显示状态"hide"|"show"
"batch_load/loading_state" string 当前分步加载的状态"unstarted"| "downloading"| "downloading failed" "download finish" "loading" | "loading failed"| "loding finish"
"batch_load/ loading_progress" float 当前分步加载的进度:0.00 - 1.00

示例:

sample code:
local app_controller = ARApplicationController:shared_instance()
local application = app_controller:add_application_with_name("my_ar_application")

scene:set_property_bool("visible",true)

get_property

void get_property_int(string &key) ;

void get_property_bool(string &key) ;

void get_property_float(string &key) ;

void get_property_string(string &key) ;

void get_property_vec2(string &key) ;

void get_property_vec4(string &key) ;

通过Key-Value的方式来获取Application的属性

Parameters

  • string | key : 对应的要修改的property的名字
  • int /bool/ float/ string/ ARVec2 /ARVec4 | value : 用来获取值的对应类型的变量,value将会在get_property方法内部被赋值

当前版本可用的Key和对应的Value Type如下:

Key Value Type description Default
"name" string scene的名字
"empty" bool 是否是一个有效的节点,empty=true时无效
"visible" bool 是否可见 true
"interaction/disable_all" bool 是否禁用所有手势交互 false
"interaction/disable_pinch" bool 是否禁用双指捏合操作 false
"interaction/disable_click" bool 是否禁用点击操作 false
"interaction/disable_scroll" bool 是否禁用滑动操作 false
"interaction/disable_long_press" bool 是否禁用长按操作 false
"interaction/disable_double_click" bool 是否禁用双击操作 false
"interaction/disable_two_finger_scroll" bool 是否禁用双指滑动操作 false
"interaction/enable_touch_zone " bool 是否开启可操作范围设置(热区)(全局开关) false
"interaction/plane_move_limit_near" float 在给定平面上手势交互移动物体时的离相机最近距离限制
"interaction/ plane_move_limit_far " float 在给定平面上手势交互移动物体时的离相机最远距离限制
"offscreen_guidance/enabled" bool 是否开启场景中主体离开屏幕可视区域时的找寻引导 false
"offscreen_guidance/target_node_name" string 对应的当离开屏幕可视区域时要显示找寻引导的对应的节点的名称
"offscreen_guidance/current_state" string 当前显示状态"hide"|"show"
"batch_load/loading_state" string 当前分步加载的状态 "loading" | "failed"| "finish"
"batch_load/ loading_progress" float 当前分步加载的进度:0.00 - 1.00

示例:

sample code:
local visible = scene:get_property_bool("visible")

KVO支持(Key-Value Observing)

API起始版本:190

add_observer_for_property

 void add_observer_for_property(string &key, ARLuaFunction on_observer);

为指定的property设置观察者回调,当对应的property值发生改变时,会触发所注册的回调, 并将改变前和改变后的数据以参数形式传递到对应的回调函数中

Parameters

  • string | key : 要设置监听的的property的名字
  • LUA_FUNCTION | on_observer : 观察者回调, 需要包含3个参数,key、old_value和new_value
sample code:

function on_loading_progress(key, old_value, new_value)
     ARLOG("current progress"..new_value * 100 .."%")
end

scene:add_observer_for_property("batch_load/loading_progress", on_loading_progress)

remove_observer_for_property

 void remove_observer_for_property(string &key);

删除指定的property已设置的观察者回调,删除不存在的Observer或者重复删除将会被忽略

Parameters

  • string | key : 要删除监听设置的的property的名字
scene:remove_observer_for_property("batch_load/loading_progress")

Deprecated methods(建议不再使用的方法)

过期的方法将在若干个版本后停止维护。

project

ARVec3 project(float x, float y, float z);

新版本中请使用ARCamera类提供的project方法

unproject

ARVec3 unproject(float x, float y, float depth);

新版本中请使用ARCamera类提供的unproject方法

remove_node_by_name

void remove_node_by_name(string &name);

删除指定节点

Parameters

  • string | name : 要被删除的节点的名字
sample code: 

local new_node_name = node:get_property_string("name")
scene:remove_node_by_name(new_node_name)

set_event_handler

void set_event_handler(int event_type, int handler_id);

未使用,已废弃

get_camera_pitch_angle

float get_camera_pitch_angle();

新版本中可以在脚本中获取Camera朝向和IMU数据,在脚本中自定义camera pitch的计算

set_enable_touch_zone

void set_enable_touch_zone(bool enable) { _interaction_config.enable_touch_zone = enable; };

新版本中请使用上述KVC的方式来实现。scene:set_property_bool("enable_touch_zone", true)

get_enable_touch_zone

bool get_enable_touch_zone() { return _interaction_config.enable_touch_zone; };

新版本中请使用上述KVC的方式来实现。scene:get_property_bool("enable_touch_zone")

set_user_interaction_config

void set_user_interaction_config(string config_name, int value);

新版本中请使用上述KVC的方式来实现。eg. scene:set_property_bool("interaction/disable_click")

set_offscreen_guidance_target

void set_offscreen_guidance_target(string node_name);

新版本中请使用上述KVC的方式来实现 eg.scene:set_property_bool("offscreen_guidance/target_node_name")

set_slam_move_limits

void set_slam_move_limits(float min, float max);

新版本中请使用相机节点距离来实现

set_show_offscreen_guidance

void set_show_offscreen_guidance(bool show);

新版本中请使用上述KVC的方式来实现: scene:set_property_bool("offscreen_guidance/enabled")

set_visible

void set_visible(bool visible);

新版本中请使用上述KVC的方式来实现: scene:set_property_bool("visible")

get_visible

bool get_visible();

新版本中请使用上述KVC的方式来实现: scene:get_property_bool("visible")

load_batch

void load_batch(int id);

异步加载指定批次

load_all_batch

void load_all_batch();

顺序加载所有批次

set_if_imu_relay_ctrl_when_track_lost

void set_if_imu_relay_ctrl_when_track_lost(bool enable);

设定场景是否开启imu接管

上一篇
ARNode
下一篇
多媒体