ARScene
所有文档

          AR开放平台

          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 | 新克隆节点名字的前缀

          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
          下一篇
          多媒体