API 惯例

在使用 EasyAR Sense 的 API 时，需要遵循一些惯例，否则可能会引起程序崩溃、出现内存泄漏或其他运行不正常的情况。

支持的语言

EasyAR Sense 支持如下语言：

• C

  支持 C99 和 Visual C++、gcc、clang

• C++

  支持 C++17 和 Visual C++、gcc、clang

  用到的 C++17 特性只有 std::optional，如果需要在 C++11 环境使用，可以使用 optional lite，将接口头文件中的 std::optional 替换为 nonstd::optional，并将 #include <optional> 替换为#include "nonstd/optional.hpp"

• Java

  仅支持 Android 平台，支持 Java SE 6 及以上

• Kotlin

  仅支持 Android 平台

• Objective-C

  仅支持 iOS/macOS/visionOS 平台

• Swift

  支持 Swift 4.2 及以上

• C#

  支持 .Net Framework 3.5 及以上、.Net Core、.Net 5+、Mono、Unity/Mono、Unity/IL2CPP

线程安全模型

每个类，如果不加说明，则其静态成员是线程安全的。

每个类，如果不加说明，则其实例成员在外部加锁的情况下是线程安全的，在不加锁的情况下不是线程安全的。

每个类，如果不加说明，则在结束对对象的其他调用后，可以从任意线程调用其析构函数，此时是线程安全的。

内存模型

EasyAR Sense 内部使用 C++ 的 std::shared_ptr 进行引用计数，而引用计数和垃圾回收之间存在着根本上的不兼容，不能无缝转换。

• C, C#, Java/Kotlin

  需要进行手动引用计数，使用 dispose 释放持有的对象的引用，使用 clone 从一个引用创建一个新的引用。

  特别需要注意的是传入到 EasyAR Sense 的回调的参数会在回调结束后自动释放，如果需要保留必须进行 clone，自动释放的原因是为了支持传入没有任何逻辑的回调。

  需要注意的是传入到 EasyAR Sense 的回调中如果使用到 EasyAR Sense 的对象可能导致循环引用，需要当成资源（例如文件、操作系统句柄）进行手动释放，防止内存泄漏。

• C++, Objective-C, Swift

  使用语言内置的引用计数。

  需要注意的是传入到 EasyAR Sense 的回调中如果使用到 EasyAR Sense 的对象可能导致循环引用，应合理使用引用捕捉、std::weak_ptr 等。

字符串编码

接口中使用的字符串的编码如下：

• C, C++

  UTF-8

• Java, Kotlin, Objective-C, C#

  UTF-16

• Swift

  UTF-16 或者 UTF-8, 参考 Swift文档